The one request
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer $TYPESAFE_API_KEY
Content-Type: application/json
{ "state": "<text, or a JSON object/array>",
"model": "jev-1.13.0",
"questions": {
"id": { "type": "choice", "instructions": "...", "criteria": { "opt": "description or null" } },
"id": { "type": "score", "instructions": "...", "criteria": [ "level 0", "level 1", "level 2" ] },
"id": { "type": "noul", "instructions": "..." } } }
- Response
model, answers{id: …}, usage{input_tokens, output_tokens}. Questions are evaluated independently and in parallel; they never see each other.- Choice answer
choice, probabilities{opt: p} (sum 1), confidence 0..1. Up to 255 options.- Score answer
score (expected level index, float), legend, probabilities[], confidence. 2 to 32 levels, ordered.- Noul answer
noul 0..1, probability the statement holds. No confidence field; use distance from 0.5.- Object state
- Reference fields with backtick paths in instructions:
`ticket.customer.plan`. Trim state to what the questions need.
- Errors
- 401 key · 422 malformed (message names the field) · 429 rate limit · 529 overloaded. Retry 429 and 529 with backoff.
Pick the primitive
- Choice
- One of N situations. Always include an escape option:
unclear, other, none.Options that are not plain from the name get a description. Structured criteria: {what, not_for, examples}.
- Score
- Degree along one ordered ladder. Describe each level as a situation, never as a number.Read: confidence first, then the two largest probabilities. Normalise for composites:
score / (levels - 1).
- Noul
- One statement, phrased positively, about the text. Never compound ("angry AND wants refund"), never negated.
noul(A) + noul(not A) ≠ 1. Ask each fact once.
Seven steps to a question that works
- 1 Situation
- Ask what kind of thing this is, not how good it is.
- 2 Split
- One fact per question. Compound questions fan out into several.
- 3 Escape hatch
- Add the option that the honest answer needs (benchmark call 028 had none).
- 4 Criteria
- Describe options in the words the text will use. Spell out implied cases; Jev reads literally.
- 5 Agree
- Instruction and criteria must say one thing. Contradictions make answers unpredictable.
- 6 Trim state
- Irrelevant state lowers accuracy (context rot). Cut it in code or point at a path.
- 7 Run five
- Test on five real inputs in the Playground before wiring anything.
Confidence routing
if choice == "unclear" or confidence < FLOOR: -> human (docs' starting point: FLOOR 0.5)
elif choice in RISKY and confidence < HIGH: -> confirm (docs' starting point: HIGH 0.85 to 0.9)
else: -> act
Noul: yes above ~0.7 to 0.8, no below ~0.2 to 0.3, review in between.
Score: act on the level only when confidence is high; otherwise treat it as a split.
Composite: gate on the weakest input.
- Confidence is
- A statistic of how peaked the distribution is. 0.50 / 0.48 / 0.02 gives about 0.26. Four options led by 0.37 gives 0.16.
- Confidence is not
- A guarantee (0.93 was wrong once in 40 benchmark calls) or a measure of question quality.
- Thresholds come from
- A shadow run: accuracy per confidence band on your own labelled data. Keep them in one versioned file with the questions.
Patterns
- Speculative fan-out
- Ask every question code might need in one request; output is free and questions run in parallel. Second request only when the first answer changes the state or the options.
- Intent routing
- Choice picks the kind of request; each kind has its own handler: code, a narrow specialist LLM, or a human.
- Composite scoring
- Several concrete answers combined in code with weights you can defend. Weights are policy, kept in config.
- Guardrails
- Nouls or a Choice in front of an LLM agent: in scope, override attempt, unsupported language. Ask about the text, not to it.
- Navigation (Wikirace)
- Choice over up to 255 options, one hop per call, code owns the loop. Same shape for taxonomies and article picking.
Jaggedness of jev-1.13 (do this instead)
- Counting, math, formats
- Count and compare in code; one Noul per item if needed.
- Date comparison
- Extract the parts with Choices, compare in code.
- Literal reading
- Spell implied cases out in criteria and examples.
- Indirection
- Restructure state so the referent is explicit.
- Large irrelevant state
- Trim; use paths.
- Adversarial content
- Phrase questions about the text; add a Noul for "contains instructions aimed at an AI".
- No invariants
- Never derive one answer from another.
- No generation
- Pair with an LLM for words; Jev decides whether and which.
Numbers worth remembering
- Price
- $0.042 per million input tokens, output free. A five-question call-transcript request: about 550 tokens, about $0.000025.
- Limits
- 250,000 tokens/s · 1,200 requests/min · 64k context (32k state + longest question). Documented as dynamic.
- Latency
- About 100 ms model time; 72 to 167 ms recorded; 319 ms median end to end in the community benchmark.
- Versions
jev-latest = jev-preview = jev-1.13.0 today. Pin the version in production; GET /v1/models lists them.- Data
- No training on customer data, DPA available, zero retention on enterprise. Text only.
SDK one-liners
# Python: pip install typesafe-sdk (env: TYPESAFE_API_KEY, TYPESAFE_DEFAULT_MODEL)
from typesafe_sdk import TypeSafeClient, Choice, Score, Noul
r = TypeSafeClient().system_one(state=text, questions={"k": Choice("...", {"a": "...", "other": None})})
r.answers["k"].choice, r.answers["k"].confidence
// JavaScript: npm install @typesafe-ai/sdk
import { TypeSafeClient, choice, score, noul } from "@typesafe-ai/sdk";
const r = await new TypeSafeClient().systemOne({ state, questions: { k: choice("...", { a: "...", other: null }) } });
# n8n: HTTP Request node, POST, Header Auth "Authorization: Bearer …", JSON body from the Playground,
# then IF on {{$json.answers.k.confidence}} and {{$json.answers.k.choice}}.
# Agent skill: claude plugin marketplace add typesafe-ai/skills ; claude plugin install typesafe@typesafe-ai
# Docs as Markdown: append .md to any docs.typesafe.ai URL.
Sources
- Docs
- docs.typesafe.ai: Primitives, Confidence, Patterns, Models, API, SDKs, Model jaggedness (jev-1.13).
- Playground
- console.typesafe.ai/decode. Every exercise in the course opens there via a deep link.
- Community benchmark
- Flow Dynamics AI brief, 2026-09-17: 40 German calls, 39 correct, call 028 wrong at 0.93.
- Community
- TypeSafe Discord.