@codeworksh/aikit 0.3.0 → 0.4.0

package/src/model/catalog.ts

@@ -0,0 +1,94 @@
+import { Filesystem, lazy } from "@codeworksh/utils";
+
+export namespace ModelCatalog {
+	export interface ModelsDevModel {
+		id: string;
+		name: string;
+		family: string;
+		attachment: boolean;
+		reasoning?: boolean;
+		tool_call?: boolean;
+		temperature?: boolean;
+		knowledge?: string | boolean;
+		release_date: string;
+		last_updated: string;
+		modalities: {
+			input?: string[];
+			output: string[];
+		};
+		open_weights: boolean;
+		baseUrl?: string;
+		headers?: Record<string, string>;
+		cost?: {
+			input?: number;
+			output?: number;
+			cache_read?: number;
+			cache_write?: number;
+		};
+		limit?: {
+			context?: number;
+			output?: number;
+		};
+	}
+	export interface ModelsDevProvider {
+		id: string;
+		env: string[];
+		npm?: string;
+		api: string;
+		baseUrl?: string;
+		name: string;
+		doc?: string;
+		key?: string;
+		headers?: Record<string, string>;
+		models: Record<string, ModelsDevModel>;
+	}
+	// Doesn't represent the full spec from models.dev.
+	// Represents the provider entries on a best-effort basis.
+	export type ModelsDevCatalog = Record<string, ModelsDevProvider>;
+	type LazyModelsDevCatalog = ReturnType<typeof lazy<Promise<ModelsDevCatalog>>>;
+
+	function modelsDevURL(): string {
+		return process.env.OPENCODE_MODELS_URL || "https://models.dev";
+	}
+
+	function modelsDevPath(): string | undefined {
+		return process.env.CODEWORK_AIKIT_MODELS_PATH;
+	}
+
+	export const modelsDevData: LazyModelsDevCatalog = lazy(async () => {
+		const path = modelsDevPath();
+		if (path) {
+			const result = await Filesystem.readJson<ModelsDevCatalog>(path).catch(() => undefined);
+			if (result) return result;
+		}
+
+		const json = await fetch(`${modelsDevURL()}/api.json`).then((x) => x.text());
+		return JSON.parse(json) as ModelsDevCatalog;
+	});
+
+	export async function get(): Promise<ModelsDevCatalog> {
+		return modelsDevData();
+	}
+
+	export async function refresh(): Promise<void> {
+		const result = await fetch(`${modelsDevURL()}/api.json`, {
+			signal: AbortSignal.timeout(10 * 1000),
+		}).catch(() => undefined);
+		if (!result?.ok) return;
+
+		const json = await result.text();
+		const path = modelsDevPath();
+		if (path) {
+			await Filesystem.write(path, json);
+		}
+		modelsDevData.reset();
+	}
+
+	void ModelCatalog.refresh();
+	setInterval(
+		async () => {
+			await ModelCatalog.refresh();
+		},
+		60 * 1000 * 60,
+	).unref();
+}

package/src/model/model.ts

@@ -0,0 +1,250 @@
+import { lazy } from "@codeworksh/utils";
+import Type, { type Static } from "typebox";
+import { keys, mapValues, pick, pipe } from "remeda";
+import { Provider } from "../provider/provider";
+import { ModelCatalog } from "./catalog";
+import { applyModification } from "./transform";
+
+export namespace Model {
+	export const KnownProtocolEnum = {
+		anthropicMessages: "anthropic-messages",
+		openaiCompletions: "openai-completions",
+		openaiResponses: "openai-responses",
+	} as const;
+	export const KnownProtocolSchema = Type.Union([
+		Type.Literal(KnownProtocolEnum.anthropicMessages),
+		Type.Literal(KnownProtocolEnum.openaiCompletions),
+		Type.Literal(KnownProtocolEnum.openaiResponses),
+	]);
+	export type KnownProtocol = Static<typeof KnownProtocolSchema>;
+
+	const InputSchema = Type.Array(Type.Union([Type.Literal("text"), Type.Literal("image")]));
+	const CostSchema = Type.Object({
+		input: Type.Number(),
+		output: Type.Number(),
+		cacheRead: Type.Number(),
+		cacheWrite: Type.Number(),
+	});
+	const HeadersSchema = Type.Optional(Type.Record(Type.String(), Type.String()));
+
+	export const SupportedProtocolsSchema = Type.Object({
+		anthropicMessages: Type.Optional(Type.Literal(KnownProtocolEnum.anthropicMessages)),
+		openaiCompletions: Type.Optional(Type.Literal(KnownProtocolEnum.openaiCompletions)),
+		openaiResponses: Type.Optional(Type.Literal(KnownProtocolEnum.openaiResponses)),
+	});
+	//
+	// reprsents common base schema for a model
+	export const BaseSchema = Type.Object({
+		id: Type.String(),
+		name: Type.String(),
+		provider: Provider.Info,
+		baseUrl: Type.String(),
+		reasoning: Type.Boolean(),
+		input: InputSchema,
+		cost: CostSchema,
+		contextWindow: Type.Number(),
+		maxTokens: Type.Number(),
+		headers: HeadersSchema,
+		supportedProtocols: Type.Optional(Type.Partial(SupportedProtocolsSchema)), // optionally supported protocols
+	});
+
+	/**
+	 * Compatibility settings for OpenAI-compatible completions APIs.
+	 * Use this to override URL-based auto-detection for custom providers.
+	 */
+	export const OpenAICompletionsCompatSchema = Type.Object({
+		supportsStore: Type.Optional(Type.Boolean()),
+		supportsDeveloperRole: Type.Optional(Type.Boolean()),
+		supportsReasoningEffort: Type.Optional(Type.Boolean()),
+		reasoningEffortMap: Type.Optional(Provider.ReasoningEffortMapSchema),
+		supportsUsageInStreaming: Type.Optional(Type.Boolean()),
+		maxTokensField: Type.Optional(Type.Union([Type.Literal("max_completion_tokens"), Type.Literal("max_tokens")])),
+		requiresToolResultName: Type.Optional(Type.Boolean()),
+		requiresAssistantAfterToolResult: Type.Optional(Type.Boolean()),
+		requiresThinkingAsText: Type.Optional(Type.Boolean()),
+		thinkingFormat: Type.Optional(
+			Type.Union([
+				Type.Literal("openai"),
+				Type.Literal("openrouter"),
+				Type.Literal("zai"),
+				Type.Literal("qwen"),
+				Type.Literal("qwen-chat-template"),
+			]),
+		),
+		openRouterRouting: Type.Optional(Provider.OpenRouterRoutingSchema),
+		vercelGatewayRouting: Type.Optional(Provider.VercelGatewayRoutingSchema),
+		zaiToolStream: Type.Optional(Type.Boolean()),
+		supportsStrictMode: Type.Optional(Type.Boolean()),
+	});
+	export type OpenAICompletionsCompat = Static<typeof OpenAICompletionsCompatSchema>;
+
+	/** Compatibility settings for OpenAI Responses APIs. */
+	export const OpenAIResponsesCompatSchema = Type.Object({});
+	export type OpenAIResponsesCompat = Static<typeof OpenAIResponsesCompatSchema>;
+
+	export const OpenAICompatSchema = Type.Union([OpenAICompletionsCompatSchema, OpenAIResponsesCompatSchema]);
+
+	export const AnthropicSchema = Type.Evaluate(
+		Type.Intersect([
+			BaseSchema,
+			Type.Object({
+				protocol: Type.Literal(KnownProtocolEnum.anthropicMessages),
+			}),
+		]),
+	);
+
+	export const OpenAICompletionsSchema = Type.Evaluate(
+		Type.Intersect([
+			BaseSchema,
+			Type.Object({
+				protocol: Type.Literal(KnownProtocolEnum.openaiCompletions),
+				compat: Type.Optional(OpenAICompletionsCompatSchema),
+			}),
+		]),
+	);
+	export const OpenAIResponsesSchema = Type.Evaluate(
+		Type.Intersect([
+			BaseSchema,
+			Type.Object({
+				protocol: Type.Literal(KnownProtocolEnum.openaiResponses),
+				compat: Type.Optional(OpenAIResponsesCompatSchema),
+			}),
+		]),
+	);
+
+	export const Info = Type.Union([AnthropicSchema, OpenAICompletionsSchema, OpenAIResponsesSchema]);
+	export type Info = Static<typeof Info>;
+	export type TModel<TProtocol extends KnownProtocol> = Extract<Info, { protocol: TProtocol }>;
+	const BUILTINS = keys(Provider.KnownProviderEnum) as Provider.KnownProvider[];
+
+	export function calculateCost(
+		model: Info,
+		usage: {
+			input: number;
+			output: number;
+			cacheRead: number;
+			cacheWrite: number;
+			cost: {
+				input: number;
+				output: number;
+				cacheRead: number;
+				cacheWrite: number;
+				total: number;
+			};
+		},
+	): void {
+		usage.cost.input = (usage.input / 1_000_000) * model.cost.input;
+		usage.cost.output = (usage.output / 1_000_000) * model.cost.output;
+		usage.cost.cacheRead = (usage.cacheRead / 1_000_000) * model.cost.cacheRead;
+		usage.cost.cacheWrite = (usage.cacheWrite / 1_000_000) * model.cost.cacheWrite;
+		usage.cost.total = usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
+	}
+
+	export type BuiltInModels = Partial<Record<Provider.KnownProvider, Record<string, Info>>>;
+
+	export function normalizeInput(input?: string[]): Array<"text" | "image"> {
+		const normalized = new Set<"text" | "image">();
+		for (const modality of input ?? ["text"]) {
+			if (modality === "text" || modality === "image") {
+				normalized.add(modality);
+			}
+		}
+		if (normalized.size === 0) normalized.add("text");
+		return [...normalized];
+	}
+
+	export function toProviderInfo(
+		providerId: Provider.KnownProvider,
+		provider: ModelCatalog.ModelsDevProvider,
+	): Provider.Info {
+		return {
+			id: providerId,
+			name: provider.name,
+			env: provider.env,
+			key: provider.key,
+			options: provider.headers,
+		};
+	}
+
+	function toModelValue(
+		providerId: Provider.KnownProvider,
+		provider: ModelCatalog.ModelsDevProvider,
+		model: ModelCatalog.ModelsDevModel,
+	): Info {
+		return applyModification(providerId, provider, model);
+	}
+
+	export async function getBuiltInModels(): Promise<BuiltInModels> {
+		const catalog = await ModelCatalog.get();
+		return pipe(
+			catalog,
+			pick(BUILTINS),
+			mapValues((provider, providerId) =>
+				mapValues(provider.models, (model) => toModelValue(providerId as Provider.KnownProvider, provider, model)),
+			),
+		) as BuiltInModels;
+	}
+
+	export const registry = lazy(async () => {
+		const registry: Map<Provider.KnownProvider, Map<string, Info>> = new Map();
+		const models = await getBuiltInModels();
+		for (const [provider, value] of Object.entries(models) as Array<[Provider.KnownProvider, Record<string, Info>]>) {
+			const providerModels = new Map<string, Info>();
+			for (const [id, model] of Object.entries(value)) {
+				providerModels.set(id, model);
+			}
+			registry.set(provider, providerModels);
+		}
+		return registry;
+	});
+
+	export async function getModel<TProvider extends Provider.KnownProvider, TModel extends Info["id"]>(
+		provider: TProvider,
+		model: TModel,
+		overrides?: Partial<Info>,
+	) {
+		const data = await registry();
+		const providerModels = data.get(provider);
+		const result = providerModels?.get(model);
+		if (result && overrides) {
+			return { ...result, ...overrides };
+		}
+		return result;
+	}
+
+	export async function getProviders(): Promise<Provider.KnownProvider[]> {
+		const data = await registry();
+		return Array.from(data.keys());
+	}
+
+	export async function getModels<TProvider extends Provider.KnownProvider>(provider: TProvider): Promise<Info[]> {
+		const data = await registry();
+		const models = data.get(provider);
+		return models ? Array.from(models.values()) : [];
+	}
+
+	function isGpt5OrLater(modelID: string): boolean {
+		const match = /^gpt-(\d+)/.exec(modelID);
+		if (!match) {
+			return false;
+		}
+		return Number(match[1]) >= 5;
+	}
+
+	/**
+	 * Check if a model supports xhigh thinking level.
+	 * Currently only certain OpenAI Codex models support this.
+	 */
+	export function supportsXhigh(model: Info): boolean {
+		return isGpt5OrLater(model.id);
+	}
+
+	/**
+	 * Check if two models are equal by comparing both their id and provider id.
+	 * Returns false if either model is null or undefined.
+	 */
+	export function modelsAreEqual(a: Info | null | undefined, b: Info | null | undefined): boolean {
+		if (!a || !b) return false;
+		return a.id === b.id && a.provider.id === b.provider.id;
+	}
+}

package/src/model/transform.ts

@@ -0,0 +1,59 @@
+import { Provider } from "../provider/provider";
+import type { ModelCatalog } from "./catalog";
+import { Model } from "./model";
+
+function defaultBaseUrl(providerId: Provider.KnownProvider): string | undefined {
+	switch (providerId) {
+		case Provider.KnownProviderEnum.openai:
+			return "https://api.openai.com/v1";
+		default:
+			return undefined;
+	}
+}
+
+function resolveDefaultProtocol(providerId: Provider.KnownProvider): Model.KnownProtocol {
+	switch (providerId) {
+		case Provider.KnownProviderEnum.anthropic:
+			return Model.KnownProtocolEnum.anthropicMessages;
+		case Provider.KnownProviderEnum.openai:
+			return Model.KnownProtocolEnum.openaiResponses;
+		default:
+			return Model.KnownProtocolEnum.openaiCompletions;
+	}
+}
+
+export function applyModification(
+	providerId: Provider.KnownProvider,
+	provider: ModelCatalog.ModelsDevProvider,
+	model: ModelCatalog.ModelsDevModel,
+): Model.Info {
+	const baseUrl = model.baseUrl ?? provider.baseUrl ?? provider.api ?? defaultBaseUrl(providerId);
+	const normalized: Model.Info = {
+		id: model.id,
+		name: model.name,
+		provider: Model.toProviderInfo(providerId, provider),
+		baseUrl,
+		reasoning: Boolean(model.reasoning),
+		input: Model.normalizeInput(model.modalities.input),
+		cost: {
+			input: model.cost?.input ?? 0,
+			output: model.cost?.output ?? 0,
+			cacheRead: model.cost?.cache_read ?? 0,
+			cacheWrite: model.cost?.cache_write ?? 0,
+		},
+		contextWindow: model.limit?.context ?? 0,
+		maxTokens: model.limit?.output ?? 0,
+		headers: model.headers ?? provider.headers,
+		protocol: resolveDefaultProtocol(providerId),
+	};
+	//
+	// add support for multiple known protocols
+	if (providerId === Provider.KnownProviderEnum.openai) {
+		normalized.supportedProtocols = {
+			openaiCompletions: Model.KnownProtocolEnum.openaiCompletions,
+		};
+		return normalized;
+	} else {
+		return normalized;
+	}
+}

package/src/provider/provider.ts

@@ -0,0 +1,60 @@
+import Type, { type Static } from "typebox";
+
+export namespace Provider {
+	export const KnownProviderEnum = {
+		anthropic: "anthropic",
+		openai: "openai",
+		githubCopilot: "github-copilot",
+		openrouter: "openrouter",
+		groq: "groq",
+		xai: "xai",
+		cerebras: "cerebras",
+		zai: "zai",
+		opencode: "opencode",
+	} as const;
+	export const KnownProviderSchema = Type.Union([
+		Type.Literal(KnownProviderEnum.anthropic),
+		Type.Literal(KnownProviderEnum.openai),
+		Type.Literal(KnownProviderEnum.githubCopilot),
+		Type.Literal(KnownProviderEnum.openrouter),
+		Type.Literal(KnownProviderEnum.groq),
+		Type.Literal(KnownProviderEnum.xai),
+		Type.Literal(KnownProviderEnum.cerebras),
+		Type.Literal(KnownProviderEnum.zai),
+		Type.Literal(KnownProviderEnum.opencode),
+	]);
+	export type KnownProvider = Static<typeof KnownProviderSchema>;
+
+	export const Info = Type.Object({
+		id: KnownProviderSchema,
+		name: Type.String(),
+		env: Type.Array(Type.String()),
+		key: Type.Optional(Type.String()),
+		options: Type.Optional(Type.Record(Type.String(), Type.Any())),
+	});
+	export type Info = Static<typeof Info>;
+
+	export const ReasoningEffortMapSchema = Type.Object({
+		minimal: Type.Optional(Type.String()),
+		low: Type.Optional(Type.String()),
+		medium: Type.Optional(Type.String()),
+		high: Type.Optional(Type.String()),
+		xhigh: Type.Optional(Type.String()),
+	});
+	export type ReasoningEffortMap = Static<typeof ReasoningEffortMapSchema>;
+	export type StrictReasoningEffortMap = {
+		[K in keyof ReasoningEffortMap]-?: NonNullable<ReasoningEffortMap[K]>;
+	};
+
+	export const OpenRouterRoutingSchema = Type.Object({
+		only: Type.Optional(Type.Array(Type.String())),
+		order: Type.Optional(Type.Array(Type.String())),
+	});
+	export type OpenRouterRouting = Static<typeof OpenRouterRoutingSchema>;
+
+	export const VercelGatewayRoutingSchema = Type.Object({
+		only: Type.Optional(Type.Array(Type.String())),
+		order: Type.Optional(Type.Array(Type.String())),
+	});
+	export type VercelGatewayRouting = Static<typeof VercelGatewayRoutingSchema>;
+}