简体中文

A provider extension toolkit for Pi. It registers LLM providers, discovers model catalogs, tunes requests, and reports cached or explicitly refreshed account status while preserving Pi's native footer.

Adapter contract · Support · Contributing · Changelog · Security

• One Pi Provider Host for registration, status, preflight checks, live checks, and request tuners
• Provider, status, preflight, and tuner Adapter files discovered by one Pi entrypoint on /reload
• Resilient model catalogs with cached online snapshots, bounded background refresh, and failure retention
• Provider-first metadata completed by Pi native manufacturer catalog, with deterministic field-level provenance
• Explicit diagnostics: cached /status, free /status refresh, and potentially billable /status check
• Built-in integrations for Charm Hyper, DeepSeek, Google Gemini, OpenAI Codex, OpenCode Zen, and OpenCode Go
• Status/preflight adapters for the native Pi providers Anthropic, GitHub Copilot, OpenRouter, Groq, and xAI
• Status/preflight adapters for Moonshot (Kimi) international and China platforms, and Hugging Face plan/credits
• Status/preflight adapters for the Vercel AI Gateway (auth, catalog, and credits)
• Catalog preflight adapters for the native Pi providers OpenAI, Anthropic, Mistral, NVIDIA NIM, and Cerebras

Requires Node.js 22.19.0 or newer, Pi, and credentials for the providers you use.

pi install npm:@hyav/pi-provider

1. Configure credentials in Pi. Charm Hyper accepts HYPER_API_KEY or Pi's /login OAuth flow.

2. Select a model, for example:

   /model charm-hyper/deepseek-v4-pro
   

3. Inspect the cached report:

   /status
   

Use /status refresh for free endpoint, authentication, catalog, and account checks. Use /status check only when you explicitly accept a real model request and possible usage charges.

A dynamic Provider whose API key references environment variables keeps its last successful online catalog snapshot and skips network catalog refreshes until those variables or a stored credential are available. Providers without a successful snapshot expose an empty catalog rather than inventing models. This prevents unconfigured Providers from surfacing model-refresh warnings.

Programmatic integrations can configure pricing policies, request timeouts, and provider options through createPiProviderRuntime() or createPiProviderHost(). Programmatic defaults resolve the agent directory from PI_CODING_AGENT_DIR (falling back to ~/.pi/agent); the Pi entrypoint overrides it with Pi's own resolution. Host packages with a custom capability root can call createPiProviderExtension({ adapterRoot, dependencies }). The source definition PiProviderDependencies is authoritative.

Built-in Adapters ship inside the package and are always discovered. User Adapters live under Pi's resolved agent directory and are discovered too:

<agent-dir>/extensions/pi-provider/
  providers/   # provider Adapter files
  status/      # status Adapter files
  preflight/   # preflight Adapter files
  tuners/      # tuner Adapter files

Add, remove, or modify files there, then run /reload to rediscover them without touching the package; edits to existing files are re-read from disk. User Adapters load after built-ins, so a same-ID file overrides the built-in Adapter (the Host keeps the latest registration and warns). createPiProviderExtension({ adapterRoot }) replaces the default user directory with a custom root; built-ins are always scanned. The built-in Adapters under the package's providers/, status/, and preflight/ are reference templates with this exact shape — copy one and customize it (Charm Hyper and preflight/openai-codex.ts also use package-private helpers). Complete non-built-in references are available for Ant Digital MaaS and Command Code.

Adapter files import helpers and types from @hyav/pi-provider (aliased inside the loader):

import { defineProviderExtension } from "@hyav/pi-provider";

Adapter files must not runtime-import Pi's bundled packages (@earendil-works/pi-coding-agent, @earendil-works/pi-tui, @earendil-works/pi-ai); type-only imports are fine. Runtime values such as the agent directory, stored credentials, and the ANSI text wrapper are injected by the Pi entrypoint. See the adapter extension contract for helpers, validation, conflicts, reload behavior, and lifecycle boundaries. The root index.ts defines the public TypeScript exports.

/status is offline, /status refresh performs free remote checks and updates catalog caches, and /status check sends a live model request that may consume quota. Configured credentials are sent only to the corresponding provider endpoints and are omitted from status output.

MIT