# Pi Model Router (`@suaiva/pi-model-router`)

> Declarative modular model router, multi-account rotation pools, dynamic compute escalation & WAF fingerprint spoofing for Pi and Oh My Pi.

## Architecture

Instead of maintaining a fragile 300+ line monolithic configuration, Model Router decouples routing into 3 distinct declarative modules:

```text
catalog/
  ├── settings.yml    # Compaction (70% shake), advisor cadences, UI themes
  ├── routing.yml     # modelRoles, tiers, pools, auto-upgrade & fallback chains
  └── providers.yml   # Endpoints, keys, multi-account rotation & WAF headers
```

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                       Pi Dynamic Escalation & Routing                       │
├─────────────────────────────────────────────────────────────────────────────┤
│ 1. Default Primary: Gemini 3.7 Flash / Claude Sonnet 4.6                    │
│    │ (on refusal, complex failure or rate-limit)                            │
│    ▼                                                                        │
│ 2. Dynamic Auto-Upgrade: OpenAI Codex GPT-5.6 Luna:high (Deep Reasoning)    │
│    │ (on subscription / token exhaustion)                                  │
│    ▼                                                                        │
│ 3. Fresh Free Pool: Stealth Ox-Alpha (1M Free) / OpenCode Zen X-Preview     │
│    │ (on daily free-tier rate limits)                                       │
│    ▼                                                                        │
│ 4. Multi-Account Failover: Gateway Pool (Keys 1/2 with WAF Bypass)         │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Features

- **Modular 3-File Catalog**: Separate concerns between system settings, routing topologies, and provider credentials.
- **Dynamic Compute Escalation**: Automatically promotes tough coding turns to `gpt-5.6-luna:high` before dropping to free models.
- **Multi-Account Rotation**: Rotates across multiple API keys per provider (`@account.openrouter.1/2`, `@account.custom-gateway.1/2`) on 429 quota exhaustion.
- **WAF Client Spoofing**: Injects custom client headers (`User-Agent`, `x-client-name`) to satisfy upstream gateway requirements.
- **Free Model Prioritization**: Automatically prioritizes high-context, high-TTFT free models (`stealth/ox-alpha` 1M and `opencode-zen/x-preview-f-free` 1M).

## Installation

```bash
# Install package into Pi
pi install git:github.com/suainam/pi-model-router
# Or from local clone:
pi install ./pi-model-router
```


### Python Dependency
```bash
pip install -r requirements.txt   # PyYAML
```

## Quick Start

### 1. Compile Catalog Projections
```bash
python3 scripts/render_config.py \
  --source templates/catalog \
  --config ~/.pi/agent/config.yml \
  --models ~/.pi/agent/models.yml
```

### 2. Probe and Benchmark Free Models
```bash
# Discover free models and run 3-run serial latency benchmark
python3 scripts/probe_free_models.py --runs 3
```

## License

MIT © suainam