pi-tinyllm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-tinyllm contributors
+
+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,90 @@
+# pi-tinyllm
+
+[![CI](https://github.com/mipsel64/pi-tinyllm/actions/workflows/ci.yml/badge.svg)](https://github.com/mipsel64/pi-tinyllm/actions/workflows/ci.yml)
+
+A standalone [Pi](https://pi.dev) package that discovers models from a local [TinyLLM](https://github.com/mipsel64/tinyllm) gateway and inherits their metadata from Pi's installed model catalogs.
+
+## Install
+
+Install the published package:
+
+```sh
+pi install npm:pi-tinyllm
+```
+
+Or install the current GitHub version:
+
+```sh
+pi install git:github.com/mipsel64/pi-tinyllm
+```
+
+Or try a local checkout without installing it:
+
+```sh
+pi -e /path/to/pi-tinyllm --list-models tinyllm
+```
+
+Install a local checkout for future Pi sessions:
+
+```sh
+pi install /path/to/pi-tinyllm
+```
+
+## Configure
+
+Set the gateway URL and its bearer token before starting Pi:
+
+```sh
+export TINYLLM_BASE_URL=http://127.0.0.1:8080
+export TINYLLM_API_KEY=your-gateway-token
+pi --list-models tinyllm
+```
+
+`TINYLLM_BASE_URL` defaults to `http://127.0.0.1:8080`. Values ending in `/anthropic` or `/v1` are accepted and normalized. When TinyLLM authentication is disabled, explicitly set the token accepted by that gateway (commonly `TINYLLM_API_KEY=tinyllm`); this package does not guess a credential.
+
+You can store both the gateway URL and key through Pi's native `/login` flow instead of keeping them in the environment. Environment configuration is still needed for first-run `--list-models`, because extensions cannot read Pi's credential store before registration. Later native refreshes use the stored values.
+
+Select a discovered public ID without removing its TinyLLM namespace:
+
+```sh
+pi --provider tinyllm --model anthropic/claude-sonnet-4-6
+```
+
+## Behavior and limitations
+
+- Canonical TinyLLM namespaces map to same-named Pi catalogs. `codex` maps to `openai-codex`; `openai` prefers `openai-codex` metadata and then `openai`.
+- Generated OpenAI `-fast` IDs are filtered from discovery. Select an advertised base `openai/gpt-*` model, then run `/fast` to toggle TinyLLM fast routing for the current session. The command changes only the outgoing request ID; run it again to disable fast routing.
+- `/fast` is available only while a `tinyllm` `openai/gpt-*` model is selected. Other models are left unchanged and produce a warning. The toggle follows the active session branch and is restored on reload or resume.
+- Anthropic Messages, OpenAI Responses, and Chat Completions models use TinyLLM's corresponding routes.
+- Unknown aliases, unknown models, and models using unsupported wire APIs are omitted rather than assigned guessed metadata.
+- Pi owns the persisted model catalog. Failed refreshes retain the last known good catalog, and offline refreshes restore it.
+- Pi 0.87.1 performs only a cache refresh after registering an extension provider. This package does one bounded first-run discovery before registration so `--list-models` works with environment configuration. Pi may then restore an older persisted catalog during the same startup; a later native catalog refresh reconciles it. The package does not maintain a second cache.
+
+## Publishing
+
+npm requires the first version to exist before trusted publishing can be configured. Publish `0.1.0` once with `npm login && npm publish`, then add this trusted publisher in the package settings on npmjs.com:
+
+- Organization or user: `mipsel64`
+- Repository: `pi-tinyllm`
+- Workflow: `release.yml`
+- Environment: leave blank
+- Allowed action: `npm publish`
+
+Future releases are tokenless and include npm provenance:
+
+```sh
+npm version patch
+git push origin main --follow-tags
+```
+
+## Development
+
+```sh
+npm test
+```
+
+Requires Node.js 22.19 or newer. Pi supplies the peer packages at runtime.
+
+## License
+
+MIT

package/extensions/tinyllm.ts

@@ -0,0 +1,322 @@
+import {
+	createProvider,
+	type Api,
+	type Model,
+	type Provider,
+	type ProviderStreams,
+} from "@earendil-works/pi-ai";
+import { anthropicMessagesApi, openAICompletionsApi, openAIResponsesApi } from "@earendil-works/pi-ai/compat";
+import { getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_BASE_URL = "http://127.0.0.1:8080";
+const MAX_DIAGNOSTIC_IDS = 5;
+const MAX_DIAGNOSTIC_ID_LENGTH = 120;
+const SUPPORTED_APIS = new Map<Api, Api>([
+	["anthropic-messages", "anthropic-messages"],
+	["openai-completions", "openai-completions"],
+	["openai-responses", "openai-responses"],
+	["openai-codex-responses", "openai-responses"],
+	["azure-openai-responses", "openai-responses"],
+]);
+
+type Warn = (message: string) => void;
+
+export interface TinyllmProviderOptions {
+	baseUrl?: string;
+	fetch?: typeof fetch;
+	warn?: Warn;
+}
+
+export function normalizeBaseUrl(value: string): string {
+	const baseUrl = value.trim().replace(/\/+$/, "");
+	return baseUrl.replace(/\/(?:anthropic|v1)$/, "");
+}
+
+export function apiBaseUrl(baseUrl: string, api: Api): string {
+	const root = normalizeBaseUrl(baseUrl);
+	return api === "anthropic-messages" ? `${root}/anthropic` : `${root}/v1`;
+}
+
+function catalogCandidates(prefix: string): string[] {
+	if (prefix === "openai") return ["openai-codex", "openai"];
+	if (prefix === "codex") return ["openai-codex"];
+	return getBuiltinProviders().includes(prefix as ReturnType<typeof getBuiltinProviders>[number]) ? [prefix] : [];
+}
+
+function parsePublicId(publicId: string): { prefix: string; nativeId: string } | undefined {
+	if (publicId !== publicId.trim() || publicId.includes("//")) return undefined;
+	const slash = publicId.indexOf("/");
+	if (slash <= 0 || slash === publicId.length - 1) return undefined;
+	return { prefix: publicId.slice(0, slash), nativeId: publicId.slice(slash + 1) };
+}
+
+function lookupCatalogModel(prefix: string, nativeId: string): Model<Api> | undefined {
+	for (const provider of catalogCandidates(prefix)) {
+		const model = getBuiltinModels(provider as Parameters<typeof getBuiltinModels>[0]).find(
+			(candidate) => candidate.id === nativeId,
+		);
+		if (model) return model as Model<Api>;
+	}
+	return undefined;
+}
+
+function routedCompat(source: Model<Api>, api: Api): Model<Api>["compat"] {
+	if (api !== "anthropic-messages") return source.compat;
+	const compat = source.compat as Model<"anthropic-messages">["compat"];
+	if (!compat?.allowedFallbackModels) return compat;
+	return {
+		...compat,
+		allowedFallbackModels: compat.allowedFallbackModels.map((fallback) => ({
+			...fallback,
+			provider: "tinyllm",
+		})),
+	};
+}
+
+export function mapDiscoveredModels(
+	ids: readonly unknown[],
+	baseUrl: string,
+	warn: Warn = console.warn,
+): Model<Api>[] {
+	const models: Model<Api>[] = [];
+	const seen = new Set<string>();
+	const omitted: string[] = [];
+	let omittedCount = 0;
+	const omit = (id: string) => {
+		omittedCount++;
+		const sanitized = id.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+		const display = sanitized.length > MAX_DIAGNOSTIC_ID_LENGTH
+			? `${sanitized.slice(0, MAX_DIAGNOSTIC_ID_LENGTH - 3)}...`
+			: sanitized;
+		if (omitted.length < MAX_DIAGNOSTIC_IDS) omitted.push(display);
+	};
+
+	for (const value of ids) {
+		if (typeof value !== "string") {
+			omit("<invalid id>");
+			continue;
+		}
+		const discovered = parsePublicId(value);
+		if (
+			discovered?.prefix === "openai"
+			&& discovered.nativeId.startsWith("gpt-")
+			&& discovered.nativeId.endsWith("-fast")
+		) {
+			continue;
+		}
+		const publicId = value;
+		if (seen.has(publicId)) continue;
+		seen.add(publicId);
+		const parsed = parsePublicId(publicId);
+		const source = parsed ? lookupCatalogModel(parsed.prefix, parsed.nativeId) : undefined;
+		const api = source ? SUPPORTED_APIS.get(source.api) : undefined;
+		if (!parsed || !source || !api) {
+			omit(value);
+			continue;
+		}
+		models.push({
+			...source,
+			id: publicId,
+			provider: "tinyllm",
+			api,
+			baseUrl: apiBaseUrl(baseUrl, api),
+			compat: routedCompat(source, api),
+		});
+	}
+
+	if (omitted.length > 0) {
+		const suffix = omittedCount > omitted.length ? ` (+${omittedCount - omitted.length} more)` : "";
+		warn(`TinyLLM omitted unknown, malformed, or unsupported models: ${omitted.join(", ")}${suffix}`);
+	}
+	return models;
+}
+
+export async function discoverModels(
+	baseUrl: string,
+	apiKey: string,
+	signal: AbortSignal,
+	fetchImpl: typeof fetch = fetch,
+	warn: Warn = console.warn,
+): Promise<Model<Api>[]> {
+	const response = await fetchImpl(`${normalizeBaseUrl(baseUrl)}/v1/models`, {
+		headers: { Authorization: `Bearer ${apiKey}` },
+		signal,
+	});
+	if (!response.ok) throw new Error(`TinyLLM model discovery failed with HTTP ${response.status}`);
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch (error) {
+		signal.throwIfAborted();
+		throw new Error("TinyLLM model discovery returned invalid JSON", { cause: error });
+	}
+	if (!payload || typeof payload !== "object" || !("data" in payload) || !Array.isArray(payload.data)) {
+		throw new Error("TinyLLM model discovery returned an invalid payload");
+	}
+	return mapDiscoveredModels(
+		payload.data.map((entry) =>
+			entry && typeof entry === "object" && "id" in entry ? (entry as { id?: unknown }).id : undefined,
+		),
+		baseUrl,
+		warn,
+	);
+}
+
+function routedStreams(delegate: ProviderStreams, api: Api): ProviderStreams {
+	const route = <T extends Model<Api>>(model: T): T =>
+		({ ...model, api, provider: "tinyllm", baseUrl: apiBaseUrl(model.baseUrl, api) }) as T;
+	const routeOptions = <T extends { apiKey?: string; headers?: Record<string, string> } | undefined>(options: T): T => {
+		if (api !== "anthropic-messages" || !options?.apiKey) return options;
+		return {
+			...options,
+			headers: { ...options.headers, Authorization: `Bearer ${options.apiKey}` },
+		} as T;
+	};
+	return {
+		stream: (model, context, options) => delegate.stream(route(model), context, routeOptions(options)),
+		streamSimple: (model, context, options) => delegate.streamSimple(route(model), context, routeOptions(options)),
+	};
+}
+
+export function createTinyllmProvider(options: TinyllmProviderOptions = {}): Provider<Api> {
+	const defaultBaseUrl = normalizeBaseUrl(options.baseUrl ?? process.env.TINYLLM_BASE_URL ?? DEFAULT_BASE_URL);
+	const warn = options.warn ?? console.warn;
+	const fetchImpl = options.fetch ?? fetch;
+
+	return createProvider<Api>({
+		id: "tinyllm",
+		name: "TinyLLM",
+		baseUrl: defaultBaseUrl,
+		auth: {
+			apiKey: {
+				name: "TinyLLM API key",
+				async login({ prompt, signal }) {
+					signal.throwIfAborted();
+					const enteredBaseUrl = await prompt({
+						type: "text",
+						message: "TinyLLM URL",
+						placeholder: defaultBaseUrl,
+					});
+					signal.throwIfAborted();
+					const key = await prompt({ type: "secret", message: "TinyLLM API key" });
+					signal.throwIfAborted();
+					return {
+						type: "api_key",
+						key,
+						env: { TINYLLM_BASE_URL: normalizeBaseUrl(enteredBaseUrl || defaultBaseUrl) },
+					};
+				},
+				async resolve({ ctx, credential, signal }) {
+					signal.throwIfAborted();
+					const key = credential?.key ?? (await ctx.env("TINYLLM_API_KEY"));
+					signal.throwIfAborted();
+					if (!key) return undefined;
+					const configuredBaseUrl = credential?.env?.TINYLLM_BASE_URL ?? (await ctx.env("TINYLLM_BASE_URL"));
+					signal.throwIfAborted();
+					const baseUrl = normalizeBaseUrl(configuredBaseUrl ?? defaultBaseUrl);
+					return {
+						auth: { apiKey: key, baseUrl },
+						env: { TINYLLM_BASE_URL: baseUrl },
+						source: credential?.key !== undefined ? "Stored API key" : "TINYLLM_API_KEY",
+					};
+				},
+			},
+		},
+		models: [],
+		fetchModels: async ({ credential, signal }) => {
+			if (credential?.type !== "api_key" || !credential.key) {
+				throw new Error("TinyLLM API key is not configured");
+			}
+			return discoverModels(
+				credential.env?.TINYLLM_BASE_URL ?? defaultBaseUrl,
+				credential.key,
+				signal,
+				fetchImpl,
+				warn,
+			);
+		},
+		api: {
+			"anthropic-messages": routedStreams(anthropicMessagesApi(), "anthropic-messages"),
+			"openai-responses": routedStreams(openAIResponsesApi(), "openai-responses"),
+			"openai-completions": routedStreams(openAICompletionsApi(), "openai-completions"),
+		},
+	});
+}
+
+export async function bootstrapProvider(provider: Provider<Api>, apiKey: string, baseUrl: string): Promise<void> {
+	if (!provider.refreshModels) return;
+	const signal = AbortSignal.timeout(5_000);
+	await provider.refreshModels({
+		credential: { type: "api_key", key: apiKey, env: { TINYLLM_BASE_URL: normalizeBaseUrl(baseUrl) } },
+		allowNetwork: true,
+		signal,
+		async publish({ update }) {
+			update?.();
+			return true;
+		},
+	});
+}
+
+export function isFastCapable(model: Pick<Model<Api>, "provider" | "id"> | undefined): boolean {
+	return model?.provider === "tinyllm" && /^openai\/gpt-.+/.test(model.id) && !model.id.endsWith("-fast");
+}
+
+export function rewriteFastPayload(
+	payload: unknown,
+	enabled: boolean,
+	model: Pick<Model<Api>, "provider" | "id"> | undefined,
+): unknown {
+	if (!enabled || !isFastCapable(model) || !payload || typeof payload !== "object" || Array.isArray(payload)) {
+		return payload;
+	}
+	const request = payload as Record<string, unknown>;
+	if (typeof request.model !== "string" || request.model !== model.id || request.model.endsWith("-fast")) return payload;
+	return { ...request, model: `${request.model}-fast` };
+}
+
+const FAST_STATE = "tinyllm-fast-mode";
+
+export function registerFastMode(pi: ExtensionAPI): void {
+	let enabled = false;
+	const restore = (ctx: ExtensionContext) => {
+		enabled = false;
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type === "custom" && entry.customType === FAST_STATE) {
+				enabled = (entry.data as { enabled?: unknown } | undefined)?.enabled === true;
+			}
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => restore(ctx));
+	pi.on("session_tree", (_event, ctx) => restore(ctx));
+	pi.on("before_provider_request", (event, ctx) => rewriteFastPayload(event.payload, enabled, ctx.model));
+	pi.registerCommand("fast", {
+		description: "Toggle TinyLLM fast routing for the selected OpenAI GPT model",
+		handler: async (_args, ctx) => {
+			if (!isFastCapable(ctx.model)) {
+				ctx.ui.notify("/fast is only available for TinyLLM openai/gpt-* models", "warning");
+				return;
+			}
+			enabled = !enabled;
+			pi.appendEntry(FAST_STATE, { enabled });
+			ctx.ui.notify(`TinyLLM fast routing ${enabled ? "enabled" : "disabled"}`, "info");
+		},
+	});
+}
+
+export default async function tinyllmExtension(pi: ExtensionAPI): Promise<void> {
+	registerFastMode(pi);
+	const baseUrl = process.env.TINYLLM_BASE_URL ?? DEFAULT_BASE_URL;
+	const provider = createTinyllmProvider({ baseUrl });
+	const apiKey = process.env.TINYLLM_API_KEY;
+	if (apiKey) {
+		try {
+			await bootstrapProvider(provider, apiKey, baseUrl);
+		} catch (error) {
+			console.warn(`TinyLLM startup discovery unavailable: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	pi.registerProvider(provider);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pi-tinyllm",
+  "version": "0.1.0",
+  "description": "Dynamic TinyLLM provider package for Pi",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mipsel64/pi-tinyllm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mipsel64/pi-tinyllm/issues"
+  },
+  "homepage": "https://github.com/mipsel64/pi-tinyllm#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/tinyllm.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1"
+  }
+}