Execute an Interaction by Name

Interactions can be executed by name using the /execute endpoint.

This operation is similar to the Execute Interaction and is using the sane payload with the difference that the interaction field points to an interaction name.

To execute an interaction by ID use the Execute Interaction endpoint.

The interaction name specifier

An interaction name specifier is a string that identifies an interaction. It is composed of the interaction name and the interaction tag name separated by an at @ character. The interaction tag name can be a regular tag, a version number or the special value draft.

A value of draft will select the draft version of the interaction given that name.
An integer value will select the interaction with that version number.
A tag name will select the interaction with that tag. If more than one interaction is found the first one is selected.
If no interaction tag is specified the latest version of the interaction is selected. If no latest version was published then the draft version is selected.

Examples:

ReviewContract - select the latest version of the interaction with the name ReviewContract.
ReviewContract@draft - select the draft version of the interaction with the name ReviewContract.
ReviewContract@1 - select the version 1 of the interaction with the name ReviewContract.
ReviewContract@fixed -select the interaction with the tag fixed and the name ReviewContract.

Execute an Interaction by Name
POST /execute

This endpoint is creating an execution run by starting the execution of an interaction. There are 2 modes of execution:

blocking: the execution is started and the response is returned when the execution is completed.
streaming: the execution is started and the response is returned immediately as an execution run in created state.
The client must then start the execution by requesting an event stream as specified by the Server-Sent-Events.
In the browser you can do this by using the EventSource API. In Node.js you can use a sevrer side implementation of the EventSource API like eventsource.
The event stream will sent the following events:

message - a new chunk of the result data is available. The event data property is the chunk as a string.
close - the execution is completed. The event data property is the final execution result object which can either has a status of completed or failed.

To start streaming the execution you should perform a GET request on /runs/:runId/stream.

Parameters

Name
interaction
Type
string
Modifier
required
Description
The interaction selector in the format name@tag to execute.
Name
stream
Type
boolean
Modifier
optional
Description
Wheter or not to stream the execution. Default is false.
Name
data
Type
object
Modifier
optional
Description
The input data to use to generate the prompt.
Name
tags
Type
string
Modifier
optional
Description
The tags to add to the execution run.
Name
config
Type
object
Modifier
optional
Description
A configuration object to customize the execution.
Name
environment
Type
string
Modifier
optional
Description
An execution environment ID to be used to generate the test data. If not specified the default interaction environment will be used.
Name
model
Type
string
Modifier
optional
Description
The model to be used to execute the interaction. If not specified the default model of the environment is used.
Name
temperature
Type
number
Modifier
optional
Description
The temperature to be used to execute the data. Defaults to 0.7.
Name
max_tokens
Type
number
Modifier
optional
Description
The maximum number of tokens to be used when generating the result.
Name
formatter
Type
number
Modifier
optional
Description
A custom formatter to use.

Returns

An execution run object.

Request

curl https://api.composableprompts.com/api/v1/execute \
  -H "Accept: application/json"
  -H "Authorization: Bearer {token}"
  -X POST
  -d {...}

Response

{
  result: {
    color: "blue"
  },
  parameters: {
    object: "car"
  },
  tags: [],
  environment: "654dfa3109676ad3b8631e24",
  interaction: "6554cf617eae1c28ef5f3d40",
  modelId: "gpt-4",
  status: "completed",
  ttl: 3600,
  source: {
    type: "api",
    label: "Key Created On 2023-10-24 16:31:28 via API",
    principal_type: "apikey",
    principal_id: "653772d5d73c5ac92045df97",
    client_ip: "::1"
  },
  account: "652d77895674c387e105948c",
  project: "654df9de09676ad3b8631dc3",
  config: {
    environment: "654dfa3109676ad3b8631e24",
    model: "gpt-4",
    id: "656486b6958d9210bae70291"
  },
  input_embedding: [],
  result_embedding: [],
  created_at: "2023-11-27T12:08:22.691Z",
  updated_at: "2023-11-27T12:08:23.925Z",
  execution_time: 1100,
  token_use: {
    prompt: 51,
    result: 9,
    total: 60
  },
  prompt: [
    {
      content: "\n What color is the car?\n",
      role: "user"
    }
  ],
  id: "656486b6958d9210bae70290"
}