@clinebot/llms 0.0.0

package/dist/models/query.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Model Query API
+ *
+ * High-level API for querying and filtering models across all providers.
+ * Uses the registry and schema validation for type-safe queries.
+ */
+import { type ModelMatch, type ModelQueryConfig } from "./schemas/index";
+/**
+ * Query models using a configuration object
+ *
+ * @example
+ * ```typescript
+ * // Get all models with image support
+ * const imageModels = queryModels({
+ *   capabilities: ["images"],
+ * })
+ *
+ * // Get cheap reasoning models
+ * const cheapReasoning = queryModels({
+ *   capabilities: ["reasoning"],
+ *   maxInputPrice: 1,
+ *   sortBy: "inputPrice",
+ * })
+ *
+ * // Get Anthropic and OpenAI models
+ * const models = queryModels({
+ *   providers: ["anthropic", "openai"],
+ *   includeDeprecated: false,
+ * })
+ * ```
+ */
+export declare function queryModels(config: ModelQueryConfig): ModelMatch[];
+/**
+ * Get all models with vision/image capabilities
+ */
+export declare function getVisionModels(): ModelMatch[];
+/**
+ * Get all models with reasoning/thinking capabilities
+ */
+export declare function getReasoningModels(): ModelMatch[];
+/**
+ * Get all models with prompt caching support
+ */
+export declare function getCachingModels(): ModelMatch[];
+/**
+ * Get all models with tool/function calling support
+ */
+export declare function getToolModels(): ModelMatch[];
+/**
+ * Get all models supporting computer use
+ */
+export declare function getComputerUseModels(): ModelMatch[];
+/**
+ * Get all active (non-deprecated) models
+ */
+export declare function getActiveModels(): ModelMatch[];
+/**
+ * Get all deprecated models
+ */
+export declare function getDeprecatedModels(): ModelMatch[];
+/**
+ * Get models within a price range (input price per million tokens)
+ */
+export declare function getModelsInPriceRange(maxInputPrice: number, maxOutputPrice?: number): ModelMatch[];
+/**
+ * Get models with minimum context window size
+ */
+export declare function getModelsWithContextWindow(minTokens: number): ModelMatch[];
+/**
+ * Get models by provider
+ */
+export declare function getModelsByProvider(providerId: string): ModelMatch[];
+/**
+ * Search models by name or ID
+ */
+export declare function searchModels(searchTerm: string): ModelMatch[];
+/**
+ * Fluent query builder for constructing model queries
+ *
+ * @example
+ * ```typescript
+ * const models = createQuery()
+ *   .fromProviders(["anthropic", "openai"])
+ *   .withCapabilities(["images", "reasoning"])
+ *   .maxPrice({ input: 5 })
+ *   .sortBy("inputPrice")
+ *   .limit(10)
+ *   .execute()
+ * ```
+ */
+export declare class ModelQueryBuilder {
+    private config;
+    /**
+     * Filter by provider IDs
+     */
+    fromProviders(providers: string[]): this;
+    /**
+     * Require all specified capabilities
+     */
+    withCapabilities(capabilities: ModelQueryConfig["capabilities"]): this;
+    /**
+     * Require at least one of the specified capabilities
+     */
+    withAnyCapabilities(capabilities: ModelQueryConfig["anyCapabilities"]): this;
+    /**
+     * Exclude models with specified capabilities
+     */
+    excludeCapabilities(capabilities: ModelQueryConfig["excludeCapabilities"]): this;
+    /**
+     * Filter by model status
+     */
+    withStatus(status: ModelQueryConfig["status"]): this;
+    /**
+     * Include deprecated models
+     */
+    includeDeprecated(include?: boolean): this;
+    /**
+     * Filter by API format
+     */
+    withApiFormat(format: ModelQueryConfig["apiFormat"]): this;
+    /**
+     * Filter by context window size
+     */
+    contextWindow(options: {
+        min?: number;
+        max?: number;
+    }): this;
+    /**
+     * Filter by minimum output tokens
+     */
+    minMaxTokens(tokens: number): this;
+    /**
+     * Filter by maximum price
+     */
+    maxPrice(options: {
+        input?: number;
+        output?: number;
+    }): this;
+    /**
+     * Search by name or ID
+     */
+    search(term: string): this;
+    /**
+     * Filter by thinking/reasoning support
+     */
+    hasThinking(has?: boolean): this;
+    /**
+     * Sort results
+     */
+    sortBy(field: ModelQueryConfig["sortBy"], direction?: ModelQueryConfig["sortDirection"]): this;
+    /**
+     * Limit number of results
+     */
+    limit(count: number): this;
+    /**
+     * Get the current config
+     */
+    getConfig(): ModelQueryConfig;
+    /**
+     * Execute the query
+     */
+    execute(): ModelMatch[];
+}
+/**
+ * Create a new query builder
+ */
+export declare function createQuery(): ModelQueryBuilder;
+/**
+ * Get statistics about registered models
+ */
+export declare function getModelStatistics(): Promise<{
+    totalModels: number;
+    modelsByProvider: Record<string, number>;
+    modelsByCapability: Record<string, number>;
+    modelsByStatus: Record<string, number>;
+    priceRange: {
+        min: number;
+        max: number;
+        avg: number;
+    };
+}>;

package/dist/models/registry.d.ts

@@ -0,0 +1,123 @@
+import type { ModelCollection, ModelInfo, ProviderInfo } from "./schemas/index";
+/**
+ * Get all registered provider IDs (does not load providers)
+ */
+export declare function getProviderIds(): string[];
+/**
+ * Check if a provider is registered (does not load it)
+ */
+export declare function hasProvider(providerId: string): boolean;
+/**
+ * Get provider by ID (async - loads if needed)
+ */
+export declare function getProvider(providerId: string): Promise<ProviderInfo | undefined>;
+/**
+ * Get provider collection by ID (async - loads if needed)
+ */
+export declare function getProviderCollection(providerId: string): Promise<ModelCollection | undefined>;
+/**
+ * Get all providers (async - loads all providers)
+ */
+export declare function getAllProviders(): Promise<ProviderInfo[]>;
+/**
+ * Preload specific providers into cache
+ */
+export declare function preloadProviders(providerIds: string[]): Promise<void>;
+/**
+ * Preload all providers into cache
+ */
+export declare function preloadAllProviders(): Promise<void>;
+/**
+ * Get provider from cache (sync) - returns undefined if not loaded yet
+ * Use this when you know the provider has been preloaded
+ */
+export declare function getProviderSync(providerId: string): ProviderInfo | undefined;
+/**
+ * Get provider collection from cache (sync) - returns undefined if not loaded yet
+ * Use this when you know the provider has been preloaded
+ */
+export declare function getProviderCollectionSync(providerId: string): ModelCollection | undefined;
+/**
+ * Get all loaded providers (sync) - only returns already-loaded providers
+ */
+export declare function getLoadedProviders(): ProviderInfo[];
+/**
+ * Check if a provider is loaded in cache
+ */
+export declare function isProviderLoaded(providerId: string): boolean;
+/**
+ * Get all models for a provider (async - loads provider if needed)
+ */
+export declare function getModelsForProvider(providerId: string): Promise<Record<string, ModelInfo>>;
+/**
+ * Get a specific model by provider and model ID (async)
+ */
+export declare function getModel(providerId: string, modelId: string): Promise<ModelInfo | undefined>;
+/**
+ * Get the default model for a provider (async)
+ */
+export declare function getDefaultModel(providerId: string): Promise<{
+    id: string;
+    info: ModelInfo;
+} | undefined>;
+/**
+ * Get all models across all providers (async - loads all providers)
+ */
+export declare function getAllModels(): Promise<Array<{
+    providerId: string;
+    modelId: string;
+    info: ModelInfo;
+}>>;
+/**
+ * Get total count of registered models (async - loads all providers)
+ */
+export declare function getModelCount(): Promise<number>;
+/**
+ * Get models for an already-loaded provider (sync)
+ * Returns empty object if provider is not loaded
+ */
+export declare function getModelsForProviderSync(providerId: string): Record<string, ModelInfo>;
+/**
+ * Get a specific model from an already-loaded provider (sync)
+ */
+export declare function getModelSync(providerId: string, modelId: string): ModelInfo | undefined;
+/**
+ * Register a custom provider (immediately available, not lazy loaded)
+ */
+export declare function registerProvider(collection: ModelCollection): void;
+/**
+ * Register a custom model for a provider
+ */
+export declare function registerModel(providerId: string, modelId: string, info: ModelInfo): void;
+/**
+ * Unregister a custom model
+ */
+export declare function unregisterModel(providerId: string, modelId: string): boolean;
+/**
+ * Unregister a provider
+ */
+export declare function unregisterProvider(providerId: string): boolean;
+/**
+ * Clear all custom models (keeps built-in)
+ */
+export declare function clearCustomModels(): void;
+/**
+ * Reset registry to initial state (clears cache, keeps loaders)
+ */
+export declare function resetRegistry(): void;
+/**
+ * Register multiple models at once
+ */
+export declare function registerModels(providerId: string, models: Record<string, ModelInfo>): void;
+/**
+ * Update model info (merges with existing) - async
+ */
+export declare function updateModel(providerId: string, modelId: string, updates: Partial<ModelInfo>): Promise<ModelInfo | undefined>;
+/**
+ * Mark a model as deprecated - async
+ */
+export declare function deprecateModel(providerId: string, modelId: string, options?: {
+    notice?: string;
+    replacedBy?: string;
+    deprecationDate?: string;
+}): Promise<ModelInfo | undefined>;

package/dist/models/schemas/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Schema Exports
+ *
+ * Re-exports all Zod schemas and types for model definitions.
+ */
+export { ApiFormat, type ApiFormat as ApiFormatType, ApiFormatSchema, getPricing, hasCapability, isActive, isDeprecated, type ModelCapability, ModelCapabilitySchema, type ModelCollection, ModelCollectionSchema, type ModelEntry, ModelEntrySchema, type ModelInfo, ModelInfoSchema, type ModelPricing, ModelPricingSchema, type ModelStatus, ModelStatusSchema, type ProviderCapability, ProviderCapabilitySchema, type ProviderInfo, ProviderInfoSchema, type ProviderProtocol, ProviderProtocolSchema, safeValidateModelInfo, type ThinkingConfig, ThinkingConfigSchema, validateModelInfo, } from "./model";
+export { type ModelMatch, type ModelQueryConfig, ModelQueryConfigSchema, type ModelQueryResult, ModelQueryResultSchema, matchesQuery, safeValidateQueryConfig, sortModels, validateQueryConfig, } from "./query";

package/dist/models/schemas/model.d.ts

@@ -0,0 +1,340 @@
+/**
+ * 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 variants for different provider protocols
+ */
+export declare const ApiFormatSchema: z.ZodEnum<{
+    default: "default";
+    "openai-responses": "openai-responses";
+    r1: "r1";
+}>;
+export type ApiFormat = z.infer<typeof ApiFormatSchema>;
+export declare const ApiFormat: {
+    readonly DEFAULT: "default";
+    readonly OPENAI_RESPONSES: "openai-responses";
+    readonly R1: "r1";
+};
+/**
+ * Capabilities a model may support
+ */
+export declare const ModelCapabilitySchema: z.ZodEnum<{
+    images: "images";
+    tools: "tools";
+    streaming: "streaming";
+    "prompt-cache": "prompt-cache";
+    reasoning: "reasoning";
+    "reasoning-effort": "reasoning-effort";
+    "computer-use": "computer-use";
+    "global-endpoint": "global-endpoint";
+    structured_output: "structured_output";
+    temperature: "temperature";
+    files: "files";
+}>;
+export type ModelCapability = z.infer<typeof ModelCapabilitySchema>;
+/**
+ * Model lifecycle status
+ */
+export declare const ModelStatusSchema: z.ZodEnum<{
+    active: "active";
+    preview: "preview";
+    deprecated: "deprecated";
+    legacy: "legacy";
+}>;
+export type ModelStatus = z.infer<typeof ModelStatusSchema>;
+/**
+ * Token pricing configuration (per million tokens)
+ */
+export declare const ModelPricingSchema: z.ZodObject<{
+    input: z.ZodOptional<z.ZodNumber>;
+    output: z.ZodOptional<z.ZodNumber>;
+    cacheWrite: z.ZodOptional<z.ZodNumber>;
+    cacheRead: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ModelPricing = z.infer<typeof ModelPricingSchema>;
+/**
+ * Configuration for models with thinking/reasoning capabilities
+ */
+export declare const ThinkingConfigSchema: z.ZodObject<{
+    maxBudget: z.ZodOptional<z.ZodNumber>;
+    outputPrice: z.ZodOptional<z.ZodNumber>;
+    thinkingLevel: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        high: "high";
+    }>>;
+}, z.core.$strip>;
+export type ThinkingConfig = z.infer<typeof ThinkingConfigSchema>;
+/**
+ * Complete model information schema
+ */
+export declare const ModelInfoSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    contextWindow: z.ZodOptional<z.ZodNumber>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        images: "images";
+        tools: "tools";
+        streaming: "streaming";
+        "prompt-cache": "prompt-cache";
+        reasoning: "reasoning";
+        "reasoning-effort": "reasoning-effort";
+        "computer-use": "computer-use";
+        "global-endpoint": "global-endpoint";
+        structured_output: "structured_output";
+        temperature: "temperature";
+        files: "files";
+    }>>>;
+    apiFormat: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        "openai-responses": "openai-responses";
+        r1: "r1";
+    }>>;
+    systemRole: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        developer: "developer";
+    }>>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    pricing: z.ZodOptional<z.ZodObject<{
+        input: z.ZodOptional<z.ZodNumber>;
+        output: z.ZodOptional<z.ZodNumber>;
+        cacheWrite: z.ZodOptional<z.ZodNumber>;
+        cacheRead: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    thinkingConfig: z.ZodOptional<z.ZodObject<{
+        maxBudget: z.ZodOptional<z.ZodNumber>;
+        outputPrice: z.ZodOptional<z.ZodNumber>;
+        thinkingLevel: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            high: "high";
+        }>>;
+    }, z.core.$strip>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        preview: "preview";
+        deprecated: "deprecated";
+        legacy: "legacy";
+    }>>;
+    deprecationNotice: z.ZodOptional<z.ZodString>;
+    replacedBy: z.ZodOptional<z.ZodString>;
+    releaseDate: z.ZodOptional<z.ZodString>;
+    deprecationDate: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ModelInfo = z.infer<typeof ModelInfoSchema>;
+/**
+ * A model entry with its ID and info
+ */
+export declare const ModelEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    info: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            images: "images";
+            tools: "tools";
+            streaming: "streaming";
+            "prompt-cache": "prompt-cache";
+            reasoning: "reasoning";
+            "reasoning-effort": "reasoning-effort";
+            "computer-use": "computer-use";
+            "global-endpoint": "global-endpoint";
+            structured_output: "structured_output";
+            temperature: "temperature";
+            files: "files";
+        }>>>;
+        apiFormat: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "openai-responses": "openai-responses";
+            r1: "r1";
+        }>>;
+        systemRole: z.ZodOptional<z.ZodEnum<{
+            system: "system";
+            developer: "developer";
+        }>>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        pricing: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodNumber>;
+            output: z.ZodOptional<z.ZodNumber>;
+            cacheWrite: z.ZodOptional<z.ZodNumber>;
+            cacheRead: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        thinkingConfig: z.ZodOptional<z.ZodObject<{
+            maxBudget: z.ZodOptional<z.ZodNumber>;
+            outputPrice: z.ZodOptional<z.ZodNumber>;
+            thinkingLevel: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                high: "high";
+            }>>;
+        }, z.core.$strip>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            preview: "preview";
+            deprecated: "deprecated";
+            legacy: "legacy";
+        }>>;
+        deprecationNotice: z.ZodOptional<z.ZodString>;
+        replacedBy: z.ZodOptional<z.ZodString>;
+        releaseDate: z.ZodOptional<z.ZodString>;
+        deprecationDate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ModelEntry = z.infer<typeof ModelEntrySchema>;
+/**
+ * Provider capability (applies to all models from this provider)
+ */
+export declare const ProviderCapabilitySchema: z.ZodEnum<{
+    tools: "tools";
+    "prompt-cache": "prompt-cache";
+    reasoning: "reasoning";
+    oauth: "oauth";
+}>;
+export type ProviderCapability = z.infer<typeof ProviderCapabilitySchema>;
+/**
+ * Provider protocol/transport family
+ */
+export declare const ProviderProtocolSchema: z.ZodEnum<{
+    "openai-responses": "openai-responses";
+    anthropic: "anthropic";
+    gemini: "gemini";
+    "openai-chat": "openai-chat";
+    "openai-r1": "openai-r1";
+}>;
+export type ProviderProtocol = z.infer<typeof ProviderProtocolSchema>;
+/**
+ * Provider configuration
+ */
+export declare const ProviderInfoSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    protocol: z.ZodOptional<z.ZodEnum<{
+        "openai-responses": "openai-responses";
+        anthropic: "anthropic";
+        gemini: "gemini";
+        "openai-chat": "openai-chat";
+        "openai-r1": "openai-r1";
+    }>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    defaultModelId: z.ZodString;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        tools: "tools";
+        "prompt-cache": "prompt-cache";
+        reasoning: "reasoning";
+        oauth: "oauth";
+    }>>>;
+    env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ProviderInfo = z.infer<typeof ProviderInfoSchema>;
+/**
+ * A collection of models from a provider
+ */
+export declare const ModelCollectionSchema: z.ZodObject<{
+    provider: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        protocol: z.ZodOptional<z.ZodEnum<{
+            "openai-responses": "openai-responses";
+            anthropic: "anthropic";
+            gemini: "gemini";
+            "openai-chat": "openai-chat";
+            "openai-r1": "openai-r1";
+        }>>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        defaultModelId: z.ZodString;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            tools: "tools";
+            "prompt-cache": "prompt-cache";
+            reasoning: "reasoning";
+            oauth: "oauth";
+        }>>>;
+        env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    models: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            images: "images";
+            tools: "tools";
+            streaming: "streaming";
+            "prompt-cache": "prompt-cache";
+            reasoning: "reasoning";
+            "reasoning-effort": "reasoning-effort";
+            "computer-use": "computer-use";
+            "global-endpoint": "global-endpoint";
+            structured_output: "structured_output";
+            temperature: "temperature";
+            files: "files";
+        }>>>;
+        apiFormat: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "openai-responses": "openai-responses";
+            r1: "r1";
+        }>>;
+        systemRole: z.ZodOptional<z.ZodEnum<{
+            system: "system";
+            developer: "developer";
+        }>>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        pricing: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodNumber>;
+            output: z.ZodOptional<z.ZodNumber>;
+            cacheWrite: z.ZodOptional<z.ZodNumber>;
+            cacheRead: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        thinkingConfig: z.ZodOptional<z.ZodObject<{
+            maxBudget: z.ZodOptional<z.ZodNumber>;
+            outputPrice: z.ZodOptional<z.ZodNumber>;
+            thinkingLevel: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                high: "high";
+            }>>;
+        }, z.core.$strip>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            preview: "preview";
+            deprecated: "deprecated";
+            legacy: "legacy";
+        }>>;
+        deprecationNotice: z.ZodOptional<z.ZodString>;
+        replacedBy: z.ZodOptional<z.ZodString>;
+        releaseDate: z.ZodOptional<z.ZodString>;
+        deprecationDate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ModelCollection = z.infer<typeof ModelCollectionSchema>;
+/**
+ * Check if a model has a specific capability
+ */
+export declare function hasCapability(info: ModelInfo, capability: ModelCapability): boolean;
+/**
+ * Check if a model is deprecated
+ */
+export declare function isDeprecated(info: ModelInfo): boolean;
+/**
+ * Check if a model is active (not deprecated or legacy)
+ */
+export declare function isActive(info: ModelInfo): boolean;
+/**
+ * Get pricing for a model
+ */
+export declare function getPricing(info: ModelInfo): ModelPricing;
+/**
+ * Validate model info against schema
+ */
+export declare function validateModelInfo(data: unknown): ModelInfo;
+/**
+ * Safely validate model info (returns undefined on failure)
+ */
+export declare function safeValidateModelInfo(data: unknown): ModelInfo | undefined;