# Pi-Bifrost examples

These recipes show decisions Bifrost can automate. They are templates, not universal model lists. Replace model patterns with models available in your Pi registry.

## Reliability: circuit breaker for flaky models

Adds model health tracking and automatic fallback. Models with repeated failures are skipped temporarily (circuit open). Probes close circuits on success.

```json
"reliability": {
  "enabled": true,
  "failureThreshold": 3,
  "windowMinutes": 5,
  "cooldownMinutes": 60
}
```

**What this does:**
- Records probe failures and runtime failures (`setModel` errors)
- Opens circuit after `failureThreshold` failures in `windowMinutes`
- Skips open-circuit models, falls back to default tier
- Circuit closes on successful probe or timeout (`cooldownMinutes`)
- Persists breaker state in `.pi/bifrost-reliability.json`

See full example: `economical-frontier-reliability.json`

## Recipes

### `economical-frontier-reliability.json`

Extends `economical-frontier.json` with reliability configuration.

Try:

```text
/bifrost preview fix this race condition
/bifrost preview summarize this file
```

If a model fails repeatedly (e.g., network timeout or auth error), it will be skipped temporarily and the system falls back to the default tier.

## Install Bifrost first:

```text
pi install npm:pi-bifrost
/bifrost init
```

Copy a recipe to `.pi/bifrost.json`, then reload:

```text
/bifrost reload
```

Preview before sending:

```text
/bifrost preview fix the race condition in the worker queue
```

## Recipes

### `rules-only-local.json`

Use when prompts must stay local or routing should never make an extra classifier call.

- Disables the LLM classifier.
- Uses ordered regex rules.
- Routes complex work to a local frontier tier.
- Falls back to `economical` when no rule matches.

Try:

```text
/bifrost preview explain what this function does
/bifrost preview fix this race condition
```

Tradeoff: deterministic and private, but rules only understand patterns you define.

### `economical-frontier.json`

General-purpose setup for using cheap models by default and stronger models for harder work.

- Optional classifier handles prompts regex rules do not describe well.
- Economical tier selects by combined cost.
- Frontier tier selects the largest available context window.
- Classification cache reduces repeated classifier calls.
- Regex remains the fallback path.

Try:

```text
/bifrost preview summarize this file
/bifrost preview design a retry strategy for this distributed worker
```

Tradeoff: better coverage for ambiguous prompts, with possible classifier tokens and latency on cache misses.

### `large-context.json`

Use when repository analysis, migrations, logs, or long conversations need a dedicated context tier.

- Adds `quick`, `deep`, and `long-context` tiers.
- Uses `largest_context` for deep and long-context work.
- Routes explicit large-input prompts before general debugging rules.

Replace `provider/replace-with-large-context-model` with an installed model.

Try:

```text
/bifrost preview analyze the whole repository for duplicated authorization logic
/bifrost preview summarize this 20000-line log
```

Tradeoff: large-context models may cost more or respond slower.

### `exact-bindings.json`

Use when certain operations must always use a specific model.

- Direct `provider/id` rules bypass tier selection.
- Commits and release notes can use a dependable model.
- Tests and formatting can use a fast local model.
- Security prompts can route to the frontier tier.

Try:

```text
/bifrost preview write the changelog for this release
/bifrost preview run through this security audit
```

Tradeoff: exact bindings are predictable but less flexible when model availability changes.

### `task-aware-routing.json`

Use when you want fine-grained routing across many task types without maintaining per-project rules.

- 14 categories: `architecture`, `implementation`, `debugging`, `code_review`, `reasoning`, `frontend`, `testing`, `summarisation`, `writing`, `quick`, `long_context`, `free_pool`, `premium`, and `general`.
- Per-category selection strategies (e.g. `cheapest_input` for summarisation, `largest_context` for long_context).
- Task-tuned classifier system prompt and regex fallback rules.
- Model lists use placeholder `provider/...` patterns — replace them with models from your Pi registry.

Try:

```text
/bifrost preview review this pull request
/bifrost preview debug this memory leak
/bifrost preview summarize these logs
/bifrost preview use a free model only
```

Tradeoff: more categories to maintain, but routing matches task shape closely.

### `subscription-balance-frontier.json`

Use when frontier capacity comes from subscriptions such as OpenAI/Codex and Google/Antigravity, with paid OpenRouter-compatible models reserved as fallback.

- Uses `subscription_balance` only for the frontier tier.
- Favors the subscription provider with more weekly allowance remaining.
- Moves toward even selection as remaining allowances approach equilibrium.
- Gives paid-credit candidates zero weight while any measured subscription remains above `reservePercent`.
- Degrades to neutral routing when telemetry is stale or unavailable.

Replace every model placeholder with models available in your Pi registry.

### `advanced-classifier-prompt.json`

Use when the built-in classifier prompt is too terse for your workflow and you want the LLM to route by task intent rather than isolated keywords.

- Overrides `classifier.systemPrompt` with a detailed 3-tier task description.
- Keeps the same `quick` / `general` / `frontier` model tiers as the default config.
- Works best when the classifier model is capable enough to follow nuanced instructions.

Try:

```text
/bifrost preview design a migration strategy for this database
/bifrost preview write unit tests for this function
/bifrost preview format this json
```

Tradeoff: more tokens per classification, but sharper routing on ambiguous prompts.

### `project-routes.json`

Use when each repository needs different routing rules.

Rename it to `.pi/bifrost-routes.json` inside a project. It overrides the `rules` array from the main config while keeping the same model tiers.

The example separates frontend, backend, and infrastructure work. Add matching tiers to `.pi/bifrost.json` first:

```json
{
  "models": {
    "frontend": ["provider/frontend-model"],
    "backend": ["provider/backend-model"],
    "infrastructure": ["provider/infrastructure-model"]
  }
}
```

Try:

```text
/bifrost preview make this layout responsive
/bifrost preview add an index for this query
/bifrost preview update the deployment pipeline
```

Tradeoff: project-local rules keep routing relevant, but they need maintenance as the repository changes.

## Manual control

Automation is always reversible:

```text
frontier implement the auth module
/bifrost pin
/bifrost unpin
/bifrost classifier off
/bifrost classifier on
```

Use `/bifrost preview` before changing rules. Use `/bifrost debug` to inspect loaded tiers and rules, `/bifrost benchmark` to compare per-tier candidates, and `/bifrost probe` to check which models respond.

## Strategy cookbook

Set a global strategy or override it per tier:

```json
{
  "strategy": "first",
  "categoryStrategies": {
    "quick": "cheapest",
    "deep": "largest_context",
    "latency-sensitive": "fastest",
    "load-balanced": "random",
    "frontier": "subscription_balance"
  }
}
```

- `cheapest`: lowest combined input and output cost.
- `cheapest_input`: lowest input cost.
- `cheapest_output`: lowest output cost.
- `largest_context`: largest context window.
- `first`: first available candidate in list order.
- `fastest`: probe-sorted first candidate.
- `random`: random available candidate.
- `subscription_balance`: weighted subscription selection using fresh weekly quota telemetry; paid-credit providers unlock after subscriptions reach reserve.