Model routing for Pi
Stop switching models by hand.
Choose which of your Pi models can handle quick work and demanding work. Bifrost picks from your list, then Pi runs that model.
Pi · Bifrost loaded
/model
selected: bifrost/auto
quick commit these changes
Bifrost auto: quick → example/fast-model
Pi runs example/fast-model
tool continuation → same physical model
No matching commands.
↑ ↓ select · Enter play · Esc close
Illustrative model IDs and output. No provider requests.
01 / Pi-native virtual model
Auto routes inside Pi, not through a proxy.
Run /model in Pi and select bifrost/auto. For each new user turn, Bifrost chooses from your configured models. Pi dispatches the physical model and records which model answered.
Tool continuations stay with that physical model. Selecting Auto is deliberate; normal routing instead sets Pi's active physical model before generation.
02 / Persistent failure circuit
Failed model? Skip it on the next turn.
After repeated failures within your configured window, Bifrost opens that model's circuit. It excludes the model from new routing decisions and can choose another healthy model from your list.
The circuit survives a restart. After cooldown, one controlled trial checks recovery. Set thresholds under reliability in .pi/bifrost.json. Bifrost never replays the failed user prompt.
This scene shows the third failure with the default threshold, then a separate new user turn. See reliability rules.
03 / Classifier choice
Choose who decides the group.
Run /bifrost classifier to choose a Pi chat model, TypeSafe/Jev, or Pi's native classifier API. Pi-native appears only on hosts that support classification. Run /bifrost classifier off to use rules and the default group without a classifier.
A classifier chooses a group such as quick or frontier. It does not choose your provider model. Your pools, reliability circuit, and selection strategy make that decision.
An omitted backend can be detected from credentials; an explicit backend overrides detection. Classifier requests can incur usage. Compare backends.
More of Bifrost
Everyday tools, each with its own terminal scene.
Scroll through them, or jump to one. Nothing is tucked away.
04 / Default route
Pi switches models before the prompt.
After /bifrost init, send a normal message with routing on and no pin. Bifrost selects a tier, skips unhealthy candidates, and sets Pi's active provider/model before generation. You do not need to select Auto.
05 / Setup
Probe, propose, then review.
Run /bifrost init inside Pi. It reuses recent probe results or tests available models, then proposes groups. Review the model IDs before you confirm writing .pi/bifrost.json, especially if the file already exists. Probes can incur provider usage or rate limits.
06 / Explicit routes
Use rules, a direct model, or a tier prefix.
Each rule in .pi/bifrost.json has a text pattern and a model value. Below, quick means “choose from the quick pool.” example/deep-model means “use this exact model,” without a tier strategy.
{
"rules": [
{ "pattern": "commit",
"model": "quick" },
{ "pattern": "security audit",
"model": "example/deep-model" }
]
}Replace example/deep-model with a model ID available in Pi. The commit rule can select quick if no earlier tier choice wins. To force quick for one unpinned turn, type quick commit the changes. Bifrost removes quick before the model sees it.
07 / Your selection policy
Pick how each group chooses a model.
Set categoryStrategies in .pi/bifrost.json. This example makes the quick pool choose the healthy model with the lowest combined input and output price:
{
"categoryStrategies": {
"quick": "cheapest"
}
}Other choices include first, largest_context, and random. fastest uses list order, not live speed. Init can sort that list using one-time probe results. Open circuits are removed first.
08 / Check before sending
Preview the actual model.
Run /bifrost preview security audit this code in Pi. It shows the chosen tier, model, source, and exclusions without starting a generation turn or switching Pi's active model. An enabled classifier can receive the preview text and incur usage. Preview does not treat a leading tier name as an override. Pass --json before the prompt for a machine-readable report.
09 / Manual control
Pin, unpin, or switch routing off.
Run /bifrost pin to keep the current physical model for this session. Even a tier prefix stays in the prompt while pinned. Run /bifrost unpin to resume routing. Selecting a physical model in Pi's /model picker also pins it.
Run /bifrost off to stop routing, then /bifrost on to resume. On/off survives a restart; a pin does not. Pin or off while Auto is selected switches back to a physical model.
10 / Local classification cache
Reuse a tier decision, not an answer.
Run /bifrost cache stats to inspect stored tier decisions or /bifrost cache clear to remove them. To disable this cache, set "cache": { "enabled": false } in .pi/bifrost.json and run /bifrost reload. Normalized prompt words can contain sensitive text. Bifrost never caches generated answers.
11 / Inspect
See status and local diagnostics.
Run /bifrost debug to see effective routing settings and open-circuit count. To record local JSONL events, set "debug": { "enabled": true } in .pi/bifrost.json and run /bifrost reload. Normal traces omit raw prompt bodies.
Routing stays bounded by configuration.
Tier arrays define eligibility. Per-tier strategies choose among healthy candidates. Optional semantic judgment decides only which configured tier fits the prompt.
{
"models": {
"quick": ["provider/fast-model", "provider/backup-fast"],
"general": ["provider/general-model"],
"frontier": ["provider/frontier-model"]
},
"categoryStrategies": {
"quick": "cheapest",
"general": "first",
"frontier": "largest_context"
}
}Another view of classification
What TypeSafe/Jev sees.
This optional backend receives your current prompt and tier criteria, not your provider model pool. It returns a tier, probabilities, and confidence. Confidence does not prove the tier is correct.
Jev sees the current prompt and configured tier criteria, not Bifrost's provider model pool.
Another view of Auto
From virtual selection to physical model.
Watch the same Pi-native dispatch as a route. The terminal above shows what you see in Pi.
Auto starts only when you select it in Pi's model picker.
Illustrative route. No model or provider request is sent.Get started
Your models. Your route.
Use Pi 1.0.1 or newer with at least one authenticated provider model.
-
01
Install Bifrost
Run this in your shell, then open Pi.
pi install npm:pi-bifrost -
02
Set up your model groups
Run this inside Pi. It probes available models, which can incur provider usage or rate limits. Review the proposal before confirming it.
/bifrost init
Two independent choices: /bifrost classifier changes how Bifrost picks a tier; selecting bifrost/auto in Pi's model picker changes how Pi dispatches the chosen model. Use either, both, or neither. Rules work without a classifier.
Four useful answers
Detailed setup and reference material lives in the versioned guide.
Do I need an LLM classifier?
No. A tier name at the start of a message, regex rules, or the configured default can route without another model call. Prompt classifiers are optional when semantic tier judgment adds value. Choose a prompt, Pi-native, or TypeSafe backend.
When should I avoid adaptive routing?
Pin one exact model when a long session builds on the same context, prompt-cache locality matters, or switching would disrupt latency, billing, or workflow expectations. Adaptive routing trades continuity for per-turn task fit. It does not guarantee better results, lower cost, lower latency, or cache savings.
Does routing affect provider prompt caching?
It can. Treat every provider/model pair as an independent cache history. Returning to a model may reuse its longest still-valid prefix, while newer conversation content remains an uncached tail. Bifrost does not manage provider caches. Read the dedicated A → B → A and N-switch guide.
What happens when a model fails?
Bifrost records the failure, opens a circuit after the configured threshold, and excludes that model from future routes until a controlled recovery trial. It never automatically replays the failed prompt.