--- title: "FAQ for agents and developers" type: synthesis tags: [faq, questions, onboarding, claims, troubleshooting] created: 2026-09-17 updated: 2026-09-17 confidence: high sources: - wiki/concepts/system-one.md - wiki/concepts/primitives.md - wiki/concepts/confidence.md - wiki/concepts/jaggedness-jev-1-13.md - wiki/concepts/machine-learning-primer.md - wiki/concepts/workflow-evals.md - wiki/concepts/state.md - wiki/reference/http-api.md - wiki/reference/models-and-pricing.md - wiki/reference/rate-limits-and-errors.md - wiki/reference/migrating-to-v1.md - wiki/reference/python-sdk.md - wiki/reference/python-sdk-changelog.md - wiki/reference/python-sdk-responses.md - wiki/reference/javascript-sdk.md - wiki/reference/javascript-sdk-changelog.md - wiki/reference/environment-variables.md - wiki/reference/agent-skill.md - wiki/reference/system-one-adapter.md - wiki/reference/legal-and-data.md - wiki/entities/typesafe-ai.md - wiki/entities/jev.md - wiki/entities/blog-introducing-system-one.md - wiki/entities/press-and-coverage.md - wiki/cookbooks/parallel-questions.md - wiki/cookbooks/consistency-choice.md - wiki/cookbooks/consistency-noul.md - raw/site/typesafe-ai-home.txt - raw/site/blog-introducing-system-one.txt - raw/docs/models.md - raw/docs/api.md - raw/docs/cookbooks__consistency_choice_cookbook.md - raw/docs/cookbooks__parallel_questions.md jev_version: "jev-1.13.0" sdk_python: "0.6.0" sdk_js: "0.6.0" summary: "Forty answers about Jev — what it is, the API, the SDKs, design, confidence, limits and pricing, company and legal — each linked to the page carrying the detail." --- # FAQ for agents and developers > **TL;DR** Short answers, each with a link to the page that carries the contract. If you read only three: Jev takes one `state` plus a map of typed `questions` and returns typed answers with probabilities ([[reference/http-api]]); it can be wrong but cannot return a value outside your schema ([[concepts/jaggedness-jev-1-13]]); and you compose answers in your own code rather than prompting your way to a decision ([[concepts/how-to-build]]). Seven questions below are the ones listed on TypeSafe's homepage. Only the first homepage answer exists in the capture (`raw/site/typesafe-ai-home.txt`) — the rest are collapsed accordions. Those questions are marked **(homepage FAQ — answer not captured)** and are answered here from the documentation, the launch post, and TypeSafe's own cookbooks instead. ## What is it **1. What is Jev?** Jev is TypeSafe AI's first and flagship System One model: text in, typed decisions with calibrated probabilities out, no generated text. Current version `jev-1.13.0`, reached through the aliases `jev-latest` and `jev-preview`. See [[entities/jev]]. **2. What is a System One model, and where do the names come from?** A class of model that evaluates one `state` and returns typed answers plus probabilities software can branch on directly, trained with RLCD (Reinforcement Learning for Calibrated Decisions) rather than RLHF or RLVR. "System One" is from Kahneman's fast/slow distinction; "Jev" is after William Stanley Jevons, because TypeSafe expects each order-of-magnitude drop in the cost of intelligence to unlock orders of magnitude more use cases. See [[concepts/system-one]]. **3. Is Jev just a smaller LLM?** *(homepage FAQ — answer not captured; the same heading appears unanswered in the launch post's FAQ)* No source states a parameter count, so the size question cannot be answered from the sources. What they claim is a different stack rather than a smaller one: a new architecture, a **parallel sampler** that emits all outputs in one query instead of token by token, an output space constrained to your `criteria`, and RLCD post-training. See [[concepts/system-one]] and [[concepts/machine-learning-primer]]. **4. How is this different from JSON mode or structured outputs?** *(homepage FAQ — answer not captured)* JSON mode constrains an LLM's *text* to a shape; Jev never generates text, so the answer space is the schema and every answer arrives with a probability distribution over it. The long-form comparison, including how to use both together, is [[syntheses/jev-vs-llm-structured-outputs]]. **5. What is Jev good at? Where does it struggle?** *(homepage FAQ — answer not captured)* Good at narrow snap judgments with a known answer space: classification, routing, scoring, detection, verification, guardrails, ranking, feature extraction ([[concepts/use-case-map]]). Struggles with literal misreadings of your instruction, arithmetic and counting, date ordering, indirection, large irrelevant states, adversarial text, criteria that contradict the instruction, structural invariants across questions, and anything generative — the nine documented failure modes in [[concepts/jaggedness-jev-1-13]]. **6. Who builds it, and can I sign up?** TypeSafe AI, Inc., a San Francisco lab founded in 2024, which left stealth on 2026-09-15 with approximately $40M in seed funding led by DCVC. Jev is in waitlisted early access as of 2026-09-17; keys come from the console once you have access. See [[entities/typesafe-ai]] and [[entities/typesafe-console]]. ## API and models **7. What is the endpoint, and how do I authenticate?** `POST https://api.typesafe.ai/v1/systemone` with `Authorization: Bearer ` and `Content-Type: application/json`; a missing or invalid key returns `401`. Keys come from `https://console.typesafe.ai/settings/keys`. See [[reference/http-api]]. **8. What do I put in `model`, and how do I see what is available?** `"jev-latest"` in most code — it is the SDK default and currently resolves to `jev-1.13.0`. `GET /v1/models` returns `{models: [{name, description, release_date}]}`, currently listing the aliases; versioned IDs are accepted whether or not they appear. Pin the versioned ID if you have tuned thresholds, because aliases move silently. See [[reference/models-and-pricing]]. **9. What comes back?** `{model, answers, usage}`, where `answers` is keyed by the question ids you chose, each answer carries the same `type` as its question, and `usage` reports `input_tokens` / `output_tokens`. Log the response's `model` field — it tells you which version actually answered. See [[reference/http-api]]. **10. How many questions can I send in one request?** As many as the token budget allows; no count limit is documented. Batching is the intended usage — [[cookbooks/parallel-questions]] measured 13 questions in one call at **12.2x cheaper and 10.0x faster** than 13 single-question calls, with no change in the answers. **11. What are the input limits?** 64k tokens per request for `state` plus all questions, and 32k tokens for `state` plus the single longest question — `state` counts against both. Input is text only: a string, a JSON object, or an array of text values, so pre-process images, audio, and PDFs into text first. See [[concepts/state]]. **12. What happened to `/preview/evaluation`?** It was replaced outright by `/v1/systemone`: `document` → `state`, `prompts[]` → a `questions` map, `options`/`levels` → a unified `criteria`, `responses[]` → an `answers` map, and the answer value fields were renamed. v1 now rejects `document` entirely, and `confidence` uses a different computation, so re-tune thresholds. See [[reference/migrating-to-v1]]. ## SDKs **13. Which SDKs exist, and how do I read an answer?** Python `typesafe-sdk` (`pip install typesafe-sdk`, import `typesafe_sdk`, Python ≥ 3.10, with `AsyncTypeSafeClient` for async) and JavaScript/TypeScript `@typesafe-ai/sdk` (`npm install @typesafe-ai/sdk`, Node ≥ 20, promise-based throughout). In Python read `response.answers["my_id"]`, or the typed views `response.nouls` / `.choices` / `.scores`. See [[reference/python-sdk]], [[reference/javascript-sdk]], [[reference/python-sdk-responses]]. **14. What version should I write against, and what broke?** 0.6.0 in both SDKs. The one breaking change is that `Score.criteria` is now an **ordered sequence** of level descriptions rather than a dictionary keyed by integers; the answer side (`legend`, `probabilities`) is unchanged. See [[reference/python-sdk-changelog]] and [[reference/javascript-sdk-changelog]]. **15. Which environment variables do the SDKs read?** Exactly four, in both SDKs: `TYPESAFE_API_KEY`, `TYPESAFE_BASE_URL`, `TYPESAFE_DEFAULT_MODEL`, `TYPESAFE_LOG_LEVEL`. Names like `TYPESAFE_MODEL` and `TYPESAFE_PRICE` appear in cookbook code but are **not** SDK variables. See [[reference/environment-variables]]. **16. Is there something that teaches a coding agent to use Jev?** Yes — the `typesafe-ai` agent skill, shipped as the Claude Code plugin `typesafe` (`claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`) or via `npx skills add typesafe-ai/skills --skill typesafe-ai`. See [[reference/agent-skill]] and [[guides/agent-integration-playbook]]. **17. Can I run the same code against an LLM to compare?** Yes — `system-one-adapter` is a drop-in `TypeSafeClient` replacement backed by OpenAI or Anthropic that returns the same `typesafe_sdk` answer objects plus latency, token, and per-attempt traces. See [[reference/system-one-adapter]]. ## Design and prompting **18. Choice, Score, or Noul?** Unordered set of options → `choice`; an ordered spectrum whose levels you can describe → `score`; a single yes/no where the probability is the signal → `noul`. If none fits cleanly, the judgment is too big — split it and combine in code. See [[guides/choosing-a-primitive]]. **19. How should I phrase `instructions` and `criteria`?** Write the exact condition, put boundary cases in the criteria, keep `true` meaning yes, and name the part of the state you mean with a backticked path such as `` `ticket.messages[0].text` ``. When a wrong answer makes you say "but I meant…", that sentence is the missing half of the instruction. See [[guides/writing-instructions-and-criteria]]. **20. Should I ask questions separately or together?** Together. Questions in one request share the state, run in parallel and in isolation, and adding one barely changes latency — so ask the speculative ones too and let code discard what it does not need. See [[patterns/fan-out]]. **21. Can one question use another question's answer?** Not within a request — answers are independent and never become context for each other. Make a second request only when your code genuinely cannot build it until it has the first answer: to fetch more evidence, construct new state, or choose the next options. See [[concepts/primitives]]. **22. What has to stay in my code?** Arithmetic, counting, date comparison, and anything generative. Extract date *parts* as Choices over enumerated options and assemble the date yourself; count by asking one question per item and summing; for bounded extraction, make the candidate values the `criteria` so Jev selects a verbatim span instead of writing one. See [[concepts/jaggedness-jev-1-13]], [[cookbooks/date-extraction]], [[cookbooks/pre-parsed-value-extraction]]. **23. What if none of my options is right?** Choice probabilities always sum to 1, so some option always wins — add an explicit `other` / `none` option, or a separate presence `Noul`, whenever your list might not cover the input. See [[concepts/choice]] and [[cookbooks/semantic-find]]. ## Confidence and probabilities **24. What is the difference between `probabilities` and `confidence`?** `probabilities` is the full distribution over your options or levels; `confidence` is a single 0–1 statistic summarising how concentrated that distribution is. TypeSafe does not publish the formula, so compute your own (entropy, top-two margin) from `probabilities` if you need a specific measure. See [[concepts/confidence]]. **25. Do Noul answers have a `confidence`?** No. For a yes/no question the probability *is* the uncertainty — `noul` near 0.5 is the uncertain case — and reading `.confidence` off a Noul answer is a bug. See [[concepts/noul]]. **26. What threshold should I use?** One the stakes justify, validated on your own data. The docs' own examples span `0.5` (floor before doing anything at all), `0.75`–`0.8` (route a Choice to human review), and `0.9` (before a destructive action); they are illustrations, not defaults. See [[patterns/confidence-routing]]. **27. What does "calibrated" actually guarantee?** That across *many* predictions, outcomes given probability 0.8 occur about 80% of the time. It guarantees nothing about any single answer, so validate calibration in aggregate buckets, never one request at a time. See [[concepts/machine-learning-primer]]. **28. Can Jev still get things wrong?** *(homepage FAQ — answer not captured)* Yes, and the sources say so plainly: schema conformance is guaranteed, judgment is not, so Jev can return a wrong but valid answer. The MCA adds that Output "may be inaccurate or erroneous" and that the customer is responsible for independently evaluating it. See [[entities/jev]] and [[reference/legal-and-data]]. **29. Is Jev deterministic?** *(homepage FAQ — answer not captured)* No source claims bit-identical repeats, and none exposes a temperature or seed parameter. What is measured: across 15 repeats of the same rubric, mean per-answer probability standard deviation was `0.0098` (Choice) and `0.0102` (Noul), with raw top-label agreement of 90.8% rising to 99.2% once an `uncertain` band below `0.60` was added. Treat it as highly repeatable but not deterministic, and absorb the wobble with an uncertainty band — see [[cookbooks/consistency-choice]] and [[cookbooks/consistency-noul]]. ## Limits, errors, and pricing **30. What does it cost?** $42 per Btok / $0.042 per Mtok, charged on **input tokens only**; output tokens are free. Usage is metered against TypeSafe-managed Credits, whose consumption rate "may vary based on account settings, including the model used." See [[reference/models-and-pricing]]. **31. How can Jev be so fast and inexpensive?** *(homepage FAQ — answer not captured)* TypeSafe's stated mechanism is architectural: a parallel sampler emitting all outputs in a single query instead of autoregressively, a constrained output space, and no string generation — which is also why output tokens are free ("too cheap to meter"). See [[concepts/system-one]]. **32. Are these prices temporary or subsidized?** *(homepage FAQ — answer not captured)* The launch post addresses this and does not deny it: "We make our pricing transparent. We can't prove it isn't subsidized; we'll need the long-term to prove the sustainability of our pricing (which we expect to go down, not up)." See [[entities/blog-introducing-system-one]]. **33. What are the rate limits?** 250,000 tokens per second and 1,200 requests per minute; breaching either returns `429`. TypeSafe warns the limits "can change without notice," so do not treat them as a client-side budget — and note the MCA makes exceeding Usage Limits a suspension trigger. See [[reference/models-and-pricing]]. **34. Which errors should I retry, and what does a `422` mean?** Retry `408`, `429`, and every `5xx` including `529 Overloaded`, with backoff; both SDKs already do this by default (2 retries, 500 ms → 5,000 ms, 25% jitter, honouring `retry-after-ms` then `retry-after`). Do not retry `400`, `401`, `403`, `404`, or `422` — a `422` body names the offending field, most often a missing `instructions` or a Score `criteria` sent as a map instead of an ordered list. See [[reference/rate-limits-and-errors]]. **35. How fast is it in practice, and where do "193.6x faster, 444.6x cheaper" come from?** TypeSafe claims 70–500 ms end to end; its own cookbook runs report 111 ms for a 14-question Noul call and 114 ms for an 8-question Choice call, measured from laptops on the US West Coast. The multipliers come from four workflow evals comparing Jev against LLMs running the *identical* harness through TypeSafe's own wrapper, scored against labels averaged from GPT-6 Astra and Claude Fable 5.1 — figures TypeSafe itself calls "on the higher end of real world gains." See [[concepts/workflow-evals]]. **36. Is any of this independently verified?** Not in any captured source. Every performance number traces back to TypeSafe's own evals; the press write-ups re-report them with caveats and differ only in aggregation (best workflow row versus four-workflow average). See [[entities/press-and-coverage]]. ## Company and legal **37. Will my requests train the model?** The Privacy Policy and the docs say no ("Jev is not trained on customer requests or responses"); MCA §4.1 phrases it as not "without Customer's prior consent." Separately, **Telemetry** — logs, hashes, summary statistics, classifications, "learnings" — may be processed without restriction. See [[reference/legal-and-data]]. **38. How long is my data retained?** No period is stated; the MCA says TypeSafe has no obligation to retain Customer Data and may delete it at any time. Zero data retention is an enterprise option via privacy@typesafe.ai. See [[reference/legal-and-data]]. **39. Is there an uptime SLA?** No SLA, availability percentage, or service credit exists in any of the three legal documents — only a "performs materially as described in its Documentation" warranty with a correct-or-refund remedy. Design for `429` and `529` as normal, not exceptional. See [[reference/legal-and-data]]. **40. Can I publish my own benchmark of Jev, and how do I get started?** *(the second half is a homepage FAQ question — answer not captured)* MCA §2.3(f) prohibits publishing "benchmarks or performance information about the Services," which sits awkwardly beside TypeSafe's own advice to run private evals — run them, and check the contract before publishing ([[reference/legal-and-data]], [[entities/blog-antibenchmaxxing]]). To start: get a key at `https://console.typesafe.ai/settings/keys`, `export TYPESAFE_API_KEY=...`, and follow [[guides/quickstart]]; support is support@typesafe.ai, sales/limits sales@typesafe.ai, privacy/ZDR privacy@typesafe.ai, and TypeSafe invites failure-mode reports on its Discord (`https://discord.com/invite/WUujKYBp8s`). ## Related - [[syntheses/glossary]] — every term used above, defined - [[syntheses/jev-vs-llm-structured-outputs]] — the long-form answer to questions 4 and 31 - [[syntheses/version-timeline]] — every date and version in one table - [[guides/quickstart]] — the first call, end to end - [[guides/agent-integration-playbook]] — what an agent should do with all of this - [[guides/testing-and-evaluation]] — validating thresholds and calibration on your own data - [[concepts/how-to-build]] — the design workflow these answers assume - [[cookbooks/overview]] — eighteen worked recipes ## Sources - wiki pages listed in the frontmatter (all under `wiki/`) - raw/site/typesafe-ai-home.txt (https://typesafe.ai/) — the homepage FAQ headings; only the first answer is captured - raw/site/blog-introducing-system-one.txt (https://typesafe.ai/blog/introducing-system-one-models-and-jev) — pricing-subsidy and speed statements - raw/docs/models.md (https://docs.typesafe.ai/models), raw/docs/api.md (https://docs.typesafe.ai/api) - raw/docs/cookbooks__consistency_choice_cookbook.md, raw/docs/cookbooks__consistency_noul_cookbook.md — repeatability numbers - raw/docs/cookbooks__parallel_questions.md — "batching: 12.2x cheaper, 10.0x faster"