> For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt

# Jev

Jev provides a VoxEngine client for the TypeSafe System One API. A scenario sends text, and optional images, and receives typed answers for routing, triage, or scoring.

This client does not take call audio. Use `Jev.createSystemOneClient(...)` to keep one connection open, then call `systemOne` for each decision.

Build questions with `noul`, `choice`, `score`, and `box`. Use the `jev-preview` model when a request includes `box`.

## Related guides

#### [Jev overview](/voice-ai-orchestration/jev/overview)

See how System One fits a scenario that needs structured decisions instead of a realtime voice pipeline.

#### [System One client](/voice-ai-orchestration/jev/system-one-client)

Create the client, send a request, and handle the result.

## Contents

* [Usage](#usage): required module import.
* [Factory and question helpers](#factory-and-question-helpers): create the client and build System One questions.
* [Methods](#methods): send a System One request and manage the connection.
* [SystemOneEvents](#systemoneevents): result, error, and connector information events.
* [Parameter types](#parameter-types): client and request parameters.

## Usage

Add the module before using the namespace:

```js
require(Modules.Jev);
```

Create the client, wait for ConnectorInformation, then send systemOne requests on the same connection. A failed request does not close the client.

## Factory and question helpers

### box

Creates a question that locates what its instructions describe in the request image.
Use the `jev-preview` model for this question.
The arguments and the returned question are described in the [TypeSafe System One documentation](https://docs.typesafe.ai/concepts/system-one).

```ts
box(instructions?: Object): Object
```

**Parameters**

| Parameter      | Type     | Req. | Description |
| -------------- | -------- | ---- | ----------- |
| `instructions` | `Object` | ✗    |             |

**Returns**

| Type     | Description                   |
| -------- | ----------------------------- |
| `Object` | The requested `Object` value. |

### choice

Creates a question that selects between named alternatives.
The arguments and the returned question are described in the [TypeSafe System One documentation](https://docs.typesafe.ai/concepts/system-one).

```ts
choice(instructions: Object, criteria: Object): Object
```

**Parameters**

| Parameter      | Type     | Req. | Description |
| -------------- | -------- | ---- | ----------- |
| `instructions` | `Object` | ✓    |             |
| `criteria`     | `Object` | ✓    |             |

**Returns**

| Type     | Description                   |
| -------- | ----------------------------- |
| `Object` | The requested `Object` value. |

### createSystemOneClient

Creates a [Jev.SystemOneClient](/api-reference/voxengine/jev#systemoneclient) that keeps one connection open for many System One requests.

```ts
createSystemOneClient(parameters: SystemOneClientParameters): Promise<SystemOneClient>
```

**Parameters**

| Parameter    | Type                                                 | Req. | Description |
| ------------ | ---------------------------------------------------- | ---- | ----------- |
| `parameters` | <code>SystemOne<wbr />Client<wbr />Parameters</code> | ✓    |             |

**Returns**

| Type                       | Description                                                         |
| -------------------------- | ------------------------------------------------------------------- |
| `Promise<SystemOneClient>` | Resolves to the [`Jev.SystemOneClient`](#systemoneclient) instance. |

### noul

Creates a yes/no question.
When `instructions` is omitted or `null`, `criteria` must describe the yes outcome or the no outcome.
The arguments and the returned question are described in the [TypeSafe System One documentation](https://docs.typesafe.ai/concepts/system-one).

```ts
noul(instructions?: Object, criteria?: Object): Object
```

**Parameters**

| Parameter      | Type     | Req. | Description |
| -------------- | -------- | ---- | ----------- |
| `instructions` | `Object` | ✗    |             |
| `criteria`     | `Object` | ✗    |             |

**Returns**

| Type     | Description                   |
| -------- | ----------------------------- |
| `Object` | The requested `Object` value. |

### score

Creates a question that assigns a score using an ordered rubric.
A list of fewer than two entries is rejected when the request is sent.
The arguments and the returned question are described in the [TypeSafe System One documentation](https://docs.typesafe.ai/concepts/system-one).

```ts
score(instructions: Object, criteria: Object): Object
```

**Parameters**

| Parameter      | Type     | Req. | Description |
| -------------- | -------- | ---- | ----------- |
| `instructions` | `Object` | ✓    |             |
| `criteria`     | `Object` | ✓    |             |

**Returns**

| Type     | Description                   |
| -------- | ----------------------------- |
| `Object` | The requested `Object` value. |

## SystemOneClient

## Methods

### addEventListener

Adds a handler for the specified [Jev.SystemOneEvents](/api-reference/voxengine/jev#systemoneevents) or `Jev.Events` event. Use only functions as handlers; anything except a function leads to the error and scenario termination when a handler is called.

```ts
addEventListener(event: Jev.Events | Jev.SystemOneEvents | string, callback: (event: object) => any): void
```

**Parameters**

| Parameter  | Type                                                                   | Req. | Description                                   |
| ---------- | ---------------------------------------------------------------------- | ---- | --------------------------------------------- |
| `event`    | <code>Jev.Events \| Jev.<wbr />SystemOne<wbr />Events \| string</code> | ✓    | Event constant or event name to subscribe to. |
| `callback` | `(event: object) => any`                                               | ✓    | Function called when the event is emitted.    |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

### close

Closes the connection or the connection attempt.

```ts
close(): void
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

### id

Returns the client id.

```ts
id(): string
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type     | Description                 |
| -------- | --------------------------- |
| `string` | The requested string value. |

### removeEventListener

Removes a handler for the specified [Jev.SystemOneEvents](/api-reference/voxengine/jev#systemoneevents) or `Jev.Events` event.

```ts
removeEventListener(event: Jev.Events | Jev.SystemOneEvents | string, callback?: (event: object) => any): void
```

**Parameters**

| Parameter  | Type                                                                   | Req. | Description                                   |
| ---------- | ---------------------------------------------------------------------- | ---- | --------------------------------------------- |
| `event`    | <code>Jev.Events \| Jev.<wbr />SystemOne<wbr />Events \| string</code> | ✓    | Event constant or event name to subscribe to. |
| `callback` | `(event: object) => any`                                               | ✗    | Function called when the event is emitted.    |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

### systemOne

Sends one System One request on the open connection.
The promise resolves with the TypeSafe result. The matching `Jev.SystemOneEvents.Result` or `Jev.SystemOneEvents.Error` is also dispatched. A failed request does not close the client.
`parameters.body` and the resolved value are described in the [TypeSafe System One documentation](https://docs.typesafe.ai/concepts/system-one).

```ts
systemOne(parameters: SystemOneRequest): Promise<Object>
```

**Parameters**

| Parameter    | Type                                 | Req. | Description |
| ------------ | ------------------------------------ | ---- | ----------- |
| `parameters` | <code>SystemOne<wbr />Request</code> | ✓    |             |

**Returns**

| Type              | Description                     |
| ----------------- | ------------------------------- |
| `Promise<Object>` | Resolves to the `Object` value. |

### webSocketId

Returns the WebSocket id.

```ts
webSocketId(): string
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type     | Description                 |
| -------- | --------------------------- |
| `string` | The requested string value. |

## SystemOneEvents

These events report each System One result or failure, plus connector session information. The `data` field contains the provider payload.

#### Unknown

The unknown event.

Event constant: `SystemOneEvents.Unknown`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------- |
| `client` | <code>SystemOne<wbr />Client</code>                              | ✓    | The [Jev.SystemOneClient](/api-reference/voxengine/jev#systemoneclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | The event data. `payload` holds the integration payload for that custom event.    |

#### Result

The System One response. `data.payload` is `{ requestId?, body }`. `body` is described in the [TypeSafe System One documentation](https://docs.typesafe.ai/concepts/system-one). `Jev.SystemOneClient.systemOne` resolves with that same body.

Event constant: `SystemOneEvents.Result`

**Payload**

| Field    | Type                                                                                                     | Req. | Description                                                                       |
| -------- | -------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------- |
| `client` | <code>SystemOne<wbr />Client</code>                                                                      | ✓    | The [Jev.SystemOneClient](/api-reference/voxengine/jev#systemoneclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: \{ request<wbr />Id?: string; body?: Object; }; }</code> | ✗    | The event data. `payload.body` is the TypeSafe result.                            |

#### Error

A System One request failed. The client stays open. `data.payload` is `{ requestId?, statusCode?, text }`. `Jev.SystemOneClient.systemOne` rejects with this failure.

Event constant: `SystemOneEvents.Error`

**Payload**

| Field    | Type                                                                                                                                 | Req. | Description                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---- | --------------------------------------------------------------------------------- |
| `client` | <code>SystemOne<wbr />Client</code>                                                                                                  | ✓    | The [Jev.SystemOneClient](/api-reference/voxengine/jev#systemoneclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: \{ request<wbr />Id?: string; status<wbr />Code?: number; text?: string; }; }</code> | ✗    | The event data. `payload.text` describes the failure.                             |

#### ConnectorInformation

Contains Voice AI integration session information.

Event constant: `SystemOneEvents.ConnectorInformation`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------- |
| `client` | <code>SystemOne<wbr />Client</code>                              | ✓    | The [Jev.SystemOneClient](/api-reference/voxengine/jev#systemoneclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | The event data. `payload` holds the integration payload for that custom event.    |

## Parameter types

### SystemOneClientParameters

[Jev.SystemOneClient](/api-reference/voxengine/jev#systemoneclient) parameters. Can be passed as arguments to the `Jev.createSystemOneClient` method.

| Property                              | Type                      | Req. | Description                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------- | ------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  `apiKey`                             | `string`                  | ✓    | The TypeSafe API key. Sent as `Authorization: Bearer` on each System One request.                                                                                                                                                                                                                                                                                                                                                                     |
|  `baseUrl`                            | `string`                  | ✗    | Overrides the TypeSafe API host. The default host is `https://api.typesafe.ai`.                                                                                                                                                                                                                                                                                                                                                                       |
|  `longContext`                        | `boolean`                 | ✗    | When true, each request sends `TypeSafe-Danger-Zone-Long-Context: true` unless a call overrides it.                                                                                                                                                                                                                                                                                                                                                   |
|  <code>onWebSocket<wbr />Close</code> | `(event: object) => void` | ✗    | \_inherited from *VoiceAIClientParameters* A callback function that is called when the [WebSocket](/api-reference/voxengine/websocket) connection is closed.                                                                                                                                                                                                                                                                                          |
|  `privacy`                            | `boolean`                 | ✗    | \_inherited from *WebSocketBasedClientParameters* Whether to enable the privacy functionality. If privacy is enabled, the logging for the WebSocket connection is disabled. NOTE: the default value is **false**.                                                                                                                                                                                                                                     |
|  `statistics`                         | `boolean`                 | ✗    | \_inherited from *WebSocketBasedClientParameters* Enables statistics functionality.                                                                                                                                                                                                                                                                                                                                                                   |
|  `trace`                              | `boolean`                 | ✗    | \_inherited from *WebSocketBasedClientParameters* Whether to enable the tracing functionality. If tracing is enabled, a URL to the trace file appears in the 'websocket.created' message. The file contains all sent and received WebSocket messages in the plain text format. The file is uploaded to the S3 storage. NOTE: enable this only for diagnostic purposes. You can provide the trace file to our support team to help investigate issues. |

### SystemOneRequest

One System One evaluation sent on the open [Jev.SystemOneClient](/api-reference/voxengine/jev#systemoneclient) connection.

| Property       | Type      | Req. | Description                                                                                                                                                                            |
| -------------- | --------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  `body`        | `Object`  | ✓    | The TypeSafe request object (`state`, `questions`, optional `model` and `assets`). Described in the [TypeSafe System One documentation](https://docs.typesafe.ai/concepts/system-one). |
|  `longContext` | `boolean` | ✗    | Overrides the session `longContext` value for this request.                                                                                                                            |
|  `requestId`   | `string`  | ✗    | Echoed on `Jev.SystemOneEvents.Result` and `Jev.SystemOneEvents.Error`. Not sent upstream. When omitted, the client assigns an id so the result can be matched to this call.           |