Model Router Extension

Intelligent per-turn model router for the pi coding agent. Automatically selects between high, medium, and low-tier LLMs based on task intent, session budget, context size, and custom rules.

Quick Start

# 1. Create a config from the example
/router init

# 2. Enable the router with the default profile
/router enable

# 3. Or switch to a specific profile
/router profile balanced

# 4. Check status
/router status

Configuration

The router reads config from:

• Global: ~/.pi/agent/model-router.json (created by /router init)
• Project: .pi/model-router.json (relative to your workspace root)

Project config overrides global config.

What it does

• Logical Router Provider: Registers a router provider that exposes stable profiles (e.g., router/balanced) as models.
• Per-Turn Routing: Intelligently chooses between high, medium, and low tiers for every turn based on task intent and complexity.
• Task-Aware Heuristics: Detects planning vs. implementation vs. lightweight tasks using keyword analysis, word count, and conversation history.
• LLM Classifier: Optionally uses a fast, cheap model to categorize intent (overrides heuristics).
• Advanced Controls: Custom rules, cost budgeting, fallback chains, phase memory, and thinking level overrides.
• Per-Profile Classifier: Each profile can override or disable the global classifier. Set classifierModel: false on a profile to skip classification entirely (useful for profiles like openrouter-auto where all tiers use the same model).
• Upstream Model Visibility: For aliases such as openrouter/auto, the widget, /router status, and debug history show the concrete model reported by the provider after each response.

Installation

Install it alone:

pi install npm:@lucascaro/pi-model-router

It is also included in the batteries-included @lucascaro/pi-devkit package. Choose one package by default; installing both can load the router twice. After installation, run /router init to create a configuration.

Basic Config Shape

{
  "classifierModel": "google/gemini-flash-latest",
  "maxSessionBudget": 1.0,
  "profiles": {
    "balanced": {
      "high": { "model": "openai/gpt-5.4", "thinking": "high", "fallbacks": ["anthropic/claude-sonnet-4-6"] },
      "medium": { "model": "anthropic/claude-sonnet-4-6", "thinking": "medium" },
      "low": { "model": "google/gemini-flash-latest", "thinking": "low" }
    }
  }
}

Configuration Fields

Commands

Profiles

Ship with three default profiles:

• balanced — GPT-5.4 for high, Sonnet for medium, Gemini Flash for low.
• cheap — All tiers use budget models (Flash/Haiku).
• deep — GPT-5.4 with xhigh thinking for high, Sonnet for medium, Flash for low.

Architecture

The router uses a tiered decision flow:

1. Budget Check — Downgrade to medium if maxSessionBudget is exceeded.
2. Manual Pin — Use tier pinned via /router pin or /router fix.
3. Custom Rules — Check keyword-based rules against the user prompt.
4. LLM Classifier — Call classifierModel for intent categorization (optional).
5. Heuristics — Use local heuristics (keyword detection, phase stickiness) as fallback.
6. Phase Bias — Apply stickiness to maintain a consistent tier during multi-turn tasks.

Extensibility

• New profiles: Add entries to the profiles object in the config file.
• New rules: Add entries to the rules array with matches keywords and tier.
• Model aliases: Define aliases in the models object for reuse across profiles.
• Custom classifier: Change classifierModel to any fast model for intent detection.