pi-vertex

A Google Vertex AI provider for the Pi Coding Agent — Gemini, Claude, Llama, DeepSeek, Qwen, Mistral and the rest of the Vertex Model Garden behind a single provider, billed through your GCP project, with dynamic model discovery so models that are enabled in your project show up in the selector without a code change or a release.

pi install npm:@cebarks/pi-vertex
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json   # or: gcloud auth application-default login

About this fork

Lineage:

1. ssweens/pi-packages — original @ssweens/pi-vertex, published inside a mono-repo
2. lhl/pi-vertex — git filter-repo extraction into a standalone repo with tests, lint and CI (@lhl/pi-vertex, v1.1.5 → v1.1.9)
3. this repo — cebarks/pi-vertex (@cebarks/pi-vertex, v2.x → v3.x)

The reason for the second fork is discovery. Up to v1.1.9 the model list was a hand-maintained static table: every new Vertex model required an upstream code change, a release, and a pi-package update on your side — and enabling a model your project has access to was invisible until someone shipped it. This fork queries the Model Garden API at startup, probes each model for project-level access, and registers what actually answers. Static metadata is still used where it exists, so pricing and capability limits for known models stay authoritative rather than guessed.

What this fork adds (v2.x–v3.x, on top of v1.1.9)

Carried over from the previous fork

Standalone repo; 128 unit tests across 9 files (auth, config, utils, model integrity, discovery enrichment, convertToGeminiMessages, streaming dispatch, mocked Gemini + MaaS streams, thinking payloads and transcript replay); Biome lint/format; GitHub Actions workflow for type-check, lint, coverage; real build/check/test scripts; Anthropic stream lifecycle fixed to end() exactly once; hardcoded maxTokens / 2 halving removed; regional Claude pricing (costRegional) applied when the resolved endpoint isn't global; Gemini cache-token accounting, image tool-result replay, missing-tool-result synthesis, and safety/blocked finish handling.

Provenance

• Upstream: lhl/pi-vertex → ssweens/pi-packages (path pi-vertex/, filtered with git filter-repo --path pi-vertex/ --path-rename pi-vertex/:, so upstream history is intact)
• Fork point: v1.1.9 (f7b1a46), rebranded in d5ca3b3 (2026-08-25)
• npm: @cebarks/pi-vertex · repo: cebarks/pi-vertex
• Requirements: pi ≥ 0.87 (the provider stream contract changed shape there); developed against 0.87.1, verified live on 0.99.x

Model discovery

At startup the extension runs four phases, then registers the provider once:

1. List — one GET /v1beta1/publishers/{publisher}/models?pageSize=100 per publisher (5 s timeout each, all in parallel). Publishers: anthropic, google, meta, mistralai, deepseek-ai, xai, qwen, moonshotai, minimaxai, openai, zai-org.
2. Filter — drop IDs matching -tts, -embedding, -imagen, textembedding, -native-audio, -image.
3. Probe — a countTokens request per candidate, 8 workers, 5 s timeout each. Probing uses each publisher's serving region (us-east5 for Anthropic, global for Google, us-central1 for the rest), which is only an availability check — it does not change the endpoint your requests go to.
4. Enrich — models present in the static tables keep their real pricing, context window and capability flags; models discovered but not described statically get publisher defaults (below) and show up with a generated display name.

The result is cached as JSON on disk and reused until the TTL expires, so the probe cost is paid once per day. The startup widget reports the count and whether it came from cache:

   [pi-vertex] Project: my-gcp-project | 48 models available (cached)

Defaults for models that aren't in the static tables (_default catches any publisher not listed):

Because defaults include placeholder pricing, costs shown in pi for an unknown model are approximate until you add it to the static tables — that's a deliberate trade-off: surfacing a model beats hiding it, and a one-line PR to models/maas.ts makes it exact.

Features

• 45 statically described models across Gemini (9), Claude (12), Llama (3) and other MaaS (21) — plus whatever else discovery finds in your project
• Unified streaming through one provider: Gemini via @google/genai, Claude via the native @anthropic-ai/vertex-sdk, everything else via Vertex's OpenAI-compatible endpoint
• Full tool calling with multi-turn tool use and tool-result handling on every path
• Thinking / reasoning: Gemini 3 thinking levels, Gemini 2.5 thinking budgets, thought-signature preservation, Claude adaptive and legacy thinking formats
• Automatic auth via Application Default Credentials or a service-account key
• Region awareness: global endpoints by default, regional when required, with regional Claude pricing applied automatically
• Cost tracking for all statically known models, including cache reads/writes and thinking tokens

Installation

# Via pi (recommended)
pi install npm:@cebarks/pi-vertex

# Or via npm
npm install -g @cebarks/pi-vertex

# Or from source
git clone https://github.com/cebarks/pi-vertex.git
cd pi-vertex && npm install
pi install /path/to/pi-vertex

Setup

1. Authenticate with Google Cloud

# Option A: user credentials (development)
gcloud auth application-default login

# Option B: service account (production)
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

The project also needs the Vertex AI API enabled (gcloud services enable aiplatform.googleapis.com), and any model you want must be enabled for the project — that's exactly what discovery probes for.

2. Environment variables

export GOOGLE_CLOUD_PROJECT=your-project-id    # required (GCLOUD_PROJECT also accepted)
export GOOGLE_CLOUD_LOCATION=us-central1       # optional: override the per-model region

3. Configuration file (optional)

~/.pi/agent/settings/pi-vertex.json — every field is optional, and file values take priority over environment variables:

{
  "googleCloudProject": "my-gcp-project",
  "googleCloudLocation": "us-central1",
  "googleApplicationCredentials": "/path/to/service-account.json",
  "discoveryEnabled": true,
  "discoveryCacheTtlMs": 86400000,
  "discoveryPublishers": ["anthropic", "google", "meta"]
}

4. Verify

pi --provider vertex --model gemini-2.5-pro --version

Usage

pi --provider vertex --model claude-opus-4-8
pi --provider vertex --model gemini-3.1-pro
pi --provider vertex --model llama-4-maverick
pi --provider vertex --model deepseek-v3.2
pi --provider vertex --model claude-sonnet-4-6 --reasoning high

Within a session, /vertex-refresh clears the cache, re-probes, and reports what is now available:

/vertex-refresh
→ Vertex model cache refreshed. 48 models available: claude-opus-4-8, gemini-3.5-flash, …

Shell aliases keep the typing down — note pi's --provider vertex plus a model id, so one alias per model you actually use:

alias pic='GOOGLE_CLOUD_PROJECT=my-project pi --provider vertex --model claude-opus-4-8'
alias pig='GOOGLE_CLOUD_PROJECT=my-project pi --provider vertex --model gemini-3.5-flash'

Model reference

Static metadata; discovery may register additional models, and may omit ones listed here if your project has no access. Prices are USD per 1M tokens on the global endpoint unless noted.

Gemini

Claude

Non-global regions use costRegional where Google publishes a regional premium.

Llama

Other MaaS

mistral-ocr is billed per page ($0.0005/page on both sides) rather than per token; the two *-ocr models do not support tool calling.

Endpoints and regions

Every static model defaults to region: "global", which resolves to https://aiplatform.googleapis.com/v1/projects/{project}/locations/global/.... A regional endpoint looks like https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/....

GOOGLE_CLOUD_LOCATION (or googleCloudLocation) is a global override applied on top of each model's own region — setting it forces every request through that region, including for models that only serve from global. Use it when you have a data-residency requirement and have confirmed the models you rely on are servable there; it also switches Claude pricing to costRegional when a premium is defined.

Architecture

                         ┌─────────────┐
                         │     Pi      │
                         └──────┬──────┘
      registerProvider("vertex")│  /vertex-refresh
                                ▼
   ┌────────────────────────────────────────────────┐
   │                   pi-vertex                    │
   │                                                │
   │  config.ts ─ settings/pi-vertex.json           │
   │  auth.ts ───── ADC / service account, project, │
   │                location, endpoint builder      │
   │  discovery.ts ─ Model Garden list ──┐          │
   │                  countTokens probe ─┤ cache    │
   │                                     ▼          │
   │  models/ ─ static metadata ═══► merged model set (45+ registered)
   └────────────────────────────────┬───────────────┘
                                streamVertex()
                                     │ endpointType
                    ┌────────────────┴────────────────┐
                    ▼                                 ▼
        ┌───────────────────────┐        ┌──────────────────────────┐
        │  gemini (@google/genai)│        │ maas (OpenAI-compat) or  │
        │                        │        │ Claude (vertex-sdk)      │
        └───────────────────────┘        └──────────────────────────┘

Development

npm ci
npm run build         # tsc --noEmit
npm run check         # biome check
npm test              # vitest run
npm run test:coverage

The GitHub Actions workflow (.github/workflows/ci.yml) runs build + check in one job and test:coverage (with a coverage artifact) in another, on every push and PR touching main.

Two conventions worth knowing if you touch this code:

• tests/auth.test.ts rebuilds process.env from a baseline with GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, CLOUD_ML_REGION and GOOGLE_APPLICATION_CREDENTIALS stripped. Every assertion there is about fallback order, so an ambient value exported by your shell would outrank the fixture and silently invert the test. Keep new auth assertions inside that baseline.
• biome.json disables the formatter for package.json: npm rewrites that file on every npm version / dependency change, expanding short arrays back onto separate lines, which biome then flags. Same reasoning for tests/** and streaming/maas.ts, where noExplicitAny is off (mock objects, and the Anthropic normalize/replay pipeline — see the note at the top of that file).

Dependencies

• @google/genai — Gemini generateContent streaming
• @anthropic-ai/vertex-sdk — native Claude-on-Vertex streaming
• google-auth-library — ADC/service-account tokens
• @earendil-works/pi-ai, @earendil-works/pi-coding-agent — peer dependencies (provided by pi)

License

MIT — see LICENSE. Copyright for the original work is held by ssweens; this fork preserves the upstream notice and full commit history.