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:[email protected]

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