typesafe-ai · diff
git:20260912.65a39f3 to git:20261023.302eea6
260 added, 121 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: typesafe-ai
license: MIT
description: >
- Build AI-powered software with TypeSafe: small units of AI intelligence you
- can use like programming primitives. Its System One models, including Jev,
- turn natural language and application state into typed judgments and
- probabilities that code can combine. Use when a feature needs programmable
- common sense, when brainstorming what AI could make possible in an app, or
- when an LLM prompt-and-parse step could become a structured decision.
- Applications include routing, ranking, extraction, verification, and
- interactive experiences; these are starting points, not the limits.
- Read live docs and cookbooks to find useful patterns and discover new combinations.
+ TypeSafe integration craft for System One models (sometimes called Decision Models) such as Jev,
+ which answer typed questions about text, images, and application state with calibrated
+ probabilities. Use when building, reviewing, or debugging code that calls TypeSafe; when writing
+ its questions or state; when replacing an LLM prompt-and-parse step, keyword matching, or a
+ brittle heuristic with a typed question; or when brainstorming where programmable common sense
+ fits in an app.
---
# Build with TypeSafe
- 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.
+ TypeSafe's **Jev**, the first public **System One model**, answers typed questions about state your
+ application supplies. State is the text, images, and application data your code sends with a
+ request. Jev can answer a Choice among options, a Noul (the probability that a statement is true), a
+ Score on levels you describe, or a Box that locates something in an image. Each answer comes back as
+ typed data with calibrated probabilities, for your code to use.
- ## Read the live docs
+ The rest of this skill is guidance: patterns that tend to produce reliable integrations. None of it
+ is absolute. Models change, applications differ, and edge cases exist. When a situation calls for
+ something else, test the alternative and use your judgment.
- **The live TypeSafe docs are the source of truth. Read them as part of the task.**
- This skill gives direction; the docs carry current concepts, prompting guidance,
- API contracts, SDK usage, models, limits, and worked examples.
+ ## Judgments from Jev, decisions in code
- - Start with the [documentation index](https://docs.typesafe.ai/llms.txt) to discover
- relevant pages and cookbooks. Use targeted reads rather than loading the entire site.
- - Mintlify serves Markdown by appending `.md` to a page path, for example
- [how to build with TypeSafe](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md).
- Follow links from the index; convert extensionless documentation page links to
- `.md` when useful. 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, also inspect the
- closest cookbook: it often shows a better decomposition than a generic classifier.
- - If the index is unavailable, use the direct links below or the site's navigation.
- If Markdown fetching fails, try the normal page. If live access is unavailable,
- use available local docs or installed SDK types, state that limitation, and avoid
- inventing version-dependent details.
+ Integrations tend to work best when Jev makes the judgments and code decides what to do with
+ them. Think of each decision as a **truth table**. Jev supplies the inputs, such as "Does the
+ customer sound frustrated?" or "Which product is the message about?". Code holds the logic that
+ maps those inputs to an action.
- | Task | Start here; follow the relevant details |
- | --- | --- |
- | 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 from the index |
- | Prepare inputs and questions | [State](https://docs.typesafe.ai/concepts/state.md), [primitives](https://docs.typesafe.ai/primitives.md), then the chosen primitive's page |
- | 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 |
+ A question that asks Jev to make the decision, such as "Should this ticket be escalated?" or "What
+ should the agent do next?", usually means the question is at the wrong layer. Instead, break the
+ decision into the judgments it depends on, and write the decision itself in code, where it's
+ visible and testable. Writing out the table often shows gaps in the business logic too. A
+ combination of judgments with no defined outcome is a design question about the system, and it is
+ best settled in code.
- ## Find the useful shape
+ ## Live docs
- 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.
+ The live docs are the source of truth for request syntax, SDKs, question types, limits, and current
+ model behavior. Read the relevant pages as part of the task.
- When brainstorming or choosing an architecture, consider more than classification.
- The patterns below are starting points: combine primitives around the user's goal,
- including ideas that do not fit an established recipe.
+ - Start at the [documentation index](https://docs.typesafe.ai/llms.txt). Append `.md` to a page
+ path to get the page as Markdown, and resolve relative links against `https://docs.typesafe.ai`.
+ - Exact request and response schemas: the [OpenAPI spec](https://api.typesafe.ai/openapi.json) and
+ the [HTTP API](https://docs.typesafe.ai/go/api.md) page. For an SDK, see the
+ [Python](https://docs.typesafe.ai/go/python-sdk.md) or
+ [JavaScript](https://docs.typesafe.ai/go/js-sdk.md) page and the types in the installed package.
+ - Question types: [primitives](https://docs.typesafe.ai/go/primitives.md) and each type's own page,
+ [structured instructions and criteria](https://docs.typesafe.ai/go/advanced.md), and
+ [images](https://docs.typesafe.ai/go/images.md).
+ - Models, context limits, and rate limits: [models](https://docs.typesafe.ai/go/models.md). Known
+ model weak spots and their workarounds are on the
+ [jaggedness page](https://docs.typesafe.ai/go/jaggedness.md).
+ - Architecture: [how to build with TypeSafe](https://docs.typesafe.ai/go/how-to-build.md),
+ [patterns](https://docs.typesafe.ai/go/patterns.md), and
+ [cookbooks](https://docs.typesafe.ai/go/cookbooks.md). The cookbook closest to your use case is a
+ good starting point for a new workflow.
- - **Route and fill known arguments.** A request can select a handler and its typed
- parameters. Ask useful branch-specific questions up front and consume only the
- relevant answers. 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.** Find candidate values or source spans in code,
- use a judgment to select the intended one, then copy or normalize it. Code can
- also assemble source text into a formatted document or reading guide. 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 to a
- query, 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 or
- user controls change weights, thresholds, rankings, and views. With labeled
- outcomes, those signals can become classical ML features. 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 specific claims or fields against their 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.** Code can retain goals and observations while fresh
- judgments guide the next bounded step. Keep inferred state distinct from observed
- facts, and check freshness before applying a result to a changed situation.
+ If you can't reach the live docs, use the installed SDK's types or local docs, and tell the user
+ you did. Leave out details that depend on the version rather than guessing them.
- For open-ended requests, offer the few directions that best serve the user's goal
- and recommend a starting point. For a concrete request, choose the relevant pattern
- and build; a brainstorm is not a mandatory detour.
+ ## Workflow
- ## Design the judgments
+ 1. **Start from the decision logic.** Begin with what the application will show, select, change,
+ or hand off. Sketch the truth table or rules that decide it, and list the inputs they need.
+ Inputs that need an understanding of language or images make good questions. Arithmetic, dates,
+ exact lookups, and policy usually belong in code. Aim for every question to feed the table, and
+ give every combination of answers an outcome, including the case where a Noul lands between your
+ thresholds. If code alone can already make the decision reliably, tell the user.
+ 2. **Keep all question wording in one place.** Questions, options, criteria, and thresholds are the
+ parts of an integration people audit and edit most. Keeping them together in one module makes
+ that easier. [Design the state](#design-the-state) and
+ [Write the questions](#write-the-questions) describe what tends to work.
+ 3. **Probe the live API**: send test requests as described in
+ [Test with the live API](#test-with-the-live-api). Use representative cases, hard cases, and
+ negative cases. Keep going until the application behaves as intended.
+ 4. **Integrate.** A few habits help here. Expose or log the exact request payload. When a call to
+ the API fails, surface it as an error, not as an answer; for example, don't treat a failed call
+ as a "no". Keep API keys on the server.
- Choose by what the answer means, then read the relevant primitive page:
+ If the user's request is open-ended, offer the few directions from [Cookbooks](#cookbooks) that
+ best serve their goal, and recommend one. If the request is concrete, build it.
- | 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 |
+ ## Design the state
- Give each question enough relevant **state** to answer: source text, identities,
- relationships, policies, and current facts. Prefer named JSON fields when context
- has several parts. Put the judgment in **instructions** and define its 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`.
+ A useful check for any question is the **human test**: could a smart person, shown only this state
+ and this question, answer quickly by intuition? When a question fails the test, the fix is usually
+ in the state, not in the wording.
- Ask one narrow, coherent judgment per question. Split independently useful dimensions,
- without destroying the relationship being judged. A bounded action selection or
- contextual interpretation is valid; atomic does not mean literal fact extraction
- or a one-sentence limit. Strings work for simple questions. Use structured objects
- or arrays when definitions, contrasts, exclusions, or examples clarify instructions
- or criteria. Score levels must describe concrete situations and stand on their own.
+ - **Give what a person would look at.** That means who sent each message, the full thread rather
+ than a truncated last line, names rather than raw IDs or @-mention markup, and the item the
+ question is about rather than the whole catalogue. State facts your code already knows, such as
+ "all messages in `replies` were sent after the refund was issued", rather than leaving the model
+ to work them out again.
+ - **Supply facts the model may lack**, such as what an internal product name or codename refers
+ to.
+ - **Ensure every field in the state is relevant.** Irrelevant detail clutters the context and
+ reduces accuracy. A field added for one question can sway the answer to another, and the model
+ can read an empty list as a signal.
+ - **Be mindful when truncating.** Truncate long strings only when you need to, and check that the
+ cut doesn't remove context the questions need.
+ - **Structure with named fields.** JSON objects with descriptive keys work better than a string of
+ serialized JSON. They also let a question refer to each part by its path. Stable names such as
+ `candidates.refund_policy` are easier to refer to than array positions.
+ - **Consider leaving out what no person could judge**, such as an unreadable crop or a distinction
+ experts dispute. The model's answer there tends to be noise, and code will treat that noise as
+ signal.
- Keep the needed answers available. Include a no-match outcome when nothing may fit;
- use a separate presence judgment when it is independently useful. For source-value
- selection, check candidate coverage: the model cannot choose an omitted value.
+ ## Write the questions
- ## Compose and verify
+ Break complex judgments or decisions into their parts, and combine the answers in code with
+ weighted sums, boolean logic, thresholds, or other heuristics to reach the final decision. For
+ example, rather than asking "Is this fraud?" or "Is this spam?", ask the set of atomic questions
+ about what might make something fraud or spam. Each question tends to work best when it asks for
+ **one judgment** that a person could make at a glance.
- **Ask independent questions over the same state together**, including useful
- speculative questions. They run in parallel and cannot see one another's answers.
- State each speculative premise explicitly; code consumes the applicable answers.
- A second request is warranted when an earlier answer is needed to fetch evidence,
- construct new state, or determine the next options. Extra questions still use tokens;
- measure actual request budgets, cost, and end-to-end latency.
+ - **Ask the concrete, observable thing.** Aim for something a person could point to: "Is a SQL
+ query built by string concatenation here?" rather than "Are there SQL injection risks?".
+ - **One judgment per question; beware the "or".** Two conditions joined by "or" or "and" usually
+ work better as two questions. Likewise, a list of rules usually works better as one question per
+ rule.
+ - **Anchor intent to the goal.** When the judgment is about what someone wants, it helps to name
+ their goal: "Which of these files does the user want copied?" rather than "Which of these names
+ the main input?".
+ - **Name the subject directly.** "Where is the coffee mug in `photo`?" reads better than "Where is
+ `target` in `photo`?" with the target defined somewhere else. Context that only one question
+ needs, including an image, usually fits best in that question's instructions (the question text)
+ or its criteria (the descriptions of its options, its levels, or what yes and no mean). Context
+ that many questions share can go in the state once, and each question can refer to it by its
+ exact path in backticks. When you ask the same question about many items, it usually works better
+ to put each item into its own question than to give an ID the model has to look up in a shared
+ list.
+ - **Each question is answered on its own.** Questions in a request can't see each other or each
+ other's answers. Any context a question relies on belongs in the state or in that question.
+ - **Write plainly.** A question isn't an LLM prompt. Preambles, "consider X, Y, and Z" lists, and
+ output-format instructions add noise. Descriptions of the options belong in the criteria, not in
+ the question. Phrase the question so that a true answer means yes. Watch for double negatives,
+ and for presuppositions such as "the next step".
+ - **Name the case that causes confusion.** If answers keep mixing up two outcomes, say in the
+ criteria what separates them, using the specific case. For example, for "Is this a refund
+ request?", note that a question about the refund policy is not a request. A vague exclusion such
+ as "not other kinds of message" helps less, and can draw attention to the wrong answer.
- Use probabilities and confidence to guide behavior, with thresholds evaluated on
- the user's data and consequences. Choice/Score confidence summarizes distribution
- concentration, not overall workflow correctness or permission to act. A Noul near
- 0.5 means similar probability for yes and no, not medium intensity. Several
- acceptable alternatives can also spread probability; low confidence need not
- invalidate a harmless preference choice. Ignore uncertainty on unused branches.
+ ### Criteria
- Keep policy explicit and raw judgments reusable. Weighted scores suit compensating
- preferences; an “any serious violation” rule needs separate conditions. Changing a
- weight or display filter need not rerun inference when evidence and question meanings
- are unchanged. Typed output guarantees the interface, not truth. System One models
- are trained for calibrated decisions; validate their performance in the target domain.
+ - **Ask about the null case separately.** A Box always returns a location and a Choice always picks
+ an option, even when nothing fits. Pair either one with a Noul in the same request that asks
+ whether anything fits ("Is there a coffee mug in `photo`?", "Does `message` name any of our
+ products?"), so code can tell when nothing does. As of Jev 1.14, this companion Noul usually works
+ better than a "none of the above" option.
+ - **Option names are sent to the model; question IDs are not.** Names that describe the content
+ (`refund_request`, `shipping_delay`) help the model. Positional names (`A`, `left`, `option_1`)
+ give it nothing meaningful to go on and can bias the answer.
+ - **Keep options distinct and concrete.** Wording that options share with each other, or with the
+ input, can pull probability toward those options. An option that covers several meanings is
+ often worth splitting, because its probability can't tell code which meaning applied. Direction
+ and magnitude usually work better as separate questions, so that the answer to one doesn't get
+ mixed into the other.
+ - **Describe each Score level as a situation.** Each level should make sense when read on its own:
+ "The customer mentions a minor inconvenience" rather than "More upset than the previous level".
+ - **Describe a Noul's `false` criterion as a concrete situation**, such as "the package arrived on
+ time", rather than as "not late".
+ - **Use a Noul per statement when more than one can be true.** A Choice picks one option, so a
+ message that is both a refund request and a complaint forces it to split probability between the
+ two. Separate Nouls let each one be true on its own.
- Test representative cases and the resulting application behavior. For failures,
- inspect the exact state, questions, candidates, answers, composition, and observed
- outcome. Separate missing evidence, model errors, code errors, and service failures.
- Treat cookbook thresholds and demo results as examples to evaluate, not universal
- rules or permanent model limitations. Keep API credentials server-side in web apps.
+ ## Compose requests
+
+ **Bundle questions that share state.** A handy heuristic: if two calls would send the same state
+ with different questions, they can likely be one call. Questions are cheap and run in parallel, and
+ the state is read and paid for once. See
+ [parallel questions](https://docs.typesafe.ai/cookbooks/parallel_questions.md).
+
+ **Ask speculatively**, meaning ask a question before you know whether you'll need its answer. A
+ question that only matters in some cases can go in the same request as the question that
+ identifies the case. Ask "Is `order` a return request?" and "Which item in `order.items` is being
+ returned?" together, and have code read the second answer only when the first is yes. The second
+ question doesn't need an "if" clause, because code handles the condition. See
+ [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out.md).
+
+ A second request is usually worth it when:
+
+ - code needs an answer to build the next state, fetch evidence, or choose the next options;
+ - a state field needed for one question measurably misleads another;
+ - different sets of questions need to be cached or versioned separately.
+
+ ## Read the answers
+
+ ### Confidence is rarely the gate
+
+ Naive implementations often use an answer's `confidence` as the check that decides whether code
+ acts. Confidence measures how concentrated an answer's probability distribution is, which is not
+ the same as how likely the answer is to be correct. Think about what the probabilities should look
+ like in your use case; another calculation over them may suit it better.
+
+ ### Probabilities and thresholds
+
+ - **A probability is the likelihood that an answer is correct.** Jev isn't a calculator for
+ probability problems. Ask it for judgments, and do any math on odds or probabilities in code. A
+ Noul near 0.5 usually means the state doesn't settle the question.
+ - **The top answer is a good default**: the Choice's top option, or the Score's position.
+ - **0.7 and 0.3 make good starting thresholds for a Noul**: above 0.7 reads as yes, below 0.3 as no,
+ and the band between means the question isn't settled, which can get its own row in the truth
+ table. Adjust them when the application calls for it, and be wary of over-fitting them to a
+ handful of test cases.
+ - **Look at Score distributions.** The Score's position can get pulled toward the middle and hide
+ two-peaked answers, so look at the level probabilities before deciding which value your code
+ reads.
+
+ ## Test with the live API
+
+ Sending test requests to the live API is a great way to test questions against your data. Ask the
+ user for permission first. Get a budget for experimentation (TypeSafe is very inexpensive, so a
+ little can go a very long way), disclose what data will be sent (point out any personal or private
+ data), and say that their `TYPESAFE_API_KEY` will be used.
+
+ - Start with a few representative cases, plus hard ones and some whose answer is "no" or "nothing
+ fits".
+ - Compare wordings by sending each variant as a separate question in one request, over the same
+ state.
+ - Read individual answers, not only aggregates.
+ - Keep the exact request payload for each case so any result can be rerun.
+ - Check each change against cases you didn't use while tuning.
+
+ Make sure any agent that sends test requests has network access to the API endpoint.
+
+ ### When an answer looks wrong
+
+ Check these, in this order:
+
+ 1. the payload as actually sent;
+ 2. the state, against the human test;
+ 3. the options and candidates: is the right answer among them?
+ 4. the scope of the questions: can each one be broken down into smaller judgments?
+ 5. the wording.
+
+ If a clear question with complete state still gets an answer you're confident is wrong, check the
+ jaggedness page for the model you're using. It lists known weak spots and how to work around them.
+ If the behavior isn't listed, the TypeSafe team welcomes examples through the channel linked on
+ that page. In the meantime, work out an alternative approach with the user that avoids the weak
+ spot.
+
+ ### Yellow flags
+
+ Typically, a good change is one that makes the definition clearer or improves the state. Check each
+ change on cases you didn't tune on. Wording written to produce a particular value is **prompt
+ gymnastics**, and it tends to break on new inputs and on the next model version. Some yellow flags:
+
+ - criteria that name specific test items, or that gain a clause for each failing case;
+ - caveats that explain away a model quirk;
+ - thresholds fitted to particular cases;
+ - tests that assert an exact probability;
+ - code that quietly overrides answers.
+
+ The structural fix is usually better state, a separate question, or code.
+
+ ## Cookbooks
+
+ Each of these starting points combines questions to serve one goal. Ideas outside this list are
+ welcome.
+
+ - **Route and fill arguments.** One request identifies what the user is asking for and which
+ values go in each argument. Code then calls the handler. See
+ [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md) and
+ [intent routing](https://docs.typesafe.ai/patterns/intent-routing.md).
+ - **Select instead of generate.** Code finds candidate values or spans of text, the model picks
+ the intended one, and code copies or normalizes it. See
+ [value extraction](https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook.md),
+ [date extraction](https://docs.typesafe.ai/cookbooks/date_extraction_cookbook.md), and
+ [structure recovery](https://docs.typesafe.ai/cookbooks/autoformat.md).
+ - **Find and judge evidence.** Retrieve candidates and ask how relevant each one is. See
+ [line-by-line search](https://docs.typesafe.ai/cookbooks/semantic_find.md),
+ [re-ranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md), and
+ [classifying RAG passages](https://docs.typesafe.ai/cookbooks/classifying_rag_passages.md).
+ - **Turn answers into data.** Score each dimension once, then let code or users change the weights
+ and views. If you have labeled outcomes, the answers can become features for a model. See
+ [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 their evidence, and send the cases that
+ fail to a person or a reasoning model. See
+ [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md) and
+ [extraction cascades](https://docs.typesafe.ai/cookbooks/sde_cascade.md).
+
+ The TypeSafe team is constantly adding cookbooks of well-tested patterns to the live documentation.
+ It's a good idea to check the [cookbooks index](https://docs.typesafe.ai/go/cookbooks.md) for one
+ that fits the problem you're solving.