@clinebot/llms 0.0.0

package/src/models/index.ts

@@ -0,0 +1,271 @@
+/**
+ * @clinebot/models
+ *
+ * Model definitions and registry for all supported AI providers.
+ *
+ * This package provides:
+ * - Type-safe model definitions using Zod schemas
+ * - A central registry for accessing models across providers
+ * - Powerful query API for filtering models by capabilities, pricing, etc.
+ * - Support for custom models and runtime registration
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   queryModels,
+ *   createQuery,
+ *   getModel,
+ *   ANTHROPIC_MODELS,
+ * } from "@clinebot/models"
+ *
+ * // Get all models with vision support
+ * const visionModels = queryModels({
+ *   capabilities: ["images"],
+ * })
+ *
+ * // Use fluent query builder
+ * const cheapModels = createQuery()
+ *   .fromProviders(["anthropic", "openai"])
+ *   .maxPrice({ input: 5 })
+ *   .withCapabilities(["reasoning"])
+ *   .execute()
+ *
+ * // Access specific model info
+ * const claude = getModel("anthropic", "claude-sonnet-4-20250514")
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Schema Exports (Types & Validation)
+// =============================================================================
+
+export {
+	// API Format
+	ApiFormat,
+	ApiFormatSchema,
+	type ApiFormatType,
+	getPricing,
+	// Model Helpers
+	hasCapability,
+	isActive,
+	isDeprecated,
+	type ModelCapability,
+	// Model Capabilities
+	ModelCapabilitySchema,
+	type ModelCollection,
+	ModelCollectionSchema,
+	type ModelEntry,
+	// Model Entry
+	ModelEntrySchema,
+	type ModelInfo,
+	// Model Info
+	ModelInfoSchema,
+	// Query Match
+	type ModelMatch,
+	type ModelPricing,
+	// Pricing
+	ModelPricingSchema,
+	type ModelQueryConfig,
+	// Query Config
+	ModelQueryConfigSchema,
+	type ModelQueryResult,
+	// Query Result
+	ModelQueryResultSchema,
+	type ModelStatus,
+	// Model Status
+	ModelStatusSchema,
+	// Query Helpers
+	matchesQuery,
+	type ProviderCapability,
+	// Provider
+	ProviderCapabilitySchema,
+	type ProviderInfo,
+	ProviderInfoSchema,
+	safeValidateModelInfo,
+	safeValidateQueryConfig,
+	sortModels,
+	type ThinkingConfig,
+	// Thinking Config
+	ThinkingConfigSchema,
+	validateModelInfo,
+	validateQueryConfig,
+} from "./schemas/index";
+
+// =============================================================================
+// Registry Exports
+// =============================================================================
+
+export {
+	clearCustomModels,
+	deprecateModel,
+	getAllModels,
+	// Provider Access
+	getAllProviders,
+	getDefaultModel,
+	getModel,
+	getModelCount,
+	// Model Access
+	getModelsForProvider,
+	getProvider,
+	getProviderCollection,
+	getProviderIds,
+	hasProvider,
+	registerModel,
+	registerModels,
+	// Registration
+	registerProvider,
+	resetRegistry,
+	unregisterModel,
+	unregisterProvider,
+	// Updates
+	updateModel,
+} from "./registry";
+
+// =============================================================================
+// Query API Exports
+// =============================================================================
+
+export {
+	createQuery,
+	getActiveModels,
+	getCachingModels,
+	getComputerUseModels,
+	getDeprecatedModels,
+	// Statistics
+	getModelStatistics,
+	getModelsByProvider,
+	getModelsInPriceRange,
+	getModelsWithContextWindow,
+	getReasoningModels,
+	getToolModels,
+	// Convenience Queries
+	getVisionModels,
+	// Query Builder
+	ModelQueryBuilder,
+	// Main Query Function
+	queryModels,
+	searchModels,
+} from "./query";
+
+// =============================================================================
+// Generated Catalog Exports
+// =============================================================================
+
+export {
+	getGeneratedModelsForProvider,
+	getGeneratedModelsVersion,
+	getGeneratedProviderModels,
+} from "./generated-access";
+
+// =============================================================================
+// Provider Model Exports
+// =============================================================================
+
+export {
+	AIHUBMIX_PROVIDER,
+	ANTHROPIC_DEFAULT_MODEL,
+	// Anthropic
+	ANTHROPIC_MODELS,
+	ANTHROPIC_PROVIDER,
+	ASKSAGE_PROVIDER,
+	// Other Providers
+	BASETEN_PROVIDER,
+	BEDROCK_DEFAULT_MODEL,
+	BEDROCK_MODELS,
+	BEDROCK_PROVIDER,
+	CEREBRAS_DEFAULT_MODEL,
+	// Cerebras
+	CEREBRAS_MODELS,
+	CEREBRAS_PROVIDER,
+	CLAUDE_CODE_DEFAULT_MODEL,
+	CLAUDE_CODE_MODELS,
+	CLAUDE_CODE_PROVIDER,
+	CLINE_DEFAULT_MODEL,
+	CLINE_MODELS,
+	CLINE_PROVIDER,
+	DEEPSEEK_DEFAULT_MODEL,
+	// DeepSeek
+	DEEPSEEK_MODELS,
+	DEEPSEEK_PROVIDER,
+	DEFAULT_EXTERNAL_OCA_BASE_URL,
+	DEFAULT_INTERNAL_OCA_BASE_URL,
+	DIFY_PROVIDER,
+	FIREWORKS_DEFAULT_MODEL,
+	// Fireworks
+	FIREWORKS_MODELS,
+	FIREWORKS_PROVIDER,
+	GEMINI_DEFAULT_MODEL,
+	// Gemini
+	GEMINI_MODELS,
+	GEMINI_PROVIDER,
+	GROQ_DEFAULT_MODEL,
+	// Groq
+	GROQ_MODELS,
+	GROQ_PROVIDER,
+	// Helpers
+	getActiveAnthropicModels,
+	getActiveGeminiModels,
+	getActiveOpenAIModels,
+	getActiveXAIModels,
+	getAnthropicReasoningModels,
+	getDeepSeekReasoningModels,
+	getFireworksFunctionModels,
+	getGeminiThinkingModels,
+	getGroqVisionModels,
+	getOpenAIReasoningModels,
+	getTogetherLlamaModels,
+	HICAP_PROVIDER,
+	HUAWEI_CLOUD_MAAS_PROVIDER,
+	HUGGINGFACE_PROVIDER,
+	LITELLM_PROVIDER,
+	LMSTUDIO_PROVIDER,
+	MINIMAX_DEFAULT_MODEL,
+	MINIMAX_MODELS,
+	MINIMAX_PROVIDER,
+	MISTRAL_PROVIDER,
+	MOONSHOT_DEFAULT_MODEL,
+	MOONSHOT_MODELS,
+	MOONSHOT_PROVIDER,
+	NEBIUS_DEFAULT_MODEL,
+	// Nebius
+	NEBIUS_MODELS,
+	NEBIUS_PROVIDER,
+	NOUS_RESEARCH_DEFAULT_MODEL,
+	// Nous Research
+	NOUS_RESEARCH_MODELS,
+	NOUS_RESEARCH_PROVIDER,
+	OCA_DEFAULT_MODEL,
+	OCA_MODELS,
+	OCA_PROVIDER,
+	// Local Providers
+	OLLAMA_PROVIDER,
+	OPENAI_CODEX_DEFAULT_MODEL,
+	OPENAI_CODEX_PROVIDER,
+	OPENAI_DEFAULT_MODEL,
+	// OpenAI
+	OPENAI_MODELS,
+	OPENAI_PROVIDER,
+	OPENROUTER_DEFAULT_MODEL,
+	OPENROUTER_MODELS,
+	OPENROUTER_PROVIDER,
+	// Gateway Providers
+	REQUESTY_PROVIDER,
+	SAMBANOVA_DEFAULT_MODEL,
+	// SambaNova
+	SAMBANOVA_MODELS,
+	SAMBANOVA_PROVIDER,
+	TOGETHER_DEFAULT_MODEL,
+	// Together
+	TOGETHER_MODELS,
+	TOGETHER_PROVIDER,
+	VERCEL_AI_GATEWAY_PROVIDER,
+	VERTEX_DEFAULT_MODEL,
+	VERTEX_MODELS,
+	VERTEX_PROVIDER,
+	XAI_DEFAULT_MODEL,
+	// xAI
+	XAI_MODELS,
+	XAI_PROVIDER,
+} from "./providers/index";

package/src/models/models-dev-catalog.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	fetchModelsDevProviderModels,
+	type ModelsDevPayload,
+	normalizeModelsDevProviderModels,
+} from "./models-dev-catalog";
+
+describe("models-dev-catalog", () => {
+	it("normalizes payload with model filtering and defaults", () => {
+		const payload: ModelsDevPayload = {
+			openai: {
+				models: {
+					"gpt-live": {
+						name: "GPT Live",
+						tool_call: true,
+						reasoning: true,
+						structured_output: true,
+						temperature: true,
+						release_date: "2026-01-01",
+						modalities: { input: ["text", "image"] },
+						limit: { context: 1_000_000 },
+						cost: { input: 1, output: 2, cache_read: 0.5, cache_write: 0.8 },
+						status: "preview",
+					},
+					"gpt-no-tools": {
+						name: "GPT No Tools",
+						tool_call: false,
+					},
+					"gpt-deprecated": {
+						name: "GPT Deprecated",
+						tool_call: true,
+						status: "deprecated",
+					},
+				},
+			},
+			anthropic: {
+				models: {
+					"claude-defaults": {
+						tool_call: true,
+						status: "experimental",
+						release_date: "2025-02-01",
+					},
+					"claude-older": {
+						tool_call: true,
+						release_date: "2024-02-01",
+					},
+				},
+			},
+		};
+
+		const providerModels = normalizeModelsDevProviderModels(payload, {
+			openai: "openai-native",
+			anthropic: "anthropic",
+		});
+
+		expect(providerModels).toEqual({
+			"openai-native": {
+				"gpt-live": {
+					id: "gpt-live",
+					name: "GPT Live",
+					contextWindow: 1_000_000,
+					maxTokens: 4096,
+					capabilities: [
+						"images",
+						"tools",
+						"reasoning",
+						"structured_output",
+						"temperature",
+					],
+					pricing: {
+						input: 1,
+						output: 2,
+						cacheRead: 0.5,
+						cacheWrite: 0.8,
+					},
+					status: "preview",
+					releaseDate: "2026-01-01",
+				},
+			},
+			anthropic: {
+				"claude-defaults": {
+					id: "claude-defaults",
+					name: "claude-defaults",
+					contextWindow: 4096,
+					maxTokens: 4096,
+					capabilities: ["tools"],
+					pricing: {
+						input: 0,
+						output: 0,
+						cacheRead: 0,
+						cacheWrite: 0,
+					},
+					status: undefined,
+					releaseDate: "2025-02-01",
+				},
+				"claude-older": {
+					id: "claude-older",
+					name: "claude-older",
+					contextWindow: 4096,
+					maxTokens: 4096,
+					capabilities: ["tools"],
+					pricing: {
+						input: 0,
+						output: 0,
+						cacheRead: 0,
+						cacheWrite: 0,
+					},
+					status: undefined,
+					releaseDate: "2024-02-01",
+				},
+			},
+		});
+		expect(Object.keys(providerModels.anthropic ?? {})).toEqual([
+			"claude-defaults",
+			"claude-older",
+		]);
+		expect(providerModels["openai-native"]).not.toHaveProperty(
+			"gpt-deprecated",
+		);
+	});
+
+	it("fetches and normalizes models.dev payload", async () => {
+		const fetcher = vi.fn(async () => ({
+			ok: true,
+			json: async () =>
+				({
+					openai: {
+						models: {
+							"gpt-live": { tool_call: true },
+						},
+					},
+				}) satisfies ModelsDevPayload,
+		}));
+
+		const result = await fetchModelsDevProviderModels(
+			"https://models.dev/api.json",
+			{ openai: "openai-native" },
+			fetcher as unknown as typeof fetch,
+		);
+
+		expect(fetcher).toHaveBeenCalledWith("https://models.dev/api.json");
+		expect(result["openai-native"]).toHaveProperty("gpt-live");
+	});
+
+	it("throws when models.dev request fails", async () => {
+		const fetcher = vi.fn(async () => ({
+			ok: false,
+			status: 503,
+		}));
+
+		await expect(
+			fetchModelsDevProviderModels(
+				"https://models.dev/api.json",
+				{ openai: "openai-native" },
+				fetcher as unknown as typeof fetch,
+			),
+		).rejects.toThrow(
+			"Failed to load model catalog from https://models.dev/api.json: HTTP 503",
+		);
+	});
+});

package/src/models/models-dev-catalog.ts

@@ -0,0 +1,161 @@
+import type { ModelInfo } from "./schemas/index";
+
+export interface ModelsDevModel {
+	name?: string;
+	tool_call?: boolean;
+	reasoning?: boolean;
+	structured_output?: boolean;
+	temperature?: boolean;
+	release_date?: string;
+	limit?: {
+		context?: number;
+		output?: number;
+	};
+	cost?: {
+		input?: number;
+		output?: number;
+		cache_read?: number;
+		cache_write?: number;
+	};
+	modalities?: {
+		input?: string[];
+	};
+	status?: string;
+}
+
+interface ModelsDevProviderPayload {
+	models?: Record<string, ModelsDevModel>;
+}
+
+export type ModelsDevPayload = Record<string, ModelsDevProviderPayload>;
+export type ModelsDevProviderKeyMap = Record<string, string>;
+
+const DEFAULT_CONTEXT_WINDOW = 4096;
+const DEFAULT_MAX_TOKENS = 4096;
+
+function parseReleaseDate(value: string | undefined): number {
+	if (!value) {
+		return Number.NEGATIVE_INFINITY;
+	}
+
+	const timestamp = Date.parse(value);
+	return Number.isNaN(timestamp) ? Number.NEGATIVE_INFINITY : timestamp;
+}
+
+export function sortModelsByReleaseDate(
+	models: Record<string, ModelInfo>,
+): Record<string, ModelInfo> {
+	return Object.fromEntries(
+		Object.entries(models).sort(([modelIdA, modelA], [modelIdB, modelB]) => {
+			const releaseDateA = parseReleaseDate(modelA.releaseDate);
+			const releaseDateB = parseReleaseDate(modelB.releaseDate);
+			if (releaseDateA !== releaseDateB) {
+				return releaseDateB - releaseDateA;
+			}
+			return modelIdA.localeCompare(modelIdB);
+		}),
+	);
+}
+
+function toCapabilities(model: ModelsDevModel): ModelInfo["capabilities"] {
+	const capabilities: NonNullable<ModelInfo["capabilities"]> = [];
+	if (model.modalities?.input?.includes("image")) {
+		capabilities.push("images");
+	}
+	if (model.modalities?.input?.includes("pdf")) {
+		capabilities.push("files");
+	}
+	if (model.tool_call === true) {
+		capabilities.push("tools");
+	}
+	if (model.reasoning === true) {
+		capabilities.push("reasoning");
+	}
+	if (model.structured_output === true) {
+		capabilities.push("structured_output");
+	}
+	if (model.temperature === true) {
+		capabilities.push("temperature");
+	}
+	return capabilities;
+}
+
+function toStatus(status: string | undefined): ModelInfo["status"] {
+	if (
+		status === "active" ||
+		status === "preview" ||
+		status === "deprecated" ||
+		status === "legacy"
+	) {
+		return status;
+	}
+	return undefined;
+}
+
+function toModelInfo(modelId: string, model: ModelsDevModel): ModelInfo {
+	return {
+		id: modelId,
+		name: model.name || modelId,
+		contextWindow: model.limit?.context ?? DEFAULT_CONTEXT_WINDOW,
+		maxTokens: model.limit?.output ?? DEFAULT_MAX_TOKENS,
+		capabilities: toCapabilities(model),
+		pricing: {
+			input: model.cost?.input ?? 0,
+			output: model.cost?.output ?? 0,
+			cacheRead: model.cost?.cache_read ?? 0,
+			cacheWrite: model.cost?.cache_write ?? 0,
+		},
+		status: toStatus(model.status),
+		releaseDate: model.release_date,
+	};
+}
+
+function isDeprecatedModel(model: ModelsDevModel): boolean {
+	return model.status === "deprecated";
+}
+
+export function normalizeModelsDevProviderModels(
+	payload: ModelsDevPayload,
+	providerKeyMap: ModelsDevProviderKeyMap,
+): Record<string, Record<string, ModelInfo>> {
+	const providerModels: Record<string, Record<string, ModelInfo>> = {};
+
+	for (const [sourceProviderKey, targetProviderId] of Object.entries(
+		providerKeyMap,
+	)) {
+		const source = payload[sourceProviderKey];
+		if (!source?.models) {
+			continue;
+		}
+
+		const models: Record<string, ModelInfo> = {};
+		for (const [modelId, model] of Object.entries(source.models)) {
+			if (model.tool_call !== true || isDeprecatedModel(model)) {
+				continue;
+			}
+			models[modelId] = toModelInfo(modelId, model);
+		}
+
+		if (Object.keys(models).length > 0) {
+			providerModels[targetProviderId] = sortModelsByReleaseDate(models);
+		}
+	}
+
+	return providerModels;
+}
+
+export async function fetchModelsDevProviderModels(
+	url: string,
+	providerKeyMap: ModelsDevProviderKeyMap,
+	fetcher: typeof fetch = fetch,
+): Promise<Record<string, Record<string, ModelInfo>>> {
+	const response = await fetcher(url);
+	if (!response.ok) {
+		throw new Error(
+			`Failed to load model catalog from ${url}: HTTP ${response.status}`,
+		);
+	}
+
+	const payload = (await response.json()) as ModelsDevPayload;
+	return normalizeModelsDevProviderModels(payload, providerKeyMap);
+}

package/src/models/providers/aihubmix.ts

@@ -0,0 +1,19 @@
+/**
+ * AIhubmix Provider
+ */
+
+import { getGeneratedModelsForProvider } from "../generated-access";
+import type { ModelCollection } from "../schemas/index";
+
+export const AIHUBMIX_PROVIDER: ModelCollection = {
+	provider: {
+		id: "aihubmix",
+		name: "AI Hub Mix",
+		description: "AI model aggregator",
+		protocol: "openai-chat",
+		baseUrl: "https://api.aihubmix.com/v1",
+		defaultModelId: "gpt-4o",
+		env: ["AIHUBMIX_API_KEY"],
+	},
+	models: getGeneratedModelsForProvider("aihubmix"),
+};

package/src/models/providers/anthropic.ts

@@ -0,0 +1,60 @@
+/**
+ * Anthropic Models
+ *
+ * Model definitions for Anthropic's Claude family of models.
+ * https://docs.anthropic.com/en/docs/about-claude/models
+ */
+
+import { getGeneratedModelsForProvider } from "../generated-access";
+import type { ModelCollection, ModelInfo } from "../schemas/index";
+
+/**
+ * Anthropic model definitions
+ */
+export const ANTHROPIC_MODELS = getGeneratedModelsForProvider("anthropic");
+
+/**
+ * Default Anthropic model ID
+ */
+export const ANTHROPIC_DEFAULT_MODEL =
+	Object.keys(ANTHROPIC_MODELS)[0] ?? "claude-sonnet-4-6";
+
+/**
+ * Anthropic provider information
+ */
+export const ANTHROPIC_PROVIDER: ModelCollection = {
+	provider: {
+		id: "anthropic",
+		name: "Anthropic",
+		description: "Creator of Claude, the AI assistant",
+		protocol: "anthropic",
+		baseUrl: "https://api.anthropic.com",
+		defaultModelId: ANTHROPIC_DEFAULT_MODEL,
+		capabilities: ["reasoning", "prompt-cache"],
+		env: ["ANTHROPIC_API_KEY"],
+	},
+	models: ANTHROPIC_MODELS,
+};
+
+/**
+ * Get all active Anthropic models
+ */
+export function getActiveAnthropicModels(): Record<string, ModelInfo> {
+	return Object.fromEntries(
+		Object.entries(ANTHROPIC_MODELS).filter(
+			([, info]) =>
+				!info.status || info.status === "active" || info.status === "preview",
+		),
+	);
+}
+
+/**
+ * Get Anthropic models with reasoning/thinking support
+ */
+export function getAnthropicReasoningModels(): Record<string, ModelInfo> {
+	return Object.fromEntries(
+		Object.entries(ANTHROPIC_MODELS).filter(
+			([, info]) => info.thinkingConfig !== undefined,
+		),
+	);
+}

package/src/models/providers/asksage.ts

@@ -0,0 +1,19 @@
+/**
+ * AskSage Provider
+ */
+
+import type { ModelCollection } from "../schemas/index";
+
+export const ASKSAGE_PROVIDER: ModelCollection = {
+	provider: {
+		id: "asksage",
+		name: "AskSage",
+		description: "AskSage platform",
+		protocol: "openai-chat",
+		baseUrl: "https://api.asksage.ai/server",
+		defaultModelId: "gpt-4o",
+		capabilities: ["tools"],
+		env: ["ASKSAGE_API_KEY"],
+	},
+	models: {},
+};

package/src/models/providers/baseten.ts

@@ -0,0 +1,21 @@
+/**
+ * Baseten Provider
+ */
+
+import { getGeneratedModelsForProvider } from "../generated-access";
+import type { ModelCollection } from "../schemas/index";
+
+const BASETEN_MODELS = getGeneratedModelsForProvider("baseten");
+
+export const BASETEN_PROVIDER: ModelCollection = {
+	provider: {
+		id: "baseten",
+		name: "Baseten",
+		description: "ML inference platform",
+		protocol: "openai-chat",
+		baseUrl: "https://model-api.baseten.co/v1",
+		defaultModelId: Object.keys(BASETEN_MODELS)[0],
+		env: ["BASETEN_API_KEY"],
+	},
+	models: BASETEN_MODELS,
+};