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 added Dialogflow-style system entities; jev-lite@0.0.3 adds a privacy filter and a reranker (all three are previews, below); jev-lite@0.0.4 adds images and Box answers for Jev 1.14.

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. jev-1.14.0 matches 1.13 on the modules below but scores lower on hard semantic decisions, so the modules stay on 1.13; TypeSafe will retire 1.13 with 60 days' notice, and the pins move then (1.14 vs 1.13).

Re-running unchanged questions can replay answers from disk (pip install "jev-lite[cache]"):

client = TypeSafe(cache="~/.cache/jev")  # or a configured diskcache.Cache

Only 200 responses are stored, keyed on the request body (which carries the model id). Leave the cache off when you measure repeat or order stability.

Images and Box (Jev 1.14, experimental)

Put an Image anywhere a value can go: in state, instructions or criteria. The client uploads it as an asset and adds the TypeSafe-Danger-Zone-Images header. A Box answer is where a target is, as edges in fractions of the image; it needs jev-1.14.0.

from pathlib import Path
from jev_lite import Box, Image, Noul, TypeSafe

with TypeSafe(model="jev-1.14.0") as client:
    result = client.system_one.create(
        state={"photo": Image(Path("kitchen.jpg"))},  # PNG/JPEG, sides 280-1568 px
        questions={
            "has_mug": Noul(instructions="Is there a coffee mug in `photo`?"),
            "mug": Box(instructions="the coffee mug in `photo`"),
        },
    )

mug = result.boxes["mug"]
print(mug.box.left, mug.box.top, mug.box.right, mug.box.bottom, mug.confidence)

A Box always returns a box, so gate it on the Noul. An image costs about 2·⌈w/28⌉·⌈h/28⌉ input tokens. Measured limits (targets under ~40 px, counting past five, text under 7 px) and usage rules: docs/system-one/use/images.md; the benchmark is image-questions@v0.0.1.

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; a same-day rerun gave 98.9% on jev-1.13.0 and 99.3% on jev-1.14.0 (release gates).

Privacy filter and reranker (preview)

jev_lite.privacy_filter and jev_lite.reranker ship in jev-lite@0.0.3 as previews: the APIs may change within 0.0.x. Import them as modules (from jev_lite.privacy_filter import detect, from jev_lite.reranker import rerank). All numbers pin jev-1.13.0.

Privacy filter: private-span detection. Public multilingual gold (ai4privacy OpenPII, Gretel finance, NVIDIA Nemotron-PII), 300 test texts, exact-span precision / recall:

The default uses per-label proposers and cuts fitted on dev, and finds people with system_entities person spans plus a person detect Noul (person recall 43.9 → 71.9), with an order-stable name boundary. On overlap it scores 88.9 / 77.6; exact address recall is 0 because the gold splits an address into components while the filter masks the whole address. It fails most written robustness bars, so it is a preview. Hosted Jev sees the raw text before masking. Details: docs/privacy-filter/.

Reranker: batched evidence Noul over a first-stage pool (balanced batches of at most 30, independent of the caller's order), nDCG@10:

A batch score is relative to the other passages in its request, not a standalone probability. A passage that echoes the relevance criteria can be lifted into the top 10; rerank(..., check_echo=True) (off by default) re-checks the top-k and moves such passages down, at about +0.23 s. Details: docs/reranker/.

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 13,608 first attempts (27 models × 504) are valid, with no errors. Adapters differ, so these are task-level scores, not weight comparisons. Jev jev-1.14.0 scores 20 fewer than jev-1.13.0, all on hard (293 vs 313; a repeat gave 462 in all), so keep jev-1.13.0 pinned for text decisions. 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