- 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>
4.7 KiB
OpenJev Python SDK
Now part of Scribase: scribase.com/decisions. This
SDK itself is unchanged and still distributed as openjev-client — the link above is a
Jev-compatible quickstart that uses this package, not a rename or a republish.
openjev is an open Python client for OpenJev — a self-hostable decision engine
that speaks the same System One /v1 wire protocol as the upstream TypeSafe AI API, so a
single client works unchanged against:
- a self-hosted OpenJev deployment (default base URL:
http://localhost:8080) - the hosted TypeSafe AI API at
https://api.typesafe.ai
This SDK is derived from @typesafe-ai/typesafe-sdk-python (MIT).
See NOTICE for attribution. The request/response shapes (model + state +
questions-as-dict) and the public class names (TypeSafeClient, AsyncTypeSafeClient, …) are
kept identical so existing TypeSafe code is drop-in compatible.
Quickstart
Install the SDK:
pip install openjev-client
# or: uv add openjev-client
Live on PyPI as
openjev-client(the importable module isopenjev). The project was renamed to Umpirix; theumpirix-clientpackage name is publishing soon andopenjev-clientwill keep installing. The plain PyPI nameopenjevbelongs to an unrelated project — do not install it. To work from source instead:
git clone https://github.com/caelum0x/umpirix
pip install ./umpirix/sdk/python
No API key is needed for a self-hosted server: the client talks to http://localhost:8080
by default and sends no Authorization header unless a key is configured. Start the server
(npm run dev in the repository root), then:
from openjev import Choice, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={"document": "I was charged twice. Please fix this ASAP."},
questions={
"category": Choice(
instructions="What is this ticket about?",
criteria={"billing": None, "technical": None, "other": None},
),
},
)
print(response.choices["category"].choice)
Configuration
Point the SDK at a self-hosted OpenJev endpoint or the upstream TypeSafe AI API by setting environment variables or passing arguments to the client constructor.
| Purpose | Primary (OpenJev) | Back-compat alias (legacy) |
|---|---|---|
| API key (optional) | OPENJEV_API_KEY |
TYPESAFE_API_KEY |
| Base URL | OPENJEV_BASE_URL |
TYPESAFE_BASE_URL |
| Default model | OPENJEV_DEFAULT_MODEL |
TYPESAFE_DEFAULT_MODEL |
| Log level | OPENJEV_LOG_LEVEL |
TYPESAFE_LOG_LEVEL |
The primary OPENJEV_* variable is checked first; the TYPESAFE_* alias is consulted only
when the primary variable is absent so that callers already using TYPESAFE_* continue to work
without changes.
Default base URL when no variable is set: http://localhost:8080.
Example — point at a self-hosted deployment (the key line is only needed if your server issues keys):
export OPENJEV_BASE_URL="https://systemone.internal.example.com"
export OPENJEV_API_KEY="ots_live_..." # optional
Example — point at the upstream TypeSafe AI API using the back-compat alias:
export TYPESAFE_BASE_URL="https://api.typesafe.ai"
export TYPESAFE_API_KEY="ts_live_..."
from openjev import TypeSafeClient
# Explicit override also works and takes precedence over the environment:
client = TypeSafeClient(
base_url="https://systemone.internal.example.com", api_key="..."
)
Trust layer (OpenJev servers)
from openjev import Choice, TypeSafeClient
with TypeSafeClient() as client:
questions = {
"intent": Choice(
instructions="What does the customer want?",
criteria={"refund": None, "status": None},
abstain=True,
)
}
result = client.system_one(
"Where is my order?",
questions,
model="auto", # local first, LLM only for low-confidence questions
calibration_id="cal_...", # confidence fitted on your own labels
)
intent = result.choices["intent"]
if intent.abstained:
print("out of scope", intent.ood)
# Shadow mode: compare with your production LLM or human labels.
client.shadow.run(
"Where is my order?",
questions,
incumbent={"kind": "label", "answers": {"intent": "status"}},
)
summary = client.shadow.summary(days=7)