Oxygen AI Positron Assistant

1. Go to Help > Install new add-ons to open an add-on selection dialog box. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.
   Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file.
2. Select the Oxygen AI Positron Assistant add-on and click Next.
   Important: There are two different iterations of the add-on and you can only have one or the other installed at once:

   • Oxygen AI Positron Assistant - The regular version of the add-on.
   • Oxygen AI Positron Assistant (Enterprise) - This Enterprise version is for those who want to connect to their own OpenAI or MS Azure OpenAI account.
3. Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
4. Restart the application.

• The Actions drop-down menu at the top of the AI Positron Assistant side view.
• The main chat panel when a conversation has not yet started.
• The AI Positron Assistant submenu that is available in the contextual menu when right-clicking in the main editor.
• The AI main menu at the top of the application.

Accessibility

• Generate Image Alternate Text - Generates an alternate text for an image that is selected in the main editing area when working with DITA XML content in the Author visual editing mode.

Content Generation

• Generate Documentation Draft - Generates a documentation draft of a DITA XML topic based on a configuration file that fine tunes the generation process by specifying the context, audience, summary, instructions, images, and a similar topic to help the AI generate the draft content.
• New DITA Topic - Generates a DITA XML topic based on a text description entered in a popup dialog box. For Oxygen XML Editor version 27 and newer, related content from the current set of project resources is also taken into account.
• Update Content Based on Images - Updates the content of a DITA XML topic based on the images that it references.
• Continue Writing - Generates additional text based on the content preceding the cursor position.
• Short Description - Generates a short description ( inside a <shortdesc> element) based on a summary of the selected text (or the entire document if there is no selection). You can configure the style and the approximate number of sentences to be generated.
• Index Terms - Generates a <keywords> element that contains index terms obtained from the selected text (or the entire document if there is no selection).
• Add Structured Content - Replaces the current selection with additional structured content generated based upon similar content from the current project (if available).
• Follow Instructions (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Replaces the selected instructions with content generated based on them.

Development

• Explain Code (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Generates an explanation of the code found in the current selection or the element content at the current cursor location.
• Chat About Code (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Creates a new chat to start a discussion with the AI regarding the code found in the current selection or the element content at the current cursor location.
• Document Code (available for XSLT, XSD, and Schematron) - Generates the documentation for the code and includes it as a comment in the document. If code is selected, it documents the selected code. Otherwise, it documents the element at the cursor location. It inserts the documentation as an XML comment before the documented code.
• Generate Code (available for XSLT, Schematron, XSD, CSS, XQuery, JSON, and JSON Schema) - Generates the code for the current editor type (text/xsl, text/xquery, text/css, text/json, text/xsd, text/sch) based on an instruction. It also reuses components found in the current document when generating the new code. The instruction can be a selected text, in which case the text will be replaced with the generated code. Alternatively, the instruction can be the previous XML comment, in which case the generated text will be inserted after the comment.
• Suggest Refactoring (available for XSLT and XSD) - Generates a suggestion for refactoring the selected code to simplify it and make it easier to read and understand.

Rewrite

• Correct Grammar - Generates a suggestion for correcting the grammar and spelling within the selected content.
• Improve Readability - Modifies the selected content to improve readability and fix grammar/spelling errors. If you hover the mouse prompt over this button, a Settings button becomes available in the top-right corner. Clicking the Settings button opens a pop-up window where you can choose the writing level of the content to be generated. You can choose between: 5th grade (Very Easy), 8th grade (Plain English), and College (Advanced).
• Use Active Voice - Generates a suggestion for replacing the selected content with content that has been converted from passive to active voice.
• Improve Structure - Improves the selected DITA XML content by adding additional structure or inline elements.
• Itemize - Generates a suggestion for converting the selected content into a list of items.
• Join Items - Generates a suggestion for converting the selected list of items into a paragraph.

Review

• Proofread - Adds comments in content that has logical consistency problems, grammar or spelling mistakes, or is hard to read and comprehend.
• Resolve Comments - Changes the selected content based on the suggestions within comments and then removes the comments.

Overview

• Answer Questions - Generates answers to questions that the AI finds within the selected content (or the entire document if there is no selection).
• Generate Questions - Generates a list of five questions that are answered within the selected content (or the entire document if there is no selection).
• Summarize - Generates a summary of the selected content (or the entire document if there is no selection).
• Readability - Generates suggestions for changing the selected content (or the entire document if there is no selection) to improve its general readability.

Translation

• English, French, German, Japanese - These actions translate the selected text to the target language, while preserving the original XML markup.
• Other... - This action behaves like the previous ones, but it allows you to provide the target language. You can either choose from the predefined values or type another one.

Intelligent Agents

• Split Topic - Analyzes the current DITA XML topic based on modular document development best practices. If the topic is too large or contains multiple subjects, the AI may split it into several topic files. References to the new topics are also added in the DITA map that is currently open in the DITA Maps Manager.
• Expand Draft - Enhances a draft of a DITA XML topic by refining the content, adding markup that is consistent with similar topics, and generating documentation based on the referenced images using Vision support. The AI looks for similar content in topics gathered from the related links or through the Retrieval-Augmented Generation (RAG) process.
• Create Topics - Generates DITA XML topics based upon user input, incorporating relevant project content. It creates a topic hierarchy, assigns DITA document types, and proposes a DITA map location. Topics are then saved and added upon user approval. The AI considers the DITA map opened in the DITA Maps Manager and the selected topic and then looks for similar content in topics gathered from the related links or through the Retrieval-Augmented Generation (RAG) process.

Reuse

• Product Names - Finds product names in the selected content and replaces them with key references (@keyref). If keys are not defined for specific product names, those names are wrapped in <keyword> elements.
• Component - Use the AI to identify the closest existing reusable component that matches the current selected paragraph.

Marketing

• Release Notes - Creates release notes based on a set of features or issue ticket numbers with optional descriptions.
• Marketing Post - Creates a marketing post based on a list of ideas or release notes.
• Improve SEO - Rewrites the content to enhance search engine optimization.
• Pain-Agitate-Solution - Rewrites the content using a marketing style based on the Pain-Agitate-Solution framework.
• Features-Advantages-Benefits - Rewrites the content using a marketing style based on the Features-Advantages-Benefits framework.

• My account - Opens a webpage where you can see your current subscription package and credit status.
• Disconnect - Disconnects Oxygen from the Oxygen Positron Service.
• Preferences - Opens the Oxygen AI Positron Assistant preferences page where you can configure the AI Positron service address and provide a Context for the user that the AI will use to create more relevant and personalized responses.

• Create document - Available only for the actions that generate an entire DITA topic, this action opens the topic in a new editor.
• Insert/Replace - Inserts the response at the cursor location within the document (or replaces the selected content).
• Preview - Opens the built-in file comparison tool where you to preview the content that would be inserted at the cursor location within the document. You can choose to preview the comparison in either Text or Author mode.
• Copy - Copies the response to the system clipboard.
• Regenerate - Requests the AI to give another response. You can also use the drop-down arrow to decide which engine model to use.

Favorites

Insert Variables

• ${selection} - Expands to the currently selected content.
• ${selection-original} - Expands to the currently selected content. If the current selected content contains track changes, they are rejected, resulting in the original version of the text.
• ${selection-final} - Expands to the currently selected content. If the current selected content contains track changes, they are accepted, resulting in the final version of the text.
• ${document} - Expands to the content of the entire document.
• ${attach(filePath)} - Attaches a specified image (in png or jpeg format) or an XML or text file to the conversation. You can also attach files in an easier way by using the dedicated Attach action.

• New chat - Clears the information in the chat pane and starts a new chat.
• Rewrite content - Opens a floating input box where you can provide the AI with instructions on how to rewrite the selected content (or the current paragraph if there is no current selection). It can be accessed easily by using the Ctrl - Alt - R (Windows) or Cmd - Alt - R (Mac) keyboard shortcut.
• Preferences - Opens the Oxygen AI Positron Assistant preferences page where you can configure the AI Positron service address and provide a Context for the user that the AI will use to create more relevant and personalized responses.

<?xml version="1.0" encoding="UTF-8"?>
<doc-draft>
  <title>Generate Documentation Draft</title>
  <instructions>
    <draft-summary>The new "Generate Documentation Draft" action was added to the 
"Content Generation" category and can be used to draft a DITA documentation topic
using AI and a configuration file.</draft-summary>
  </instructions>
</doc-draft>

<?xml version="1.0" encoding="UTF-8"?>
<doc-draft>
  <title>Generate Documentation Draft</title>
  <context>I am working on the user manual of a software application called Oxygen XML Editor,
 used for authoring and publishing XML content.</context>
  <prolog>
    <metadata>
      <audience>The audience of our user manual is very wide and includes 
people without a technical background.</audience>
    </metadata>
  </prolog>
  <instructions>
    <draft-summary>We have a new action in the contextual menu of the Project side-view,
 called "Format and Indent...",
 that can be used to pretty print multiple files at once. The action is available in both 
the Oxygen XML Editor stand-alone distribution and the Eclipse plug-in.</draft-summary>
    <instruction>Analyze the following image and document the dialog box
 and all its components.</instruction>
    <image href="format-and-indent-files.png"/>
    <instruction>Also add a DITA "note" element that mentions the fact that this feature 
is not available for XQuery files.</instruction>
  </instructions>
  <relationship-context>
    <similar-topic href="spell-check-in-files.dita"/>
  </relationship-context>
</doc-draft>

• Generate alternate text for images in DITA XML topics - Generates an alternate text for images in DITA XML topics.
• Generate missing short descriptions in DITA XML topics - Generates a short description (inside a <shortdesc> element) for DITA XML topics.
• Shorten existing short descriptions in DITA XML topics - Generates a shorter version of an existing short description for DITA XML topics.

Context

The context provides useful information about the user to the AI and is used in each action and chat request to create more relevant and personalized responses.

Actions section

Load default actions

Specifies if default actions are loaded.

Additional actions folder

You can use this option to specify a local folder where you have stored additional actions.

Actions to exclude

You can specify a comma-separated list of IDs for the actions that you do not want presented in the list of available actions. Use the menu to the right of the text field to choose the actions to exclude.

Embed AI Assistant in Author page

Controls whether or not the AI Positron Assistant drop-down widget is displayed when documents are open in the Author visual editing mode. This drop-down list contains some of the most useful AI actions for creating and improving the structure and content of the current document.

XPath Functions section

Enable XPath Functions

Enables the use of AI-specific XPath functions in Oxygen XML Editor when applying Schematron validation or XSLT transformations. This feature is disabled by default.

Cache responses and reuse them for identical prompts

If enabled (default), responses for identical requests are stored (cached), resulting in fewer requests being sent to the AI server and faster completion times. A Clear cache button located to the right of this option can be used to clear the cache.

Cache size

Specifies a maximum limit for the cache size.

Notify me when the number of requests exceeds

You can select this option and specify a number of AI requests that when exceeded, a confirmation dialog box is displayed asking if you want to continue using the XPath AI functions. If you select "No" for the answer, the XPath functions will be disabled.

AI Positron Service address

Currently, there is only one public platform that provides this service.

Default model

The default model is used for the chat pane and for actions that do not explicitly specify a fixed model. Each chosen model consumes a certain number of credits per token. The gpt-4o model is used by default if no other model is not chosen.

Enable project-based RAG

Enables retrieval-augmented generation based on similar content obtained from the current open project. Actions and chat interactions generate content give more precise and meaningful responses when this setting is enabled. It is enabled by default. The available functions used for RAG are listed in the text box.

The AI actions that use RAG are:

• Generate Documentation Draft
• New DITA Topic
• Add Structured Content
• Expand Draft

Ask for confirmation

When selected (default), the end user is asked to confirm whenever each specific project-based RAG function is about to be run.

Content retrieval token limit

Specifies a limitation for the upper amount of project content that may be sent to the AI engine to enhance responses and tune them based on the current open project.

Enable external RAG sources

Enables the use of external retrieval augmented generation sources.

Oxygen Feedback site token

When the Oxygen Feedback product is used to provide search functionality for a web site generated from the DITA XML project, its search system can be used to retrieve related content. In the Oxygen Feedback administrative interface, find the installation instructions for the site version that you want to use (click the Installation button on your version's tile in the Site Version page). The installation information contains a unique deploymentToken value that can be copied and pasted into the Oxygen Feedback site token field.

Oxygen Feedback site description

A description for this external content retrieval site that is passed to the AI engine to help it decide whether or not the external source is used.

Enable writing content in project (Experimental)

Allows functions that can be used by the AI to write content in the current project. The available functions used for this purpose are listed in the text box.

Project read/write sandbox

Comma-separated list of resource paths where functions are allowed to read/write content.

{
    "id": "my.action.id",
    "title": "Improve Grammar",
    "type": "replace-selection-with-fragment",
    "input-type": "markup",
    "context": "Improve grammar in the following content preserving the XML markup:"
}

{
   "id": "my.action.id",
   "title": "Improve Grammar",
   "type": "replace-selection-with-fragment",
   "input-type": "markup",
   "context": "${style} Improve grammar in the following content preserving the XML markup:",
   "expand-params":[
   {
           "name": "style",
           "label": "Style",
           "value": "",
           "alternate-values": ["Use active voice.", "Use passive voice."],
           "alternate-value-labels": ["Active voice", "Passive voice"],
           "choice-type": "single-choice"
    }
  ]
}

{
    "id": "action.summarize",
    "title": "Summarize",
    "categoryId": "Overview",
    "type": "show-response",
    "description": "Generate a summary of the selected content or the entire document.",
    "context": "Your task is to summarize the provided user text.",
    "parameters": {
        "function_refs": [
            {
                "ref": "get_current_document_plain_text_content"
            }
        ]
    }
}

add_to_toc(ditaMapURL, resourceURL, anchorNodeURL, positionOfInsertion)

Modifies the DITA map currently opened in the DITA Maps Manager view and adds a topic reference to it.

find_similar_reusable_content

Retrieves a list of reusable DITA XML components that match keywords provided by the AI.

get_content_around_caret

Retrieves size-limited content around the current cursor location within the document open in the editor.

get_corresponding_dita_keyrefs

Finds DITA key references that correspond to product names in the context DITA map.

get_current_document_marked_up_content

Retrieves all text with markup from the current document open in the editor.

get_current_document_plain_text_content

Retrieves all plain text (e.g. without markup) from the current document open in the editor.

get_current_editor_file_location

Retrieves the location (absolute path/URL) of the current file that is open in the editor.

get_related_content_from_project

Retrieves content from the user's local project based on given key words.

Notice: This function is only available in Oxygen XML Editor versions 26.1 (latest build) or newer. The returned content is limited to a maximum of 50k characters, by default.

get_related_content_from_webhelp

Returns content from the associated Oxygen Feedback WebHelp system for which a Enable external RAG sources has been configured.

get_related_resources_overview_from_project

Retrieves an overview of a maximum of 5 documents that each contain a URL and the most relevant information (usually titles, key words, and short descriptions). This function is paired with the get_content_for_document_url function, which retrieves the entire content for a document with a specific URL. Here is an example of how the functions can be referenced inside the definition of an AI action:

"function_refs": [
        {"ref": "get_related_resources_overview_from_project"},
        {"ref": "get_content_for_document_url"}
      ]

Notice: This function is only available in Oxygen XML Editor versions 26.1 (latest build) or newer. The returned content is limited to a maximum of 50k characters, by default.

get_topic_context_in_toc

Returns the hierarchical structure path that references the selected topic from the DITA map that is open in the DITA Maps Manager view, providing context such as its parent, siblings, and surrounding nodes within the DITA map. This is useful for understanding the topic's location in relation to other elements in the DITA map.

resolve_dita_key_or_content_reference

Resolves a DITA XML key reference, a content key reference, or a content reference to the target text.

save_document(URL,content)

Saves the document at the specified path and writes content to it. If a resource already exists at the specified URL, the content of the document will be overridden with the new content.

1. Click the Record button.
2. In the Record examples for instructions dialog box, enter some instructions like: You are a technical writer. Add DITA markup to menu cascades.
3. Click Start recording.
4. Open a DITA topic that has a menu cascade without markup (for example: File > Export).
5. Edit the topic and add markup, transforming it to:

   <menucascade>
     <uicontrol>File</uicontrol>
     <uicontrol>Export</uicontrol>
   </menucascade>

6. Click the Record button again to stop the recording. The system generates the following instructions with examples:

   You are a technical writer. Add DITA markup to a menu cascades.
   ###
   Input:
           <p>File > Export</p>
   
   Output:
         <p><menucascade><uicontrol>File</uicontrol>
         <uicontrol>Export</uicontrol></menucascade></p>
   
   Input: ${selection}
   Output:
   

7. In the resulting dialog box, save the final result as either a Positron action or as a favorite chat prompt.

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>