OpenAI Data Connector

The OpenAI Data Connector provides acccess to the OpenAI API. The Data Connector provides functionality for performing edits, queries and completions. It also provides core functionality for interacting with OpenAI that is built upon by other Data Connectors.

Constructor

OpenAI(key, orgopt, defaultModelopt) → {object}

We recommend that you create a Data Connector Configuration called "OpenAI" via the Verj.io Runtime Environment's Administration Application.

The Data Connector Configuration should include the following properties:

  • apikey, your OpenAI API key.

The Data Connector Configuration may also include the following properties

  • org, an organisation ID.
  • model, the default OpenAI model to use.

An OpenAI Data Connector is then available at connectors.verjio.openai using that configuration.

If you are unable to do that, you may use this constructor to create a new OpenAI Data Connector.

This method accepts an API key, an optional organisation ID and an optional default model.

Parameters:
Name Type Attributes Default Description
key string    

OpenAI API key.
org string <optional>  

Organisation ID.
defaultModel string <optional> 'gpt-4.1-nano'

The default OpenAI model to use.
Returns:
object

The OpenAI Data Connector.

Members

helpers

A collection of helper methods for formatting and querying API data.

Functions

helpers.getChoices(obj) → {Array.<object>|object}

Extract choices (results) from API response. If there is a single choice, return it directly. Otherwise, return an array.

Parameters:
Name Type Description
obj object

API response.
Returns:
Array.<object> | object

The result choice or an array of choice objects.

helpers.getResult(obj, commandToRemoveopt) → (nullable) {string}

Selects the best result from the available choice(s), formats and returns it.

Parameters:
Name Type Attributes Description
obj object  

API response.
commandToRemove string <optional>

The initial command text. This is removed from the response as it is usually echoed back.
Returns:
string

The best result, or null if none were available.

Example:
// Returns 'Pear' (or similar), ready for use
var response = connectors.verjio.openai.edit('Apple', 'Swap this for another fruit');
var result = connectors.verjio.openai.getResult(response, `${instruction}:);

helpers.makeMessage(prompt, roleopt) → {OpenAI.OpenAIMessage}

Returns a message for use with the chat endpoints.

Parameters:
Name Type Attributes Default Description
prompt string    

The message prompt.
role OpenAI.OpenAIMessageRole <optional> user

The role of sender.
Returns:
OpenAI.OpenAIMessage

The formatted message.

Example:
connectors.verjio.openai.makeMessage(
  'Make your previous suggestion more evocative.',
  connectors.verjio.openai.messageRoles.USER
);

completion(messages, modelopt, additionalParamsopt) → {object}

Perform an completion using a chat messages as input. The input can be a single message or an entire conversation. You may wish to include messages from a previous request as context.

Parameters:
Name Type Attributes Default Description
messages Array.<OpenAI.OpenAIMessage>    

Array of messages to use as input.
model string <optional> default model

ID of the model to use.
additionalParams object <optional>  

Additional parameters to include with request.
See:
Returns:
object

Details of the chat completion result.

Example:
var instruction = `Rewrite this to be more sympathetic`;
var prompt = `Our testing did not find the product fault that you reported.`;

var messages = [
  connectors.verjio.openai.helpers.makeMessage(
    'You are an AI assistant. You will answer questions in written English.',
    connectors.verjio.openai.messageRoles.SYSTEM
  ),
  connectors.verjio.openai.helpers.makeMessage(
    `${instruction}: ${prompt}`,
    connectors.verjio.openai.messageRoles.USER
  )
];

var response = connectors.verjio.openai.completion(messages);
var result = connectors.verjio.openai.helpers.getResult(response, `${instruction}:`);

edit(input, instruction, modelopt, additionalParamsopt) → {object}

Perform an edit using a specified input, instruction and model. An edit request typically modifies the input in some manner. The instruction describes how the input should be edited.

Parameters:
Name Type Attributes Default Description
input string    

The input to perform the edit on.
instruction string    

The edit instruction.
model string <optional> default model

ID of the model to use.
additionalParams object <optional>  

Additional parameters to include with request.
Returns:
object

Details of the edit result.

Example:
var prompt = 'Alice went to the supermarket.';
var instruction = 'Rename the character in this text "Sam"';

var response = connectors.verjio.openai.edit(prompt, instruction);
var result = connectors.verjio.openai.helpers.getResult(response, `${instruction}:`);

getModel(id) → {object}

Retrieve details about a specific model.

Parameters:
Name Type Description
id string

The model ID.
See:
Returns:
object

Details of the model.

Example:
// {"id":"dall-e-3","object":"model","created":1698785189,"owned_by":"system"}
var modelDetails = connectors.verjio.openai.getModel('dall-e-3');

getModels() → {Array.<object>}

Retrieve a list of models available to the Data Connector.

Returns:
Array.<object>

Details of available models.

Example:
// [{"id":"dall-e-3","object":"model","created":1698785189,"owned_by":"system"}, ...]
var availableModels = connectors.verjio.openai.getModels();

handleError(response)

Checks an API response for errors. If an error is encountered, the appropriate Error is thrown.

Parameters:
Name Type Description
response object

the response from a services.rest request
See:
Throws:
  • HttpAuthorisationError

    Thrown when the API key supplied is not valid or the account quota has been reached. See the error message for more context.

  • HttpNotFoundError

    Thrown when the OpenAI resource being accessed cannot be found.

  • HttpServerError

    Thrown when the OpenAI servers encounter a problem. Try retrying the request.

Example:
try {
  var response = connectors.verjio.openai.edit(fields.prompt.value, 'Simplify this text');
  var result = connectors.verjio.openai.helpers.getResult(response, `${instruction}:`);
}
catch(e) {
  if (e instanceof HttpAuthorisationError) {
    event.owner.addErrorMessage(`OpenAI authorisation error: ${e.getMessage()}`);
  } else {
    event.owner.addErrorMessage('Unable to perform request using OpenAI');
  }
}

query(prompt, modelopt, additionalParamsopt) → (nullable) {string}

Query the model directly. This method is used for retrieving answers to factual questions.

Parameters:
Name Type Attributes Default Description
prompt string    

The query prompt or question.
model string <optional> default model

ID of the model to use.
additionalParams object <optional>  

Additional parameters to include with request.
Returns:
string

Results of the query. Returns null if something went wrong.

Example:
// The capital of Nepal is Kathmandu.
var result = connectors.verjio.openai.query('What is the capital of Nepal?');

Type definitions

OpenAIMessage

A representation of a single message in a chat. A message has a role and some content.

Properties:
Name Type Description
role OpenAI.OpenAIMessageRole

The role of the message sender.
content string

The content of the message.

OpenAIMessageRole

Constants used to identify message roles.

These can be accessed via connectors.verjio.openai.messageRoles.

Properties:
Name Type Description
SYSTEM string

System messages help set the behaviour of the assistant. Typically a system message is sent first.
USER string

User messages provide requests or comments for the assistant to respond to.
ASSISTANT string

Assistant messages respond to the user.
See: