Oxygen AI Positron Assistant for Eclipse

1. Download the Oxygen AI Positron Assistant Enterprise for Eclipse archive.
2. Extract the archive's contents into the dropins folder located within your Eclipse installation directory.
3. Restart Oxygen XML.

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

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

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

• 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.
• Fix Terminology Problems [optional] - When installed along with the latest Terminology Checker add-on, this action that is contributed by the Terminology Checker gathers terminology problems from the entire content of the current document, 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.

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.

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

  

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 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. You can also attach files in an easier way by using the dedicated Attach action.

Settings

Enable AI Positron Assistant

Deselect this setting to disable the AI assistant.

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.

Settings

Enable functions

Enables the use of functions for retrieval-augmented generation and for writing content in the project.

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
• Expand Draft
• Create Topics

Ask for confirmation

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

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

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.

Limit read/write access to

Allows you to restrict the locations where functions can read and write content. You can specify these locations as a comma-separated list of resource paths. By default, read and write access is restricted to the project directory and the directory of the current root map.

Settings

AI Connector

Specifies the connector type: OpenAI, Microsoft Azure OpenAI or Anthropic Claude.

Address

The web address of the OpenAI service. By default: https://api.openai.com.

API key

The OpenAI API key necessary to work with the connector.

Note:

This option does not get saved in the Project-level options.

Organization ID

For users who belong to multiple organizations, they can specify which organization is used for an API request. Usage from these API requests will count as usage for the specified organization.

Default model

The default model is used for the chat view and for actions that do not explicitly specify a model.

Enable text moderation

This setting applies moderation (checks whether content complies with OpenAI's usage policies) to both the input text sent to the AI service and the response received from the AI service. It is enabled by default.

Tip:

By default, when executing an action using the OpenAI connector, three requests are made:

• A moderation on input content request to configured_web_address/v1/moderations.
• A completion request to configured_web_address/v1/chat/completions.

• A moderation on content returned by AI to configured_web_address/v1/moderations.

  If your AI service does not require moderation (for example, moderation is already made by chat/completions endpoint) you can disable it by unchecking this checkbox.

Enable streaming

This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.

Extra Headers

Extra name/value parameters to set in the headers that are specific for the AI requests.

Tip:

If the service uses Bearer Authentication, you can specify the key in the Key text field. If another authentication method is used, the Key field can be left empty, and the Extra Headers table can be used to set the authentication info on the request header. Note that editor variables can be used in this field and you can set your key in editor variables and specify the value in this table like this: ${env(AI_SERVICE_KEY)} to access pre-set values of environmental variables.

Endpoint

The web address where the connector service is located. This value can be found in the Keys & Endpoint section when examining your resource from the Azure portal. For example: https://your-company-name.openai.azure.com/.

Deployment

The deployment name that was chosen when the model was deployed in Microsoft Azure.

API key

The Microsoft Azure OpenAI Service key necessary to work with the connector.

If you do not specify an API key, the add-on will try to use environment variables to authenticate using Microsoft Entra ID.

To use this method, you must create a service principal and assign a role to it that allows access to the Azure OpenAI service (e.g. the Cognitive Services OpenAI User role).

The connector supports these authentication methods:

Service principal authentication using a client secret

For this type of authentication, create a client secret and set these environment variables:

Variable name	Value
AZURE_CLIENT_ID	ID of a Microsoft Entra application.
AZURE_TENANT_ID	ID of the application's Microsoft Entra tenant.
AZURE_CLIENT_SECRET	One of the application's client secrets.

Service principal authentication using a client certificate

For this type of authentication, set up a certificate and set these environment variables:

Variable name	Value
AZURE_CLIENT_ID	ID of a Microsoft Entra application.
AZURE_TENANT_ID	ID of the application's Microsoft Entra tenant.
AZURE_CLIENT_CERTIFICATE_PATH	Path of a PFX/PEM certificate file
AZURE_CLIENT_CERTIFICATE_PASSWORD	Password for a PFX/PEM certificate

Username and password authentication

For username and password authentication, set these environment variables:

Variable name	Value
AZURE_CLIENT_ID	ID of a Microsoft Entra application.
AZURE_TENANT_ID	ID of the application's Microsoft Entra tenant.
AZURE_USERNAME	A username (usually an email address).
AZURE_PASSWORD	The associated password for the given username.

Note:

Oxygen XML should be restarted after each environment variable change for the changes to take effect.

Vision-specific Settings

Vision-specific settings are only used when images are attached in the Chat panel or sent to the AI engine with specific actions (e.g. Generate Documentation Draft).

Vision - Endpoint

Optional Azure AI deployment endpoint that can analyze images using Vision. This setting specifies the web address where the connector service is located. This value can be found in the Keys & Endpoint section when examining your resource from the Azure portal. For example: https://your-company-name.openai.azure.com/.

Vision - Deployment

Optional deployment name that was chosen when the Vision model was deployed in Microsoft Azure.

Vision - API key

Optional Microsoft Azure OpenAI Service for the endpoint that can analyze images using Vision.

Enable streaming

This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.

Extra Headers

Extra name/value parameters to set in the headers that are specific for the AI requests.

Endpoint

The web address where the connector service is located. By default, it is https://api.anthropic.com/.

API key

The Anthropic Claude API key necessary to work with the connector.

Model

The Anthropic Claude model to use. By default, it is claude-3-opus-20240229.

Enable streaming

This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.

Extra Headers

Extra name/value parameters to set in the headers that are specific for the AI requests.

{
    "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.

get_content_around_caret

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

get_content_for_document_url

Retrieves content from the document specified by the provided URL. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.

get_current_document_marked_up_content

Retrieves all text with markup from the current document open in the editor. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.

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_webhelp

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

get_related_content_from_specific_feedback_site

Returns content from the specified Oxygen Feedback WebHelp token passed as a parameter. The Enable external RAG sources checkbox must be selected.

get_topic_context_in_toc

Returns a hierarchical structure of the DITA map that is currently open in the DITA Maps Manager view. This structure shows the selected topic and provides context, including its parent, siblings, descendants, and nearby nodes within the DITA map. This feature helps the AI understand where the topic is located in relation to other elements in the DITA map. If the selected topic cannot be identified, the hierarchy will start from the root of the DITA map.

invoke_ai_action(actionID, content)

Invoke an action by passing the action ID and content to process.

Tip:

To define actions that are hidden in the interface and intended only for use by other actions, prefix their IDs with agent.hidden.action.

retrieve_all_ai_actions

Get IDs and descriptions for each available AI action.

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. For actions that use this function, the application gathers a list of resources to modify and displays them in a Preview dialog box after the action processes.

validate_document_content(URL, content)

Validates specified content and reports error messages in JSON format.

validate_current_document()

Validates the current document's content and reports error messages in JSON format.

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 as a Tool for Technical Content Creation
• Oxygen AI Positron: Your Helper in All Stages of Content Creation
• Oxygen AI Positron: Transforming Technical Content Creation through AI-Powered Writing

• Leveraging the Power of AI and Schematron for Content Verification and Correction
• AI-Powered Development, Part 1: Automating Error Resolution