pi-provider-service-tier

A Pi extension that lets you choose an API service_tier per provider/model.

Use it when you want to turn on faster or paid priority tiers for one model without changing your prompts, tools, selected model, or the rest of your Pi setup.

What it does

• Adds a top-level service_tier field to outgoing provider request payloads.
• Scopes settings to the current provider/model pair.
• Supports project-local settings and user-global defaults.
• Provides simple /fast-* commands for service_tier: "priority".
• Keeps a support map so unsupported provider/model pairs are not modified.
• Detects unsupported tier errors and updates the support map.

The extension only injects service_tier when all of these are true:

1. the current provider/model pair is active in the effective config,
2. a service tier is configured for that pair, and
3. the support map says that tier is supported for that pair.

[!NOTE] This extension injects the provider payload field service_tier. For Pi's built-in OpenAI providers, Pi also has an internal serviceTier stream option used for cost accounting. This extension is intentionally broader and payload-hook based, so it does not adjust Pi's internal cost multiplier.

Prerequisites

• Pi installed and available as pi.
• Node.js >=22.
• git, if installing directly from GitHub.
• A provider/model that supports service_tier if you want injection to happen.

Quick start

Option A: install from npm

Install globally for your Pi user settings:

pi install npm:pi-provider-service-tier

Or install only for the current project:

pi install -l npm:pi-provider-service-tier

Restart Pi, or run this inside Pi:

/reload

Then select a provider/model and enable priority mode:

/fast-project on

Check the current project setting:

/fast-project status

Option B: install from GitHub

Install globally for your Pi user settings:

pi install git:github.com/luxmargos/pi-provider-service-tier

Or install only for the current project:

pi install -l git:github.com/luxmargos/pi-provider-service-tier

Option C: clone locally

git clone https://github.com/luxmargos/pi-provider-service-tier.git
cd pi-provider-service-tier
npm install

Load it temporarily for one Pi run:

pi -e .

Or install the local checkout for the current project:

pi install -l .

Restart Pi or run /reload, then enable a tier:

/service-tier-project priority

Verify or remove

List installed Pi packages:

pi list

Remove the user-global npm install:

pi remove npm:pi-provider-service-tier

Remove the project-local npm install:

pi remove -l npm:pi-provider-service-tier

Remove the user-global GitHub install:

pi remove git:github.com/luxmargos/pi-provider-service-tier

Remove the project-local GitHub install:

pi remove -l git:github.com/luxmargos/pi-provider-service-tier

Remove the project-local local checkout install:

pi remove -l .

[!TIP] Do not load the same checkout with pi -e . while it is also installed with pi install -l .. Pi may load duplicate commands with numeric suffixes.

Common usage

Fast mode

Fast mode is a convenience wrapper for enabling service_tier: "priority" for the current provider/model.

Command	Scope	Description
/fast-project	Current project	Toggle priority tier for the current provider/model.
/fast-project on	Current project	Enable priority tier.
/fast-project off	Current project	Disable this extension for the current provider/model in this project.
/fast-project status	Current project	Show the current project setting.
/fast-user	User-global	Toggle priority tier for the current provider/model.
/fast-user on	User-global	Enable priority tier as a user default.
/fast-user off	User-global	Disable the user-global setting for the current provider/model.
/fast-user status	User-global	Show the current user-global setting.

Explicit service tiers

Use these commands when you want a tier other than priority.

Command	Scope	Arguments
/service-tier-project <tier>	Current project	priority, flex, default, auto, scale, off, status
/service-tier-user <tier>	User-global	priority, flex, default, auto, scale, off, status

Examples:

/service-tier-project flex
/service-tier-project off
/service-tier-user priority
/service-tier-user status

Commands apply only to the current provider/model pair. Argument completions are available; type a command plus a space, then press Tab.

Build or refresh the support map

/service-tier-build-map
/service-tier-build-map-all

• /service-tier-build-map updates the support map for the current provider/model.
• /service-tier-build-map-all updates the support map for all models returned by Pi's model registry.

With aggressive probing off, map building uses bundled presets. With aggressive probing on, the extension sends low-token probe requests for each tier and model.

[!WARNING] Aggressive probing can cost money and trigger provider rate limits. It is off by default.

Debug injection decisions

/service-tier-debug on
/service-tier-debug off
/service-tier-debug status

Debug mode is session-local. When enabled, the extension notifies whether each provider request was injected with service_tier or skipped.

Configuration files

This package uses pi-provider-service-tier for package and config-file identity.

Project config:

.pi/extensions/pi-provider-service-tier.json

User-global config:

~/.pi/agent/extensions/pi-provider-service-tier.json

Global support map:

~/.pi/agent/extensions/pi-provider-service-tier-map.json

Project and user configs are merged:

• user config provides defaults,
• project config overrides fields for the same provider/model key,
• provider/model entries that exist only in user config still apply in projects unless overridden.

If you previously used an older local package name, move or copy any existing pi-service-tier*.json files to the filenames above.

Config schema

Example:

{
  "version": 1,
  "aggressiveProbe": false,
  "entries": {
    "openai/gpt-5.5": {
      "active": true,
      "serviceTier": "priority"
    },
    "openai/gpt-4.1": {
      "active": false,
      "serviceTier": "flex"
    }
  }
}

aggressiveProbe defaults to false. Set it manually in either config file. Project config overrides user config for this field.

Support map schema

Example:

{
  "version": 1,
  "entries": {
    "openai/gpt-5.5": {
      "provider": "openai",
      "id": "gpt-5.5",
      "api": "openai-responses",
      "supported": true,
      "tiers": ["priority", "flex", "default", "auto", "scale"],
      "source": "preset",
      "updatedAt": "2026-05-19T00:00:00.000Z"
    }
  }
}

Preset support currently includes:

Provider/API	Models	Tiers
openai + openai-responses	all	priority, flex, default, auto, scale
openai + openai-completions	all	priority, flex, default, auto, scale
openai-codex + openai-codex-responses	probed models in presets/openai-codex.json	priority, default
openai-codex + openai-codex-responses	fallback for other models	priority
opencode-go + openai-completions	probed models in presets/opencode-go.json	model-specific; usually priority, flex, default, auto, scale

Other providers/models are marked unsupported by presets until aggressive probing or future presets add support.

Unsupported tier errors

If a provider returns an error indicating service_tier is unsupported or invalid, the extension:

1. removes that tier from the map entry for the current provider/model,
2. records it in unsupportedTiers,
3. notifies the user, and
4. does not retry the failed request.

Development

git clone https://github.com/luxmargos/pi-provider-service-tier.git
cd pi-provider-service-tier
npm install
npm run check

Local smoke test:

pi -e . --provider openai --model gpt-5.5

npm run check runs TypeScript type checking, Node tests, and npm pack --dry-run to verify the published package contents.

License

MIT