@billjr99/pi-openai-compat 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# @billjr99/pi-openai-compat — pi-coding-agent extension
+
+Registers OpenAI-compatible LLM endpoints as first-class providers inside
+[pi](https://pi.dev), so their models appear directly in pi's native `/model`
+list and `Ctrl+L` picker alongside built-in Anthropic, OpenAI, and Google
+models.  No custom model selection UI — pi handles it natively.
+
+Multiple providers can be registered at the same time.  All of their models
+appear together in `/model` under their own provider label.
+
+---
+
+## Quick start
+
+```bash
+# Install from npm
+pi install npm:@billjr99/pi-openai-compat
+
+# Or from GitHub
+pi install git:github.com/BillJr99/pi-openai-compat
+```
+
+Then inside pi:
+
+```
+/compat-login
+```
+
+Pick your provider, enter credentials, and pi fetches the model list
+automatically.  Your models are immediately available in `/model`.
+
+If pi is already running when you install, type `/reload` first.
+
+---
+
+## Supported providers
+
+| Provider | Default base URL | Auth |
+|---|---|---|
+| **OpenRouter** | `https://openrouter.ai/api/v1` | `sk-or-...` from openrouter.ai/keys |
+| **NVIDIA NIM** | `https://integrate.api.nvidia.com/v1` | `nvapi-...` from build.nvidia.com |
+| **Nous Research Portal** | `https://inference-api.nousresearch.com/v1` | Nous Portal API key |
+| **Ollama (local)** | `http://localhost:11434/v1` | Keyless |
+| **Custom** | Any URL you supply | Optional bearer token |
+
+---
+
+## Commands
+
+Only two commands are needed.
+
+### `/compat-login`
+
+Walks you through a short wizard:
+
+1. Select a provider from the list above (or choose Custom).
+2. For Ollama and Custom, confirm or change the base URL.
+3. Enter your API key (skipped for keyless providers like Ollama).
+4. The extension connects, fetches the model list from `/v1/models`, and
+   registers the provider with pi.
+
+After login, the provider's models appear in pi's `/model` command and
+`Ctrl+L` picker immediately.  You can run `/compat-login` again to add a
+second provider — all providers are active simultaneously.
+
+### `/compat-logout`
+
+Unregisters a provider from pi.  If you have multiple providers registered,
+you are asked which one to remove.  If you have only one, you are asked to
+confirm.
+
+When the last compat provider is removed, the extension restores whichever
+built-in model you were using before you added any compat providers.
+
+---
+
+## Typical workflow
+
+```
+/compat-login
+  → pick Ollama
+  → press Enter to accept http://localhost:11434/v1
+  → 3 models added to /model
+
+/model
+  → scroll to ollama/gemma4:latest
+  → select it
+
+(start chatting)
+
+/compat-logout
+  → confirm remove Ollama
+  → previous model restored automatically
+```
+
+To add OpenRouter alongside Ollama:
+
+```
+/compat-login
+  → pick OpenRouter
+  → enter API key
+  → 300+ models added to /model alongside your Ollama models
+```
+
+---
+
+## How it works
+
+The extension uses pi's `registerProvider` API to register each configured
+endpoint as a named provider.  This is the same mechanism pi uses internally
+for Anthropic, OpenAI, and Google.  Registered providers appear in `/model`
+and `Ctrl+L` with their own label, and pi handles all model selection,
+routing, and request formatting natively.
+
+On unregistration, pi's built-in `unregisterProvider` restores the original
+model list automatically.
+
+Model lists are cached in `config.json` at startup so no network call is
+needed to re-register providers when pi restarts.
+
+---
+
+## Config file
+
+Credentials and cached model lists are stored at:
+
+```
+~/.config/pi-openai-compat/config.json
+```
+
+API keys are stored in plaintext.  Protect the file with `chmod 600` if
+needed, or delete it to clear all saved credentials.
+
+---
+
+## Publishing to npmjs.com
+
+### First-time setup
+
+1. Register at https://www.npmjs.com/signup — use `billjr99` as your username
+   to match the `@billjr99/` package scope.
+2. Verify your email address (required before publishing).
+3. Enable two-factor authentication under your npm account settings.
+4. Log in from the command line:
+
+```bash
+npm login
+```
+
+### Publishing
+
+```bash
+cd /path/to/pi-openai-compat
+npm publish --access public
+```
+
+`--access public` is required for scoped packages on the first publish.
+Subsequent publishes do not need it.
+
+The package is immediately available at
+https://www.npmjs.com/package/@billjr99/pi-openai-compat.
+
+### Releasing a new version
+
+```bash
+npm version patch   # 1.0.0 → 1.0.1  (bug fixes)
+npm version minor   # 1.0.0 → 1.1.0  (new features)
+npm version major   # 1.0.0 → 2.0.0  (breaking changes)
+npm publish --access public
+```
+
+`npm version` also creates a git tag, so GitHub gets release tags automatically.
+
+### Installing from npm
+
+```bash
+pi install npm:@billjr99/pi-openai-compat         # latest
+pi install npm:@billjr99/pi-openai-compat@1.0.0   # pinned version
+pi update  npm:@billjr99/pi-openai-compat          # update to latest
+pi remove  npm:@billjr99/pi-openai-compat          # uninstall
+```
+
+---
+
+## Troubleshooting
+
+**Connection fails during `/compat-login`**
+Verify the base URL does not have a trailing slash and ends with `/v1`.
+Confirm the API key is correct and has model-access permissions.
+For Ollama: ensure `ollama serve` is running.
+
+**No models appear after login**
+For Ollama: pull at least one model first (`ollama pull llama3`).
+For OpenRouter: some keys are restricted to free-tier models only.
+For NIM: confirm your account has inference access enabled.
+
+**Models appear in `/model` but requests fail**
+Check `/compat-login` ran successfully (no error message).
+Verify Ollama is still running if using a local endpoint.

package/index.ts

@@ -0,0 +1,377 @@
+/**
+ * @billjr99/pi-openai-compat — pi-coding-agent extension
+ *
+ * Registers OpenAI-compatible LLM endpoints as first-class pi providers so
+ * their models appear in pi's native /model list and Ctrl+L picker.
+ *
+ * Design:
+ *   - Every provider saved in config.json is registered automatically at
+ *     startup.  The factory is async so pi waits for registration to complete
+ *     before showing the model list — no session_start delay.
+ *   - /compat-login  adds a provider (fetches fresh model list, registers).
+ *   - /compat-logout removes a provider (unregisters, restores previous model).
+ *   - No activeProviders list — presence in config.providers means registered.
+ *
+ * Config: ~/.config/pi-openai-compat/config.json
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface CachedModel {
+  id: string;
+  contextWindow?: number;
+  maxTokens?: number;
+}
+
+interface ProviderConfig {
+  displayName: string;
+  baseUrl: string;
+  apiKey: string | null;
+  cachedModels: CachedModel[];
+}
+
+interface ExtensionConfig {
+  /** Last non-compat model; restored when the last compat provider is removed. */
+  previousModel: { provider: string; id: string } | null;
+  /** Every key here is a registered provider. Presence = registered. */
+  providers: Record<string, ProviderConfig>;
+}
+
+interface OpenAIModelsResponse {
+  data: Array<{ id: string; context_window?: number; max_tokens?: number }>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider templates
+// ─────────────────────────────────────────────────────────────────────────────
+
+const TEMPLATES: Record<string, {
+  displayName: string;
+  baseUrl: string;
+  keyless: boolean;
+  keyHint?: string;
+}> = {
+  openrouter: {
+    displayName: "OpenRouter",
+    baseUrl: "https://openrouter.ai/api/v1",
+    keyless: false,
+    keyHint: "sk-or-... from openrouter.ai/keys",
+  },
+  nvidia_nim: {
+    displayName: "NVIDIA NIM",
+    baseUrl: "https://integrate.api.nvidia.com/v1",
+    keyless: false,
+    keyHint: "nvapi-... from build.nvidia.com",
+  },
+  nous: {
+    displayName: "Nous Research Portal",
+    baseUrl: "https://inference-api.nousresearch.com/v1",
+    keyless: false,
+    keyHint: "Your Nous Portal API key",
+  },
+  ollama: {
+    displayName: "Ollama (local, keyless)",
+    baseUrl: "http://localhost:11434/v1",
+    keyless: true,
+  },
+  custom: {
+    displayName: "Custom Endpoint",
+    baseUrl: "",
+    keyless: false,
+    keyHint: "Bearer token or API key (leave blank if keyless)",
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CONFIG_DIR = path.join(os.homedir(), ".config", "pi-openai-compat");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+function loadConfig(): ExtensionConfig {
+  const empty: ExtensionConfig = { previousModel: null, providers: {} };
+  try {
+    if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    if (!fs.existsSync(CONFIG_PATH)) return empty;
+
+    const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8")) as Record<string, unknown>;
+    const config: ExtensionConfig = {
+      previousModel: (raw.previousModel as any) ?? null,
+      providers: (raw.providers as Record<string, ProviderConfig>) ?? {},
+    };
+
+    // Migrate: cachedModels missing on older records.
+    for (const key of Object.keys(config.providers)) {
+      if (!Array.isArray(config.providers[key].cachedModels)) {
+        config.providers[key].cachedModels = [];
+      }
+    }
+
+    return config;
+  } catch (e) {
+    console.error("[openai-compat:loadConfig]", e);
+    return empty;
+  }
+}
+
+function saveConfig(config: ExtensionConfig): void {
+  try {
+    if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
+  } catch (e) {
+    console.error("[openai-compat:saveConfig]", e);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Networking
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function fetchModels(baseUrl: string, apiKey: string | null): Promise<CachedModel[]> {
+  const url = `${baseUrl.replace(/\/+$/, "")}/models`;
+  const headers: Record<string, string> = { Accept: "application/json" };
+  if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+
+  const resp = await fetch(url, { headers });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(`HTTP ${resp.status} from ${url}: ${body}`);
+  }
+
+  const json = (await resp.json()) as OpenAIModelsResponse;
+  if (!Array.isArray(json?.data)) throw new Error(`Unexpected response from ${url}`);
+
+  return json.data
+    .map((m) => ({ id: m.id, contextWindow: m.context_window, maxTokens: m.max_tokens }))
+    .filter((m) => Boolean(m.id))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider registration helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildProviderModels(models: CachedModel[]) {
+  return models.map((m) => ({
+    id: m.id,
+    name: m.id,
+    reasoning: false,
+    input: ["text"] as string[],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: m.contextWindow ?? 128_000,
+    maxTokens: m.maxTokens ?? 4_096,
+  }));
+}
+
+function compatKey(key: string): string {
+  return `compat-${key}`;
+}
+
+function registerProvider(pi: ExtensionAPI, key: string, p: ProviderConfig): void {
+  pi.registerProvider(compatKey(key), {
+    name: p.displayName,
+    baseUrl: p.baseUrl,
+    apiKey: p.apiKey ?? "ollama",
+    api: "openai-completions" as const,
+    models: buildProviderModels(p.cachedModels),
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Extension — async factory so registration completes before pi shows /model
+// ─────────────────────────────────────────────────────────────────────────────
+
+export default async function (pi: ExtensionAPI) {
+  let config = loadConfig();
+
+  // Register all saved providers immediately using cached model lists.
+  // The factory is async, so pi waits for this to finish before startup
+  // continues — providers are visible in /model from the very first render.
+  for (const [key, p] of Object.entries(config.providers)) {
+    if (p.cachedModels.length > 0) {
+      registerProvider(pi, key, p);
+    }
+  }
+
+  // ── session_start ──────────────────────────────────────────────────────────
+  // Reload config in case it changed (e.g. edited by hand) and re-register
+  // any providers whose cache was empty at factory time.
+  pi.on("session_start", async (_event, ctx) => {
+    config = loadConfig();
+
+    const registered: string[] = [];
+    const failed: string[] = [];
+
+    for (const [key, p] of Object.entries(config.providers)) {
+      if (p.cachedModels.length > 0) {
+        // Use cached list — fast, no network call.
+        registerProvider(pi, key, p);
+        registered.push(p.displayName);
+      } else {
+        // Cache is empty (e.g. migrated from older config).  Try a live fetch.
+        try {
+          const models = await fetchModels(p.baseUrl, p.apiKey);
+          if (models.length > 0) {
+            p.cachedModels = models;
+            saveConfig(config);
+            registerProvider(pi, key, p);
+            registered.push(`${p.displayName} (refreshed)`);
+          } else {
+            failed.push(p.displayName);
+          }
+        } catch {
+          failed.push(p.displayName);
+        }
+      }
+    }
+
+    if (registered.length > 0) {
+      ctx.ui.notify(`OpenAI-compat: ${registered.join(", ")} available in /model`, "info");
+    }
+    if (failed.length > 0) {
+      ctx.ui.notify(
+        `OpenAI-compat: could not reach ${failed.join(", ")} — run /compat-login to refresh.`,
+        "warning"
+      );
+    }
+  });
+
+  // ── model_select ───────────────────────────────────────────────────────────
+  // Track the last non-compat model for logout restoration.
+  pi.on("model_select", async (event, _ctx) => {
+    const compatProviderKeys = Object.keys(config.providers).map(compatKey);
+    if (!compatProviderKeys.includes(event.model.provider)) {
+      config.previousModel = { provider: event.model.provider, id: event.model.id };
+      saveConfig(config);
+    }
+  });
+
+  // ── /compat-login ──────────────────────────────────────────────────────────
+  pi.registerCommand("compat-login", {
+    description: "Fetch models from an OpenAI-compatible endpoint and add it to /model",
+    handler: async (args, ctx) => {
+      // Step 1 — pick provider template
+      const keys = Object.keys(TEMPLATES);
+      const labels = keys.map((k) => TEMPLATES[k].displayName);
+      const selectedLabel = await ctx.ui.select("Select Provider", labels);
+      if (!selectedLabel) { ctx.ui.notify("Login cancelled.", "info"); return; }
+      const key = keys[labels.indexOf(selectedLabel)];
+      const tpl = TEMPLATES[key];
+
+      // Step 2 — base URL (prompted for ollama / custom)
+      let baseUrl = tpl.baseUrl;
+      if (key === "ollama" || key === "custom") {
+        const defaultUrl = tpl.baseUrl;
+        const entered = await ctx.ui.input(
+          "Base URL",
+          key === "ollama"
+            ? `Ollama base URL — press Enter for default (${defaultUrl}):`
+            : "Base URL of your endpoint (e.g. https://api.example.com/v1):",
+          defaultUrl
+        );
+        if (entered === null) { ctx.ui.notify("Login cancelled.", "info"); return; }
+        baseUrl = (entered.trim() || defaultUrl).replace(/\/+$/, "");
+        if (!baseUrl) { ctx.ui.notify("Base URL cannot be empty.", "error"); return; }
+      }
+
+      // Step 3 — API key
+      let apiKey: string | null = null;
+      if (!tpl.keyless) {
+        const entered = await ctx.ui.input(
+          "API Key",
+          `${tpl.keyHint ?? "Your API key"} — leave blank if keyless:`,
+          ""
+        );
+        if (entered === null) { ctx.ui.notify("Login cancelled.", "info"); return; }
+        apiKey = entered.trim() || null;
+      }
+
+      // Step 4 — fetch fresh model list
+      ctx.ui.notify(`Connecting to ${baseUrl} …`, "info");
+      let models: CachedModel[];
+      try {
+        models = await fetchModels(baseUrl, apiKey);
+      } catch (err) {
+        ctx.ui.notify(`Connection failed — not saved.\n${err}`, "error");
+        return;
+      }
+      if (!models.length) {
+        ctx.ui.notify("Connected but no models returned. Check URL and key.", "error");
+        return;
+      }
+
+      // Step 5 — save to config and register with pi
+      config.providers[key] = {
+        displayName: tpl.displayName,
+        baseUrl,
+        apiKey,
+        cachedModels: models,
+      };
+      saveConfig(config);
+      registerProvider(pi, key, config.providers[key]);
+
+      ctx.ui.notify(
+        `${tpl.displayName} registered — ${models.length} model(s) added to /model.`,
+        "success"
+      );
+    },
+  });
+
+  // ── /compat-logout ─────────────────────────────────────────────────────────
+  pi.registerCommand("compat-logout", {
+    description: "Remove an OpenAI-compatible provider from pi's model list",
+    handler: async (_args, ctx) => {
+      const providerKeys = Object.keys(config.providers);
+      if (!providerKeys.length) {
+        ctx.ui.notify("No compat providers are registered.", "info");
+        return;
+      }
+
+      // If only one provider, confirm directly; otherwise ask which to remove.
+      let key: string;
+      if (providerKeys.length === 1) {
+        key = providerKeys[0];
+        const name = config.providers[key].displayName;
+        const ok = await ctx.ui.confirm("Remove Provider", `Unregister "${name}"?`);
+        if (!ok) { ctx.ui.notify("Cancelled.", "info"); return; }
+      } else {
+        const labels = providerKeys.map((k) => config.providers[k].displayName);
+        const chosen = await ctx.ui.select("Remove which provider?", labels);
+        if (!chosen) { ctx.ui.notify("Cancelled.", "info"); return; }
+        key = providerKeys[labels.indexOf(chosen)];
+      }
+
+      const name = config.providers[key].displayName;
+      pi.unregisterProvider(compatKey(key));
+      delete config.providers[key];
+      saveConfig(config);
+
+      // If no compat providers remain, restore the previous model.
+      const isLast = Object.keys(config.providers).length === 0;
+      if (isLast && config.previousModel) {
+        const prev = config.previousModel;
+        try {
+          await (pi as any).setModel({ provider: prev.provider, id: prev.id });
+          ctx.ui.notify(`"${name}" removed. Restored ${prev.provider}/${prev.id}.`, "info");
+        } catch {
+          ctx.ui.notify(`"${name}" removed. Use /model to pick a model.`, "info");
+        }
+      } else {
+        ctx.ui.notify(
+          isLast
+            ? `"${name}" removed. Use /model to pick a model.`
+            : `"${name}" removed.`,
+          "info"
+        );
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@billjr99/pi-openai-compat",
+  "version": "1.0.0",
+  "description": "pi-coding-agent extension: OpenAI-compatible endpoint support (OpenRouter, NVIDIA NIM, Nous Portal, Ollama, custom)",
+  "author": "Bill Mongan <https://github.com/BillJr99>",
+  "license": "MIT",
+  "homepage": "https://github.com/BillJr99/pi-openai-compat#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BillJr99/pi-openai-compat.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BillJr99/pi-openai-compat/issues"
+  },
+  "files": [
+    "index.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {}
+}