Skip to navigation

Jev

TypeSafe System One client for structured decisions over text.
View as Markdown

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.

Contents

Usage

Add the module before using the namespace:

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.

box(instructions?: Object): Object

Parameters

ParameterTypeReq.Description
instructionsObject✗

Returns

TypeDescription
ObjectThe 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.

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

Parameters

ParameterTypeReq.Description
instructionsObject✓
criteriaObject✓

Returns

TypeDescription
ObjectThe requested Object value.

createSystemOneClient

Creates a Jev.SystemOneClient that keeps one connection open for many System One requests.

createSystemOneClient(parameters: SystemOneClientParameters): Promise<SystemOneClient>

Parameters

ParameterTypeReq.Description
parametersSystemOneClientParameters✓

Returns

TypeDescription
Promise<SystemOneClient>Resolves to the Jev.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.

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

Parameters

ParameterTypeReq.Description
instructionsObject✗
criteriaObject✗

Returns

TypeDescription
ObjectThe 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.

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

Parameters

ParameterTypeReq.Description
instructionsObject✓
criteriaObject✓

Returns

TypeDescription
ObjectThe requested Object value.

SystemOneClient

Methods

addEventListener

Adds a handler for the specified 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.

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

Parameters

ParameterTypeReq.Description
eventJev.Events | Jev.SystemOneEvents | string✓Event constant or event name to subscribe to.
callback(event: object) => any✓Function called when the event is emitted.

Returns

TypeDescription
voidDoes not return a value.

close

Closes the connection or the connection attempt.

close(): void

Parameters

This method does not accept parameters.

Returns

TypeDescription
voidDoes not return a value.

id

Returns the client id.

id(): string

Parameters

This method does not accept parameters.

Returns

TypeDescription
stringThe requested string value.

removeEventListener

Removes a handler for the specified Jev.SystemOneEvents or Jev.Events event.

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

Parameters

ParameterTypeReq.Description
eventJev.Events | Jev.SystemOneEvents | string✓Event constant or event name to subscribe to.
callback(event: object) => any✗Function called when the event is emitted.

Returns

TypeDescription
voidDoes 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.

systemOne(parameters: SystemOneRequest): Promise<Object>

Parameters

ParameterTypeReq.Description
parametersSystemOneRequest✓

Returns

TypeDescription
Promise<Object>Resolves to the Object value.

webSocketId

Returns the WebSocket id.

webSocketId(): string

Parameters

This method does not accept parameters.

Returns

TypeDescription
stringThe requested string value.

SystemOneEvents

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

The unknown event.

Event constant: SystemOneEvents.Unknown

Payload

FieldTypeReq.Description
clientSystemOneClient✓The Jev.SystemOneClient instance.
data{ customEvent?: string; payload?: Object; }✗The event data. payload holds the integration payload for that custom event.

The System One response. data.payload is { requestId?, body }. body is described in the TypeSafe System One documentation. Jev.SystemOneClient.systemOne resolves with that same body.

Event constant: SystemOneEvents.Result

Payload

FieldTypeReq.Description
clientSystemOneClient✓The Jev.SystemOneClient instance.
data{ customEvent?: string; payload?: { requestId?: string; body?: Object; }; }✗The event data. payload.body is the TypeSafe result.

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

FieldTypeReq.Description
clientSystemOneClient✓The Jev.SystemOneClient instance.
data{ customEvent?: string; payload?: { requestId?: string; statusCode?: number; text?: string; }; }✗The event data. payload.text describes the failure.

Contains Voice AI integration session information.

Event constant: SystemOneEvents.ConnectorInformation

Payload

FieldTypeReq.Description
clientSystemOneClient✓The Jev.SystemOneClient instance.
data{ customEvent?: string; payload?: Object; }✗The event data. payload holds the integration payload for that custom event.

Parameter types

SystemOneClientParameters

Jev.SystemOneClient parameters. Can be passed as arguments to the Jev.createSystemOneClient method.

PropertyTypeReq.Description
apiKeystring✓The TypeSafe API key. Sent as Authorization: Bearer on each System One request.
baseUrlstring✗Overrides the TypeSafe API host. The default host is https://api.typesafe.ai.
longContextboolean✗When true, each request sends TypeSafe-Danger-Zone-Long-Context: true unless a call overrides it.
onWebSocketClose(event: object) => void✗_inherited from VoiceAIClientParameters A callback function that is called when the WebSocket connection is closed.
privacyboolean✗_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.
statisticsboolean✗_inherited from WebSocketBasedClientParameters Enables statistics functionality.
traceboolean✗_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 connection.

PropertyTypeReq.Description
bodyObject✓The TypeSafe request object (state, questions, optional model and assets). Described in the TypeSafe System One documentation.
longContextboolean✗Overrides the session longContext value for this request.
requestIdstring✗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.