Extending Functionality Using Add-ons

The Oxygen AI Positron add-on offers advanced options for developers to extend its functionality. Below is an overview of the main extension points available:

AI Connectors Extension

This extension point lets developers build an add-on that adds an AI connector to the Oxygen AI Positron. It enables connections with AI providers not covered by our built-in options.

To create a connector, follow these steps:

Add oxygen-ai-positron-api as a dependency in your plugin project's pom.xml:

<dependency>
  <groupId>com.oxygenxml</groupId>
  <artifactId>oxygen-ai-positron-api</artifactId>
  <version>8.0.0</version>
  <scope>provided</scope>
</dependency>

The oxygen-ai-positron-api artifact is available from a public repository at https://oxygenxml.com/maven/. To use this artifact in your plugin project, add the repository configuration to your project's pom.xml file:
```
 <repository>
   <id>oxygen-public-repo</id>
  <url>https://www.oxygenxml.com/maven/</url>
 </repository>
```
Implement the ro.sync.exml.plugin.ai.AIConnectorsPluginExtension interface in your plugin's libraries.
In the plugin descriptor file, define the <extension> element that points to the implementation of your classes:
```
<extension type="AIConnectors" class="my.pack.CustomAIConnectorsProviderPluginExtension"/>
```

A sample plugin is available to show how to create a connector for a custom AI service that uses a REST API to provide OpenAI chat completions. You can find it here: https://github.com/oxygenxml/oxygen-ai-positron-custom-connector-addon

Key Concepts for 'oxygn-ai-positron-api':

The oxygen-ai-positron-api artifact provides the types used to declare a connector, expose UI parameters, and implement the runtime service.

AIConnector

Declares a connector that appears in Preferences and links the UI configuration to an AIService implementation. It does the following:

Defines the identity and display name (getConnectorId, getConnectorName).
Exposes the list of UI parameters (getParametersList).
Creates the runtime service (createAIService).
Optionally adapts outgoing requests (configureCompletionRequest).

AIService

Encapsulates calls to the AI backend (chat completions in streaming and non-streaming mode, moderation).

ConnectorParamBase parameters

Typed parameters drive both the Preferences UI and, when relevant, the AI Positron side-view. Common types:

TextFieldConnectorParam (e.g. base URL, model)
PasswordTextFieldConnectorParam (e.g. API key)
CheckBoxConnectorParam (e.g. moderation, streaming)
KeyValueTableConnectorParam (e.g. extra headers, extra query params)
ModelsComboConnectorParam (supplies the model combo in Preferences and the side-view)

For a code-level example of a connector class, see https://github.com/oxygenxml/oxygen-ai-positron-custom-connector-addon/blob/main/src/main/java/com/oxygenxml/positron/custom/connector/CustomAIConnector.java.

Note:

The AIConnectors extension type can be implemented starting with version 27.1 of Oxygen.

AI Tools Extension

The AI Tools extension point lets developers add their own custom callback tools or replace the built-in ones. This makes it possible to create custom interactions with AI engines.

To implement a tool, follow these steps:

Implement the ro.sync.exml.plugin.ai.AIFunctionsPluginExtension interface in your plugin's libraries.
In the plugin descriptor file, define the <extension> element that points to the implementation of your classes:
```
<extension type="AIFunctions" class="my.pack.CustomAIFunctionsProviderPluginExtension"/>
```

Note:

The AIFunctions extension point can be implemented starting with version 27.0 of Oxygen.