StarRouter for Pi

StarRouter is a focused model-routing extension for Pi. It chooses the best available model and thinking level for each prompt using a deterministic heuristic prompt profiler, Artificial Analysis benchmark data, provider-scoped model pools, strict model identity matching, and an explicit confirmation UI.

The V1 goal is intentionally narrow: make routing trustworthy, explainable, and easy to control. StarRouter does not call a hidden classifier model before your prompt, does not expose policy-profile sprawl, and does not auto-switch unless you explicitly allow it.

---

Install

Install from npm as a Pi package:

pi install npm:@ketchh/pi-star-router

Reload the current Pi session:

/reload

Open settings and enable routing:

/router settings
/router on

Try it without a global install:

pi -e npm:pi-star-router

---

Command surface

StarRouter keeps the public command surface small:

/router status
/router on
/router off
/router refresh
/router settings

Command	What it does
/router status	Shows whether the router is enabled and summarizes the latest route decision.
/router on	Enables routing for future turns.
/router off	Disables routing and leaves model selection manual.
/router refresh	Refreshes the cached Artificial Analysis dataset.
/router settings	Opens the interactive settings UI.

Routing is off by default. You opt in when you want StarRouter to choose.

---

What happens before a turn

When routing is enabled and you submit a prompt, StarRouter runs this pipeline:

1. Profile the prompt locally

   • detects coding, debugging, architecture, research, structured output, long-context, vision, simple-output, and mechanical-transform signals;
   • estimates complexity and routing tier;
   • picks a target thinking level.

2. Choose benchmark weights

   • maps the prompt to relevant Artificial Analysis metrics such as Coding, Terminal-Bench Hard, IFBench, GDPval, Tau2, GPQA, or AA-LCR.

3. Scope the candidate pool

   • compares only models from the configured provider;
   • applies benchmark-safe family/model filters;
   • generates candidates only for thinking levels the Pi model actually supports.

4. Match Pi models to Artificial Analysis rows

   • checks vendor, family, subfamily, generation, moving aliases, variant level, and host affinity;
   • allows explicit model overrides for known provider/AA naming drift.

5. Score candidates

   • blends benchmark fit, estimated cost, latency, speed, context window, model specialization, and thinking-level fit.

6. Apply hard constraints

   • filters text-only models for vision prompts;
   • applies long-context requirements;
   • enforces thinking floors/caps for difficult or simple tasks;
   • abstains if confidence is too low.

7. Ask before switching

   • by default, StarRouter opens a route confirmation panel;
   • you can keep the current model with Esc, or accept the focused route with Enter.

8. Explain the decision

   • a compact widget shows the selected model, thinking level, confidence, benchmark fit, and trade-off summary.

---

Core features

Deterministic heuristic prompt profiler

StarRouter’s profiler is local and deterministic. It uses modular English and Italian dictionaries plus structural signals such as code blocks, file mentions, list fan-out, prompt length, images, and long-context phrases.

It produces:

• routingTier: booster, simple, standard, complex, or frontier;
• complexityScore;
• matched signals;
• benchmark weights;
• priorities for cost, speed, reasoning, context, vision, tool use, and format reliability;
• target thinking level;
• Artificial Analysis prompt-length profile.

Because no classifier model is called, routing adds no hidden provider latency and no hidden classification cost.

Provider-scoped routing

StarRouter compares models only inside one provider scope, for example openrouter or github-copilot.

This keeps decisions understandable: if your provider is GitHub Copilot, StarRouter chooses among GitHub Copilot models; if your provider is OpenRouter, it chooses among OpenRouter models.

Strict Artificial Analysis matching

Model routing is only as good as benchmark matching. StarRouter uses strict identity gates before a Pi model can use an Artificial Analysis row:

• vendor match;
• family match;
• subfamily match where relevant;
• generation/version compatibility;
• moving-alias protection for names such as latest, auto, and free;
• variant-level compatibility for reasoning and non-reasoning rows;
• host affinity when provider data is available.

Examples of matches StarRouter rejects by default:

• GLM borrowing Claude benchmark rows;
• Claude Sonnet borrowing Claude Haiku rows;
• Hermes 3 borrowing Hermes 4 rows;
• kimi-latest silently pinning itself to a fixed Kimi generation.

When a provider name legitimately differs from an AA slug, use modelOverrides to pin it explicitly.

Benchmark-safe filters

Large catalogs can contain free endpoints, auto routers, deprecated aliases, or long-tail models that do not map cleanly to benchmark data. StarRouter includes filter presets such as:

• benchmark-safe
• frontier-safe
• coding-safe
• budget-safe

Presets are templates, not locks. You can apply a preset, then use the model filter screen to enable or disable families and individual models.

Route confirmation panel

With auto-accept off, StarRouter shows an overlay before switching:

• current route;
• recommended route;
• top candidates;
• benchmark fit;
• route score;
• cost score;
• latency score;
• context score;
• confidence;
• short reason bits.

Keyboard controls:

↑↓      focus a route
Space   mark a route
Enter   choose the focused route
Esc     keep the current route

Decision widget

After a route is applied, StarRouter shows a compact widget above the editor with:

• selected provider/model/thinking level;
• confidence;
• selected objective;
• benchmark summary;
• AA match;
• fit/cost/speed/latency/context trade-off;
• short explanation of why the route won.

---

Routing objectives

StarRouter supports four ranking objectives:

Objective	Use it when
balanced	Default. Good fit/cost/speed trade-off for everyday agent work.
quality	Hard debugging, architecture, research, or high-stakes coding.
cheapest	Bulk, repetitive, low-risk prompts where cost matters most after constraints.
fastest	Interactive work where latency matters more than absolute quality.

For a polished first experience, keep balanced as the default and change objectives only when you have a clear reason.

---

Example configuration

StarRouter loads configuration from:

• global: ~/.pi/agent/model-router.json
• project: .pi/model-router.json

Project settings override global settings.

{
  "enabled": false,
  "strategy": {
    "objective": "balanced",
    "qualityFloor": 0.88,
    "preferCurrentWithin": 0.04,
    "minAaMatch": 0.52,
    "minRouteConfidence": 0.42,
    "routingProvider": "github-copilot"
  },
  "ui": {
    "showAdvancedSettings": false,
    "autoAcceptRouting": false
  },
  "filters": {
    "providers": {
      "openrouter": {
        "preset": "benchmark-safe",
        "disabledFamilies": [],
        "disabledModels": []
      }
    }
  }
}

See model-router.json.example for the full example, including data-source defaults and model overrides.

---

Competitive data

The latest validation data in this repo showed strong savings against a frontier-baseline mix while preserving hard constraints.

Projected monthly totals vs frontier baseline mix

Objective	Router monthly	Baseline monthly	Savings USD	Savings %
balanced	$305.26	$1,259.40	$954.14	75.76%
cheapest	$143.88	$1,259.40	$1,115.52	88.58%
quality	$575.25	$1,259.40	$684.15	54.32%

Representative scenario savings

Scenario	Balanced monthly	Baseline monthly	Savings %
Mechanical transform	$3.02	$108.00	97.20%
JSON extraction	$62.50	$675.00	90.74%
Routine coding	$6.80	$135.00	94.96%
Long-context repo triage	$20.01	$116.00	82.75%
Vision invoice extraction	$2.93	$23.40	87.50%

Example routes from the validation snapshot

Scenario	Balanced route	Cheapest route	Quality route
Mechanical transform	deepseek/deepseek-v4-flash @ off	deepseek/deepseek-v4-flash @ off	deepseek/deepseek-v4-flash @ off
JSON extraction	google/gemini-3.1-flash-lite @ off	google/gemini-3.1-flash-lite @ off	google/gemini-3.1-flash-lite @ off
Routine coding	deepseek/deepseek-v4-flash @ off	deepseek/deepseek-v4-flash @ off	deepseek/deepseek-v4-flash @ medium
Debugging	openai/gpt-5.1-codex @ medium	deepseek/deepseek-v4-pro @ xhigh	openai/gpt-5.1-codex @ medium
Critical architecture	openai/gpt-5.5 @ xhigh	deepseek/deepseek-v4-pro @ medium	openai/gpt-5.5 @ xhigh
Long context	deepseek/deepseek-v4-pro @ medium	deepseek/deepseek-v4-pro @ medium	openai/gpt-5.5 @ xhigh

---

Validation

Run the release checks:

npm test
npm run typecheck
npm run smoke
npm run golden -- tests/fixtures/golden-prompts.json /tmp/golden.json

Current validation targets:

Check	Target
Release tests	38 passing tests
Golden prompt bank	80 passing prompts
TypeScript	strict typecheck passing
Release smoke checks	passing

---

Project structure

index.ts                         Pi extension wiring and runtime flow
src/router-core.ts               config, AA ingestion, matching, scoring, ranking
src/prompt-understanding.ts      deterministic heuristic prompt profiler
src/prompt-dictionaries/         modular EN/IT signal dictionaries
src/route-choice-screen.ts       route confirmation overlay and decision widget
src/settings-screen.ts           searchable settings tree
src/model-filters-screen.ts      provider/family/model filter UI
src/filter-presets/              built-in and saved model filter presets
model-router.json.example        example configuration
docs/index.html                  public HTML presentation page

---

Security and trust model

StarRouter is conservative by design:

• it is disabled until you run /router on;
• it does not call a hidden classifier model before your prompt;
• it asks before switching by default;
• it scopes routing to the configured provider;
• it rejects suspicious benchmark matches;
• it blocks moving aliases unless explicitly overridden;
• it can abstain instead of forcing a low-confidence route.

---

License

MIT