pi-weighted-model-router

Pi extension that selects a model from weighted pools at session start, then keeps the session on that model unless a provider error or input capability requires fallback.

What this is

pi-weighted-model-router balances model and provider usage across weighted pools in Pi. It picks one entry when a session starts, restores that choice on resume when configured, and falls back to another pool candidate on provider errors or unsupported image input.

Features

• Daily balanced weighted selection so weights such as 7 / 2 / 1 stay close to the configured ratio across sessions in the same day.
• Session boundary policy: restore on startup and resume, reselect on new, reload, and fork by default.
• Runtime fallback on provider failure statuses such as 400, 429, 500, 502, 503, and 504.
• Image capability fallback before prompts when the selected model does not support image input.
• Tool model_router_config for agent-guided config updates after confirmation.
• Colon flat commands: /model-router:status, /model-router:next, and /model-router:configure.

Install

From npm:

pi install npm:pi-weighted-model-router

Project-local install:

pi install -l npm:pi-weighted-model-router

Pin a specific version:

pi install npm:pi-weighted-model-router@0.4.3

From a local checkout:

pi install /absolute/path/to/pi-weighted-model-router

For temporary testing:

pi -e npm:pi-weighted-model-router
pi -e /absolute/path/to/pi-weighted-model-router

Quick start

1. Install the package with one of the commands above.
2. Start Pi and run /model-router:configure for guided weight setup, or edit config directly (see docs/usage.md).
3. Check status with /model-router:status.

Config paths:

• Project-local (.pi/settings.json): .pi/weighted-model-router/config.json
• Global install: ~/.pi/agent/weighted-model-router/config.json

For local development in this repository, .pi/settings.json loads the package from ../. Start pi from the repo root and run /reload if a session is already open.

Usage summary

Command	Purpose
/model-router:configure	Guided setup through the agent and model_router_config
/model-router:status	Current pool, model, today's success counts, and config path
/model-router:next	Reselect within the same session without reload

Legacy /model-router with a selection menu and /model-router next remain available for one release; prefer the colon commands above.

Configuration, session boundary tables, manual model overrides, and privacy notes are in docs/usage.md. Concurrency assumptions and mitigations are in docs/RACE_CONDITIONS.md.

Package contents

Path	Purpose
src/	Extension entrypoint and routing logic
docs/	Usage, release, and concurrency decision docs
README.md	Public entrypoint (this file)
SECURITY.md	Vulnerability reporting
LICENSE	MIT license
CHANGELOG.md	Version history

Development

npm install
npm run check

The core selection, ledger, and config logic is testable without starting Pi.

Release

This package uses npm Trusted Publishing with GitHub Actions OIDC — no NPM_TOKEN is required.

npm version patch
git push

On main, .github/workflows/auto-release.yml creates the v<version> tag and GitHub Release, then dispatches .github/workflows/publish.yml to publish to npm.

See docs/release.md for setup details.

Security

Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.

For vulnerability reporting, see SECURITY.md.

Links

• npm: https://www.npmjs.com/package/pi-weighted-model-router
• GitHub: https://github.com/eiei114/pi-weighted-model-router
• Issues: https://github.com/eiei114/pi-weighted-model-router/issues

License

MIT