/typesafe-ai

name: typesafe-ai
description: Build AI-powered software with TypeSafe System One models, including Jev, as typed judgments and probabilities for routing, ranking, extraction, verification, and other structured decisions. Use when integrating TypeSafe or replacing a semantic LLM prompt-and-parse step with a programmable decision primitive.

Build with TypeSafe

This guide is bundled from [TypeSafe AI's official skill](https://github.com/typesafe-ai/skills/tree/main/skills/typesafe-ai) under its MIT license. The [live TypeSafe docs](https://docs.typesafe.ai/llms.txt) are the source of truth for current concepts, prompting guidance, API contracts, SDK usage, models, limits, and examples.

TypeSafe makes units of AI intelligence usable like programming primitives: small judgments you can compose into larger capabilities. Its **System One models** return fast, focused judgments that software can consume directly. **Jev** is TypeSafe's flagship and first System One model. It understands natural language and returns typed answers and probabilities rather than generating text or reasoning explanations. Code owns the workflow; the model supplies programmable common sense where ordinary code needs semantic understanding.

Read the live docs

• Start with the [documentation index](https://docs.typesafe.ai/llms.txt) and read only relevant pages.
• Mintlify serves Markdown by appending `.md` to a page path. Follow links from the index and resolve relative links against `https://docs.typesafe.ai`.
• Before writing an integration, read the current API or chosen SDK page and the question guidance relevant to the design. For a new workflow, inspect the closest cookbook.
• If live access is unavailable, use available local docs or installed SDK types, state the limitation, and avoid inventing version-dependent details.

| Task | Start here | | --- | --- | | Understand the programming model | [System One](https://docs.typesafe.ai/concepts/system-one.md), [building guide](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md) | | Explore what to build | [Use-case map](https://docs.typesafe.ai/concepts/use-case-map.md), then relevant cookbooks | | Prepare inputs and questions | [State](https://docs.typesafe.ai/concepts/state.md), [primitives](https://docs.typesafe.ai/primitives.md) | | Decide how to handle uncertainty | [Confidence](https://docs.typesafe.ai/confidence.md) | | Write API code | [HTTP API](https://docs.typesafe.ai/api.md), [Python SDK](https://docs.typesafe.ai/sdk/python.md), or [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript.md) | | Update an older integration | [Migration guide](https://docs.typesafe.ai/migrating-to-v1.md) and the installed SDK's current reference |

Find the useful shape

Start from the behavior the user wants: what will the application show, select, change, or hand off? Work backward to the judgments it needs. Keep known rules, calculations, exact lookups, and execution in code. Preserve the user's chosen stack and scope; add TypeSafe where semantic understanding helps.

Useful patterns include:

• **Route and fill known arguments.** Select a handler and typed parameters from a candidate set; ask useful branch-specific questions up front. Explore [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md) and [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out.md).
• **Select instead of generate.** Let code build candidate values or source spans, use a judgment to select the intended one, then copy or normalize it. Explore [value extraction](https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook.md) and [structure recovery](https://docs.typesafe.ai/cookbooks/autoformat.md).
• **Find and judge evidence.** Retrieve candidates, compare their relevance, and select useful context. Explore [reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md) and [hierarchical classification](https://docs.typesafe.ai/cookbooks/hierarchical_classification.md).
• **Turn judgments into reusable data.** Score dimensions once, then let code change weights, thresholds, rankings, and views. Explore [composite scoring](https://docs.typesafe.ai/patterns/composite-scoring.md) and [feature discovery](https://docs.typesafe.ai/cookbooks/autoresearch_feature_discovery.md).
• **Verify and escalate.** Check claims or fields against evidence; send uncertain or failing cases to a person or reasoning model. Explore [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md) and [extraction cascades](https://docs.typesafe.ai/cookbooks/sde_cascade.md).
• **Respond to changing state.** Keep inferred state distinct from observed facts and check freshness before applying a result to changed state.

Design the judgments

Choose by what the answer means, then read the relevant primitive page:

| Need | Primitive | Important distinction | | --- | --- | --- | | One of a defined set | [Choice](https://docs.typesafe.ai/primitives/choice.md) | Picks one option; its distribution compares competing options | | Whether a condition holds | [Noul](https://docs.typesafe.ai/primitives/noul.md) | Probability of yes; no separate confidence; use one per label when several may apply | | Degree along a described dimension | [Score](https://docs.typesafe.ai/primitives/score.md) | Probability-weighted position on ordered levels; use comparable per-item Scores for graded ranking |

Give each question enough relevant **state**: source text, identities, relationships, policies, and current facts. Prefer named JSON fields when context has several parts. Put the judgment in instructions and define possible answers in criteria. Question IDs are for code and are not sent to the model; include complete meaning in the question. Reference nested state with backticked paths such as `ticket.messages[0].text`.

Ask one narrow, coherent judgment per question. Split independently useful dimensions without destroying the relationship being judged.