pi-custom-model-provider 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,13 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 - 2026-11-22
4
+
5
+ First release.
6
+
7
+ - Discovers models at startup from every `openai-completions` provider with a
8
+ `baseUrl` in `models.json`.
9
+ - Implements `refreshModels` so Pi's own model refresh re-reads the endpoint
10
+ with the credential it resolved.
11
+ - `/custom-models` re-fetches, `/custom-models status` reports counts and key
12
+ source.
13
+ - `PI_OFFLINE` skips the startup fetch.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 zaypen
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,110 @@
1
- # Temporary Holding Version
1
+ # pi-custom-model-provider
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Discover the model catalog of the OpenAI-compatible providers you already
4
+ configured in `~/.pi/agent/models.json`, instead of maintaining the list twice.
5
+
6
+ For every provider there whose `api` is `openai-completions` and that has a
7
+ `baseUrl`, the extension:
8
+
9
+ 1. reads the model list from `GET {baseUrl}/models` at startup,
10
+ 2. registers the result through `pi.registerProvider()`, so the models appear
11
+ in `/model` and in `pi --list-models`,
12
+ 3. implements `refreshModels`, so Pi's own model refresh re-reads the endpoint
13
+ with the effective credential.
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ pi install npm:pi-custom-model-provider
19
+ # or from git
20
+ pi install git:github.com/zaypen/pi-custom-model-provider
21
+ ```
22
+
23
+ Run `/reload` if Pi is already running.
24
+
25
+ ## Configuration
26
+
27
+ No config file of its own. This `models.json` entry is the whole setup:
28
+
29
+ ```json
30
+ {
31
+ "providers": {
32
+ "bifrost": {
33
+ "baseUrl": "https://gateway.example.com/v1",
34
+ "apiKey": "$BIFROST_API_KEY",
35
+ "models": [
36
+ { "id": "deepseek-r1", "reasoning": true, "contextWindow": 163840 }
37
+ ]
38
+ }
39
+ }
40
+ }
41
+ ```
42
+
43
+ With 30 models on the endpoint you write one of them.
44
+
45
+ ### Key resolution
46
+
47
+ `~/.pi/agent/auth.json` first (the entry Pi writes for that provider id when you
48
+ run `/login`, `type: "api_key"`), then the `apiKey` value in `models.json`,
49
+ which is expanded for `$ENV_VAR` and `${ENV_VAR}`. Providers that resolve no key
50
+ are registered from their `models` entries only, and the fetch is reported as
51
+ `no API key`.
52
+
53
+ Live refreshes pass the credential Pi resolved to `refreshModels`, so a stored
54
+ or refreshed credential is used in preference to the startup key.
55
+
56
+ ### Merge policy
57
+
58
+ The endpoint decides **which** models exist; `models.json` decides their
59
+ metadata. If `deepseek-r1` is in your `models` array and the endpoint returns it
60
+ too, your `contextWindow`, `cost`, `reasoning`, `input`, `name`, `api`, and
61
+ `baseUrl` win. A model you never wrote gets the defaults: 128000 context
62
+ window, 8192 max tokens, zero cost, text-only input.
63
+
64
+ Models that are in `models.json` but not returned by the endpoint stay
65
+ registered. A refresh failure keeps the previously known list.
66
+
67
+ ## Commands
68
+
69
+ - `/custom-models` — re-fetch every matching provider and report.
70
+ - `/custom-models status` — show model counts, how many came from the endpoint,
71
+ and where the key came from.
72
+
73
+ ## Behaviour
74
+
75
+ - `PI_OFFLINE` set: no startup fetch. `models.json` entries are still
76
+ registered, and Pi's refresh callback is told to stay off the network.
77
+ - Each fetch is capped at 3 seconds; the caller's signal is honoured on top.
78
+
79
+ ## Limitations
80
+
81
+ - Only `openai-completions` providers are fetched. Providers on other APIs are
82
+ left alone, including `openai-responses` ones.
83
+ - The 3 second cap is per endpoint and fixed.
84
+
85
+ ## Compared to its siblings
86
+
87
+ Three other Pi extensions discover models from OpenAI-compatible endpoints, so
88
+ pick the one that matches your setup:
89
+
90
+ | | config source | refresh | metadata authority |
91
+ |---|---|---|---|
92
+ | this one | `models.json` | startup seed + native `refreshModels` | `models.json` wins |
93
+ | `pi-model-discovery` | `models.json` | its own commands | endpoint wins |
94
+ | `pi-dynamic-models` | separate `dynamic-models.json` | startup + `session_start` | its defaults |
95
+
96
+ Differences that actually matter: this one finds keys that `/login` stored in
97
+ `auth.json`, and hands discovery to Pi's refresh machinery rather than running
98
+ on its own clock.
99
+
100
+ ## Development
101
+
102
+ Try it without installing:
103
+
104
+ ```bash
105
+ pi -e ./extensions/index.ts
106
+ ```
107
+
108
+ ## License
109
+
110
+ MIT
@@ -0,0 +1,254 @@
1
+ /**
2
+ * Discover models for the OpenAI-compatible providers already declared in
3
+ * ~/.pi/agent/models.json, and keep the live catalog in sync.
4
+ *
5
+ * No new config file: the `providers` section of models.json is the source of
6
+ * truth. Fetched ids are merged with the models.json entries, so hand-set
7
+ * context windows, costs, and reasoning flags survive a refresh.
8
+ *
9
+ * Two discovery paths, because Pi only calls `refreshModels` during model
10
+ * refresh, not during normal startup:
11
+ * - a startup fetch seeds `models`, so the catalog is visible to normal
12
+ * startup and to `pi --list-models`
13
+ * - `refreshModels` answers live refreshes with the provider's effective
14
+ * credential, which is the one stored by `/login`
15
+ */
16
+
17
+ import { readFileSync } from "node:fs";
18
+ import { homedir } from "node:os";
19
+ import { join } from "node:path";
20
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
21
+
22
+ const AGENT_DIR = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
23
+ const AUTH_PATH = join(AGENT_DIR, "auth.json");
24
+ const MODELS_PATH = join(AGENT_DIR, "models.json");
25
+ const FETCH_TIMEOUT_MS = 3000;
26
+ const SUPPORTED_API = "openai-completions";
27
+ const DEFAULT_CONTEXT_WINDOW = 128000;
28
+ const DEFAULT_MAX_TOKENS = 8192;
29
+
30
+ interface ModelTemplate {
31
+ id: string;
32
+ name?: string;
33
+ api?: string;
34
+ baseUrl?: string;
35
+ reasoning?: boolean;
36
+ input?: ("text" | "image")[];
37
+ cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
38
+ contextWindow?: number;
39
+ maxTokens?: number;
40
+ }
41
+
42
+ interface AuthEntry {
43
+ type?: string;
44
+ key?: string;
45
+ }
46
+
47
+ interface ProviderConfig {
48
+ name?: string;
49
+ baseUrl?: string;
50
+ api?: string;
51
+ apiKey?: string;
52
+ headers?: Record<string, string>;
53
+ models?: ModelTemplate[];
54
+ }
55
+
56
+ interface Target {
57
+ id: string;
58
+ name: string;
59
+ baseUrl: string;
60
+ /** Key used for the startup seed fetch; live refreshes use the effective credential. */
61
+ seedKey: string | undefined;
62
+ keySource: "auth.json" | "models.json" | "none";
63
+ headers?: Record<string, string>;
64
+ templates: ModelTemplate[];
65
+ }
66
+
67
+ interface ModelProviderConfig {
68
+ id: string;
69
+ name: string;
70
+ api?: string;
71
+ baseUrl?: string;
72
+ reasoning: boolean;
73
+ input: ("text" | "image")[];
74
+ cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
75
+ contextWindow: number;
76
+ maxTokens: number;
77
+ }
78
+
79
+ /** Per-target state kept for the status command and for failed refreshes. */
80
+ interface TargetState {
81
+ target: Target;
82
+ models: ModelProviderConfig[];
83
+ fetched: number;
84
+ /** true when `models` came from the endpoint rather than only from models.json. */
85
+ discovered: boolean;
86
+ error?: string;
87
+ lastRefresh: "startup" | "refreshModels" | "command" | "-";
88
+ }
89
+
90
+ function readJsonFile<T>(path: string, fallback: T): T {
91
+ try {
92
+ return JSON.parse(readFileSync(path, "utf8")) as T;
93
+ } catch {
94
+ return fallback;
95
+ }
96
+ }
97
+
98
+ function expandEnv(value: string): string {
99
+ return value.replace(/\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g, (_match, name: string) => process.env[name] ?? "");
100
+ }
101
+
102
+ /**
103
+ * Resolve a key the same way Pi does, but only what is readable without Pi's
104
+ * credential store: auth.json first, then the models.json value.
105
+ */
106
+ function resolveSeedKey(config: ProviderConfig, stored: AuthEntry | undefined): { key: string | undefined; source: Target["keySource"] } {
107
+ if (stored?.type === "api_key" && stored.key) return { key: stored.key, source: "auth.json" };
108
+ const configured = expandEnv(config.apiKey ?? "");
109
+ return configured ? { key: configured, source: "models.json" } : { key: undefined, source: "none" };
110
+ }
111
+
112
+ function collectTargets(): Target[] {
113
+ const auth = readJsonFile<Record<string, AuthEntry>>(AUTH_PATH, {});
114
+ const providers = readJsonFile<{ providers?: Record<string, ProviderConfig> }>(MODELS_PATH, {}).providers ?? {};
115
+ const targets: Target[] = [];
116
+ for (const [id, config] of Object.entries(providers)) {
117
+ if ((config.api ?? SUPPORTED_API) !== SUPPORTED_API || !config.baseUrl) continue;
118
+ const { key, source } = resolveSeedKey(config, auth[id]);
119
+ targets.push({
120
+ id,
121
+ name: config.name ?? id,
122
+ baseUrl: config.baseUrl,
123
+ seedKey: key,
124
+ keySource: source,
125
+ headers: config.headers,
126
+ templates: config.models ?? [],
127
+ });
128
+ }
129
+ return targets;
130
+ }
131
+
132
+ /** GET {baseUrl}/models, tolerating `data`, bare arrays, and catalogs under `models`. */
133
+ async function fetchModelIds(url: string, key: string | undefined, headers: Record<string, string> | undefined, signal: AbortSignal): Promise<string[]> {
134
+ const auth = key ? { Authorization: `Bearer ${key}` } : {};
135
+ const response = await fetch(url, { headers: { ...headers, ...auth }, signal });
136
+ if (!response.ok) throw new Error(`HTTP ${response.status} ${(await response.text().catch(() => "")).slice(0, 120)}`);
137
+ const payload = (await response.json()) as unknown;
138
+ const entries = Array.isArray(payload)
139
+ ? payload
140
+ : ((payload as { data?: unknown[]; models?: unknown[] })?.data ??
141
+ (payload as { models?: unknown[] })?.models ??
142
+ []);
143
+ return entries
144
+ .map((entry) => (typeof entry === "string" ? entry : (entry as { id?: unknown })?.id))
145
+ .filter((id): id is string => typeof id === "string" && id.length > 0);
146
+ }
147
+
148
+ function buildModel(id: string, template: ModelTemplate | undefined): ModelProviderConfig {
149
+ return {
150
+ id,
151
+ name: template?.name ?? id,
152
+ ...(template?.api ? { api: template.api } : {}),
153
+ ...(template?.baseUrl ? { baseUrl: template.baseUrl } : {}),
154
+ reasoning: template?.reasoning ?? false,
155
+ input: template?.input ?? ["text"],
156
+ cost: template?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
157
+ contextWindow: template?.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
158
+ maxTokens: template?.maxTokens ?? DEFAULT_MAX_TOKENS,
159
+ };
160
+ }
161
+
162
+ /** Fetched ids win on presence, models.json entries win on metadata. */
163
+ function mergeModels(ids: string[], templates: ModelTemplate[]): ModelProviderConfig[] {
164
+ const byId = new Map(templates.map((template) => [template.id, template]));
165
+ const fetched = new Set(ids);
166
+ const kept = templates.filter((template) => !fetched.has(template.id)).map((template) => buildModel(template.id, template));
167
+ return [...ids.map((id) => buildModel(id, byId.get(id))), ...kept];
168
+ }
169
+
170
+ function withTimeout(signal: AbortSignal): AbortSignal {
171
+ const timeout = AbortSignal.timeout(FETCH_TIMEOUT_MS);
172
+ return AbortSignal.any([signal, timeout]);
173
+ }
174
+
175
+ /** Ask the endpoint for ids, or keep the previous list when it will not answer. */
176
+ async function discover(state: TargetState, source: TargetState["lastRefresh"], key: string | undefined, signal: AbortSignal): Promise<void> {
177
+ const url = `${state.target.baseUrl.replace(/\/+$/, "")}/models`;
178
+ state.lastRefresh = source;
179
+ if (!key) {
180
+ state.error = `no API key (auth.json: ${state.target.keySource})`;
181
+ state.models = mergeModels([], state.target.templates);
182
+ state.discovered = false;
183
+ return;
184
+ }
185
+ try {
186
+ const ids = await fetchModelIds(url, key, state.target.headers, withTimeout(signal));
187
+ state.models = mergeModels(ids, state.target.templates);
188
+ state.fetched = ids.length;
189
+ state.discovered = true;
190
+ state.error = undefined;
191
+ } catch (error) {
192
+ state.error = (error as Error).message.slice(0, 160);
193
+ state.models = mergeModels(state.discovered ? state.models.map((model) => model.id) : [], state.target.templates);
194
+ }
195
+ }
196
+
197
+ function register(pi: ExtensionAPI, state: TargetState): void {
198
+ const { target } = state;
199
+ pi.registerProvider(target.id, {
200
+ name: target.name,
201
+ baseUrl: target.baseUrl,
202
+ api: SUPPORTED_API,
203
+ ...(target.headers ? { headers: target.headers } : {}),
204
+ models: state.models,
205
+ async refreshModels(context) {
206
+ // Offline/cache-only initialization: keep what is already known.
207
+ if (context.allowNetwork === false) return state.models;
208
+ const credential = context.credential as { type?: string; key?: string } | undefined;
209
+ const key = credential?.key ?? target.seedKey;
210
+ await discover(state, "refreshModels", key, context.signal);
211
+ return state.models;
212
+ },
213
+ });
214
+ }
215
+
216
+ function formatStates(states: TargetState[]): string {
217
+ if (!states.length) return "no OpenAI-compatible providers with baseUrl in models.json";
218
+ return states
219
+ .map((state) =>
220
+ state.error
221
+ ? `${state.target.id}: ${state.fetched} discovered, last error: ${state.error}`
222
+ : `${state.target.id}: ${state.models.length} models (${state.fetched} from endpoint, key ${state.target.keySource})`,
223
+ )
224
+ .join("\n");
225
+ }
226
+
227
+ export default async function (pi: ExtensionAPI) {
228
+ const states: TargetState[] = [];
229
+ for (const target of collectTargets()) states.push({ target, models: [], fetched: 0, discovered: false, lastRefresh: "-" });
230
+
231
+ if (!process.env.PI_OFFLINE) {
232
+ await Promise.all(states.map((state) => discover(state, "startup", state.target.seedKey, AbortSignal.timeout(FETCH_TIMEOUT_MS))));
233
+ } else {
234
+ for (const state of states) state.models = mergeModels([], state.target.templates);
235
+ }
236
+ for (const state of states) register(pi, state);
237
+
238
+ pi.registerCommand("custom-models", {
239
+ description: "Show or re-fetch models from custom OpenAI-compatible providers",
240
+ handler: async (args, ctx) => {
241
+ if (args.trim().toLowerCase().startsWith("status")) {
242
+ ctx.ui.notify(formatStates(states), "info");
243
+ return;
244
+ }
245
+ await Promise.all(
246
+ states.map((state) =>
247
+ discover(state, "command", state.target.seedKey, ctx.signal ?? AbortSignal.timeout(FETCH_TIMEOUT_MS)),
248
+ ),
249
+ );
250
+ for (const state of states) register(pi, state);
251
+ ctx.ui.notify(formatStates(states), states.some((state) => state.error) ? "warning" : "info");
252
+ },
253
+ });
254
+ }
package/package.json CHANGED
@@ -1,6 +1,11 @@
1
1
  {
2
2
  "name": "pi-custom-model-provider",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Discover models from the OpenAI-compatible providers in your models.json and keep them refreshed.",
5
+ "keywords": ["pi-package", "pi", "pi-coding-agent", "openai-compatible", "model-discovery", "provider"],
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "engines": { "node": ">=22" },
9
+ "files": ["extensions", "README.md", "LICENSE", "CHANGELOG.md"],
10
+ "repository": { "type": "git", "url": "git+https://github.com/zaypen/pi-custom-model-provider.git" }
11
+ }