2026-09-25 00:12:36 +03:00
|
|
|
# OpenJev Python SDK
|
|
|
|
|
|
2026-11-11 14:26:49 +03:00
|
|
|
**Now part of Scribase: [scribase.com/decisions](https://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.
|
|
|
|
|
|
2026-09-25 00:12:36 +03:00
|
|
|
`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`](https://github.com/typesafe-ai/typesafe-sdk-python) (MIT).
|
|
|
|
|
See [`NOTICE`](./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:
|
|
|
|
|
|
2026-11-12 02:16:10 +03:00
|
|
|
```
|
|
|
|
|
pip install openjev-client
|
|
|
|
|
# or: uv add openjev-client
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
> Live on PyPI as **`openjev-client`** (the importable module is `openjev`). The project
|
|
|
|
|
> was renamed to Umpirix; the `umpirix-client` package name is publishing soon and
|
|
|
|
|
> `openjev-client` will keep installing. The plain PyPI name `openjev` belongs to an
|
|
|
|
|
> unrelated project — do not install it. To work from source instead:
|
2026-09-25 00:12:36 +03:00
|
|
|
|
|
|
|
|
```
|
2026-11-12 02:16:10 +03:00
|
|
|
git clone https://github.com/caelum0x/umpirix
|
|
|
|
|
pip install ./umpirix/sdk/python
|
2026-09-25 00:12:36 +03:00
|
|
|
```
|
|
|
|
|
|
2026-11-11 05:36:35 +03:00
|
|
|
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:
|
2026-09-25 00:12:36 +03:00
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
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) |
|
|
|
|
|
| ------------------ | -------------------------------- | --------------------------- |
|
2026-11-11 05:36:35 +03:00
|
|
|
| API key (optional) | `OPENJEV_API_KEY` | `TYPESAFE_API_KEY` |
|
2026-09-25 00:12:36 +03:00
|
|
|
| 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`.
|
|
|
|
|
|
2026-11-11 05:36:35 +03:00
|
|
|
Example — point at a self-hosted deployment (the key line is only needed if your server
|
|
|
|
|
issues keys):
|
2026-09-25 00:12:36 +03:00
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
export OPENJEV_BASE_URL="https://systemone.internal.example.com"
|
2026-11-11 05:36:35 +03:00
|
|
|
export OPENJEV_API_KEY="ots_live_..." # optional
|
2026-09-25 00:12:36 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Example — point at the upstream TypeSafe AI API using the back-compat alias:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
export TYPESAFE_BASE_URL="https://api.typesafe.ai"
|
|
|
|
|
export TYPESAFE_API_KEY="ts_live_..."
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
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)
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
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)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
MIT — see [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).
|