> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prysm1.com/llms.txt
> Use this file to discover all available pages before exploring further.
# BRAIN.md
> A declarative, version-controlled routing config — the .cursorrules of model routing.
`BRAIN.md` is a declarative routing configuration for PRYSM. Drop a `BRAIN.md` in your
project root and PRYSM reads it to customize how prompts are routed: which model handles
which kind of task, how much a request may cost, which models are off-limits, and what
to fall back to.
It's an **open standard** — plain, human-readable, and YAML-compatible — so any tool can
read or write it, not just PRYSM.
**Version 1.0 · Stable.** All fields are optional; an empty `BRAIN.md` is valid (PRYSM
uses its default auto-routing).
## File location & loading
* **Location:** project root, filename `BRAIN.md` (case-sensitive).
* **Discovery:** the SDKs and CLI auto-discover `BRAIN.md` by walking up from the current
working directory. The API accepts the parsed config per request via `brain_config`.
* **Optional:** with no `BRAIN.md`, PRYSM uses default auto-routing.
```python Python theme={null}
from prysm import Prysm
Prysm() # discovers ./BRAIN.md (walks up from cwd)
Prysm(brain="path/to/BRAIN.md") # explicit path
Prysm(brain={"max_cost": 0.005, "model": "deepseek-v4-flash"}) # inline dict
Prysm(brain=None) # ignore BRAIN.md
```
```typescript Node theme={null}
import { Prysm } from "@prysmai/sdk";
new Prysm(); // discovers ./BRAIN.md (walks up from cwd)
new Prysm({ brain: "path/to/BRAIN.md" }); // explicit path
new Prysm({ brain: { max_cost: 0.005, model: "deepseek-v4-flash" } }); // inline object
new Prysm({ brain: null }); // ignore BRAIN.md
```
## File format
`BRAIN.md` is **YAML with Markdown affordances**:
* Markdown headers (`#`, `##`) begin with `#`, which is a **YAML comment** — so headers
are free for human structure and ignored by the parser.
* Everything else is standard YAML: `key: value`, block sequences (`- item`), inline
lists (`[a, b]`), quoted strings, booleans, numbers.
* Inline comments (` # ...`) are supported and stripped.
PRYSM parses with a full YAML parser when available and ships a **dependency-free subset
parser** as a fallback, so `BRAIN.md` works in any environment.
```markdown BRAIN.md theme={null}
# BRAIN.md — My App
## Budget
max_cost_per_request: 0.005 # USD
## Routing Rules
rules:
- when: "code"
model: "deepseek-v4-flash"
reason: "95% cheaper for equivalent code quality"
```
## Field reference
All fields are optional.
| Field | Type | Description |
| ---------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Cosmetic project name (logs/dashboards). |
| `version` | string \| number | Cosmetic config version. |
| `model` | model ID | **Hard model lock.** Routes *every* request to this model, overriding auto-routing and rules. |
| `max_cost_per_request` | number > 0 | **AgentGuard** per-request USD cap. Over-budget selections are downgraded to a budget model. |
| `monthly_budget` | number > 0 | AgentGuard monthly USD ceiling (alerts on approach). |
| `rules` | rule\[] | Per-signal routing rules (see below). First matching rule wins. |
| `quality_threshold` | integer ≥ 0 | Word-count trigger for Quality mode. |
| `quality_signals` | string\[] | Extra keywords biasing toward Quality mode. |
| `fallback` | model ID\[] | Custom fallback order when a provider is unavailable or a model is blocked. |
| `blocked` | model ID\[] | Models PRYSM must never route to. Reroutes via `fallback`. |
| `compliance` | object | **[Policy-as-Code](/concepts/compliance)** gate: approved providers, jurisdictions, frameworks, certifications, data residency, blocked data classes. Non-compliant models are filtered out before scoring. |
| `log_level` | `minimal` \| `standard` \| `verbose` | Routing-decision log verbosity. |
| `log_proofs` | boolean | Emit a [PrysmProof](/concepts/prysmproof) per request. |
### The `rule` object
| Field | Type | Required | Description |
| -------- | -------- | -------- | -------------------------------------------------- |
| `when` | signal | yes | Intent signal that activates the rule (see below). |
| `model` | model ID | yes | Model to route to when the signal fires. |
| `reason` | string | no | Human note, surfaced in logs. |
`max_cost` is the canonical normalized name for `max_cost_per_request`. Use
`max_cost_per_request` in source files; both are accepted.
## Routing precedence
This is the heart of the spec. PRYSM resolves the model for each request in a fixed
order. **Later steps are guardrails and always win** over earlier preferences:
PRYSM classifies intent and picks the best model. See [How routing works](/concepts/routing).
The first rule whose `when` signal is active replaces the auto choice.
An explicit model lock replaces the above.
If the chosen model's estimated cost exceeds the cap, downgrade to a budget model
(`deepseek-v4-flash`).
If the chosen model is blocked, reroute through the fallback chain.
**Guardrails win on purpose.** A budget cap or compliance block must beat a routing
preference. If you *prefer* `claude-sonnet-4.5` for writing but set a
`max_cost_per_request` it can't satisfy, the cap wins — your spend is protected.
**Cost estimate (step 4):** PRYSM compares `(input_price + output_price) × 0.001` (USD
per MTok, a \~1K-token reference) against the cap. It's a fast pre-flight estimate, not a
post-hoc bill.
### Worked example
```yaml theme={null}
max_cost_per_request: 0.005
rules:
- when: "writing"
model: "claude-sonnet-4.5" # ($3 + $15)/MTok ⇒ est. 0.018 > 0.005
```
A "write a poem" prompt matches the rule (→ `claude-sonnet-4.5`), but the cap downgrades
it to `deepseek-v4-flash`. The guardrail wins. To honor the rule, raise the cap to ≥ `0.018`
or remove it.
## Signal vocabulary
Signals are intent categories. PRYSM normalizes **aliases** to a canonical signal, so
`writing` and `copy` both mean `write`. Use whichever spelling reads best.
| Canonical | Accepted aliases |
| ------------ | ------------------------------------------- |
| `code` | `coding`, `programming`, `dev` |
| `write` | `writing`, `content`, `copy`, `copywriting` |
| `analysis` | `research`, `analyze`, `analyse` |
| `math` | `maths`, `calculation`, `calc` |
| `translate` | `translation`, `i18n` |
| `realtime` | `real-time`, `news`, `live` |
| `simple` | `quick`, `lookup` |
| `multimodal` | `vision`, `image`, `images` |
| `reasoning` | `logic`, `reason` |
## Validation
Validate a `BRAIN.md` before you ship it — via the API, the CLI, or an SDK:
```bash CLI theme={null}
prysm brain validate # validates ./BRAIN.md
```
```python Python theme={null}
from prysm import Prysm
client = Prysm()
print(client.validate_brain(open("BRAIN.md").read()))
```
```typescript Node theme={null}
import { Prysm } from "@prysmai/sdk";
import { readFileSync } from "node:fs";
const client = new Prysm();
console.log(await client.validateBrain(readFileSync("BRAIN.md", "utf-8")));
```
```bash cURL theme={null}
curl -X POST https://api.prysm1.com/v1/brain/validate \
-H "Content-Type: application/json" \
-d '{"brain_md": "max_cost_per_request: 0.005\nrules:\n - when: code\n model: deepseek-v4-flash\n"}'
```
```json Response theme={null}
{
"valid": true,
"errors": [],
"warnings": [],
"normalized": { "max_cost": 0.005, "rules": [{ "when": "code", "model": "deepseek-v4-flash" }] }
}
```
* `valid` is `false` **iff** `errors` is non-empty.
* **Errors** block shipping: unknown locked model, unknown rule model, non-positive
`max_cost`.
* **Warnings** are advisory: unknown `blocked`/`fallback` model; every fallback also
blocked.
* `normalized` is the canonical config PRYSM's router consumes.
## Editor autocomplete
A JSON Schema (Draft 2020-12) is published for autocomplete and inline validation. In VS
Code with the YAML extension:
```jsonc .vscode/settings.json theme={null}
{
"yaml.schemas": {
"https://prysm1.com/schemas/brain.schema.json": "BRAIN.md"
}
}
```
## Complete example
```markdown BRAIN.md theme={null}
# BRAIN.md — PRYSM Routing Configuration
# Place this file in your project root.
## Identity
name: "My App"
version: "1.0"
## Budget
max_cost_per_request: 0.005 # USD — downgrades model if exceeded
monthly_budget: 50.00 # USD — alerts when approaching
## Default Model
# model: deepseek-v4-flash # uncomment to hard-lock every request
## Routing Rules
rules:
- when: "code"
model: "deepseek-v4-flash"
reason: "95% cheaper than GPT for equivalent code quality"
- when: "writing"
model: "claude-sonnet-4.5"
reason: "Best nuance and style for content"
- when: "translation"
model: "mistral-medium-3"
reason: "European language specialist"
## Quality Mode
quality_threshold: 30
quality_signals: ["analyze", "research", "compare", "evaluate"]
## Fallback Chain
fallback:
- deepseek-v4-flash
- claude-haiku-4.5
- gpt-5-nano
## Blocked Models
blocked:
- gpt-5.2-pro # too expensive
- grok-4.1-heavy # too slow
## Logging
log_level: "standard" # minimal | standard | verbose
log_proofs: true
```
## Design principles
1. **Human-first, machine-clean.** Reads like notes; parses like config.
2. **Safe by default.** Guardrails (cost, blocked) always beat preferences.
3. **Dependency-free.** Works without a YAML library; works without PRYSM.
4. **Forward-compatible.** Unknown top-level keys are preserved, not rejected — new
fields never break old parsers.