@ssweens/pi-vertex 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssweens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# pi-vertex
+
+[![npm version](https://img.shields.io/npm/v/@ssweens/pi-vertex)](https://www.npmjs.com/package/@ssweens/pi-vertex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+![pi-vertex model selector](screenshot.png)
+
+```bash
+pi install @ssweens/pi-vertex
+export GOOGLE_CLOUD_PROJECT=your-project-id
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+```
+
+Set your GCP project and credentials. Vertex AI models (Gemini, Claude, Llama, DeepSeek, Qwen, Mistral, and others) appear in pi's model selector, billed through your GCP project.
+
+## Features
+
+- **43 models** across 4 categories:
+  - **Gemini** (8): 3.1 Pro, 3 Pro, 3 Flash, 2.5 Pro, 2.5 Flash, 2.0 Flash, and more
+  - **Claude** (12): Opus 4.6, Sonnet 4.6, 4.5, 4.1, 4, 3.7 Sonnet, 3.5 Sonnet v2, 3.5 Sonnet, 3 Haiku
+  - **Llama** (3): 4 Maverick, 4 Scout, 3.3 70B
+  - **Other MaaS** (20): AI21 Jamba, Mistral, DeepSeek, Qwen, OpenAI GPT-OSS, Kimi, MiniMax, GLM
+
+- **Unified streaming**: Single provider, multiple model families
+- **Full tool calling support**: All models marked with tools support
+- **Automatic auth**: Uses Google Application Default Credentials
+- **Region awareness**: Global endpoints where supported, regional where required
+- **Pricing tracking**: Built-in cost per token for all models
+
+## Installation
+
+```bash
+# Via pi (recommended)
+pi install @ssweens/pi-vertex
+
+# Or via npm
+npm install @ssweens/pi-vertex
+```
+
+## Setup
+
+### 1. Authenticate with Google Cloud
+
+```bash
+# 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
+```
+
+### 2. Set environment variables
+
+```bash
+# Required: Your GCP project ID
+export GOOGLE_CLOUD_PROJECT=your-project-id
+
+# Optional: Override default region
+export GOOGLE_CLOUD_LOCATION=us-central1
+```
+
+### 3. Configuration file (optional)
+
+For persistent settings, create `~/.pi/agent/settings/pi-vertex.json`:
+
+```json
+{
+  "googleCloudProject": "my-gcp-project",
+  "googleCloudLocation": "us-central1",
+  "googleApplicationCredentials": "/path/to/service-account.json"
+}
+```
+
+Config file values take priority over environment variables.
+
+### 4. Verify setup
+
+```bash
+pi --provider vertex --model gemini-2.5-pro --version
+```
+
+## Usage
+
+### Command line
+
+```bash
+# Use any supported model
+pi --provider vertex --model claude-opus-4-6
+pi --provider vertex --model gemini-2.5-pro
+pi --provider vertex --model llama-4-maverick
+pi --provider vertex --model deepseek-v3.2
+
+# With options
+pi --provider vertex --model claude-sonnet-4-6 --reasoning high
+```
+
+### Shell alias (recommended)
+
+Add to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# Claude 4.6 Opus
+alias pic="GOOGLE_CLOUD_PROJECT=your-project pi --provider vertex --model claude-opus-4-6"
+
+# Gemini 2.5 Pro
+alias pig="GOOGLE_CLOUD_PROJECT=your-project pi --provider vertex --model gemini-2.5-pro"
+
+# Llama 4 Maverick
+alias pil="GOOGLE_CLOUD_PROJECT=your-project pi --provider vertex --model llama-4-maverick"
+```
+
+## Model Reference
+
+### Gemini Models
+
+| Model | Context | Max Tokens | Input | Reasoning | Price (in/out) |
+|-------|---------|------------|-------|-----------|----------------|
+| gemini-3.1-pro | 1M | 64,000 | text, image | ✅ | $2.00/$12.00 |
+| gemini-3-pro | 2M | 8,192 | text, image | ✅ | $1.25/$10.00 |
+| gemini-3-flash | 1M | 8,192 | text, image | ✅ | $0.15/$0.60 |
+| gemini-2.5-pro | 1M | 64,000 | text, image | ✅ | $1.25/$10.00 |
+| gemini-2.5-flash | 1M | 64,000 | text, image | ✅ | $0.30/$2.50 |
+| gemini-2.5-flash-lite | 1M | 64,000 | text, image | ✅ | $0.10/$0.40 |
+| gemini-2.0-flash | 1M | 8,192 | text, image | ❌ | $0.15/$0.60 |
+| gemini-2.0-flash-lite | 1M | 8,192 | text | ❌ | $0.075/$0.30 |
+
+### Claude Models
+
+| Model | Context | Max Tokens | Input | Reasoning | Price (in/out) | Region |
+|-------|---------|------------|-------|-----------|----------------|--------|
+| claude-opus-4-6 | 200K | 32,000 | text, image | ✅ | $5.00/$25.00 | global |
+| claude-sonnet-4-6 | 200K | 64,000 | text, image | ✅ | $3.00/$15.00 | global |
+| claude-opus-4-5 | 200K | 32,000 | text, image | ✅ | $5.00/$25.00 | global |
+| claude-sonnet-4-5 | 200K | 64,000 | text, image | ✅ | $3.00/$15.00 | global |
+| claude-haiku-4-5 | 200K | 64,000 | text, image | ✅ | $1.00/$5.00 | global |
+| claude-opus-4-1 | 200K | 32,000 | text, image | ✅ | $15.00/$75.00 | us-east5 |
+| claude-opus-4 | 200K | 32,000 | text, image | ✅ | $15.00/$75.00 | us-east5 |
+| claude-sonnet-4 | 200K | 64,000 | text, image | ✅ | $3.00/$15.00 | us-east5 |
+| claude-3-7-sonnet | 200K | 64,000 | text, image | ✅ | $3.00/$15.00 | us-east5 |
+| claude-3-5-sonnet-v2 | 200K | 8,192 | text, image | ❌ | $3.00/$15.00 | us-east5 |
+| claude-3-5-sonnet | 200K | 8,192 | text, image | ❌ | $3.00/$15.00 | us-east5 |
+| claude-3-haiku | 200K | 4,096 | text | ❌ | $0.25/$1.25 | us-east5 |
+
+### Llama Models
+
+| Model | Context | Max Tokens | Input | Reasoning | Price (in/out) | Region |
+|-------|---------|------------|-------|-----------|----------------|--------|
+| llama-4-maverick | 524K | 32,000 | text | ✅ | $0.35/$1.15 | global |
+| llama-4-scout | 1,310K | 32,000 | text | ✅ | $0.25/$0.70 | global |
+| llama-3.3-70b | 128K | 8,192 | text | ❌ | $0.72/$0.72 | global |
+
+### Other MaaS Models
+
+| Model | Context | Publisher | Price (in/out) | Region |
+|-------|---------|-----------|----------------|--------|
+| jamba-1.5-large | 256K | ai21 | $2.00/$8.00 | global |
+| jamba-1.5-mini | 256K | ai21 | $0.20/$0.40 | global |
+| mistral-medium-3 | 128K | mistralai | $0.40/$2.00 | global |
+| mistral-small-3.1 | 128K | mistralai | $0.10/$0.30 | global |
+| mistral-ocr | 30 pages | mistralai | $0.0005/page | global |
+| codestral-2 | 128K | mistralai | $0.30/$0.90 | global |
+| deepseek-v3.2 | 163K | deepseek-ai | $0.56/$1.68 | global |
+| deepseek-v3.1 | 163K | deepseek-ai | $0.60/$1.70 | global |
+| deepseek-r1 | 163K | deepseek-ai | $1.35/$5.40 | global |
+| deepseek-ocr | Varies | deepseek-ai | $0.0003/page | global |
+| qwen3-235b | 262K | qwen | $0.22/$0.88 | global |
+| qwen3-next-instruct | 262K | qwen | $0.15/$1.20 | global |
+| qwen3-next-thinking | 262K | qwen | $0.15/$1.20 | global |
+| qwen3-coder | 262K | qwen | $0.22/$1.80 | global |
+| gpt-oss-120b | 131K | openai | $0.09/$0.36 | global |
+| gpt-oss-20b | 131K | openai | $0.07/$0.25 | global |
+| kimi-k2-thinking | 262K | moonshotai | $0.60/$2.50 | global |
+| minimax-m2 | 196K | minimaxai | $0.30/$1.20 | global |
+| glm-5 | 200K | zai-org | $1.00/$3.20 | global |
+| glm-4.7 | 200K | zai-org | $0.60/$2.20 | global |
+
+## Regional Endpoints
+
+Models use different endpoints based on availability:
+
+- **Global** (most models): `aiplatform.googleapis.com`
+- **Regional** (older Claude models): `{region}-aiplatform.googleapis.com`
+
+Default regions by model:
+- Gemini: `global`
+- Claude 4.6/4.5: `global`
+- Claude 4/4.1/3.7/3.5/3: `us-east5`
+- MaaS: `global`
+
+Override with:
+```bash
+export GOOGLE_CLOUD_LOCATION=us-central1
+```
+
+## Architecture
+
+```
+┌─────────────┐
+│     Pi      │
+└──────┬──────┘
+       │ registerProvider("vertex")
+       ▼
+┌─────────────┐
+│  pi-vertex  │
+└──────┬──────┘
+       │ streamSimple(model, context, options)
+       ▼
+┌─────────────────────────────────────┐
+│         Handler Dispatch            │
+├──────────────┬──────────────────────┤
+│   Gemini     │        MaaS          │
+│  (@google/   │  (OpenAI-compatible  │
+│   genai)     │   endpoint)          │
+└──────────────┴──────────────────────┘
+```
+
+## Dependencies
+
+- `@google/genai`: Google GenAI SDK for Gemini models
+- `google-auth-library`: ADC authentication for all models
+- `@mariozechner/pi-ai`: Peer dependency
+- `@mariozechner/pi-coding-agent`: Peer dependency
+
+## License
+
+MIT

package/auth.ts

@@ -0,0 +1,108 @@
+/**
+ * Authentication utilities for Vertex AI
+ * Uses Google Application Default Credentials (ADC)
+ *
+ * Resolution order for each value: config file → env var → default
+ */
+
+import { GoogleAuth } from "google-auth-library";
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import type { AuthConfig } from "./types.js";
+import { loadConfig, getConfigPath } from "./config.js";
+
+const DEFAULT_ADC_PATH = join(homedir(), ".config", "gcloud", "application_default_credentials.json");
+
+/**
+ * Check if ADC credentials exist.
+ * Checks config credentialsFile → GOOGLE_APPLICATION_CREDENTIALS → default ADC path.
+ */
+export function hasAdcCredentials(): boolean {
+  const config = loadConfig();
+  const adcPath =
+    config.googleApplicationCredentials ||
+    process.env.GOOGLE_APPLICATION_CREDENTIALS ||
+    DEFAULT_ADC_PATH;
+  return existsSync(adcPath);
+}
+
+/**
+ * Resolve project ID.
+ * Checks config.googleCloudProject → GOOGLE_CLOUD_PROJECT → GCLOUD_PROJECT.
+ */
+export function resolveProjectId(): string | undefined {
+  const config = loadConfig();
+  return config.googleCloudProject || process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT;
+}
+
+/**
+ * Resolve location/region.
+ * Checks config.googleCloudLocation → GOOGLE_CLOUD_LOCATION → CLOUD_ML_REGION → defaultLocation.
+ */
+export function resolveLocation(defaultLocation: string = "us-central1"): string {
+  const config = loadConfig();
+  return (
+    config.googleCloudLocation ||
+    process.env.GOOGLE_CLOUD_LOCATION ||
+    process.env.CLOUD_ML_REGION ||
+    defaultLocation
+  );
+}
+
+/**
+ * Get authentication configuration.
+ */
+export function getAuthConfig(preferredRegion?: string): AuthConfig {
+  const projectId = resolveProjectId();
+  if (!projectId) {
+    throw new Error(
+      "Vertex AI requires a project ID.\n" +
+      `  Config file: set "project" in ${getConfigPath()}\n` +
+      "  Env var: export GOOGLE_CLOUD_PROJECT=your-project-id\n" +
+      "  Also ensure you've run: gcloud auth application-default login"
+    );
+  }
+
+  if (!hasAdcCredentials()) {
+    throw new Error(
+      "Vertex AI requires Application Default Credentials.\n" +
+      "  Run: gcloud auth application-default login\n" +
+      `  Or set "credentialsFile" in ${getConfigPath()}`
+    );
+  }
+
+  return {
+    projectId,
+    location: preferredRegion || resolveLocation(),
+  };
+}
+
+/**
+ * Get access token for HTTP requests.
+ * Uses credentialsFile from config if set, otherwise relies on ADC.
+ */
+export async function getAccessToken(): Promise<string> {
+  const config = loadConfig();
+  const auth = new GoogleAuth({
+    scopes: ["https://www.googleapis.com/auth/cloud-platform"],
+    ...(config.googleApplicationCredentials ? { keyFile: config.googleApplicationCredentials } : {}),
+  });
+  const client = await auth.getClient();
+  const token = await client.getAccessToken();
+  if (!token.token) {
+    throw new Error("Failed to get access token from ADC");
+  }
+  return token.token;
+}
+
+/**
+ * Build the base URL for Vertex AI endpoints
+ */
+export function buildBaseUrl(projectId: string, location: string): string {
+  // Global endpoint uses aiplatform.googleapis.com without region prefix
+  if (location === "global") {
+    return `https://aiplatform.googleapis.com/v1/projects/${projectId}/locations/global`;
+  }
+  return `https://${location}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${location}`;
+}

package/config.ts

@@ -0,0 +1,63 @@
+/**
+ * Config loader for pi-vertex
+ *
+ * Reads ~/.pi/agent/settings/pi-vertex.json (if present).
+ * All fields are optional — env vars remain a supported fallback.
+ *
+ * Config keys are camelCase versions of the corresponding env var names:
+ *
+ *   {
+ *     "googleCloudProject":          "my-gcp-project",
+ *     "googleCloudLocation":         "us-central1",
+ *     "googleApplicationCredentials": "/path/to/service-account.json"
+ *   }
+ */
+
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function getConfigPath(): string {
+  return join(getAgentDir(), "settings", "pi-vertex.json");
+}
+
+export interface VertexConfig {
+  /** GCP project ID. Equivalent to GOOGLE_CLOUD_PROJECT. */
+  googleCloudProject?: string;
+  /** Default region/location. Equivalent to GOOGLE_CLOUD_LOCATION. */
+  googleCloudLocation?: string;
+  /** Path to a service account JSON key. Equivalent to GOOGLE_APPLICATION_CREDENTIALS. */
+  googleApplicationCredentials?: string;
+}
+
+let _cachedPath: string | null = null;
+let _globalCached: VertexConfig | null = null;
+
+function loadGlobalConfig(): VertexConfig {
+  const configPath = getConfigPath();
+  // Bust cache if agentDir changed (e.g. different process env)
+  if (_cachedPath !== configPath) {
+    _cachedPath = configPath;
+    _globalCached = null;
+  }
+  if (_globalCached !== null) return _globalCached;
+
+  if (!existsSync(configPath)) {
+    _globalCached = {};
+    return _globalCached;
+  }
+
+  try {
+    _globalCached = JSON.parse(readFileSync(configPath, "utf-8")) as VertexConfig;
+    return _globalCached;
+  } catch (err) {
+    console.warn(`[pi-vertex] Failed to parse ${configPath}: ${err}`);
+    _globalCached = {};
+    return _globalCached;
+  }
+}
+
+/** Load config from global settings. */
+export function loadConfig(): VertexConfig {
+  return loadGlobalConfig();
+}

package/index.ts

@@ -0,0 +1,134 @@
+/**
+ * pi-vertex - Google Vertex AI provider for Pi coding agent
+ *
+ * Supports:
+ * - Gemini models (via @google/genai)
+ * - Claude models (via OpenAI-compatible endpoint)
+ * - All MaaS models (Llama, Mistral, DeepSeek, etc. via OpenAI-compatible endpoint)
+ *
+ * Configuration (resolution order: config file → env var):
+ *
+ *   Config file: ~/.pi/agent/config/pi-vertex.json
+ *     {
+ *       "project": "my-gcp-project",
+ *       "location": "us-central1",
+ *       "credentialsFile": "/path/to/service-account.json"
+ *     }
+ *
+ *   Env vars (fallback):
+ *     GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT  (required)
+ *     GOOGLE_CLOUD_LOCATION                   (optional, default: model region or us-central1)
+ *     GOOGLE_APPLICATION_CREDENTIALS          (optional, for service account auth)
+ *
+ * Usage:
+ *   pi --provider vertex --model claude-opus-4-6
+ *   pi --provider vertex --model gemini-2.5-pro
+ *   pi --provider vertex --model llama-4-maverick
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Model, Api } from "@mariozechner/pi-ai";
+import { ALL_MODELS, getModelById } from "./models/index.js";
+import { hasAdcCredentials, resolveProjectId } from "./auth.js";
+import { loadConfig, getConfigPath } from "./config.js";
+import { streamVertex } from "./streaming/index.js";
+import type { VertexModelConfig } from "./types.js";
+
+/**
+ * Convert Vertex model config to Pi model format
+ */
+function toPiModel(config: VertexModelConfig): Model<Api> {
+  return {
+    id: config.id,
+    name: config.name,
+    api: "vertex-unified",
+    provider: "vertex",
+    baseUrl: "", // Will be set dynamically
+    reasoning: config.reasoning,
+    input: config.input,
+    cost: config.cost,
+    contextWindow: config.contextWindow,
+    maxTokens: config.maxTokens,
+    headers: {},
+  };
+}
+
+/**
+ * Extension entry point
+ */
+export default function (pi: ExtensionAPI) {
+  const config = loadConfig();
+
+  // Apply credentialsFile to environment so all Google SDKs pick it up.
+  // Only set if not already overridden by env var.
+  if (config.googleApplicationCredentials && !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    process.env.GOOGLE_APPLICATION_CREDENTIALS = config.googleApplicationCredentials;
+  }
+
+  const projectId = resolveProjectId();
+
+  if (!projectId) {
+    console.log(
+      `[pi-vertex] Skipping: no project ID found.\n` +
+      `  Config file: set "project" in ${getConfigPath()}\n` +
+      `  Env var: export GOOGLE_CLOUD_PROJECT=your-project-id`
+    );
+    return;
+  }
+
+  if (!hasAdcCredentials()) {
+    console.log(
+      `[pi-vertex] Skipping: ADC credentials not found.\n` +
+      `  Run: gcloud auth application-default login\n` +
+      `  Or set "credentialsFile" in ${getConfigPath()}`
+    );
+    return;
+  }
+
+  // Register the provider
+  pi.registerProvider("vertex", {
+    // Use a placeholder baseUrl (actual URLs built per-request based on model region)
+    baseUrl: "https://aiplatform.googleapis.com",
+
+    // Use env var name for detection
+    apiKey: "GOOGLE_CLOUD_PROJECT",
+
+    // API type varies by model
+    api: "vertex-unified",
+
+    // Register all models
+    models: ALL_MODELS.map(toPiModel),
+
+    // Custom streaming implementation
+    streamSimple: (model: Model<Api>, context: any, options?: any) => {
+      const vertexModel = getModelById(model.id);
+      if (!vertexModel) {
+        throw new Error(`Unknown Vertex model: ${model.id}`);
+      }
+
+      return streamVertex(vertexModel, context, options);
+    },
+  });
+
+  // Show startup info as a widget that clears on first user input
+  const vertexStartupLines = [
+    `[pi-vertex] Initializing with project: ${projectId}`,
+    `[pi-vertex] Registered ${ALL_MODELS.length} models`,
+  ];
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.setWidget("pi-vertex-startup", (_tui, theme) => ({
+      render: () => [...vertexStartupLines.map(l => theme.fg("muted", l)), ""],
+      invalidate: () => {},
+    }));
+  });
+  pi.on("input", async (_event, ctx) => {
+    ctx.ui.setWidget("pi-vertex-startup", undefined);
+  });
+}
+
+// Export types and utilities for advanced usage
+export * from "./types.js";
+export * from "./models/index.js";
+export * from "./auth.js";
+export * from "./config.js";
+export * from "./streaming/index.js";