AI Positron View

The AI Positron add-on provides access to the AI Positron side-view. If the view is not displayed, it can be opened by selecting it from Window > Show View.

Top Header Stripe

The top header stripe contains the following actions and menus:

New Chat button

Clears the information in the chat pane and start a new chat.

History drop-down menu

Displays a list of your most recently conversations and contains an action to clear the history.

Actions drop-down menu

Contains the available AI-powered actions that can be used to generate and refine content. You can use the

Search actions button at the top of the menu to help you quickly locate a particular action. Simply select an action to trigger it. You can hover the mouse cursor over an action to see a description of what the action does. The

Record examples button allows you to create custom actions or prompts by recording changes. The next section contains a list of the 5 most recently used actions. This menu also contains actions to export or import a conversation.

User drop-down menu

This menu contains the following:

My account (available only for AI Positron Service connections) - Opens a webpage where you can see your current subscription package and credit status.
Disconnect (available only for AI Positron Service connections) - Disconnects Oxygen from the Oxygen Positron Service.
Preferences - Opens the Oxygen AI Positron preferences page where you can configure various options, including the AI Positron service address and the Context for the user that the AI will use to create more relevant and personalized responses.

Main Response Pane

Before a conversation has been initiated, the main response pane contains general instructional information and links to quickly change the chat mode. You can also click the Show actions link to see a list with all available predefined AI actions.

Once a conversation is initiated, this pane presents the results after processing an action and allows you to further refine the responses by sending messages to the AI service. When an AI Positron action is triggered, the response pane displays the progress and results.

Responses are received from the server in streaming mode (the AI sends chunks of the response as it is being generated rather than waiting to send the entire response after it is generated). Depending on the received response, AI Positron may switch the response visualization between the following modes:

Text (with syntax highlight for XML, Markdown or other content types) - You can open links from the response area in a web browser by hovering over the links, then holding the Control/Command key and mouse click.
Markdown (HTML) - The Markdown response is converted to HTML as it is received and displayed in a browser-like UI that supports styling for code blocks, links, tables, lists, headings, and inline elements (bold, italic, underline, and code phrases). You can easily copy the contents of a code block by clicking the Copy button in the top-right corner. For security reasons, this response does not load or display embedded remote resources (e.g. images).
Author - If the response contains XML content, AI Positron may switch the response to be viewed in an Author mode renderer, similar to how that same received XML content may be rendered in the main editor area.

Before the response (to the far right), there is a horizontal ellipsis (Switch how the response is rendered drop-down button) that allows you to switch between visualization modes and also to disable auto detection and choose a mode to be used preferentially.

An AI validation agent performs automatic fixes when the AI model responds with an XML document that is invalid according to the associated document type. If the response XML is not well-formed, it is also automatically fixed by the agent.

Once the entire response is received from the server, the following actions could be available under or next to the response (depending on the type of AI action):

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). If the insertion generates validation errors in the document, the AI model receives the validation errors and attempts to fix the problems.
Preview - Opens the built-in file comparison tool where you can 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. If the insertion generates validation errors in the document, the AI model receives the validation errors and attempts to fix the problem.
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.

For actions that create and modify files and save the changes to disk, a Waiting for approval box is displayed below the response and above the chat input area.

The modified files are displayed in a collapsible list. Modified files have a star icon () while new files have a plus icon (). You can double-click a file to open it in the built-in file comparison tool where you can preview the modifications. If you choose to accept the changes from within the file comparison tool, that particular file is finalized and removed from the list of modified files.

The following actions are available in the Waiting for approval box:

Keep all - Accepts the changes in all listed files.
Reject all - Discards all changes in all listed files.
Review changes - Opens the particular file in the built-in file comparison tool where you can review the modifications.
Keep changes - Accepts the changes for the particular file.
Reject changes - Rejects the changes for the particular file.

The Review changes, Keep changes, and Reject changes actions are also available from the contextual menu when right-clicking a file.

Tip:

You can also partially select content from the response area, then right-click to open the contextual menu, and use the Insert/Replace, Preview, or Copy actions on that partially selected content.

You can use the bottom chat input area to refine the response by sending a message to the AI platform and it will generate a new response based upon your message. You can edit your message by clicking the Edit button that appears to the right of your message in the response area. You would then edit your message and click Submit to regenerate the response. For multiple edited messages, you can use the Next/Previous buttons to navigate between chat threads.

Chat Input Box

You can also start chatting with the AI directly in the chat input box at the bottom of the view.

Tip:

You can invoke an existing action directly from the chat input box by providing general instructions to the AI. For example, to invoke the Correct Grammar action, you could type something similar to the following in the chat input box:

Invoke the action to correct grammar in the current document and update the document based on the results

You can drag (or copy) files (or folders) from your system file browser or screen captures and drop (or paste) them in the chat input box, or you can use the dedicated

Attach action in the top of the chat input box. For more details, see Attachments.

You can search for available AI-powered actions by using the Ctrl + Space keyboard shortcut within the chat input box. Actions in the dynamic filter results match your search based on their title or description (visible in the tooltip on hover).

To invoke an action from the filtered list, either double-click on the item or press Enter.

At the top of the chat input box, the following buttons are available:

Favorites drop-down menu

Adds a prompt as a stored favorite.

Insert Variables drop-down menu

Use this menu 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, jpeg, or svg format) or XML, Markdown, text, Word (.docx), Powerpoint (.pptx), Excel (.xlsx), or PDF file to the conversation. For Word and PDF files, the included images are also sent to the AI engine.

Start recording prompt using the microphone button

Allows you to record your voice, which is converted to a text prompt using the AI engine. After starting the recording, the button is changed to a

Stop action that you use to stop the recording.

Attach

Use this action to attach files or images to the conversation. For details, see Attachments.

Bottom Header Stripe

The bottom header stripe contains the following actions and menus:

Chat Mode drop-down menu

Allows you to change the chat mode (Agent, Ask, DITA Agent, Planner, Personas). For more details, see Chat Modes.

Tools

Opens a dialog box where can filter and choose which tools (either added via Model Context Protocol or provided in the chat mode definition) to use for the conversation.

Default AI Model drop-down menu

This menu allows you to select from the available AI models to be used for chat purposes and for actions that do not explicitly specify a model.

Context Consumption/Compact Conversation

The circular progress bar on this button shows the approximate fill level for the model's usable context window for the next request.

Hover over the button to see specific details such as the percentage of the usable context window that is filled and the current and total token counts. For external AI connections, it also shows the token count for the last response and a running total for the whole conversation (including any responses regenerated or replaced by edits). For Oxygen AI Positron Service connections, it shows the percentage of your plan's credits used, the exact credit count, and the date your credits reset.

Click the button to compact the current conversation. A confirmation dialog box verifies if you want to continue. When compaction occurs, the AI creates a hidden summary of the conversation to reduce the context that will be used by future requests. You can click the resulting visual marker that notes the conversation has been summarized to preview the summarized recap.

If the Auto-compact conversation option is enabled in the Preferences dialog box, the conversation is automatically compacted before you send a new message whenever the context exceeds 70%.

Send

Use this button (or Enter) to send your prompt to the AI. While the request is being processed, this button becomes a

Stop that can be used to stop the processing.