Edit online

Oxygen AI Positron Assistant Enterprise

The Oxygen AI Positron Assistant Enterprise add-on provides advanced support for technical documentation writers throughout their content creation process by using a company-specific AI service (by configuring your company's specific OpenAI key, Microsoft Azure OpenAI Service connection, or Anthropic Claude).

A detailed list of actions and functionality available in the add-on is presented in the Oxygen AI Positron Assistant topic.

Installation

To install this add-on, follow this procedure:

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.
Select the Oxygen AI Positron Assistant (Enterprise) 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, MS Azure OpenAI, or Anthropic Claude account.
Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
Restart the application.

Result: The AI Positron Assistant (Enterprise) side view is now available.

Licensing and Configuration

You can configure the company-specific AI service details in the AI Service Configuration Preferences Page.

The AI Positron Enterprise add-on works free of charge with any Oxygen XML Editor installation using an Enterprise license type for Oxygen XML Editor.

If your license of Oxygen XML Editor is not an Enterprise license, a special license key needs to be purchased for the add-on to enable this direct access. You can use the Register button in the AI Positron Assistant side view to configure the special license key.

Important: If you want to use the default Oxygen AI Positron service instead of a company-specific AI service, the Oxygen AI Positron Assistant add-on needs to be installed and used instead of the one listed above.

Note: If you are an integrator using the Web Author Component in your own solution and you want to license the AI Positron Enterprise for Web Author, you can set a dedicated license server for AI Positron.

AI Service Configuration Preferences Page

Various service-related connection settings can be configured in Options > Preferences > Plugins > Oxygen AI Positron Assistant (Enterprise) > AI Service Configuration:

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

OpenAI:

If OpenAI is chosen as the connector type, the following settings are available:

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.

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.

MS Azure OpenAI:

If Microsoft Azure OpenAI is chosen as the connector type, the following settings are available:

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

Extra Headers

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

Anthropic Claude:

If Anthropic Claude is chosen as the connector type, the following settings are available:

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.
Extra Headers: Extra name/value parameters to set in the headers that are specific for the AI requests.

Note: You can use editor variables such as ${env(ENV_NAME)} in all configuration and header parameter values.

Troubleshooting: If the add-on fails to connect with the custom settings, it might be useful to enable debug logging in the application to see what requests and responses are made to/from the AI server. You can enable debug logging in the application by adding a logback.xml file in the application's installation folder. A minimal logback.xml configuration XML file content to enable logging only for the AI Positron add-on's connections would look like this:

<configuration>
  <appender name="R2" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${user.home}/Desktop/oxygenLog/oxygen.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
      <fileNamePattern>${user.home}/Desktop/oxygenLog/oxygen%i.log.gz</fileNamePattern>
      <minIndex>1</minIndex>
      <maxIndex>20</maxIndex>
    </rollingPolicy>
    <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
      <maxFileSize>12MB</maxFileSize>
    </triggeringPolicy>
    <encoder>
      <pattern>%r %marker %p [ %t ] %c - %m%n</pattern>
    </encoder>
  </appender>
  <logger name="com.oxygenxml.positron.connector.openai" level="debug"/>
  <logger name="com.oxygenxml.positron.core" level="debug"/>
  <root level="error">
    <appender-ref ref="R2"/>
  </root>
</configuration>

Important: The logging information will be copied in the Desktop/oxygenLog folder once the application is started. To avoid performance problems, the logback.xml file must be deleted once the logging has been obtained.