pi-models-provider0.1.0

Pi extension for discovering models.dev-compatible provider models

dreamacro Published 7 days ago MIT ~363 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

pi-models-provider

Pi extension that discovers models from provider endpoints returning a models.dev-compatible { "models": {} } response.

Features

Registers multiple dynamic pi providers from one configuration file
Queries /v1/models with User-Agent: pi/models-fetch/<version>
Supports discovery request headers and same-origin Bearer authentication
Projects models.dev metadata into pi model configuration
Supports ordered include rules, per-rule API overrides, and exclusion rules
Uses pi's provider-scoped model store for offline and failed-refresh fallback

Installation

Requires pi 1.0 or newer.

Install the package as a global pi package:

pi install npm:pi-models-provider

For local development:

npm install
pi -e ./src/index.ts

Configuration

Create ~/.pi/agent/extensions/models-fetch.json for global configuration or .pi/models-fetch.json for project overrides:

{
  "providers": {
    "gateway": {
      "name": "AI Gateway",
      "baseUrl": "https://gateway.example.com/v1",
      "apiKey": "$GATEWAY_API_KEY",
      "api": "openai-completions",
      "discoveryHeaders": {
        "X-Tenant": "tenant-name"
      },
      "include": [
        {
          "match": "^claude",
          "api": "anthropic-messages"
        },
        {
          "match": "^(gpt|o[134])",
          "api": "openai-responses"
        }
      ],
      "exclude": ["embedding", "deprecated"]
    }
  }
}

Project providers override global providers with the same ID. Set PI_MODELS_FETCH_CONFIG to use one explicit configuration path instead. The global path follows pi's configured agent directory, including PI_CODING_AGENT_DIR; project paths follow pi's configured project directory name.

Provider options

Option	Default	Description
`name`	provider ID	Display name
`baseUrl`	required	Provider API base URL
`apiKey`	none	Literal key or `$ENV_VAR`/`${ENV_VAR}`
`api`	`openai-completions`	Default pi API
`headers`	`{}`	Headers used for model inference requests
`authHeader`	`true`	Add Bearer authentication to inference requests
`endpoint`	`/v1/models`	Relative or absolute discovery endpoint
`discoveryHeaders`	`{}`	Headers used only for discovery
`include`	`[]`	Model-key allow-list; object rules may override `api`
`exclude`	`[]`	Model-key regular expressions; exclusion wins
`timeoutMs`	`10000`	Discovery timeout
`cache`	`true`	Persist the last successful catalog through pi
`cacheTtlSeconds`	`86400`	Fresh-cache lifetime before startup refresh

An absolute cross-origin discovery endpoint never receives apiKey automatically. Set an explicit Authorization value in discoveryHeaders when required. Set discoveryHeaders.User-Agent to override the default pi/models-fetch/<version> user agent.

Refresh command

Force refresh every configured provider:

/models-fetch:refresh

Force refresh one provider:

/models-fetch:refresh hfai

The model cache is stored by pi in getAgentDir()/models-store.json (normally ~/.pi/agent/models-store.json). A fresh cache is reused during pi-managed refreshes; stale cache remains available when refresh fails.

Response format

{
  "models": {
    "claude-sonnet": {
      "id": "claude-sonnet",
      "name": "Claude Sonnet",
      "reasoning": true,
      "reasoning_options": [{ "type": "effort", "values": ["none", "low", "medium", "high"] }],
      "limit": {
        "context": 200000,
        "output": 64000
      },
      "modalities": {
        "input": ["text", "image"]
      },
      "cost": {
        "input": 3,
        "output": 15,
        "cache_read": 0.3,
        "cache_write": 3.75
      },
      "provider": {
        "api": "anthropic-messages"
      }
    }
  }
}

Models.dev reasoning_options entries with type: "effort" are projected to pi's model-level thinkingLevelMap. Unsupported or unlisted levels are hidden; none maps to pi's off level. Toggle-only and token-budget controls remain adapter-specific.

Each key in the discovered models object is used as both the pi model ID sent to the provider and its display name. Nested id and name fields do not override the key.

Missing metadata uses pi defaults: text input, a 128K context window, 16K maximum output, and zero cost.