@clinebot/llms 0.0.0

package/src/models/schemas/model.ts

@@ -0,0 +1,308 @@
+/**
+ * Model Schema Definitions
+ *
+ * Zod schemas for validating model information, capabilities, and pricing.
+ * These schemas are the source of truth for all model type definitions.
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// API Format
+// =============================================================================
+
+/**
+ * API format variants for different provider protocols
+ */
+export const ApiFormatSchema = z.enum(["default", "openai-responses", "r1"]);
+
+export type ApiFormat = z.infer<typeof ApiFormatSchema>;
+
+export const ApiFormat = {
+	DEFAULT: "default" as const,
+	OPENAI_RESPONSES: "openai-responses" as const,
+	R1: "r1" as const,
+} as const;
+
+// =============================================================================
+// Model Capabilities
+// =============================================================================
+
+/**
+ * Capabilities a model may support
+ */
+export const ModelCapabilitySchema = z.enum([
+	"images", // Image/vision inputs
+	"tools", // Tool/function calling
+	"streaming", // Streaming responses
+	"prompt-cache", // Prompt caching
+	"reasoning", // Extended thinking/reasoning
+	"reasoning-effort", // Reasoning effort parameter
+	"computer-use", // Computer use tools
+	"global-endpoint", // Global endpoint (Vertex AI)
+	"structured_output", // Structured output formats
+	"temperature", // Supports temperature parameter
+	"files", // File inputs (e.g. PDFs)
+]);
+
+export type ModelCapability = z.infer<typeof ModelCapabilitySchema>;
+
+// =============================================================================
+// Model Status
+// =============================================================================
+
+/**
+ * Model lifecycle status
+ */
+export const ModelStatusSchema = z.enum([
+	"active", // Currently available and supported
+	"preview", // Available but may change
+	"deprecated", // Will be removed, use alternative
+	"legacy", // Still works but not recommended
+]);
+
+export type ModelStatus = z.infer<typeof ModelStatusSchema>;
+
+// =============================================================================
+// Pricing
+// =============================================================================
+
+/**
+ * Token pricing configuration (per million tokens)
+ */
+export const ModelPricingSchema = z.object({
+	/** Input price per million tokens */
+	input: z.number().optional(),
+	/** Output price per million tokens */
+	output: z.number().optional(),
+	/** Cache write price per million tokens */
+	cacheWrite: z.number().optional(),
+	/** Cache read price per million tokens */
+	cacheRead: z.number().optional(),
+});
+
+export type ModelPricing = z.infer<typeof ModelPricingSchema>;
+
+// =============================================================================
+// Thinking/Reasoning Config
+// =============================================================================
+
+/**
+ * Configuration for models with thinking/reasoning capabilities
+ */
+export const ThinkingConfigSchema = z.object({
+	/** Maximum thinking budget in tokens */
+	maxBudget: z.number().optional(),
+	/** Output price when thinking is enabled (per million tokens) */
+	outputPrice: z.number().optional(),
+	/** Gemini-specific thinking level */
+	thinkingLevel: z.enum(["low", "high"]).optional(),
+});
+
+export type ThinkingConfig = z.infer<typeof ThinkingConfigSchema>;
+
+// =============================================================================
+// Model Info
+// =============================================================================
+
+/**
+ * Complete model information schema
+ */
+export const ModelInfoSchema = z.object({
+	/** Model identifier (e.g., "claude-sonnet-4-20250514") */
+	id: z.string(),
+
+	/** Human-readable model name */
+	name: z.string().optional(),
+
+	/** Model description */
+	description: z.string().optional(),
+
+	// === Token Limits ===
+
+	/** Maximum output tokens */
+	maxTokens: z.number().optional(),
+
+	/** Context window size in tokens */
+	contextWindow: z.number().optional(),
+
+	// === Capabilities ===
+
+	/** Model capabilities (images, tools, streaming, prompt-cache, reasoning, etc.) */
+	capabilities: z.array(ModelCapabilitySchema).optional(),
+
+	// === API Configuration ===
+
+	/** API format required by this model */
+	apiFormat: ApiFormatSchema.optional(),
+
+	/** System message role override (for OpenAI-compatible) */
+	systemRole: z.enum(["system", "developer"]).optional(),
+
+	/** Default temperature for this model */
+	temperature: z.number().optional(),
+
+	// === Pricing ===
+
+	/** Token pricing (per million tokens) */
+	pricing: ModelPricingSchema.optional(),
+
+	// === Thinking/Reasoning ===
+
+	/** Thinking/reasoning configuration */
+	thinkingConfig: ThinkingConfigSchema.optional(),
+
+	// === Lifecycle ===
+
+	/** Model status (active, preview, deprecated, legacy) */
+	status: ModelStatusSchema.optional(),
+
+	/** Deprecation notice if status is deprecated */
+	deprecationNotice: z.string().optional(),
+
+	/** Suggested replacement model ID if deprecated */
+	replacedBy: z.string().optional(),
+
+	/** Date when model was released (ISO 8601) */
+	releaseDate: z.string().optional(),
+
+	/** Date when model will be/was deprecated (ISO 8601) */
+	deprecationDate: z.string().optional(),
+});
+
+export type ModelInfo = z.infer<typeof ModelInfoSchema>;
+
+// =============================================================================
+// Model Entry (with ID)
+// =============================================================================
+
+/**
+ * A model entry with its ID and info
+ */
+export const ModelEntrySchema = z.object({
+	/** Model identifier (e.g., "claude-sonnet-4-20250514") */
+	id: z.string(),
+	/** Model information */
+	info: ModelInfoSchema,
+});
+
+export type ModelEntry = z.infer<typeof ModelEntrySchema>;
+
+// =============================================================================
+// Provider Info
+// =============================================================================
+
+/**
+ * Provider capability (applies to all models from this provider)
+ */
+export const ProviderCapabilitySchema = z.enum([
+	"reasoning",
+	"prompt-cache",
+	"tools",
+	"oauth",
+]);
+
+export type ProviderCapability = z.infer<typeof ProviderCapabilitySchema>;
+
+/**
+ * Provider protocol/transport family
+ */
+export const ProviderProtocolSchema = z.enum([
+	"anthropic",
+	"gemini",
+	"openai-chat",
+	"openai-responses",
+	"openai-r1",
+]);
+
+export type ProviderProtocol = z.infer<typeof ProviderProtocolSchema>;
+
+/**
+ * Provider configuration
+ */
+export const ProviderInfoSchema = z.object({
+	/** Provider ID (e.g., "anthropic", "openai") */
+	id: z.string(),
+	/** Human-readable name */
+	name: z.string(),
+	/** Provider description */
+	description: z.string().optional(),
+	/** Provider protocol family used for handler routing */
+	protocol: ProviderProtocolSchema.optional(),
+	/** Base URL for API */
+	baseUrl: z.string().optional(),
+	/** Default model ID */
+	defaultModelId: z.string(),
+	/** Provider-level capabilities */
+	capabilities: z.array(ProviderCapabilitySchema).optional(),
+	/** Environment variables associated with this provider */
+	env: z.array(z.string()).optional(),
+});
+
+export type ProviderInfo = z.infer<typeof ProviderInfoSchema>;
+
+// =============================================================================
+// Model Collection
+// =============================================================================
+
+/**
+ * A collection of models from a provider
+ */
+export const ModelCollectionSchema = z.object({
+	/** Provider information */
+	provider: ProviderInfoSchema,
+	/** Models keyed by ID */
+	models: z.record(z.string(), ModelInfoSchema),
+});
+
+export type ModelCollection = z.infer<typeof ModelCollectionSchema>;
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Check if a model has a specific capability
+ */
+export function hasCapability(
+	info: ModelInfo,
+	capability: ModelCapability,
+): boolean {
+	return info.capabilities?.includes(capability) ?? false;
+}
+
+/**
+ * Check if a model is deprecated
+ */
+export function isDeprecated(info: ModelInfo): boolean {
+	return info.status === "deprecated";
+}
+
+/**
+ * Check if a model is active (not deprecated or legacy)
+ */
+export function isActive(info: ModelInfo): boolean {
+	return !info.status || info.status === "active" || info.status === "preview";
+}
+
+/**
+ * Get pricing for a model
+ */
+export function getPricing(info: ModelInfo): ModelPricing {
+	return info.pricing ?? {};
+}
+
+/**
+ * Validate model info against schema
+ */
+export function validateModelInfo(data: unknown): ModelInfo {
+	return ModelInfoSchema.parse(data);
+}
+
+/**
+ * Safely validate model info (returns undefined on failure)
+ */
+export function safeValidateModelInfo(data: unknown): ModelInfo | undefined {
+	const result = ModelInfoSchema.safeParse(data);
+	return result.success ? result.data : undefined;
+}

package/src/models/schemas/query.ts

@@ -0,0 +1,336 @@
+/**
+ * Model Query Schema Definitions
+ *
+ * Zod schemas for configuring model queries and filters.
+ * Users can use these to find models matching specific criteria.
+ */
+
+import { z } from "zod";
+import {
+	ApiFormatSchema,
+	hasCapability,
+	isDeprecated,
+	ModelCapabilitySchema,
+	type ModelInfo,
+	ModelStatusSchema,
+} from "./model";
+
+// =============================================================================
+// Query Configuration
+// =============================================================================
+
+/**
+ * Configuration for querying models
+ */
+export const ModelQueryConfigSchema = z.object({
+	/**
+	 * Filter by provider IDs
+	 * If not specified, returns models from all providers
+	 */
+	providers: z.array(z.string()).optional(),
+
+	/**
+	 * Filter by required capabilities
+	 * Models must have ALL specified capabilities
+	 */
+	capabilities: z.array(ModelCapabilitySchema).optional(),
+
+	/**
+	 * Filter by any of these capabilities
+	 * Models must have AT LEAST ONE of the specified capabilities
+	 */
+	anyCapabilities: z.array(ModelCapabilitySchema).optional(),
+
+	/**
+	 * Exclude models with these capabilities
+	 */
+	excludeCapabilities: z.array(ModelCapabilitySchema).optional(),
+
+	/**
+	 * Filter by model status
+	 * If not specified, includes all statuses
+	 */
+	status: z.array(ModelStatusSchema).optional(),
+
+	/**
+	 * Include deprecated models
+	 * @default false
+	 */
+	includeDeprecated: z.boolean().optional(),
+
+	/**
+	 * Filter by API format
+	 */
+	apiFormat: ApiFormatSchema.optional(),
+
+	/**
+	 * Filter by minimum context window size
+	 */
+	minContextWindow: z.number().optional(),
+
+	/**
+	 * Filter by maximum context window size
+	 */
+	maxContextWindow: z.number().optional(),
+
+	/**
+	 * Filter by minimum output tokens
+	 */
+	minMaxTokens: z.number().optional(),
+
+	/**
+	 * Filter by maximum price per million input tokens
+	 */
+	maxInputPrice: z.number().optional(),
+
+	/**
+	 * Filter by maximum price per million output tokens
+	 */
+	maxOutputPrice: z.number().optional(),
+
+	/**
+	 * Search by model name or ID (case-insensitive partial match)
+	 */
+	search: z.string().optional(),
+
+	/**
+	 * Only return models with thinking/reasoning support
+	 */
+	hasThinking: z.boolean().optional(),
+
+	/**
+	 * Sort results by field
+	 */
+	sortBy: z
+		.enum(["name", "contextWindow", "maxTokens", "inputPrice", "outputPrice"])
+		.optional(),
+
+	/**
+	 * Sort direction
+	 * @default "asc"
+	 */
+	sortDirection: z.enum(["asc", "desc"]).optional(),
+
+	/**
+	 * Limit number of results
+	 */
+	limit: z.number().optional(),
+});
+
+export type ModelQueryConfig = z.infer<typeof ModelQueryConfigSchema>;
+
+// =============================================================================
+// Query Result
+// =============================================================================
+
+/**
+ * Result of a model query
+ */
+export const ModelQueryResultSchema = z.object({
+	/** Matching models with their provider */
+	models: z.array(
+		z.object({
+			providerId: z.string(),
+			modelId: z.string(),
+			info: z.any(), // ModelInfoSchema but avoiding circular ref
+		}),
+	),
+	/** Total count before limit */
+	total: z.number(),
+	/** Query config used */
+	config: ModelQueryConfigSchema,
+});
+
+export type ModelQueryResult = z.infer<typeof ModelQueryResultSchema>;
+
+// =============================================================================
+// Model Match Result
+// =============================================================================
+
+export interface ModelMatch {
+	providerId: string;
+	modelId: string;
+	info: ModelInfo;
+}
+
+// =============================================================================
+// Query Functions
+// =============================================================================
+
+/**
+ * Check if a model matches the query config
+ */
+export function matchesQuery(
+	modelId: string,
+	info: ModelInfo,
+	config: ModelQueryConfig,
+): boolean {
+	// Check deprecated filter
+	if (!config.includeDeprecated && isDeprecated(info)) {
+		return false;
+	}
+
+	// Check status filter
+	if (config.status && config.status.length > 0) {
+		const modelStatus = info.status ?? "active";
+		if (!config.status.includes(modelStatus)) {
+			return false;
+		}
+	}
+
+	// Check required capabilities (ALL must be present)
+	if (config.capabilities && config.capabilities.length > 0) {
+		const hasAll = config.capabilities.every((cap) => hasCapability(info, cap));
+		if (!hasAll) {
+			return false;
+		}
+	}
+
+	// Check any capabilities (AT LEAST ONE must be present)
+	if (config.anyCapabilities && config.anyCapabilities.length > 0) {
+		const hasAny = config.anyCapabilities.some((cap) =>
+			hasCapability(info, cap),
+		);
+		if (!hasAny) {
+			return false;
+		}
+	}
+
+	// Check excluded capabilities (NONE must be present)
+	if (config.excludeCapabilities && config.excludeCapabilities.length > 0) {
+		const hasExcluded = config.excludeCapabilities.some((cap) =>
+			hasCapability(info, cap),
+		);
+		if (hasExcluded) {
+			return false;
+		}
+	}
+
+	// Check API format
+	if (config.apiFormat && info.apiFormat !== config.apiFormat) {
+		return false;
+	}
+
+	// Check context window bounds
+	if (
+		config.minContextWindow &&
+		(info.contextWindow ?? 0) < config.minContextWindow
+	) {
+		return false;
+	}
+	if (
+		config.maxContextWindow &&
+		(info.contextWindow ?? Number.POSITIVE_INFINITY) > config.maxContextWindow
+	) {
+		return false;
+	}
+
+	// Check max tokens
+	if (config.minMaxTokens && (info.maxTokens ?? 0) < config.minMaxTokens) {
+		return false;
+	}
+
+	// Check pricing bounds
+	if (
+		config.maxInputPrice &&
+		(info.pricing?.input ?? Number.POSITIVE_INFINITY) > config.maxInputPrice
+	) {
+		return false;
+	}
+	if (
+		config.maxOutputPrice &&
+		(info.pricing?.output ?? Number.POSITIVE_INFINITY) > config.maxOutputPrice
+	) {
+		return false;
+	}
+
+	// Check search term
+	if (config.search) {
+		const searchLower = config.search.toLowerCase();
+		const nameMatch = info.name?.toLowerCase().includes(searchLower) ?? false;
+		const idMatch = modelId.toLowerCase().includes(searchLower);
+		const descMatch =
+			info.description?.toLowerCase().includes(searchLower) ?? false;
+		if (!nameMatch && !idMatch && !descMatch) {
+			return false;
+		}
+	}
+
+	// Check thinking support
+	if (config.hasThinking === true && !info.thinkingConfig) {
+		return false;
+	}
+	if (config.hasThinking === false && info.thinkingConfig) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Sort model results
+ */
+export function sortModels(
+	models: ModelMatch[],
+	sortBy: ModelQueryConfig["sortBy"],
+	direction: "asc" | "desc" = "asc",
+): ModelMatch[] {
+	if (!sortBy) {
+		return models;
+	}
+
+	const sorted = [...models].sort((a, b) => {
+		let aVal: number | string;
+		let bVal: number | string;
+
+		switch (sortBy) {
+			case "name":
+				aVal = a.info.name ?? a.modelId;
+				bVal = b.info.name ?? b.modelId;
+				break;
+			case "contextWindow":
+				aVal = a.info.contextWindow ?? 0;
+				bVal = b.info.contextWindow ?? 0;
+				break;
+			case "maxTokens":
+				aVal = a.info.maxTokens ?? 0;
+				bVal = b.info.maxTokens ?? 0;
+				break;
+			case "inputPrice":
+				aVal = a.info.pricing?.input ?? Number.POSITIVE_INFINITY;
+				bVal = b.info.pricing?.input ?? Number.POSITIVE_INFINITY;
+				break;
+			case "outputPrice":
+				aVal = a.info.pricing?.output ?? Number.POSITIVE_INFINITY;
+				bVal = b.info.pricing?.output ?? Number.POSITIVE_INFINITY;
+				break;
+			default:
+				return 0;
+		}
+
+		if (typeof aVal === "string" && typeof bVal === "string") {
+			return aVal.localeCompare(bVal);
+		}
+
+		return (aVal as number) - (bVal as number);
+	});
+
+	return direction === "desc" ? sorted.reverse() : sorted;
+}
+
+/**
+ * Validate query config
+ */
+export function validateQueryConfig(data: unknown): ModelQueryConfig {
+	return ModelQueryConfigSchema.parse(data);
+}
+
+/**
+ * Safely validate query config (returns undefined on failure)
+ */
+export function safeValidateQueryConfig(
+	data: unknown,
+): ModelQueryConfig | undefined {
+	const result = ModelQueryConfigSchema.safeParse(data);
+	return result.success ? result.data : undefined;
+}

package/src/providers/browser.ts

@@ -0,0 +1,4 @@
+export {
+	OPENAI_COMPATIBLE_PROVIDERS,
+	type ProviderDefaults,
+} from "./handlers/providers";