pi-model-failover

Pi extension that provides failover to an alternative provider/model.

Packages

Package details

extension

Install pi-model-failover from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-model-failover
Package
pi-model-failover
Version
1.0.0
Published
Aug 27, 2026
Downloads
145/mo · 145/wk
Author
ashlatham
License
MIT
Types
extension
Size
10.3 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "./model-failover.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-model-failover

Auto-switches to a preconfigured failover model when the primary model fails with a transient or connection error. Inspired by the "AI resilience" pattern in OpenAI-failover setups and operational runbooks for unreliable upstream APIs.

Features

Context replay — On model failover, captures the most recent user message from the session and re-queues it as a followUp after the swap. The failed turn is not lost, and prior assistant context upstream of the switch is preserved.

Modeled on the primary's failure — Inspects the last assistant message's errorMessage for shape and only switches when it matches a configured pattern. A successful primary never triggers a failover.

Reason surfacing — Distinguishes no target registered (model not in models.json), no API key for failover (setModel refused), and no prior user message to replay. Each gets its own level (error/error/warning) so they show up differently in the UI.

Two pattern sets —

  • transient (default) — delegates to pi-ai's isRetryableAssistantError: connection, 5xx, 429, timeout, fetch failed, etc.
  • connection — narrow /connection error/i regex for tunnels and proxies that bubble up as plain strings. Note: transient deliberately does not switch on hard quota/billing errors (insufficient_quota, quota exceeded, out of budget, billing, Monthly usage limit reached, available balance, OpenCode GoUsageLimitError / FreeUsageLimitError). Those signal the user needs to top up, not that the network is flaky, and silently falling back would hide the real problem.

Installation

Install from npm:

pi install npm:pi-model-failover

Install into the current project only:

pi install npm:pi-model-failover -l

Or install from GitHub:

pi install git:github.com/eiei114/pi-model-fallback

Try it without permanently installing:

pi -e npm:pi-model-failover

Configuration

Copy model-failover.example.json to: <cwd>/.pi/model-failover.json (project) or ~/.pi/agent/model-failover.json (global):

{
  "failover": { "provider": "providerID", "model": "modelID" },
  "patterns": "transient"
}
  • failover.provider / failover.model — required. Must resolve in your models.json or the failover is skipped with an error.
  • patterns — "transient" (default) or "connection".

Usage

Activates automatically. No slash command; tuning is by config file.

Notification levels in Pi's UI:

  • info — config active on session start (model-failover: → provider/modelID)
  • warning — failover engaged, or switched model with no prior user message to replay
  • error — failover model not found in registry, or setModel refused the switch (e.g. missing API key)

Links

License

MIT