jev-lite

OpenAI-style Python client for TypeSafe Jev (System One).

Jev does not generate text. Send state plus typed questions; get structured decisions with probabilities. jev-lite is the official TypeSafe HTTP client — sync and async, same shape as the OpenAI Python SDK. jev-lite@0.0.2 adds Dialogflow-style system entities (preview, below).

pip install jev-lite
# or: uv add jev-lite

Python 3.11+. Set TYPESAFE_API_KEY. Docs: https://docs.typesafe.ai/

Usage

from jev_lite import Choice, Noul, Score, TypeSafe

client = TypeSafe()  # TYPESAFE_API_KEY

result = client.system_one.create(
    state="I was charged twice. Please fix this ASAP.",
    questions={
        "billing": Noul(instructions="Is this ticket about billing?"),
        "tone": Choice(
            instructions="What is the customer's tone?",
            criteria={"calm": None, "frustrated": None, "angry": None},
        ),
        "urgency": Score(
            instructions="How urgent is this ticket?",
            criteria=["can wait", "this week", "today"],
        ),
    },
)

print(result.nouls["billing"].noul)
print(result.choices["tone"].choice)
print(result.scores["urgency"].score)
print(result.elapsed_ms, result.request_id, result.usage)
print(client.models.list())  # GET /v1/models

Async is the same surface with await:

from jev_lite import AsyncTypeSafe, Noul

async with AsyncTypeSafe() as client:
    result = await client.system_one.create(
        state="I was charged twice. Please fix this ASAP.",
        questions={"billing": Noul(instructions="Is this ticket about billing?")},
    )
    models = await client.models.list()

Pin the model with TypeSafe(model="jev-1.13.0") (or TYPESAFE_DEFAULT_MODEL); jev-latest moves. Prefer one system_one.create with many questions over a loop of calls.

System entities (preview)

jev_lite.system_entities extracts the 59 Dialogflow ES system entities (@sys.date-time, @sys.unit-currency, @sys.geo-city, …) and fills typed slots, in ten languages (en and zh-Hant primary). Code proposes candidates, Jev jev-1.13.0 decides, code normalizes. Preview: the API may change within 0.0.x. Same install; no extra dependency.

from datetime import datetime
from zoneinfo import ZoneInfo

from jev_lite import TypeSafe
from jev_lite.system_entities import extract

now = datetime(2026, 10, 1, 16, 0, tzinfo=ZoneInfo("Asia/Taipei"))
with TypeSafe() as client:
    result = extract(client, "Book a table for 4 next Friday at 7pm", ["date-time", "number"], now=now)
for match in result.matches:
    print(match.entity, match.span.text, match.value)  # number 4 …; date-time … 2026-10-09 19:00

Slot filling, async and the value models: API. Read the known limitations first: extraction is not a security boundary. On the held-out set system-entities-cases@v0.0.1 (301 cases, ten languages) it is 99.3% exact on accepted values (release gates).

Tracing

Off by default. Opt in and pick the destination:

from jev_lite import instrument

instrument(endpoint="http://127.0.0.1:4318")  # local Grafana LGTM

Or set OTEL_EXPORTER_OTLP_ENDPOINT and call instrument(), or install your own TracerProvider first (Logfire, etc.). Spans record prompt, result, and latency.

Develop

uv sync --dev
uv run ruff check . && uv run pytest

The supported public API is the TypeSafe client. Optional local engines live under jev_lite.engine (pip install 'jev-lite[ml]'). See docs/.

Semantic decisions v0.0.2

Dataset semantic-decisions@v0.0.2, versioned separately from the package (versions).

252 frozen zh-Hant rows in 18 families (36 easy, 48 medium, 168 hard), gold derived from visible text. This natural zh-Hant v1 qualified freeze is v0.0.2, and it is the only semantic-decision eval in this repo. Every model answers the same 504 locked requests: each row in canonical and left-rotated option order. Charts are percent correct. The families were seen during development before the freeze, so this is not unseen confirmation.

Easy and medium are regression and "insufficient information" controls. Hard carries the difference: a priority reversal counts only if both ends of a same-case pair are right in both orders. Always answering B already scores 194/336 on hard. All 6,552 calls are valid, with no errors. Adapters differ, so these are task-level scores, not weight comparisons. Details and disclosures.

Earlier banks (semantic-decisions@v0.0.1, the controlled slices, r2) are retired. v0.0.1 survives only at package tag v0.0.1, and none of their scores is pooled with v0.0.2. No model redistribution is authorized.

License

Apache-2.0