Functionality and Features (Eclipse)

Once you log in to the server, a variety of AI actions are available in:

• The Actions drop-down menu at the top of the AI Positron Assistant side view.
• The main chat area where you can start a new conversation or discuss with the AI and refine the results of an AI action.

There is also a user drop-down menu on the far-right side of the view's header that contains the following:

• 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.

You can also start chatting with the AI directly in the chat input box at the bottom of the view. In this case, if there is content selected in the main editor area when a chat is initiated, the selection is passed to the AI along with the document type as context for the conversation.

Once the entire response is received from the server, the following actions are available under the response:

• 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).
• Modify Document and Review Changes - Opens the built-in file comparison tool where you to review the changes that were inserted in the document. After reviewing the changes, click Accept to keep the changes or Reject to revert the changes.
• 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.
• Review documents and approve AI modifications - Available for actions that save changes to disk, this opens a pop-up that lists the files that are being modified by the AI operation and offers options for reviewing the changes. You can click See changes to open a visual comparison of the changes. Click Accept changes to accept the modifications or click Reject changes to revert all the modifications.

  

You can create your own favorite prompts and use supported variables to specify the content that is sent to the platform. You can use the Favorites drop-down button to store a favorite prompt. You can use the Insert Variables drop-down button to select one of the supported 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 XML, Markdown, text, Word (.docx), Powerpoint (.pptx), or PDF file to the conversation. For Word and PDF files, the included images are also sent to the AI engine.

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.
  Tip:

  Conveniently access this action by clicking the Generate Alternate Text button that is available from the floating toolbar that appears when you select an image.

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 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.
• 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).
• Formula/Equation - Generates an AI proposal for a MathML formula or equation based on information provided by the user when invoking the action (for example, a description of a substance, physics formula, mathematical expression, or LaTeX equation).
• 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 - Generates an explanation of the code found in the current selection or the element content at the current cursor location.
• Chat About Code - 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 - Generates the code for the current editor type 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. It has some enhanced features for XSLT files, such as it upgrades selected XSLT code to version 3.0, it breaks down large templates into small units, it incorporates xsl:try and xsl:catch instructions for error handling, and adds XML comments to clarify the purpose and functionality of the code.
• Annotate Code (available for XSLT, Schematron, and XSD) - Generates XML comments within the code found in the current selection, at the cursor location, or in the whole document. The generated annotations explain key concepts of the code.

Tip:

Sample files for the Development actions can be found at https://github.com/oxygenxml-incubator/ai-positron-assistant-samples/tree/main/Code%20Development.

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: Beginner, Intermediate, Advanced, and Expert.
• 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

• 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. After the action processes, a Preview dialog box shows the list of proposed changes.
• Expand Draft - Enhances a draft of a DITA XML topic by refining the existing content, adding new content, adding markup that is consistent with similar topics, and generating documentation based on the referenced images using the Vision support. The AI looks for similar content in topics gathered from the related links or through the Retrieval-Augmented Generation (RAG) process.
• 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. After the action processes, a Preview dialog box shows the list of proposed changes.
• Fix Validation Problems - Validates the entire content of the current document, finds problems, and then uses AI to fix all the reported problems.

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.

DITA Conversion

• Analyze and Update Topic - This action analyzes and optimizes your DITA topics to ensure modularity and consistency. It reviews and updates the topics to align with the DITA standards, generates new topics, and updates the DITA map as needed.
• Convert to [DITA_TYPE] - Actions that convert plain text, Markdown, or DITA content to a specific type of DITA topic:
  • Task - A topic type used to describe a series of steps to accomplish a specific goal. It is ideal for procedural information.
  • Concept - A topic type used to explain an idea, definition, or concept. It is typically used for background or explanatory information.
  • Reference - A topic type used to provide detailed, structured information such as tables, lists, or specifications. It is often used for quick look-up information.
  • Troubleshooting - A topic type used to describe problems, their causes, and solutions. It is designed to help users resolve issues effectively.
  • Glossary - A topic type used to define terms and provide explanations. It is commonly used to build a glossary of terms for a project or document.

File Creation

• Create New XSLT - Generates a new XSLT file based on a text description that you provide in a pop-up dialog box.
• Create New XML Schema - Generates a new XML Schema file (XSD) based on a text description that you provide in a pop-up dialog box.
• Create New Schematron - Generates a new Schematron file based on a text description that you provide in a pop-up dialog box.
• Create New JSON Schema - Generates a new JSON Schema file based on a text description that you provide in a pop-up dialog box.
• Create New DTD - Generates a new Document Type Definition (DTD) file based on a text description that you provide in a pop-up dialog box.

Tip:

The New Document Wizard contains a folder named AI Positron Templates with new file templates for creating these same types of documents (XSLT, XML Schema, Schematron, JSON schema, and DTD).

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.

For example, if you want to add DITA markup to menu cascades, you can follow these steps:

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.

The simplest form of the configuration file would only contain the <title> and <draft-summary> that will be used by the AI as a starting point:

<?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>

Other data elements can be used to further configure the drafting process: <context>, <target audience>, <instructions>, <image>, <file>, and <similar-topic>.

<?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...", which 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>Add additional information based on the following file.</instruction>
    <file href="format-and-indent-files-overview.docx"/>
    <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>

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.