Skip to navigation
Jev

System One client

Send several structured decisions on one connection
View as Markdown

For the complete documentation index, see llms.txt.

Use Jev System One when a voice or messaging scenario needs structured decisions (urgency, category, severity, and similar fields) rather than open-ended chat or TTS playback. From VoxEngine, use the Jev module and a Jev.SystemOneClient to call TypeSafe System One.

Credentials

Store your TypeSafe API key in an application secret (for example, TYPESAFE_API_KEY) and pass it to Jev.createSystemOneClient. Do not hardcode secrets in scenario source.

Usage

  1. Require the Modules.Jev module in your VoxEngine scenario.
  2. Create a Jev.SystemOneClient with Jev.createSystemOneClient, and your SystemOneClientParameters (apiKey, optional baseUrl, optional longContext).
  3. Wait for Jev.SystemOneEvents.ConnectorInformation, then call systemOne with a SystemOneRequest (body with state and questions, optional requestId and model).
  4. Handle each result via the returned promise and/or Jev.SystemOneEvents.Result. Handle failures with Jev.SystemOneEvents.Error; a failed request does not close the client, so you can send another systemOne on the same connection.
  5. Close the client or terminate the scenario when finished.

Build question objects with helpers such as Jev.noul, Jev.choice, Jev.score, and Jev.box (see System One questions in the API reference). Question and answer shapes follow the TypeSafe System One documentation.

When model is omitted in the request body, the platform uses the jev-latest alias unless you choose jev-preview (for example, when using Jev.box).

Here is a complete scenario that runs two System One requests on one connection:

jev-system-one.js
require(Modules.Jev);
VoxEngine.addEventListener(AppEvents.CallAlerting, async ({ call }) => {
  let client;
  const cleanup = () => {
    if (client) client.close();
    VoxEngine.terminate();
  };
  call.addEventListener(CallEvents.Disconnected, cleanup);
  call.addEventListener(CallEvents.Failed, cleanup);
  try {
    call.answer();
    client = await Jev.createSystemOneClient({
      apiKey: VoxEngine.getSecretValue("TYPESAFE_API_KEY"),
      onWebSocketClose: (event) => {
        Logger.write("===JEV_CONNECTION_CLOSED===");
        if (event) Logger.write(JSON.stringify(event));
        VoxEngine.terminate();
      },
    });
    client.addEventListener(Jev.SystemOneEvents.Error, (event) => {
      Logger.write("===JEV_ERROR===");
      Logger.write(JSON.stringify(event.data));
    });
    client.addEventListener(Jev.SystemOneEvents.ConnectorInformation, () => {
      Logger.write("===JEV_CONNECTED===");
      client.systemOne({
        requestId: "r1",
        body: {
          model: "jev-latest",
          state: "Help! My payouts have been failing for 3 days.",
          questions: {
            is_urgent: Jev.noul("Does this convey urgency?"),
          },
        },
      });
    });
    client.addEventListener(Jev.SystemOneEvents.Result, (event) => {
      const payload = event.data && event.data.payload;
      // @ts-ignore
      const requestId = payload && payload.requestId;
      Logger.write("===JEV_RESULT===");
      Logger.write(JSON.stringify(event.data));
      if (requestId === "r1") {
        client.systemOne({
          requestId: "r2",
          body: {
            model: "jev-latest",
            state: "Second decision on the same connection.",
            questions: {
              is_urgent: Jev.noul("Does this convey urgency?"),
            },
          },
        });
        return;
      }
      cleanup();
    });
  } catch (error) {
    Logger.write("===JEV_CLIENT_ERROR===");
    Logger.write(error);
    if (client) client.close();
    VoxEngine.terminate();
  }
});

When to use System One vs voice AI clients

GoalModule direction
Realtime speech in/out, TTS, STT, conversational agentOpenAI, Yandex, Deepgram, and other Voice AI clients
Structured fields from text (routing, triage, scoring)Jev System One (Modules.Jev)

System One does not replace VoxEngine.sendMediaBetween voice pipelines; combine it with your call flow (answer the call, run decisions, then route or speak via TTS/Avatar as needed).

See also