Other Functions

Functions that don’t fit into any other category.

ask-ai

ask-ai(model, message, [systemPrompt])➡String

Asks a configured chat model a question and returns its reply. The model is resolved by name or UUID; each call sends a request unless an identical response is cached.

Function Arguments:

Param Type Mandatory Default Value Allowed Values Multiple Min Count Description
model String - - - The name or UUID of the chat model.
message String - - - The message to send to the model.
systemPrompt String - - - Optional instructions for the model.

Return Value:

Type Description
String The model’s reply, or an empty sequence if the model or message is unavailable.

You must hold the Use permission on the model document. Where the model cannot be found, or you do not have permission to use it, a warning is recorded against the stream and an empty sequence is returned.

Performance

Repeated identical questions are served from a cache rather than being asked again, so calling this with the same model, message and system prompt costs one request however many records ask it. The cache is configured by the chatResponseCache property of the ai configuration branch. Setting its maximumSize to 0 asks the model every time.

Examples

Asking a model to classify a value.

<xsl:variable name="answer"
              select="stroom:ask-ai('Event Classifier', concat('Is this user agent a bot? Answer yes or no. ', UserAgent))"/>

Giving the model a role with a system prompt.

<xsl:variable name="answer"
              select="stroom:ask-ai(
                  'Event Classifier',
                  Description,
                  'You are a security analyst. Answer in one short sentence.')"/>

cosine-similarity

cosine-similarity(vectorA, vectorB)➡Decimal

Calculates the cosine similarity of two numeric vectors, such as embedding vectors. The result is between -1 and 1; larger values indicate that the vectors point more closely in the same direction.

Both vectors must have the same number of elements, otherwise an error is raised. If either vector has zero magnitude, the function returns 0.

Function Arguments:

Param Type Mandatory Default Value Allowed Values Multiple Min Count Description
vectorA Sequence - - - The first sequence of numbers.
vectorB Sequence - - - The second sequence of numbers, with the same length as vectorA.

Return Value:

Type Description
Decimal The cosine similarity of the two vectors, or 0 if either has zero magnitude.

Example

XSLT:

<xsl:variable name="a" select="(1, 0, 1)" as="xs:double*" />
<xsl:variable name="b" select="(1, 1, 1)" as="xs:double*" />
<Similarity><xsl:value-of select="stroom:cosine-similarity($a, $b)" /></Similarity>

XML:

<Similarity>0.8164965809277259</Similarity>

pointIsInsideXYPolygon

pointIsInsideXYPolygon(xPos, yPos, xPolyData, yPolyData)➡Boolean

Tests whether a point is inside a polygon. Useful for determining if a user is inside a physical zone based on their location and the boundary of that zone.

The list of values supplied for xPolyData must correspond with the list of values supplied for yPolyData and both must contain at least three points. The points that define the polygon must be provided in order, i.e. starting from one point on the polygon and then travelling round the path of the polygon until it gets back to the beginning.

Function Arguments:

Param Type Mandatory Default Value Allowed Values Multiple Min Count Description
xPos Decimal - - - The point’s X coordinate.
yPos Decimal - - - The point’s Y coordinate.
xPolyData Sequence - - - The polygon’s X coordinates, in vertex order.
yPolyData Sequence - - - The corresponding Y coordinates, in vertex order.

Return Value:

Type Description
Boolean true if the point is inside the polygon; otherwise false.

send-email

send-email(to, subject, body, [cc], [bcc])➡Empty Sequence

Sends an email using the SMTP server and from address configured in stroom.analytics.emailConfig. Each address argument is a ; separated list of email addresses, and there must be at least one recipient across to, cc and bcc. If the body contains HTML tags it is sent as HTML, otherwise as plain text.

An email is sent every time the function is called, so calling it for every record will send an email for every record. No email is sent while stepping. Instead an INFO message shows the email that would have been sent.

As the function returns an empty sequence, call it somewhere its result is used, e.g. <xsl:sequence select="stroom:send-email(...)"/>, otherwise the XSLT processor may not call it.

Function Arguments:

Param Type Mandatory Default Value Allowed Values Multiple Min Count Description
to String - - - The ; separated addresses to send the email to.
subject String - - - The subject of the email. It must be a single line.
body String - - - The body of the email, as plain text or HTML.
cc String - - - The ; separated addresses to copy the email to.
bcc String - - - The ; separated addresses to blind copy the email to.

Return Value:

Type Description
Empty Sequence An empty sequence.

split-document

split-document(doc, segmentSize, overlapSize)➡Sequence

Splits text into overlapping segments for language-model tokenisation. The segment and overlap sizes are estimated token counts.

Function Arguments:

Param Type Mandatory Default Value Allowed Values Multiple Min Count Description
doc String - - - The document text to split.
segmentSize Integer - - - The target segment size in estimated tokens.
overlapSize Integer - - - The overlap between adjacent segments in estimated tokens.

Return Value:

Type Description
Sequence An array of text segments, or an empty array if splitting fails.
Last modified October 20, 2026: Merge pull request #144 from gchq/add-7.14-rel-notes (2c6fb22)