@opperai/pi-provider

Opper AI gateway provider and tools for the pi coding agent.

Routes LLM requests through Opper, an AI control plane with:

• 260+ models across 22 providers behind a single OPPER_API_KEY
• European endpoints (AWS EU, Evroc, Berget) for data residency
• Per-session span tracing — every pi session becomes a parent span with all LLM calls linked underneath
• Optional server-side controls: guardrails, approved model governance, budgets, intelligent routing

Install

pi install npm:@opperai/pi-provider

Then set your API key (get one at opper.ai):

export OPPER_API_KEY=your-key

What's included

Two extensions are registered automatically:

provider

Registers an opper provider with 260+ models. Use /model inside pi to switch to any Opper model.

• Streams via Opper's OpenAI-compatible /v3/compat/chat/completions
• Loads models dynamically from /v3/models at startup (hardcoded fallback if unavailable)
• Creates a session span on start, closes it on shutdown — all LLM calls are linked under it in Opper's tracing UI

tools

Registers multimodal LLM-callable tools backed by Opper:

| Tool | Description | |------|-------------| | opper_generate_image | Generate images from a text prompt | | opper_analyze_image | Analyze an image file with a vision model | | opper_text_to_speech | Convert text to speech, saves audio to disk | | opper_speech_to_text | Transcribe an audio file | | opper_web_search | Search the web | | opper_web_fetch | Fetch a URL as markdown | | opper_embed | Generate text embeddings |

Load only one extension

Use pi's package filtering to load just the provider or just the tools:

# Provider only
pi install npm:@opperai/pi-provider
# then in .pi/settings.json:
{
  "packages": [
    {
      "source": "npm:@opperai/pi-provider",
      "extensions": ["extensions/provider.ts"]
    }
  ]
}

# Tools only
{
  "packages": [
    {
      "source": "npm:@opperai/pi-provider",
      "extensions": ["extensions/tools.ts"]
    }
  ]
}

Or try without installing:

OPPER_API_KEY=your-key pi -e npm:@opperai/pi-provider

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | OPPER_API_KEY | Yes | Auth for all Opper API calls | | OPPER_AGENT_NAME | No | Override the framework name sent in headers (default: pi-code) | | PI_IMAGE_SAVE_MODE | No | Default image save mode: tmp, project, global, or custom | | PI_IMAGE_SAVE_DIR | No | Directory for custom save mode |