Python API

Everything from jul import … exposes, with every argument. The names, fields and shapes of the first two sections are Jev's SDK's: code written for typesafe_sdk runs unchanged. The others are what JuL adds.

from jul import (TypeSafeClient, AsyncTypeSafeClient,            # the client
                 Choice, Noul, NoulCriteria, Score,              # questions
                 SystemOneResponse, ChoiceAnswer, NoulAnswer, ScoreAnswer, Usage,   # answers
                 Context, TuningReport,                          # adapting to your data
                 Escalation, EscalatedResponse, SystemOneHTTP,   # the hub: other deciders
                 Bundle, pack,                                   # deploying a fixed need
                 Preset, PRESETS, __version__)

TypeSafeClient

TypeSafeClient(model=None, context=None, method=None, one_word_only=False, backend=None,
               context_home=None, api_key=None, base_url=None, timeout=None, max_retries=None,
               on_long=None, **ignored)

Constructing a client loads nothing and needs no backend installed. The model loads on the first call and stays in memory; only one model is held at a time (asking another one drops the first).

system_one

Raises ValueError for an empty questions, an unknown model= passed to the call (the constructor raises it for its own) or a Score with fewer than two levels, jul.truncation.InputTooLong (a ValueError) for a state over a reading's limit with on_long="error", TypeError for a question that is not one of the three types.

AsyncTypeSafeClient

The same constructor and members, awaitable: await client.system_one(...), await client.autotune(...), await client.close(), async with AsyncTypeSafeClient() as client:. The work runs in a worker thread, so the event loop keeps turning.

Questions

Choice

Choice(instructions="", criteria={})

Pick one option. criteria is {key: description}, or a plain list of keys (then the key is also what the model reads). At least one option. See Writing good questions.

Noul

Noul(instructions="", criteria=None)

Yes or no. criteria is optional: NoulCriteria(true=…, false=…), or a dict with true/false (or yes/no) keys. Without it, yes and no read as "Yes." and "No.".

Score

Score(instructions="", criteria=[])

A level on a scale. criteria lists the level descriptions, lowest first, at least two.

Answers

SystemOneResponse

ChoiceAnswer, NoulAnswer, ScoreAnswer

Probabilities are rounded to 4 decimals. Each answer has as_dict(), which adds "type".

Usage

input_tokens (tokens fed to the model for this call), output_tokens (always 0: nothing is generated), total_tokens, and truncated_tokens: the largest cut of the call, the tokens a reading dropped to fit its limit (0 when everything was read; each cut is also logged on the jul.truncation logger, see input limits). With --backend api, the counts are characters.

Context

Context(description="", examples=[], labeled=[], name=None, use_description=False)

Anywhere a context is expected, its saved name works too: client.system_one(state, q, context="tickets"). See Adapting to your data.

autotune

reports = client.autotune(context, questions, labeled, model=None, save=True,
                          features="vector", formulations=None)

Returns {name: TuningReport}. A head is activated only if it beats zero-shot in cross-validation; otherwise only a calibration is kept. Then client.system_one(..., context=...) uses it with no other change. Not available on decision models (pointer reading). See autotune.

TuningReport

question, n_examples, n_evaluated, n_options, zero_shot_accuracy, head_accuracy (None if no head was trained), activated, reason, temperature, features. print(report) gives the summary, as_dict() the fields.

Escalation

Escalation(tiers, min_confidence=0.8, default=0.8)

Several deciders in order. The first answers every question; a question answered below the bar goes to the next tier, with the other unsure ones only, and so on.

How sure an answer is: confidence for a Choice or a Score, max(noul, 1 − noul) for a Noul. The answer kept is the last tier's that answered, even if less sure (two models' confidences do not compare). A tier that fails (network, HTTP error) is skipped and its error recorded; a malformed request (ValueError, TypeError) is raised, never sent on. system_one returns an EscalatedResponse: a SystemOneResponse plus escalation, per question:

{"tried": ["local", "jev"], "tier": "jev", "confidence": 0.91, "met_bar": True}

SystemOneHTTP

SystemOneHTTP(base_url, model="jev-latest", api_key=None, timeout=30.0, exact_url=False)

A decider over HTTP: any server speaking POST /v1/systemone (Jev at https://api.typesafe.ai, Ollama's Nimble at http://localhost:11434, Kev, another jul serve). base_url is the server root, with or without /v1. Redirects are never followed, so a key never reaches another host. Raises jul.escalate.RemoteError on any failure. jul.escalate.remote_tier("typesafe" | "ollama:nimble" | "cloudflare:clef-flash" | URL) and jul.escalate.cloudflare_tier() build one with the provider's usual key variable.

Bundle and pack

pack(client, questions, out, context=None, model=None, reading="auto") -> Path
Bundle.load(path, backend=None, model=None, cross_model=None) -> Bundle

pack computes everything that does not depend on the state (prompts, option vectors, centers, heads) into a directory. Bundle answers with the state as its only input:

reading="vector" packs every question on the vectors (one model to ship). Bundle.load(model=...) points to the weights if they moved. Vector presets only. See Deploying a fixed need.

Presets

PRESETS is the dict of built-in presets (jul-decision-wemm-4b, wemm-4b-4bit, minicpm5-2b), each a Preset with its name, repos per backend, formulations, tau, center, latency_ms, quality. Presets you add live in ~/.jul/presets/<name>@<backend>.json; jul models lists them all. jul.presets.resolve(name, backend) returns the one a client would use.

Errors you may catch