caelum0x 49ad06727d docs: point install commands at packages that resolve today
- README Status/SDKs/Layout/Rename/Roadmap: the Python SDKs are live on
  PyPI under their OpenJev-era names (openjev-client 0.7.1,
  openjev-adapters 0.2.2, otsone 0.3.0) — `pip install openjev-client
  otsone openjev-adapters` works now; umpirix-* names publishing soon.
- Say plainly that @umpirix/* and @openjev/* are not on npm; JS SDKs
  install from source.
- sdk/python, adapters/python, otsone, sdk/js, sdk/ai-sdk READMEs: drop
  "not published yet" for the live PyPI packages, replace @openjev/* npm
  names with @umpirix/*, clone URLs -> caelum0x/umpirix.
- Verified against registry.npmjs.org / pypi.org and a fresh-venv
  install + import on 2026-11-12.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-12 02:16:10 +03:00
..

OpenJev JavaScript SDK

JavaScript and TypeScript SDK for the OpenJev ecosystem.

It is wire-compatible with both backends that speak the /v1/systemone contract:

  • a self-hosted OpenJev deployment at your own URL (default: http://localhost:8080), and
  • the hosted TypeSafe API at https://api.typesafe.ai/v1 (set OPENJEV_BASE_URL).

This is a rebranded fork of the official TypeSafe JavaScript SDK. The request and response shapes (model + state + questions-as-dictionary) are unchanged, so switching between the two backends is a matter of configuration only. See NOTICE for attribution.

Quickstart

Install the SDK (Node.js 20 or newer):

Not published to npm yet (neither @umpirix/sdk nor the older @openjev/sdk resolve). Until it is, install from a clone of this repository:

git clone https://github.com/caelum0x/umpirix
cd umpirix/sdk/js && npm install && npm run build
# then, from your project:
npm install /path/to/umpirix/sdk/js

Once published, this becomes npm install @umpirix/sdk.

Create the client. No API key is needed for a self-hosted server: the default base URL is http://localhost:8080 and no Authorization header is sent unless a key is configured. The client reads configuration from explicit options first, then the environment, then SDK defaults.

import { choice, OpenJevClient } from "@openjev/sdk";

const client = new OpenJevClient();
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);

Answer types are inferred from your questions. The package includes ESM, CommonJS, and TypeScript declarations.

Choosing a backend

The base URL and API key are configurable through constructor options or environment variables. Explicit options always win over the environment.

Against a self-hosted OpenJev deployment (default)

The default base URL is http://localhost:8080. Set your host, and a key only if your server issues them:

export OPENJEV_BASE_URL="https://openjev.internal.example.com"
export OPENJEV_API_KEY="ots_live_..."   # optional

or pass options in code:

const client = new OpenJevClient({
  baseURL: "https://openjev.internal.example.com",
  // apiKey: "ots_live_...",  // only if your server issues keys
});

Against the hosted TypeSafe API

Point the base URL at https://api.typesafe.ai and supply a TypeSafe API key:

export OPENJEV_BASE_URL="https://api.typesafe.ai"
export OPENJEV_API_KEY="sk-..."

The back-compat TYPESAFE_* variable names also work:

export TYPESAFE_BASE_URL="https://api.typesafe.ai"
export TYPESAFE_API_KEY="sk-..."

Environment variables

Purpose Primary variable Back-compat alias Default
API key OPENJEV_API_KEY TYPESAFE_API_KEY (none; optional)
Base URL OPENJEV_BASE_URL TYPESAFE_BASE_URL http://localhost:8080
Default model OPENJEV_DEFAULT_MODEL TYPESAFE_DEFAULT_MODEL otsone-latest
Log level OPENJEV_LOG_LEVEL TYPESAFE_LOG_LEVEL warn

The OPENJEV_* names are read first. The TYPESAFE_* aliases are read as a back-compat fallback so existing TypeSafe setups keep working without variable renames.

Trust layer (OpenJev servers)

const { answers, calibration, escalation } = await client.systemOne({
  model: "auto", // local first, LLM only for low-confidence questions
  calibration_id: "cal_...", // confidence fitted on your own labels
  state: "Where is my order?",
  questions: {
    intent: { ...choice("What does the customer want?", { refund: null, status: null }), abstain: true },
  },
});
if (answers.intent.abstained) console.log("out of scope:", answers.intent.ood);

// Shadow mode: compare with your production LLM (or human labels) without changing production.
await client.shadow.run({ state, questions, calibration_id: "cal_...", incumbent: { kind: "label", answers: { intent: "status" } } });
const summary = await client.shadow.summary({ days: 7 });

Documentation

See the SDK's client and types for API options and defaults. For the underlying System One contract, refer to the OpenJev host you are targeting.

License

MIT. This project is a fork of @typesafe-ai/sdk (MIT); see LICENSE and NOTICE.