@oh-my-pi/pi-catalog 15.10.11

package/src/discovery/openai-compatible.ts

@@ -0,0 +1,224 @@
+import * as z from "zod/v4";
+import { UNK_CONTEXT_WINDOW, UNK_MAX_TOKENS } from "../provider-models/discovery-constants";
+import type { Api, FetchImpl, ModelSpec, Provider } from "../types";
+
+const MODELS_PATH = "/models";
+
+/**
+ * Minimal OpenAI-style model entry shape consumed by discovery.
+ *
+ * Providers may return additional fields; this type only captures
+ * fields that are useful for generic normalization.
+ */
+export interface OpenAICompatibleModelRecord {
+	id?: unknown;
+	name?: unknown;
+	object?: unknown;
+	owned_by?: unknown;
+	[key: string]: unknown;
+}
+
+/**
+ * Tolerant envelope for OpenAI-compatible `/models` responses.
+ *
+ * Common providers return `{ data: [...] }`, but variants such as
+ * `{ models: [...] }`, `{ result: [...] }`, or direct arrays are also
+ * accepted during extraction.
+ */
+export interface OpenAICompatibleModelsEnvelope {
+	data?: unknown;
+	models?: unknown;
+	result?: unknown;
+	items?: unknown;
+	[key: string]: unknown;
+}
+
+const openAICompatibleModelRecordSchema = z
+	.object({
+		id: z.string().min(1),
+		name: z.string().optional().nullable(),
+		object: z.unknown().optional(),
+		owned_by: z.unknown().optional(),
+	})
+	.loose();
+
+const openAICompatibleModelsEnvelopeSchema = z
+	.object({
+		data: z.unknown().optional(),
+		models: z.unknown().optional(),
+		result: z.unknown().optional(),
+		items: z.unknown().optional(),
+	})
+	.loose();
+
+const openAICompatibleModelsPayloadSchema = z.union([z.array(z.unknown()), openAICompatibleModelsEnvelopeSchema]);
+
+type ParsedOpenAICompatibleModelRecord = z.infer<typeof openAICompatibleModelRecordSchema>;
+
+/**
+ * Context passed to custom OpenAI-compatible model mappers.
+ */
+export interface OpenAICompatibleModelMapperContext<TApi extends Api> {
+	api: TApi;
+	provider: Provider;
+	baseUrl: string;
+}
+
+/**
+ * Options for fetching and normalizing OpenAI-compatible `/models` catalogs.
+ */
+export interface FetchOpenAICompatibleModelsOptions<TApi extends Api> {
+	/** API type assigned to normalized models. */
+	api: TApi;
+	/** Provider id assigned to normalized models. */
+	provider: Provider;
+	/** Provider base URL used for both fetch and normalized model records. */
+	baseUrl: string;
+	/** Optional bearer token for Authorization header. */
+	apiKey?: string;
+	/** Additional request headers. */
+	headers?: Record<string, string>;
+	/** Optional AbortSignal for request cancellation. */
+	signal?: AbortSignal;
+	/** Optional fetch implementation override for testing/custom runtimes. */
+	fetch?: FetchImpl;
+	/**
+	 * Optional post-normalization filter.
+	 * Return false to skip a model.
+	 */
+	filterModel?: (entry: OpenAICompatibleModelRecord, model: ModelSpec<TApi>) => boolean;
+	/**
+	 * Optional mapper override for provider-specific quirks.
+	 * Return null to skip a model.
+	 */
+	mapModel?: (
+		entry: OpenAICompatibleModelRecord,
+		defaults: ModelSpec<TApi>,
+		context: OpenAICompatibleModelMapperContext<TApi>,
+	) => ModelSpec<TApi> | null;
+}
+
+/**
+ * Fetches and normalizes an OpenAI-compatible `/models` catalog.
+ *
+ * Returns `null` on transport/protocol failures.
+ * Returns `[]` only when the endpoint responds successfully with no usable models.
+ */
+export async function fetchOpenAICompatibleModels<TApi extends Api>(
+	options: FetchOpenAICompatibleModelsOptions<TApi>,
+): Promise<ModelSpec<TApi>[] | null> {
+	const baseUrl = normalizeBaseUrl(options.baseUrl);
+	if (!baseUrl) {
+		return null;
+	}
+
+	const requestHeaders: Record<string, string> = {
+		Accept: "application/json",
+		...options.headers,
+	};
+	if (options.apiKey) {
+		requestHeaders.Authorization = `Bearer ${options.apiKey}`;
+	}
+
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	let response: Response;
+	try {
+		response = await fetchImpl(`${baseUrl}${MODELS_PATH}`, {
+			method: "GET",
+			headers: requestHeaders,
+			signal: options.signal,
+		});
+	} catch {
+		return null;
+	}
+
+	if (!response.ok) {
+		return null;
+	}
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch {
+		return null;
+	}
+
+	const entries = extractModelEntries(payload);
+	if (entries === null) {
+		return null;
+	}
+
+	const context: OpenAICompatibleModelMapperContext<TApi> = {
+		api: options.api,
+		provider: options.provider,
+		baseUrl,
+	};
+
+	const deduped = new Map<string, ModelSpec<TApi>>();
+	for (const entry of entries) {
+		const defaults: ModelSpec<TApi> = {
+			id: entry.id,
+			name: typeof entry.name === "string" && entry.name.length > 0 ? entry.name : entry.id,
+			api: options.api,
+			provider: options.provider,
+			baseUrl,
+			reasoning: false,
+			input: ["text"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: UNK_CONTEXT_WINDOW,
+			maxTokens: UNK_MAX_TOKENS,
+		};
+
+		const mapped = options.mapModel?.(entry, defaults, context) ?? defaults;
+		if (!mapped || typeof mapped.id !== "string" || mapped.id.length === 0) {
+			continue;
+		}
+		if (options.filterModel && !options.filterModel(entry, mapped)) {
+			continue;
+		}
+		deduped.set(mapped.id, mapped);
+	}
+
+	return Array.from(deduped.values()).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+	const trimmed = baseUrl.trim();
+	if (!trimmed) {
+		return "";
+	}
+	return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+}
+
+function extractModelEntries(payload: unknown): ParsedOpenAICompatibleModelRecord[] | null {
+	return extractModelEntriesFromNode(payload);
+}
+
+function extractModelEntriesFromNode(node: unknown): ParsedOpenAICompatibleModelRecord[] | null {
+	const parsedPayload = openAICompatibleModelsPayloadSchema.safeParse(node);
+	if (!parsedPayload.success) {
+		return null;
+	}
+	if (Array.isArray(parsedPayload.data)) {
+		const parsedEntries = parsedPayload.data
+			.map(entry => openAICompatibleModelRecordSchema.safeParse(entry))
+			.flatMap(entry => (entry.success ? [entry.data] : []));
+		return parsedEntries;
+	}
+	for (const candidate of [
+		parsedPayload.data.data,
+		parsedPayload.data.models,
+		parsedPayload.data.result,
+		parsedPayload.data.items,
+	]) {
+		if (candidate === undefined) {
+			continue;
+		}
+		const nested = extractModelEntriesFromNode(candidate);
+		if (nested !== null) {
+			return nested;
+		}
+	}
+
+	return null;
+}

package/src/effort.ts

@@ -0,0 +1,16 @@
+/** User-facing thinking levels, ordered least to most intensive. */
+export const enum Effort {
+	Minimal = "minimal",
+	Low = "low",
+	Medium = "medium",
+	High = "high",
+	XHigh = "xhigh",
+}
+
+export const THINKING_EFFORTS: readonly Effort[] = [
+	Effort.Minimal,
+	Effort.Low,
+	Effort.Medium,
+	Effort.High,
+	Effort.XHigh,
+];

package/src/fireworks-model-id.ts

@@ -0,0 +1,30 @@
+const FIREWORKS_WIRE_PREFIX = "accounts/fireworks/models/";
+const FIREPASS_WIRE_PREFIX = "accounts/fireworks/routers/";
+const VERSION_SEPARATOR_PATTERN = /(?<=\d)p(?=\d)/g;
+const VERSION_DOT_PATTERN = /(?<=\d)\.(?=\d)/g;
+
+export function toFireworksPublicModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREWORKS_WIRE_PREFIX) ? modelId.slice(FIREWORKS_WIRE_PREFIX.length) : modelId;
+	return stripped.replace(VERSION_SEPARATOR_PATTERN, ".");
+}
+
+export function toFireworksWireModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREWORKS_WIRE_PREFIX) ? modelId.slice(FIREWORKS_WIRE_PREFIX.length) : modelId;
+	return `${FIREWORKS_WIRE_PREFIX}${stripped.replace(VERSION_DOT_PATTERN, "p")}`;
+}
+
+/**
+ * Fire Pass exposes its Kimi K2.6 Turbo subscription through a dedicated router
+ * endpoint at `accounts/fireworks/routers/<id>` rather than the `models/` namespace.
+ * We keep a friendly public id (e.g. `kimi-k2.6-turbo`) in the catalog and translate
+ * to the wire form (`accounts/fireworks/routers/kimi-k2p6-turbo`) at request time.
+ */
+export function toFirepassPublicModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREPASS_WIRE_PREFIX) ? modelId.slice(FIREPASS_WIRE_PREFIX.length) : modelId;
+	return stripped.replace(VERSION_SEPARATOR_PATTERN, ".");
+}
+
+export function toFirepassWireModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREPASS_WIRE_PREFIX) ? modelId.slice(FIREPASS_WIRE_PREFIX.length) : modelId;
+	return `${FIREPASS_WIRE_PREFIX}${stripped.replace(VERSION_DOT_PATTERN, "p")}`;
+}

package/src/hosts.ts

@@ -0,0 +1,114 @@
+/**
+ * Known model-endpoint host classification — the single vocabulary for the
+ * `provider === id || baseUrl.includes(marker)` idiom that gates wire-level
+ * behavior (compat detection, routing, header shaping, watchdog floors).
+ *
+ * Markers are case-insensitive substrings matched against the base URL, NOT
+ * parsed hostnames: proxies regularly embed the upstream host in a path
+ * segment, and the historical call sites all used substring semantics.
+ * Callers that need strict hostname matching — where a substring false
+ * positive is dangerous, e.g. the Anthropic official-endpoint OAuth gate —
+ * parse the URL and compare the hostname themselves.
+ */
+
+interface HostClassSpec {
+	/** Provider ids that imply this host class regardless of baseUrl. */
+	readonly providers?: readonly string[];
+	/** Provider-id prefixes that imply this host class (e.g. `xiaomi-token-plan-`). */
+	readonly providerPrefixes?: readonly string[];
+	/** Case-insensitive substrings matched against the base URL. */
+	readonly urlMarkers: readonly string[];
+	// Strict hostname matching is intentionally not modeled here: the one
+	// auth-sensitive consumer (Anthropic official-endpoint) parses the URL
+	// itself; every other call site is benign and uses substring matching.
+}
+
+export const KNOWN_HOSTS = {
+	openai: { providers: ["openai"], urlMarkers: ["api.openai.com"] },
+	azureOpenAI: {
+		providers: ["azure"],
+		urlMarkers: [".openai.azure.com", "azure.com/openai", "models.inference.ai.azure.com"],
+	},
+	openrouter: { providers: ["openrouter"], urlMarkers: ["openrouter.ai"] },
+	vercelAIGateway: { providers: ["vercel-ai-gateway"], urlMarkers: ["ai-gateway.vercel.sh"] },
+	githubCopilot: { providers: ["github-copilot"], urlMarkers: ["githubcopilot.com", "copilot-api."] },
+	anthropic: { providers: ["anthropic"], urlMarkers: ["api.anthropic.com"] },
+	/** DeepSeek's first-party API only — gates direct-API quirks (max_tokens field, thinking extraBody). */
+	deepseekDirect: { providers: ["deepseek"], urlMarkers: ["api.deepseek.com"] },
+	/** Any DeepSeek-operated host (first-party API, web-chat fronts). Wider than `deepseekDirect` on purpose. */
+	deepseekFamily: { providers: ["deepseek"], urlMarkers: ["deepseek.com"] },
+	cerebras: { providers: ["cerebras"], urlMarkers: ["cerebras.ai"] },
+	zai: { providers: ["zai"], urlMarkers: ["api.z.ai"] },
+	zhipu: { providers: ["zhipu-coding-plan"], urlMarkers: ["open.bigmodel.cn"] },
+	kilo: { providers: ["kilo"], urlMarkers: ["api.kilo.ai"] },
+	alibabaDashscope: { providers: ["alibaba-coding-plan"], urlMarkers: ["dashscope"] },
+	xiaomi: { providers: ["xiaomi"], providerPrefixes: ["xiaomi-token-plan-"], urlMarkers: ["xiaomimimo.com"] },
+	xai: { providers: ["xai"], urlMarkers: ["api.x.ai"] },
+	mistral: { providers: ["mistral"], urlMarkers: ["mistral.ai"] },
+	together: { providers: ["together"], urlMarkers: ["api.together.xyz"] },
+	/** URL-only on purpose: the `fireworks`/`firepass` providers route per-model and not every model is Fireworks-shaped. */
+	fireworks: { urlMarkers: ["fireworks.ai"] },
+	groq: { providers: ["groq"], urlMarkers: ["api.groq.com"] },
+	minimax: {
+		providers: ["minimax", "minimax-code", "minimax-code-cn"],
+		urlMarkers: ["api.minimax.io", "api.minimaxi.com"],
+	},
+	qwenPortal: { providers: ["qwen-portal"], urlMarkers: ["portal.qwen.ai"] },
+	moonshotNative: { providers: ["moonshot", "kimi-code"], urlMarkers: ["api.moonshot.ai", "api.kimi.com"] },
+	opencode: { providers: ["opencode-go", "opencode-zen"], urlMarkers: ["opencode.ai"] },
+	chutes: { urlMarkers: ["chutes.ai"] },
+} as const satisfies Record<string, HostClassSpec>;
+
+export type KnownHost = keyof typeof KNOWN_HOSTS;
+
+/** URL-only host check (for call sites that have no provider id, e.g. raw env config). */
+export function hostMatchesUrl(baseUrl: string | undefined, host: KnownHost): boolean {
+	if (!baseUrl) return false;
+	const spec: HostClassSpec = KNOWN_HOSTS[host];
+	const normalized = baseUrl.toLowerCase();
+	for (const marker of spec.urlMarkers) {
+		if (normalized.includes(marker)) return true;
+	}
+	return false;
+}
+
+/** Provider-or-URL host check — the canonical `provider === id || baseUrl.includes(marker)` idiom. */
+export function modelMatchesHost(model: { provider: string; baseUrl: string }, host: KnownHost): boolean {
+	const spec: HostClassSpec = KNOWN_HOSTS[host];
+	if (spec.providers) {
+		for (const provider of spec.providers) {
+			if (model.provider === provider) return true;
+		}
+	}
+	if (spec.providerPrefixes) {
+		for (const prefix of spec.providerPrefixes) {
+			if (model.provider.startsWith(prefix)) return true;
+		}
+	}
+	return hostMatchesUrl(model.baseUrl, host);
+}
+
+// --- Endpoint-shape predicates (URL path/verb shapes, not vendor hosts) ---
+
+/** Vertex AI express-mode OpenAI-compatible endpoint (`…/endpoints/openapi`). */
+export function isVertexExpressOpenAIUrl(baseUrl: string): boolean {
+	return baseUrl.includes("/endpoints/openapi");
+}
+
+/** Vertex AI Anthropic raw-predict endpoints (`:streamRawPredict` / `:rawPredict`). */
+export function isVertexRawPredictUrl(baseUrl: string): boolean {
+	return baseUrl.includes(":streamRawPredict") || baseUrl.includes(":rawPredict");
+}
+
+/** Azure OpenAI deployment-scoped path (`…/deployments/<name>/…`). */
+export function isAzureDeploymentsUrl(baseUrl: string): boolean {
+	return baseUrl.includes("/deployments/");
+}
+
+/** Alibaba DashScope consumer `compatible-mode` endpoint (rejects multimodal arrays for some text-only SKUs). */
+export function isDashscopeCompatibleModeUrl(baseUrl: string): boolean {
+	const normalized = baseUrl.toLowerCase();
+	return (
+		normalized.includes("dashscope") && normalized.includes("aliyuncs.com") && normalized.includes("/compatible-mode")
+	);
+}

package/src/identity/bundled.ts

@@ -0,0 +1,38 @@
+/**
+ * Memoized reference datasets over the bundled model catalog.
+ *
+ * Lazy: walking every bundled model (~12K) triggers thinking enrichment, so
+ * the walk is deferred off module load and performed once for both datasets
+ * (canonical equivalence + proxy reference lookup). Consumers that need
+ * non-bundled reference data use the pure builders directly
+ * ({@link buildCanonicalReferenceData} / {@link buildModelReferenceIndex}).
+ */
+import { getBundledModels, getBundledProviders } from "../models";
+import type { Api, Model } from "../types";
+import { buildCanonicalReferenceData, type CanonicalReferenceData } from "./equivalence";
+import { buildModelReferenceIndex, type ModelReferenceIndex } from "./reference";
+
+let bundledModels: readonly Model<Api>[] | undefined;
+
+function getBundledModelList(): readonly Model<Api>[] {
+	bundledModels ??= getBundledProviders().flatMap(
+		provider => getBundledModels(provider as Parameters<typeof getBundledModels>[0]) as Model<Api>[],
+	);
+	return bundledModels;
+}
+
+let canonicalReference: CanonicalReferenceData | undefined;
+
+/** Canonical-equivalence reference data over the bundled catalog. */
+export function getBundledCanonicalReferenceData(): CanonicalReferenceData {
+	canonicalReference ??= buildCanonicalReferenceData(getBundledModelList());
+	return canonicalReference;
+}
+
+let referenceIndex: ModelReferenceIndex | undefined;
+
+/** Proxy-reference index over the bundled catalog. */
+export function getBundledModelReferenceIndex(): ModelReferenceIndex {
+	referenceIndex ??= buildModelReferenceIndex(getBundledModelList());
+	return referenceIndex;
+}

package/src/identity/classify.ts

@@ -0,0 +1,141 @@
+/**
+ * Model-id classification: parse a model id into its family (gemini / anthropic /
+ * openai), kind/variant, and version. This is the shared layer both catalog
+ * policy rules (`model-thinking.ts`) and downstream consumers build on —
+ * classification lives here, the rules that consume it stay with their domain.
+ */
+
+export type SemVer = {
+	major: number;
+	minor: number;
+	patch: number;
+};
+
+export type GeminiKind = "pro" | "flash";
+export type AnthropicKind = "opus" | "sonnet" | "fable" | "mythos";
+export type OpenAIVariant = "base" | "codex" | "codex-max" | "codex-mini" | "codex-spark" | "mini" | "max" | "nano";
+
+export interface GeminiModel {
+	family: "gemini";
+	kind: GeminiKind;
+	version: SemVer;
+}
+
+export interface AnthropicModel {
+	family: "anthropic";
+	kind: AnthropicKind;
+	version: SemVer;
+}
+
+export interface OpenAIModel {
+	family: "openai";
+	variant: OpenAIVariant;
+	version: SemVer;
+}
+
+export interface UnknownModel {
+	family: "unknown";
+	id: string;
+}
+
+export type ParsedModel = GeminiModel | AnthropicModel | OpenAIModel | UnknownModel;
+
+/** Strip a provider namespace prefix (`openai/gpt-5.4` → `gpt-5.4`). */
+export function bareModelId(modelId: string): string {
+	const p = modelId.lastIndexOf("/");
+	return p !== -1 ? modelId.slice(p + 1) : modelId;
+}
+
+export function parseKnownModel(modelId: string): ParsedModel {
+	const canonicalId = bareModelId(modelId);
+	return (
+		parseGeminiModel(canonicalId) ??
+		parseAnthropicModel(canonicalId) ??
+		parseOpenAIModel(canonicalId) ?? { family: "unknown", id: canonicalId }
+	);
+}
+
+const GEMINI_SUFFIX = "-preview";
+export function parseGeminiModel(modelId: string): GeminiModel | null {
+	if (modelId.endsWith(GEMINI_SUFFIX)) {
+		modelId = modelId.slice(0, -GEMINI_SUFFIX.length);
+	}
+	const match = /gemini-(\d+(?:\.\d+){0,2})-(pro|flash)\b/.exec(modelId);
+	if (!match) {
+		return null;
+	}
+	const version = parseSemVer(match[1]);
+	if (!version) {
+		return null;
+	}
+	return { family: "gemini", kind: match[2] as GeminiKind, version };
+}
+
+export function parseAnthropicModel(modelId: string): AnthropicModel | null {
+	const match = /claude-(opus|sonnet|fable|mythos)-(\d{1,2}(?:[.-]\d{1,2}){0,2})\b/.exec(modelId);
+	if (!match) {
+		return null;
+	}
+	const version = parseSemVer(match[2]);
+	if (!version) {
+		return null;
+	}
+	return { family: "anthropic", kind: match[1] as AnthropicKind, version };
+}
+
+export function parseOpenAIModel(modelId: string): OpenAIModel | null {
+	const match = /gpt-(\d+(?:\.\d+){0,2})(?:-(codex-spark|codex-mini|codex-max|codex|mini|max|nano))?\b/.exec(modelId);
+	if (!match) {
+		return null;
+	}
+	const version = parseSemVer(match[1]);
+	if (!version) {
+		return null;
+	}
+	return { family: "openai", variant: (match[2] as OpenAIVariant | undefined) ?? "base", version };
+}
+
+export function isFableOrMythos(kind: AnthropicKind): boolean {
+	return kind === "fable" || kind === "mythos";
+}
+
+function createSemVer(major: number, minor: number, patch = 0): SemVer {
+	return { major, minor, patch };
+}
+
+// extend this table if we need anything more than 9.10
+const precomputeTable: Record<string, SemVer> = {};
+for (let major = 0; major <= 9; major++) {
+	for (let minor = 0; minor <= 10; minor++) {
+		const version = createSemVer(major, minor, 0);
+		precomputeTable[`${major}.${minor}`] = version;
+		precomputeTable[`${major}-${minor}`] = version;
+	}
+	precomputeTable[`${major}`] = createSemVer(major, 0, 0);
+}
+
+export function parseSemVer(version: string): SemVer | null {
+	return precomputeTable[version] ?? null;
+}
+
+export function semverGte(left: SemVer | string, right: SemVer | string): boolean {
+	return compareSemVer(left, right) >= 0;
+}
+
+export function semverEqual(left: SemVer | string, right: SemVer | string): boolean {
+	return compareSemVer(left, right) === 0;
+}
+
+export function compareSemVer(left: SemVer | string | null, right: SemVer | string | null): number {
+	left = typeof left === "string" ? parseSemVer(left) : left;
+	right = typeof right === "string" ? parseSemVer(right) : right;
+	if (!left || !right) return (left ? 1 : 0) - (right ? 1 : 0);
+
+	if (left.major !== right.major) {
+		return left.major - right.major;
+	}
+	if (left.minor !== right.minor) {
+		return left.minor - right.minor;
+	}
+	return left.patch - right.patch;
+}