---
title: "Patterns overview"
type: pattern
tags: [patterns, architecture, routing, scoring, fan-out]
created: 2026-09-17
updated: 2026-09-17
confidence: high
sources:
  - raw/docs/patterns.md
  - raw/docs/patterns__fan-out.md
  - raw/docs/patterns__confidence-routing.md
  - raw/docs/patterns__composite-scoring.md
  - raw/docs/patterns__intent-routing.md
jev_version: "jev-1.13.0"
summary: "Catalog of TypeSafe's four architectural patterns — fan-out, confidence routing, composite scoring, intent routing — and when to reach for each."
---

# Patterns overview

> **TL;DR** TypeSafe documents four patterns: [[patterns/fan-out|Speculative Fan-Out]] (ask everything in one call, filter in code), [[patterns/confidence-routing|Confidence-Gated Routing]] (per-action confidence thresholds), [[patterns/composite-scoring|Composite Scoring]] (independent Score dimensions combined with weights you own), and [[patterns/intent-routing|Intent Routing]] (classify first, then invoke the cheapest adequate handler). All four rest on the same move: the model makes atomic judgments, your code composes them.

## Problem

Jev sits inside a larger system rather than being the system. The docs state it plainly: "TypeSafe is designed to sit within a larger system, powering decisions with AI. Learning to think in terms of discrete, atomic decisions that compose into complex system behavior is a key skill for getting the most out of TypeSafe."

The recurring design question is therefore not "what prompt do I write" but "which judgments do I need, how many calls do I make, and what does my code do with the numbers that come back." The four patterns are TypeSafe's documented answers.

Prerequisites, per `raw/docs/patterns.md`: "This section assumes you know the [TypeSafe primitives](/primitives) and understand [how confidence works](/confidence). If not, read those first." See [[concepts/primitives]] and [[concepts/confidence]].

## Pattern

The catalog, reproduced from `raw/docs/patterns.md`:

| Pattern | What it does | Benefits |
|---|---|---|
| [[patterns/fan-out\|Speculative Fan-Out]] | Send many questions in a single call, including speculative ones, and let your code decide what's relevant | Cost, Speed |
| [[patterns/confidence-routing\|Confidence-Gated Routing]] | Utilize confidence as a second decision axis to build safer systems | Reliability, Safety |
| [[patterns/composite-scoring\|Composite Scoring]] | Combine several dimensions of analysis into a single score | Cost, Reliability, Speed |
| [[patterns/intent-routing\|Intent Routing]] | Classify a user's intent and route to the appropriate handler | Cost, Speed |

Each page's own one-line thesis:

- **Speculative fan-out** — "Send many questions in a single call, including speculative ones, and let your code decide what's relevant."
- **Confidence-gated routing** — "Use confidence as a second axis. The answer tells you what; confidence tells you whether to act."
- **Composite scoring** — "Break a complex judgment into atomic scores, combine with weights you control in code."
- **Intent routing** — "Classify incoming requests and route each to the optimal handler: deterministic logic, a specialist LLM, or a human."

### When to reach for each

The following selection table is a synthesis of the four source pages (inferred as a table; the individual claims are sourced):

| Your situation | Pattern | Why |
|---|---|---|
| A decision tree where later branches need extra facts | [[patterns/fan-out]] | "All questions are evaluated in parallel, so adding more questions to a call typically doesn't add any latency to the response." Ask the branch-specific questions upfront and discard the irrelevant answers. |
| Actions differ in blast radius (read vs. move money) | [[patterns/confidence-routing]] | Each action type gets its own threshold "based on the consequences of acting on a wrong classification." |
| You need to rank or shortlist items on several dimensions | [[patterns/composite-scoring]] | Score each dimension separately, normalize, weight in code; weights are tunable without re-running inference. |
| Requests need different handlers (code / LLM / human) | [[patterns/intent-routing]] | "The expensive resources only get invoked for the requests that actually need them." |

These compose. The intent-routing example is itself fan-out plus a confidence gate: it asks `intent` and `complexity` in one call and checks `intent.confidence < 0.5` before acting.

## Implementation

Every pattern uses the same two-step skeleton — one `POST /v1/systemone` call carrying a `questions` map, then plain code over `response.answers`. The shared shape, from the pattern pages' Python snippets:

Step 1 is one call carrying many questions (see the individual pattern pages for the exact `questions` maps). Step 2 is plain code:

```python
answer = response.answers["<question id>"]
answer.choice        # Choice
answer.score         # Score
answer.noul          # Noul
answer.confidence    # Choice and Score only
```

For the wire contract see [[reference/http-api]]; for the SDK signatures see [[reference/python-sdk]] and [[reference/javascript-sdk]].

## When it fails

- **Treating the catalog as exhaustive.** The docs invite additions: "We're always keen to learn how people are making use of our primitives. If you've found a killer use case you think should be mentioned here, feel free to drop us a note!" The agent skill (`raw/github/skills/skills/typesafe-ai/SKILL.md`) says the same more sharply: "The patterns below are starting points: combine primitives around the user's goal, including ideas that do not fit an established recipe."
- **Skipping the prerequisites.** Confidence thresholds copied from a pattern page without reading [[concepts/confidence]] are the most common way these patterns misfire; see each page's "When it fails" section.
- **Assuming zero cost for extra questions.** Latency barely moves, but the skill warns: "Extra questions still use tokens; measure actual request budgets, cost, and end-to-end latency."

## Variants

- **Compose two or more patterns in one call.** [[patterns/intent-routing]] is the documented example.
- **Cookbooks are worked variants.** The [[cookbooks/overview|cookbook index]] shows these patterns applied end to end, often with a better decomposition than a generic classifier.
- **Demos.** [[guides/smart-home-demo]] is fan-out plus an LLM fallback in a running application.

## Related

- [[concepts/primitives]] — Choice, Score, Noul; required reading first
- [[concepts/confidence]] — what `confidence` means and how to threshold it
- [[concepts/how-to-build]] — the full design workflow
- [[guides/choosing-a-primitive]] — picking the question type
- [[cookbooks/overview]] — worked, domain-specific applications
- [[reference/agent-skill]] — the skill that teaches agents these patterns

## Sources

- raw/docs/patterns.md (https://docs.typesafe.ai/patterns)
- raw/docs/patterns__fan-out.md (https://docs.typesafe.ai/patterns/fan-out)
- raw/docs/patterns__confidence-routing.md (https://docs.typesafe.ai/patterns/confidence-routing)
- raw/docs/patterns__composite-scoring.md (https://docs.typesafe.ai/patterns/composite-scoring)
- raw/docs/patterns__intent-routing.md (https://docs.typesafe.ai/patterns/intent-routing)