---
name: model-router
description: Manage and audit declarative modular catalog routing, multi-account rotation pools, dynamic Luna compute escalation, and WAF fingerprint spoofing for Pi and OMP.
---

# Pi Model Router

Declarative 3-module catalog routing with resilient fallback, multi-key account rotation, dynamic compute escalation, and client fingerprint spoofing.

## Core Directives

1. **Modular 3-Module Source of Truth**:
   - `catalog/settings.yml`: Compaction policies (70% shake), advisor cadences, UI themes.
   - `catalog/routing.yml`: Role bindings (`default`, `plan`, `slow`, `smol`, `task`), tiers, pools, and fallback chains.
   - `catalog/providers.yml`: Custom third-party endpoints, multi-key accounts, and headers.
   - Generated files (`config.yml`, `models.yml`) are strictly read-only projections.

2. **Compute Escalation Hierarchy**:
   - Default Coding: Fast/light model (`gemini-3.7-flash` / `claude-sonnet-4-6`).
   - Dynamic Escalation: Auto-upgrade to `gpt-5.6-luna:high` on complex failure/refusal before falling back to free tiers.
   - Free Tier Safety Net: `stealth/ox-alpha` (1M context) & `opencode-zen/x-preview-f-free` prioritize the free pool.

3. **Gateway Anti-Bot & Fingerprint Spoofing**:
   - Third-party gateways enforcing WAF client white-lists can configure custom `User-Agent` and client identification headers in `providers.yml`.

4. **Multi-Account Failover**:
   - Account pools (e.g. `@account.openrouter.1`, `@account.openrouter.2`, `@account.custom-gateway.1..2`) automatically rotate across keys on 429 quota exhaustion.

## Quick CLI Usage

```bash
# Render modular catalog into runtime projections
python3 scripts/render_config.py --source templates/catalog --config config.yml --models models.yml

# Probe and benchmark free models with 3-run serial verification
python3 scripts/probe_free_models.py --runs 3
```