hankweave 0.5.7 → 0.6.2

package/dist/llm/llm-provider-registry.d.ts

@@ -0,0 +1,207 @@
+import type { LanguageModel } from "ai";
+import type { Logger } from "../utils.js";
+import { type ModelInfo } from "./models-dev-schema.js";
+/**
+ * Discriminated union for provider status
+ */
+export type ProviderStatus = {
+    status: "not-configured";
+    id: string;
+    error: string;
+} | {
+    status: "available";
+    id: string;
+    healthy: boolean;
+    lastChecked?: Date;
+    error?: string;
+} | {
+    status: "failed";
+    id: string;
+    error: string;
+    lastChecked: Date;
+};
+/**
+ * Result types for better error handling
+ */
+export type ModelResult = {
+    success: true;
+    model: LanguageModel;
+} | {
+    success: false;
+    reason: "model-not-found" | "provider-unavailable" | "provider-unhealthy" | "model-blocked";
+};
+export type ModelInfoResult = {
+    success: true;
+    info: ModelInfo;
+} | {
+    success: false;
+    reason: "model-not-found" | "model-blocked";
+};
+export type ResolveModelResult = {
+    success: true;
+    modelInfo: ModelInfo;
+    matchType: "exact" | "exact-with-inferred-provider" | "fuzzy";
+} | {
+    success: false;
+    reason: "model-not-found" | "model-blocked";
+};
+export interface BlockList {
+    providers?: string[];
+    models?: string[];
+}
+export interface LlmProviderRegistryConfig {
+    logger?: Logger;
+    healthCheckTimeout?: number;
+    performHealthCheckOnInit?: boolean;
+    blockList?: BlockList;
+}
+export declare class LlmProviderRegistry {
+    private static instance;
+    /**
+     * Common shortcuts for model names that map to search patterns.
+     * These are expanded before model resolution to improve matching.
+     */
+    private static readonly MODEL_SHORTCUTS;
+    private providers;
+    private models;
+    private uniqueModels;
+    private providerStatus;
+    private logger?;
+    private healthCheckTimeout;
+    private blockList;
+    constructor(config?: LlmProviderRegistryConfig);
+    /**
+     * Get the singleton instance of LlmProviderRegistry.
+     * Creates a new instance with the provided config if one doesn't exist.
+     *
+     * @param config - Configuration for the registry (only used on first call)
+     * @returns The singleton instance
+     */
+    static getInstance(config?: LlmProviderRegistryConfig): LlmProviderRegistry;
+    /**
+     * Reset the singleton instance (primarily for testing).
+     */
+    static resetInstance(): void;
+    private loadModelsData;
+    /**
+     * Find the cheapest model for a provider.
+     * Used for health checks and credit validation where we want the
+     * lowest-cost model that still works as a chat model.
+     *
+     * Filters to:
+     * - Chat models only (not embeddings)
+     * - Models that support both text input and text output
+     *
+     * Prefers models updated in the last 6 months (more likely to still be
+     * active on the provider's API). Falls back to 1 year if nothing recent
+     * enough is found, then drops the date filter entirely as a last resort.
+     */
+    findCheapestModel(providerId: string): string | undefined;
+    /**
+     * Get the best model for a health check.
+     * Tries provider-configured preferred models first (stable, non-preview IDs),
+     * then falls back to findCheapestModel.
+     */
+    getHealthCheckModel(providerId: string): string | undefined;
+    private initializeProviders;
+    /**
+     * Check if a model is blocked by the blocklist.
+     * Checks both model-level and provider-level blocking (case-insensitive).
+     *
+     * @param modelInfo - The model information to check
+     * @returns true if the model or its provider is blocked
+     */
+    private isModelBlocked;
+    /**
+     * Calculate Levenshtein distance between two strings
+     * Returns a similarity score from 0 to 1 (1 = identical)
+     */
+    private calculateStringSimilarity;
+    /**
+     * Get preferred provider for a model based on naming patterns
+     * Uses fuzzy matching to handle typos
+     */
+    private getPreferredProvider;
+    /**
+     * Find models matching the query using fuzzy matching
+     * Returns the most recent model above the similarity threshold
+     *
+     * @internal Match object: { model: ModelInfo, score: number, hasExactWordMatch: boolean }
+     */
+    private fuzzyMatchModels;
+    performHealthChecks(): Promise<Map<string, ProviderStatus>>;
+    /**
+     * Get a provider and model for a specific model name with parameter validation.
+     * Returns a result object with success/failure information.
+     */
+    getProviderForModel(modelName: string, llmParams?: {
+        temperature?: number;
+        maxOutputTokens?: number;
+    }): ModelResult;
+    /**
+     * Get cost information for a model.
+     */
+    getModelInfo(modelName: string): ModelInfoResult;
+    /**
+     * Resolve a model name to model information with support for:
+     * - Exact matching with explicit provider
+     * - Exact matching with provider inference
+     * - Fuzzy matching with provider preferences
+     *
+     * @param input.providerId - Optional provider ID (e.g., "anthropic", "google", "openai")
+     * @param input.model - Model name (exact or fuzzy, e.g., "claude-3-5-sonnet" or "claude-sonnet")
+     * @param input.ignoreBlockList - Whether to ignore the blocklist (default: true)
+     * @returns ResolveModelResult with model info and match type, or failure reason
+     */
+    resolveModel(input: {
+        providerId?: string;
+        model: string;
+        ignoreBlockList?: boolean;
+    }): ResolveModelResult;
+    /**
+     * Check if a model is available (provider exists and is healthy).
+     */
+    isModelAvailable(modelName: string): boolean;
+    /**
+     * Get all available models.
+     */
+    getAvailableModels(): string[];
+    /**
+     * Get provider status information.
+     */
+    getProviderStatus(): Map<string, ProviderStatus>;
+    /**
+     * Calculate cost for a given token usage with full cache support.
+     *
+     * Handles provider-specific token semantics:
+     * - OpenAI: inputTokens INCLUDES cached tokens (cache_read is a subset)
+     * - Anthropic: inputTokens is fresh only (cache_read is additive)
+     *
+     * @param modelName - Model identifier (will be resolved via registry)
+     * @param usage - Token usage breakdown
+     * @returns Cost in USD, or null if model not found or no pricing data available
+     */
+    calculateCost(modelName: string, usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheCreationTokens?: number;
+    }): number | null;
+    /**
+     * Format cost as a readable string.
+     */
+    formatCost(cost: number): string;
+    /**
+     * Get models for a specific provider
+     */
+    getModelsForProvider(providerId: string): string[];
+    /**
+     * Get summary statistics
+     */
+    getStats(): {
+        totalModels: number;
+        totalProviders: number;
+        availableProviders: number;
+        healthyProviders: number;
+    };
+}