Custom XPath Functions

The AI Positron contributes some XPath extension functions (available in the content completion proposals for Schematron, XSLT, XQuery, and XPath) that can be used to rephrase content, perform validation checks on existing content, to invoke an AI action, or to chat with the AI directly:

ai:transform-content(system, (user, assistant,)* user)

Use this function from namespace http://www.oxygenxml.com/ai/function to automatically transform content using AI.

The function has the string parameters:
  • system - This parameter is used to set up the context or provide instructions for the AI model. It can include guidelines, rules, or any other information that affects how the model should interpret inputs and generate outputs.
  • user - This parameter represents the input from the human user. The user's input guides the conversation and prompts a response from the assistant (AI model). This input is typically what you want to transform or have addressed by the AI.
  • assistant - This parameter represents the responses or actions from the AI model (assistant) based on the user's input and the context set by the system. Multiple assistant parameters can be provided to represent different stages or turns in the conversation.

It returns a string that represents the transformed content.

Here is an example of a custom Schematron schema that uses the transform-content function to correct the number of words used in a short description:
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt3"
    xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
    <sch:ns uri="http://www.oxygenxml.com/ai/function" prefix="ai"/>
    <sch:pattern>
        <sch:rule context="shortdesc">
            <sch:report test="count(tokenize(.,'\s+')) > 50" sqf:fix="rephrase">
      The phrase must contain less than 50 words.</sch:report>
            <sqf:fix id="rephrase">
                <sqf:description>
                    <sqf:title>Rephrase phrase to be less that 50 words</sqf:title>
                </sqf:description>
                <sqf:replace match="text()" select="ai:transform-content(
                'Reformulate phrase to be less that 50 words', .)"></sqf:replace>
            </sqf:fix>
        </sch:rule>
    </sch:pattern>
</sch:schema>
ai:verify-content(system, (user, assistant,)* user)

Use this function from namespace http://www.oxygenxml.com/ai/function to automatically validate content using AI.

The function has two string parameters:
  • system - This parameter is used to set up the context or provide instructions for the AI model. It can include guidelines, rules, or any other information that affects how the model should interpret inputs and generate outputs.
  • user - This parameter represents the input from the human user. The user's input guides the conversation and prompts a response from the assistant (AI model). This input is typically what you want to transform or have addressed by the AI.
  • assistant - This parameter represents the responses or actions from the AI model (assistant) based on the user's input and the context set by the system. Multiple assistant parameters can be provided to represent different stages or turns in the conversation.

It returns a boolean value that represents the result of the validation.

Here is an example of a custom Schematron schema that uses the verify-content function to check a short description for instances of a passive voice:
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt3"
  xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
  <sch:ns uri="http://www.oxygenxml.com/ai/function" prefix="ai"/>    
  <sch:pattern>
    <sch:rule context="shortdesc">
      <sch:report test="ai:verify-content('Does the following content has passive voice?', .)"
            sqf:fix="rephrase">The phrase uses passive voice.</sch:report>
      <sqf:fix id="rephrase">
         <sqf:description><sqf:title>Rephrase text to be active voice</sqf:title>
</sqf:description>
         <sqf:replace match="text()"
                select="ai:transform-content('Rephrase text to be active voice', .)"/>
         </sqf:fix>
      </sch:rule>
  </sch:pattern>
</sch:schema>
ai:invoke-action(actionId, extraPrompt, content)

Use this function from namespace http://www.oxygenxml.com/ai/function to invoke a predefined AI action on a specified content.

The function has the string parameters:
  • actionId - The ID of the action to call (string).
  • extraPrompt - An extra prompt to give to the action as a context. It gets expanded at the beginning of the action's prompt (string).
  • content - The content to process using the action (string).

It returns a string that represents the content returned by the action.

ai:chat(messages) or ai:chat(messages, options)

Use this function from namespace http://www.oxygenxml.com/ai/function to send a conversation to the AI and obtain its response along with the complete conversation history (so the conversation can be continued over multiple turns).

The function parameters are:
  • messages - The conversation to send. It can be a single string (treated as a user message), a map with role and content keys, or a sequence that mixes strings and message maps. The messages array returned by a previous call (or by ai:resolve-action) can be passed back in to continue a conversation.
  • options - An optional map with completion options: model, temperature, max-tokens, max-completion-tokens, reasoning-effort, stop, tools (full tool definitions, such as those produced by ai:resolve-action), cache, and on-error ('throw' or 'return').

It returns a map with the following keys: response (the final assistant reply, as a string), messages (the complete conversation history, as an array of message maps), an optional warnings array, and an optional error string (present only when on-error is 'return' and the call failed).

Here is an example that asks the AI a question and outputs the reply:
<xsl:value-of select="ai:chat('Summarize what a shortdesc element is in DITA.')?response"/>
ai:resolve-action(action) or ai:resolve-action(action, options)

Use this function from namespace http://www.oxygenxml.com/ai/function to turn a predefined AI action into the ready-to-use messages and options that you pass to ai:chat. This lets you reuse a configured action (its prompt, model, and tools) from XPath, with full control over how it is sent to the AI.

The function parameters are:
  • action - The action to resolve. It can be the ID of a registered action (string), the URL of an action definition file (string), or an inline map that defines the action (with keys such as prompt or prompt_ref, parameters, and base-uri).
  • options - An optional map of overrides, such as model, temperature, max-tokens, max-completion-tokens, reasoning-effort, base-uri (used to resolve a relative prompt_ref path), and extra-context.

It returns a map with the following keys: messages (the resolved conversation messages, including the system message) and opts (the completion options, including any tools), plus an optional warnings array. They are intended to be passed to ai:chat.

Here is an example that resolves a registered action and runs it with ai:chat on the current element's content:
<xsl:variable name="a" select="ai:resolve-action('summarize-action')"/>
<xsl:value-of select="ai:chat(($a?messages, string(.)), $a?opts)?response"/>