pi-provider-freellmapi 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dolfly
+
+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,74 @@
+# pi-provider-freellmapi
+
+A [pi](https://pi.dev) extension that registers the **FreeLLM API** gateway
+([freeapi.n.cofire.cn](https://freeapi.n.cofire.cn)) as an OpenAI-compatible
+provider, with automatic model discovery.
+
+It only exposes models your API key can actually use (the gateway reports
+~250 models, but most are `available: false` for a free key — this extension
+filters those out), and it reads each model's real context window and
+reasoning/vision capabilities.
+
+## Install
+
+```bash
+pi install npm:pi-provider-freellmapi
+```
+
+## Configure
+
+Copy the example config to `~/.pi/agent/freellmapi.json` and fill in your key:
+
+```bash
+cp "$(pi config-dir 2>/dev/null || echo ~/.pi/agent)/freellmapi.json" freellmapi.example.json
+# or just:
+mkdir -p ~/.pi/agent
+cp freellmapi.example.json ~/.pi/agent/freellmapi.json
+```
+
+```json
+{
+  "name": "freellmapi",
+  "label": "FreeLM API",
+  "baseUrl": "https://freeapi.n.cofire.cn/v1",
+  "apiKey": "freellmapi-...",
+  "fetchModels": true,
+  "contextWindow": 131072,
+  "maxTokens": 16384,
+  "compat": { "supportsDeveloperRole": false }
+}
+```
+
+The `apiKey` supports pi's value syntax: a literal, `$ENV_VAR`, `${ENV_VAR}`,
+or `!command`. You can also skip the config file entirely and just export
+`FREELM_API_KEY`.
+
+- Override the config path with `PI_FREELMAPI_CONFIG=/path/to/config.json`.
+- Set `"fetchModels": false` to use only the static `models` list.
+
+## Usage
+
+```bash
+pi --provider freellmapi --model auto
+pi --provider freellmapi --model deepseek-v4-flash
+```
+
+Or open `/model` in the TUI and pick from the `FreeLM API` group.
+
+## Config reference
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `name` | `freellmapi` | Provider id (`--provider <name>`) |
+| `label` | `FreeLM API` | Display label shown in `/model` |
+| `baseUrl` | `https://freeapi.n.cofire.cn/v1` | OpenAI-compatible endpoint |
+| `apiKey` | `$FREELM_API_KEY` | API key (literal / env / command) |
+| `fetchModels` | `true` | Discover models from `{baseUrl}/models` |
+| `contextWindow` | `131072` | Fallback context window per model |
+| `maxTokens` | `16384` | Fallback max output tokens |
+| `compat` | `{"supportsDeveloperRole":false}` | Provider compatibility flags |
+| `models` | `[]` | Static models (override discovered models by id) |
+
+## License
+
+MIT

package/freellmapi.example.json

@@ -0,0 +1,13 @@
+{
+  "name": "freellmapi",
+  "label": "FreeLM API",
+  "baseUrl": "https://freeapi.n.cofire.cn/v1",
+  "apiKey": "$FREELLM_API_KEY",
+  "fetchModels": true,
+  "contextWindow": 131072,
+  "maxTokens": 16384,
+  "compat": {
+    "supportsDeveloperRole": false
+  },
+  "models": []
+}

package/index.ts

@@ -0,0 +1,236 @@
+/**
+ * pi-provider-freellmapi — register the FreeLLM API gateway as a pi provider.
+ *
+ * This extension registers `https://freeapi.n.cofire.cn/v1` as an
+ * OpenAI-compatible (`openai-completions`) provider and auto-discovers the
+ * models your API key can actually use.
+ *
+ * ## Install
+ *
+ * ```bash
+ * pi install npm:pi-provider-freellmapi
+ * ```
+ *
+ * Then create the config file `~/.pi/agent/freellmapi.json`:
+ *
+ * ```json
+ * {
+ *   "name": "freellmapi",                    // provider id → --provider freellmapi
+ *   "label": "FreeLM API",                   // display label in /model
+ *   "baseUrl": "https://freeapi.n.cofire.cn/v1",
+ *   "apiKey": "freellmapi-...",              // literal, $ENV_VAR, or ${ENV_VAR}
+ *   "fetchModels": true,                     // discover models from {baseUrl}/models
+ *   "contextWindow": 131072,                 // fallback context window (tokens)
+ *   "maxTokens": 16384,                      // fallback max output tokens
+ *   "compat": { "supportsDeveloperRole": false },
+ *   "models": []                             // optional static models (override by id)
+ * }
+ * ```
+ *
+ * Config path override: `PI_FREELLMAPI_CONFIG=/path/to/config.json`.
+ * API key fallback env var: `FREELLM_API_KEY` (used when the config file has
+ * no `apiKey`).
+ *
+ * Only models the gateway reports as `available` (with a positive
+ * `context_window`) are registered, so the list stays limited to models that
+ * work with your key. Reasoning support is detected from the gateway's
+ * `supported_parameters` (`reasoning_effort`) or the model name; vision models
+ * get `input: ["text", "image"]`.
+ */
+
+import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface RemoteModel {
+  id: string;
+  name?: string;
+  context_window?: number | null;
+  available?: boolean;
+  supported_parameters?: string[];
+}
+
+interface ConfigFile {
+  name?: string;
+  label?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  fetchModels?: boolean;
+  contextWindow?: number;
+  maxTokens?: number;
+  compat?: Record<string, unknown>;
+  models?: ProviderModelConfig[];
+}
+
+// ── Defaults ───────────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG_PATH = resolve(homedir(), ".pi", "agent", "freellmapi.json");
+
+const DEFAULTS = {
+  name: "freellmapi",
+  label: "FreeLM API",
+  baseUrl: "https://freeapi.n.cofire.cn/v1",
+  contextWindow: 131072,
+  maxTokens: 16384,
+} as const;
+
+/** Fallback models when discovery fails (or fetchModels is off and no static list). */
+const FALLBACK_MODELS: Array<{ id: string; name: string }> = [
+  { id: "auto", name: "Auto (router picks best available model)" },
+  { id: "fusion", name: "Fusion (panel of models + judge)" },
+  { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash" },
+  { id: "qwen3.7-flash", name: "Qwen3.7 Flash" },
+  { id: "claude-sonnet-4-5", name: "Claude Sonnet slot" },
+];
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function loadConfig(configPath: string): ConfigFile {
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8")) as ConfigFile;
+  } catch (err) {
+    console.error(`[freellmapi] Failed to parse config: ${configPath}`, err);
+    return {};
+  }
+}
+
+/**
+ * Resolve an apiKey value that may use pi's value syntax:
+ *   - `${ENV_VAR}` / `$ENV_VAR` (whole value) → environment variable
+ *   - `!command` → returned as-is (pi resolves it at request time)
+ *   - literal string → returned as-is
+ */
+function resolveApiKey(raw: string): string {
+  if (raw.startsWith("!")) return raw;
+  const braced = raw.match(/^\$\{([^}]+)\}$/);
+  if (braced) return process.env[braced[1]] ?? "";
+  if (raw.startsWith("$") && !raw.startsWith("$$")) {
+    return process.env[raw.slice(1)] ?? raw;
+  }
+  return raw;
+}
+
+function isVision(name: string, id: string): boolean {
+  return /vision|vl|image|moondream/i.test(`${name} ${id}`);
+}
+
+/** A model supports thinking if the gateway advertises reasoning_effort, or the name hints at it. */
+function isReasoning(name: string, id: string, params: string[]): boolean {
+  return params.includes("reasoning_effort") || /reasoning|thinking/i.test(`${name} ${id}`);
+}
+
+async function fetchModelsFromEndpoint(
+  baseUrl: string,
+  apiKey?: string,
+): Promise<RemoteModel[]> {
+  const url = baseUrl.replace(/\/+$/, "") + "/models";
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (apiKey) headers["Authorization"] = `Bearer ${resolveApiKey(apiKey)}`;
+
+  const response = await fetch(url, { headers });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} from ${url}`);
+  }
+  const payload = (await response.json()) as { data?: RemoteModel[] };
+  return Array.isArray(payload.data) ? payload.data : [];
+}
+
+function mapRemoteModel(
+  m: RemoteModel,
+  contextWindow: number,
+  maxTokens: number,
+): ProviderModelConfig {
+  const name = m.name?.trim() || m.id;
+  const window = typeof m.context_window === "number" && m.context_window > 0
+    ? m.context_window
+    : contextWindow;
+  const params = m.supported_parameters ?? [];
+  return {
+    id: m.id,
+    name,
+    reasoning: isReasoning(name, m.id, params),
+    input: isVision(name, m.id) ? ["text", "image"] : ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: window,
+    maxTokens: Math.min(maxTokens, window),
+  };
+}
+
+function mergeModels(
+  staticModels: ProviderModelConfig[],
+  discoveredModels: ProviderModelConfig[],
+): ProviderModelConfig[] {
+  const map = new Map<string, ProviderModelConfig>();
+  for (const m of discoveredModels) map.set(m.id, m);
+  // Static models override discovered ones by id.
+  for (const m of staticModels) map.set(m.id, m);
+  return [...map.values()];
+}
+
+// ── Extension Entry Point ──────────────────────────────────────────────────
+
+export default async function (pi: ExtensionAPI) {
+  const configPath = process.env["PI_FREELLMAPI_CONFIG"] ?? DEFAULT_CONFIG_PATH;
+  const config = loadConfig(configPath);
+
+  const providerId = config.name ?? DEFAULTS.name;
+  const baseUrl = (config.baseUrl ?? DEFAULTS.baseUrl).replace(/\/+$/, "");
+  const apiKey = config.apiKey ?? process.env["FREELLM_API_KEY"];
+  const contextWindow = config.contextWindow ?? DEFAULTS.contextWindow;
+  const maxTokens = config.maxTokens ?? DEFAULTS.maxTokens;
+  const staticModels = config.models ?? [];
+
+  let discovered: ProviderModelConfig[] = [];
+  if (config.fetchModels !== false) {
+    try {
+      const remote = await fetchModelsFromEndpoint(baseUrl, apiKey);
+      discovered = remote
+        .filter((m) => m.available !== false)
+        .filter((m) => typeof m.context_window === "number" && m.context_window > 0)
+        .map((m) => mapRemoteModel(m, contextWindow, maxTokens));
+    } catch (err) {
+      console.warn(
+        `[freellmapi] Could not fetch models from ${baseUrl}:`,
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+
+  let models = mergeModels(staticModels, discovered);
+
+  if (models.length === 0) {
+    console.warn(`[freellmapi] No models discovered; registering fallback list`);
+    models = FALLBACK_MODELS.map(({ id, name }) => ({
+      id,
+      name,
+      reasoning: /reasoning|thinking/i.test(name),
+      input: ["text"] as ("text" | "image")[],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow,
+      maxTokens: Math.min(maxTokens, contextWindow),
+    }));
+  }
+
+  const providerConfig: Record<string, unknown> = {
+    name: config.label ?? DEFAULTS.label,
+    baseUrl,
+    apiKey,
+    api: "openai-completions",
+    models,
+    compat: {
+      supportsDeveloperRole: false,
+      ...(config.compat ?? {}),
+    },
+  };
+
+  pi.registerProvider(providerId, providerConfig as never);
+  console.log(
+    `[freellmapi] Registered "${providerId}" → ${baseUrl} (${models.length} model(s))`,
+  );
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "pi-provider-freellmapi",
+  "version": "1.0.0",
+  "description": "Register the FreeLLM API gateway (freeapi.n.cofire.cn) as an OpenAI-compatible provider in pi, with automatic model discovery",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "provider",
+    "openai",
+    "llm",
+    "freellmapi",
+    "free"
+  ],
+  "license": "MIT",
+  "author": "dolfly",
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE",
+    "freellmapi.example.json"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}