> ## 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: declarative model routing for your repo

> One YAML file at your repo root that tells every AI call in the codebase which model to use, what it costs, and what's blocked.

`BRAIN.md` is a routing configuration file you commit to your repo root. Every PRYSM client
that runs in that repo — whether in a CI pipeline, a local dev session, or a production deploy —
auto-discovers it and applies its rules to every LLM call.

Think of it as a `pyproject.toml` for your AI spend.

## A complete BRAIN.md

```yaml theme={null}
# BRAIN.md — model routing rules for this repo
# Spec: https://prysm1.com/brain-md

# Hard cost ceiling — no single request can exceed this
max_cost_per_request: 0.05

# Default routing mode when no rule matches
default_mode: balanced

rules:
  # Coding and code review → code-optimized model
  - when: "code"
    model: "claude-sonnet-4.5"

  # Math proofs and formal reasoning → best reasoning model
  - when: "reasoning"
    model: "deepseek-r1"

  # Real-time questions (news, weather, stock prices) → search-grounded
  - when: "realtime"
    model: "sonar"

  # Translations → budget multilingual
  - when: "translate"
    routing_mode: agility

  # Summaries → cheapest model that can read long context
  - when: "summarize"
    routing_mode: agility

# These models are never selected, even if the router would otherwise pick them
blocked:
  - gpt-5.2-pro    # Too expensive for this project
```

## How PRYSM applies the rules

When you call `client.complete()` or `client.chat.completions.create()`, PRYSM:

1. Loads `BRAIN.md` from the nearest ancestor directory (or from env `PRYSM_BRAIN_PATH`).
2. Classifies the prompt's intent against the ten signal dimensions.
3. Walks the `rules` list in order and applies the first match.
4. Checks `max_cost_per_request` — if the chosen model's estimated cost exceeds the ceiling,
   downgrades to the next eligible model.
5. Removes any `blocked` models from the candidate set.

```python theme={null}
from prysm import Prysm

# BRAIN.md is auto-discovered from the current directory or its ancestors.
client = Prysm()

# This call is classified as "reasoning" → routes to deepseek-r1
resp = client.complete("Prove that every even integer > 2 is the sum of two primes")
print(resp.choices[0].message.content)

# This call is classified as "code" → routes to claude-sonnet-4.5
code = client.complete("Refactor this class to use dataclasses", model="auto")
```

## Validating your BRAIN.md before committing

```python theme={null}
result = client.validate_brain(open("BRAIN.md").read())
print(result["valid"])     # True
print(result["warnings"])  # ['model "claude-sonnet-4.5" is premium — consider "claude-haiku-4.5" for cost']
```

Or via the CLI:

```bash theme={null}
prysm brain validate BRAIN.md
# ✓ BRAIN.md is valid
# 2 warnings: ...
```

## Sharing BRAIN.md with your team

```python theme={null}
url = client.brain_share(open("BRAIN.md").read(), title="My cost-safe dev config")["short_url"]
print(url)   # https://prysm1.com/b/abc123def456
```

```markdown theme={null}
<!-- Embed in your README -->
[![BRAIN.md](https://api.prysm1.com/v1/brain/badge?model=deepseek-r1)](https://prysm1.com/b/abc123def456)
```

Anyone — including other AI agents reading your README — can fetch the config:

```bash theme={null}
curl https://api.prysm1.com/v1/b/abc123def456
# {"config": {"max_cost_per_request": 0.05, "rules": [...], "blocked": [...]}}
```

## CI integration: cost-gate your PRs

```yaml theme={null}
# .github/workflows/ai-cost-gate.yml
- name: Validate AI routing config
  run: |
    pip install prysm1
    python -c "
    from prysm import Prysm
    c = Prysm()
    r = c.validate_brain(open('BRAIN.md').read())
    if not r['valid']:
        print('BRAIN.md is invalid:', r['errors'])
        exit(1)
    print('BRAIN.md OK')
    "
```

## The BRAIN.md ecosystem

`BRAIN.md` is an open specification. Any PRYSM-compatible routing engine can consume it. The
spec lives at [prysm1.com/brain-md](/concepts/brain-md), and the community shares configs at
[prysm1.com/b](https://prysm1.com) via `prysm brain share`.