|
| 1 | +--- |
| 2 | +name: typesafe-ai |
| 3 | +license: MIT |
| 4 | +description: > |
| 5 | + Build AI-powered software with TypeSafe: small units of AI intelligence you |
| 6 | + can use like programming primitives. Its System One models, including Jev, |
| 7 | + turn natural language and application state into typed judgments and |
| 8 | + probabilities that code can combine. Use when a feature needs programmable |
| 9 | + common sense, when brainstorming what AI could make possible in an app, or |
| 10 | + when an LLM prompt-and-parse step could become a structured decision. |
| 11 | + Applications include routing, ranking, extraction, verification, and |
| 12 | + interactive experiences; these are starting points, not the limits. |
| 13 | + Read live docs and cookbooks to find useful patterns and discover new combinations. |
| 14 | +--- |
| 15 | + |
| 16 | +# Build with TypeSafe |
| 17 | + |
| 18 | +TypeSafe makes units of AI intelligence usable like programming primitives: small |
| 19 | +judgments you can compose into larger capabilities. Its **System One models** return |
| 20 | +fast, focused judgments that software can consume directly. **Jev** is TypeSafe's |
| 21 | +flagship and first System One model. It understands natural language and returns |
| 22 | +typed answers and probabilities rather |
| 23 | +than generating text or reasoning explanations. Code owns the workflow; the model |
| 24 | +supplies programmable common sense where ordinary code needs semantic understanding. |
| 25 | + |
| 26 | +## Read the live docs |
| 27 | + |
| 28 | +**The live TypeSafe docs are the source of truth. Read them as part of the task.** |
| 29 | +This skill gives direction; the docs carry current concepts, prompting guidance, |
| 30 | +API contracts, SDK usage, models, limits, and worked examples. |
| 31 | + |
| 32 | +- Start with the [documentation index](https://docs.typesafe.ai/llms.txt) to discover |
| 33 | + relevant pages and cookbooks. Use targeted reads rather than loading the entire site. |
| 34 | +- Mintlify serves Markdown by appending `.md` to a page path, for example |
| 35 | + [how to build with TypeSafe](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md). |
| 36 | + Follow links from the index; convert extensionless documentation page links to |
| 37 | + `.md` when useful. Resolve relative links against `https://docs.typesafe.ai`. |
| 38 | +- Before writing an integration, read the current API or chosen SDK page and the |
| 39 | + question guidance relevant to the design. For a new workflow, also inspect the |
| 40 | + closest cookbook: it often shows a better decomposition than a generic classifier. |
| 41 | +- If the index is unavailable, use the direct links below or the site's navigation. |
| 42 | + If Markdown fetching fails, try the normal page. If live access is unavailable, |
| 43 | + use available local docs or installed SDK types, state that limitation, and avoid |
| 44 | + inventing version-dependent details. |
| 45 | + |
| 46 | +| Task | Start here; follow the relevant details | |
| 47 | +| --- | --- | |
| 48 | +| 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) | |
| 49 | +| Explore what to build | [Use-case map](https://docs.typesafe.ai/concepts/use-case-map.md), then relevant cookbooks from the index | |
| 50 | +| 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 | |
| 51 | +| Decide how to handle uncertainty | [Confidence](https://docs.typesafe.ai/confidence.md) | |
| 52 | +| 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) | |
| 53 | +| Update an older integration | [Migration guide](https://docs.typesafe.ai/migrating-to-v1.md) and the installed SDK's current reference | |
| 54 | + |
| 55 | +## Find the useful shape |
| 56 | + |
| 57 | +Start from the behavior the user wants: what will the application show, select, |
| 58 | +change, or hand off? Work backward to the judgments it needs. Keep known rules, |
| 59 | +calculations, exact lookups, and execution in code. Preserve the user's chosen stack |
| 60 | +and scope; add TypeSafe where semantic understanding helps. |
| 61 | + |
| 62 | +When brainstorming or choosing an architecture, consider more than classification. |
| 63 | +The patterns below are starting points: combine primitives around the user's goal, |
| 64 | +including ideas that do not fit an established recipe. |
| 65 | + |
| 66 | +- **Route and fill known arguments.** A request can select a handler and its typed |
| 67 | + parameters. Ask useful branch-specific questions up front and consume only the |
| 68 | + relevant answers. Explore [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md) |
| 69 | + and [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out.md). |
| 70 | +- **Select instead of generate.** Find candidate values or source spans in code, |
| 71 | + use a judgment to select the intended one, then copy or normalize it. Code can |
| 72 | + also assemble source text into a formatted document or reading guide. Explore |
| 73 | + [value extraction](https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook.md) |
| 74 | + and [structure recovery](https://docs.typesafe.ai/cookbooks/autoformat.md). |
| 75 | +- **Find and judge evidence.** Retrieve candidates, compare their relevance to a |
| 76 | + query, and select useful context. Explore [reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md) |
| 77 | + and [hierarchical classification](https://docs.typesafe.ai/cookbooks/hierarchical_classification.md). |
| 78 | +- **Turn judgments into reusable data.** Score dimensions once, then let code or |
| 79 | + user controls change weights, thresholds, rankings, and views. With labeled |
| 80 | + outcomes, those signals can become classical ML features. Explore |
| 81 | + [composite scoring](https://docs.typesafe.ai/patterns/composite-scoring.md) and |
| 82 | + [feature discovery](https://docs.typesafe.ai/cookbooks/autoresearch_feature_discovery.md). |
| 83 | +- **Verify and escalate.** Check specific claims or fields against their evidence; |
| 84 | + send uncertain or failing cases to a person or reasoning model. Explore |
| 85 | + [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md) and |
| 86 | + [extraction cascades](https://docs.typesafe.ai/cookbooks/sde_cascade.md). |
| 87 | +- **Respond to changing state.** Code can retain goals and observations while fresh |
| 88 | + judgments guide the next bounded step. Keep inferred state distinct from observed |
| 89 | + facts, and check freshness before applying a result to a changed situation. |
| 90 | + |
| 91 | +For open-ended requests, offer the few directions that best serve the user's goal |
| 92 | +and recommend a starting point. For a concrete request, choose the relevant pattern |
| 93 | +and build; a brainstorm is not a mandatory detour. |
| 94 | + |
| 95 | +## Design the judgments |
| 96 | + |
| 97 | +Choose by what the answer means, then read the relevant primitive page: |
| 98 | + |
| 99 | +| Need | Primitive | Important distinction | |
| 100 | +| --- | --- | --- | |
| 101 | +| One of a defined set | [Choice](https://docs.typesafe.ai/primitives/choice.md) | Picks one option; its distribution compares competing options | |
| 102 | +| 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 | |
| 103 | +| 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 | |
| 104 | + |
| 105 | +Give each question enough relevant **state** to answer: source text, identities, |
| 106 | +relationships, policies, and current facts. Prefer named JSON fields when context |
| 107 | +has several parts. Put the judgment in **instructions** and define its possible |
| 108 | +answers in **criteria**. Question IDs are for code and are not sent to the model; |
| 109 | +include complete meaning in the question. Reference nested state with backticked |
| 110 | +paths such as `ticket.messages[0].text`. |
| 111 | + |
| 112 | +Ask one narrow, coherent judgment per question. Split independently useful dimensions, |
| 113 | +without destroying the relationship being judged. A bounded action selection or |
| 114 | +contextual interpretation is valid; atomic does not mean literal fact extraction |
| 115 | +or a one-sentence limit. Strings work for simple questions. Use structured objects |
| 116 | +or arrays when definitions, contrasts, exclusions, or examples clarify instructions |
| 117 | +or criteria. Score levels must describe concrete situations and stand on their own. |
| 118 | + |
| 119 | +Keep the needed answers available. Include a no-match outcome when nothing may fit; |
| 120 | +use a separate presence judgment when it is independently useful. For source-value |
| 121 | +selection, check candidate coverage: the model cannot choose an omitted value. |
| 122 | + |
| 123 | +## Compose and verify |
| 124 | + |
| 125 | +**Ask independent questions over the same state together**, including useful |
| 126 | +speculative questions. They run in parallel and cannot see one another's answers. |
| 127 | +State each speculative premise explicitly; code consumes the applicable answers. |
| 128 | +A second request is warranted when an earlier answer is needed to fetch evidence, |
| 129 | +construct new state, or determine the next options. Extra questions still use tokens; |
| 130 | +measure actual request budgets, cost, and end-to-end latency. |
| 131 | + |
| 132 | +Use probabilities and confidence to guide behavior, with thresholds evaluated on |
| 133 | +the user's data and consequences. Choice/Score confidence summarizes distribution |
| 134 | +concentration, not overall workflow correctness or permission to act. A Noul near |
| 135 | +0.5 means similar probability for yes and no, not medium intensity. Several |
| 136 | +acceptable alternatives can also spread probability; low confidence need not |
| 137 | +invalidate a harmless preference choice. Ignore uncertainty on unused branches. |
| 138 | + |
| 139 | +Keep policy explicit and raw judgments reusable. Weighted scores suit compensating |
| 140 | +preferences; an “any serious violation” rule needs separate conditions. Changing a |
| 141 | +weight or display filter need not rerun inference when evidence and question meanings |
| 142 | +are unchanged. Typed output guarantees the interface, not truth. System One models |
| 143 | +are trained for calibrated decisions; validate their performance in the target domain. |
| 144 | + |
| 145 | +Test representative cases and the resulting application behavior. For failures, |
| 146 | +inspect the exact state, questions, candidates, answers, composition, and observed |
| 147 | +outcome. Separate missing evidence, model errors, code errors, and service failures. |
| 148 | +Treat cookbook thresholds and demo results as examples to evaluate, not universal |
| 149 | +rules or permanent model limitations. Keep API credentials server-side in web apps. |
0 commit comments