jev python sdk

Install and Pin the Package Deliberately

The official repository uses the distribution name typesafe-sdk and import namespace typesafe_sdk. Commit a lockfile and record the package version in deployment metadata. The SDK version and Jev model version are different: upgrading the client can change transport behavior while changing jev-1.13.0 changes model behavior.

Set TYPESAFE_API_KEY through a secret manager or process environment. Do not place it in source, fixtures, notebook output or client-side applications. Provider gateways have separate SDKs and credentials; this page covers TypeSafe’s direct client only.

uv add typesafe-sdk
# or record an approved exact version in your lockfile

One State, Several Independent Typed Questions

The three questions share state but are independent. queue does not see the result of refund_requested. If a later question depends on the selected queue, issue another call and represent the dependency explicitly. The multiple-question guide covers batching and observability.

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

questions = {
    "queue": Choice(
        instructions="Which approved team should handle this ticket?",
        criteria={
            "billing": "Charges, invoices, refunds or payment methods",
            "technical": "Product errors or integrations",
            "other": "Neither billing nor technical",
        },
    ),
    "refund_requested": Noul(
        instructions="Does the customer explicitly ask to reverse a charge?"
    ),
    "urgency": Score(
        instructions="How urgent is this ticket?",
        criteria=[
            "Routine: no deadline or blocked work",
            "Time-sensitive: a deadline or degraded workflow",
            "Critical: a current essential workflow is blocked",
        ],
    ),
}

with TypeSafeClient() as client:
    response = client.system_one(
        state={"message": "Charged twice; this blocks payroll."},
        questions=questions,
        model="jev-1.13.0",
    )

Read by Answer Type and Retain Provenance

The official quickstart accesses Choice results through response.choices; verify the exact fields against the installed SDK release. Store resolved model and usage with question/state versions. Never reconstruct a distribution later from only the selected queue or weighted score.

Noul has no separate confidence field. Its noul value is the modeled yes probability. Choice and Score confidence summarize distribution concentration, not correctness or permission. See confidence versus probability.

queue = response.choices["queue"]
refund = response.nouls["refund_requested"]
urgency = response.scores["urgency"]

record = {
    "resolved_model": response.model,
    "usage": response.usage,
    "queue": {
        "choice": queue.choice,
        "probabilities": queue.probabilities,
        "confidence": queue.confidence,
    },
    "refund_probability": refund.noul,
    "urgency": {
        "score": urgency.score,
        "probabilities": urgency.probabilities,
        "confidence": urgency.confidence,
    },
}

Own Client Lifecycle and Concurrency

The official README demonstrates the synchronous client as a context manager, which closes transport resources deterministically. In a long-running service, create the supported long-lived client at process or dependency-injection scope rather than constructing one per item, and close it during shutdown. In a short script, use with.

TypeSafe also documents synchronous and asynchronous Python clients; choose one end to end instead of calling a blocking client inside an async event loop. Bound application concurrency below account limits and downstream capacity. A large task fan-out needs backpressure even if individual calls are fast.

Classify Failures Before Deciding to Retry

Inspect the installed SDK’s documented exception hierarchy and defaults before catching broad Exception. Preserve request IDs and sanitized error metadata. A runtime policy may need fail-closed behavior while an offline evaluator can queue delayed retry; the correct response follows consequence, not the SDK.

Use Separate Contract, Fixture and Live Tests

Mocking proves application branches, not Jev quality. Live smoke tests prove API compatibility, not calibration. The full release gate needs both plus held-out outcome evaluation from Jev calibration.

1. Unit-test state projection and question construction without a network call.
2. Use sanitized captured responses to test parsing, storage and threshold behavior.
3. Run a small credentialed contract test against a pinned model outside pull requests when secrets are unavailable.
4. Replay a labeled evaluation suite for semantic changes; do not assert an exact float from a probabilistic service in ordinary unit tests.
5. Inject timeouts, 429s, malformed payloads and fallback failures.

Production Checklist

• Pin SDK and Jev model versions; log the resolved model.
• Keep the key server-side and redact request state from unsafe logs.
• Set timeout, bounded retries, concurrency and a consequence-specific fallback.
• Persist full typed answers, usage, question/state versions and outcomes.
• Re-evaluate after changing model, SDK, question, state projection or provider.