BRAIN.md

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.

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

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.

BRAIN.md

# 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 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 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:

Auto-routing

PRYSM classifies intent and picks the best model. See How routing works.

rules (override)

The first rule whose when signal is active replaces the auto choice.

model (override)

An explicit model lock replaces the above.

max_cost (guardrail)

If the chosen model’s estimated cost exceeds the cap, downgrade to a budget model (deepseek-v4-flash).

blocked (guardrail)

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

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:

prysm brain validate            # validates ./BRAIN.md

from prysm import Prysm

client = Prysm()
print(client.validate_brain(open("BRAIN.md").read()))

import { Prysm } from "@prysmai/sdk";
import { readFileSync } from "node:fs";

const client = new Prysm();
console.log(await client.validateBrain(readFileSync("BRAIN.md", "utf-8")));

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"}'

Response

{
  "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:

.vscode/settings.json

{
  "yaml.schemas": {
    "https://prysm1.com/schemas/brain.schema.json": "BRAIN.md"
  }
}

Complete example

BRAIN.md

# 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

Human-first, machine-clean. Reads like notes; parses like config.
Safe by default. Guardrails (cost, blocked) always beat preferences.
Dependency-free. Works without a YAML library; works without PRYSM.
Forward-compatible. Unknown top-level keys are preserved, not rejected — new fields never break old parsers.

Get Started

Core Concepts

SDKs & Tools

Guides

Reference

File location & loading

File format

Field reference

The `rule` object

Routing precedence

Worked example

Signal vocabulary

Validation

Editor autocomplete

Complete example

Design principles

​File location & loading

​File format

​Field reference

​The rule object

​Routing precedence

​Worked example

​Signal vocabulary

​Validation

​Editor autocomplete

​Complete example

​Design principles

File location & loading

File format

Field reference

The `rule` object

Routing precedence

Worked example

Signal vocabulary

Validation

Editor autocomplete

Complete example

Design principles