pi-verboo-provider

English · Español

Verboo Code as a first-class pi provider — a live, capability-rich model catalog with per-model thinking levels and a documented error taxonomy, instead of a hand-maintained list of model IDs.

Pi ships a declarative Verboo integration (~/.pi/agent/models.json): you hardcode IDs and nothing validates them against your key, exposes reasoning-effort capability, or explains Verboo's structured errors. This package registers verboo programmatically and fills those gaps.

Install

1. Official command (npm):

   pi install npm:@ivancavero/pi-verboo-provider

2. No-npm alternative (installs straight from the git source):

   pi install git:github.com/ivan-cavero/pi-verboo-provider

3. Project-local install (writes .pi/settings.json in the current project) — add -l:

   pi install -l npm:@ivancavero/pi-verboo-provider

4. One-liners that install Pi when missing and then the package:

   macOS/Linux:

   curl -fsSL https://raw.githubusercontent.com/ivan-cavero/pi-verboo-provider/main/install.sh | sh

   Windows PowerShell:

   irm https://raw.githubusercontent.com/ivan-cavero/pi-verboo-provider/main/install.ps1 | iex

5. The installers prefer the published npm package and fall back to the git source when npm is unavailable. Set VERBOO_PI_SOURCE to override the source the installer uses.

Installing the package is not enough to see models — authenticate first (next section).

Authenticate

The package alone is not enough: the provider must be authenticated before any model appears. With the package installed and no credentials, pi --list-models verboo prints:

No models available. Use /login to log into a provider via OAuth or API key.

Recommended: /login verboo (persistent)

1. Start pi.
2. Type /login verboo.
3. Paste your Verboo API key when prompted.
4. The key is stored for later sessions, and the models become available.

Alternative: VERBOO_API_KEY

Export the key in the environment where pi runs:

export VERBOO_API_KEY=...

Precedence

An empty env var does not count as configured. The provider is unconfigured until one of the two sources yields a non-empty key.

How it is used

Install → authenticate → list the models → select one with /model.

# 1. Install (see above).
# 2. Authenticate: run /login verboo inside pi, or export VERBOO_API_KEY=...
pi --list-models verboo     # lists the models available to your key

Without authentication, the same command prints No models available. Use /login to log into a provider via OAuth or API key. Then run /model inside pi to pick one of the listed models.

What you get

Deliberately out of scope: MCP bridges, a usage/quota command, and a payload sanitizer (the probe proved Verboo accepts every payload shape that broke Nan — see Provenance).

Models

The table below is the bundled baseline / example — the catalog committed in the package so pi can start without network. The live list is authoritative: the provider fetches it from GET /models, which "returns only models available to the authenticated key", so what you see depends on your account, plan and role. Your list may contain more, fewer, or different models than this baseline.

Thinking levels are the pi levels actually offered, derived from Verboo's declared efforts. maxTokens is 65536 for every model — see the caveat below.

Notes recorded in the generated catalog: Verboo reports vision: true for deepseek-v4.1-flash (the pi/OpenCode config used to mark it text-only), and mimo-v2.5 declares no reasoning capability yet emits reasoning_content in responses.

maxTokens caveat

Verboo publishes no output-token cap. 65536 is a conservative envelope, not a published limit: the probe measured 262144 accepted on the 1M-context models and rejected upstream (502) on qwen3.8-27b, where 131072 was accepted. Override it per model when you need the headroom:

{
  "providers": {
    "verboo": {
      "modelOverrides": {
        "deepseek-v4-flash": { "maxTokens": 262144 }
      }
    }
  }
}

modelOverrides changes metadata for the extension-provided models without replacing the catalog. The same mechanism can pin contextWindow, thinkingLevelMap, input, or compat.

Model refresh

There is no periodic timer. The catalog refreshes only at these moments:

• Cache: ~/.pi/agent/models-store.json holds one entry per provider with the models plus a checkedAt timestamp. It is written only after a successful live fetch.
• Fallback order: cached catalog → committed baseline. If the fetch fails or the network is disallowed, the cached catalog (then the baseline) is used; the previous catalog is not discarded.
• No TTL/ETag for this provider: fetchModels has no freshness gate, so every network-triggering refresh performs a live GET /models. pi's built-in catalog instead uses a 4h window.
• Auth is required for the live list: fetchModels is skipped entirely when no credential resolves (see Authenticate).
• Consequence: a model added or changed on Verboo's side appears after the next refresh (startup, opening /model, or pi update --models) — never instantly. To pick up a new Verboo model now, run pi update --models or reopen /model.

Thinking levels

Each model's thinkingLevelMap comes from that model's Verboo effort_levels: none maps to pi off, same-named efforts pass through, and every unsupported pi level is an explicit null so pi does not offer it. The distinction matters because pi-ai treats an omitted level as supported.

Reasoning cannot be disabled on most models. Only qwen3.8-27b declares none, so it is the only model whose off is real. Elsewhere off is unsupported and pi clamps the request up to the nearest supported level (usually Verboo's own default_effort).

Error taxonomy

Verboo errors are documented and structured. The provider turns them into an actionable message — and a context overflow into pi's recognized overflow wording, so pi compacts and retries.

A 400 that is not over the model window is left untouched — unrelated validation errors are never relabelled as overflow.

Development

bun install
bun run typecheck        # tsc --noEmit
bun test                 # no network; fetch is guarded in tests
bun run probe-verboo     # live compat/cap probes -> scripts/probe-report.json
bun run generate-catalog # rebuild src/catalog.generated.ts from /models

probe-verboo and generate-catalog need VERBOO_API_KEY; they fail loudly without it and never write the key anywhere. generate-catalog is byte-for-byte idempotent and refuses to guess capability data.

Maintainer: publishing

Published as @ivancavero/pi-verboo-provider@0.1.0 on npm (public) and listed in the Pi gallery at https://pi.dev/packages/@ivancavero/pi-verboo-provider. To publish a future version:

1. Bump version in package.json.
2. Log in to npm: npm login (you must own the @ivancavero scope).
3. Publish publicly: npm publish --access public

The prepublishOnly script runs bun test and bun run typecheck, so a failing check blocks the publish.

Discovery: the pi-package keyword (already in package.json) makes the package eligible for the Pi package gallery at https://pi.dev/packages. There is no separate submission step. The optional pi.image and pi.video fields add gallery previews.

Provenance

Compat flags are measured, not assumed: scripts/probe-report.json records the live probes (stream usage with and without stream_options, reasoning_effort: "max", empty tools, unknown fields, replayed reasoning_content, and per-model output-cap attempts). The headers in src/catalog.generated.ts carry the fetch time and per-model notes. Pricing is zero because Verboo publishes none — unknown values are recorded, never invented.