@yourgpt/llm-sdk 2.1.4-alpha.2 → 2.1.5

package/dist/providers/openai/index.d.mts

@@ -1,6 +1,7 @@
 import { L as LanguageModel } from '../../types-CR8mi9I0.mjs';
-import { O as OpenAIProviderConfig, A as AIProvider } from '../../types-DoZX2k3v.mjs';
+import { O as OpenAIProviderConfig, A as AIProvider } from '../../types-VDgiUvH2.mjs';
 import 'zod';
+import '../../base-5n-UuPfS.mjs';
 
 /**
  * OpenAI Provider - Modern Pattern

package/dist/providers/openai/index.d.ts

@@ -1,6 +1,7 @@
 import { L as LanguageModel } from '../../types-CR8mi9I0.js';
-import { O as OpenAIProviderConfig, A as AIProvider } from '../../types-DtPQaoJi.js';
+import { O as OpenAIProviderConfig, A as AIProvider } from '../../types-C0vLXzuw.js';
 import 'zod';
+import '../../base-Di31iy_8.js';
 
 /**
  * OpenAI Provider - Modern Pattern

package/dist/providers/openrouter/index.d.mts

@@ -1,6 +1,7 @@
 import { L as LanguageModel } from '../../types-CR8mi9I0.mjs';
-import { A as AIProvider } from '../../types-DoZX2k3v.mjs';
+import { A as AIProvider } from '../../types-VDgiUvH2.mjs';
 import 'zod';
+import '../../base-5n-UuPfS.mjs';
 
 /**
  * OpenRouter Provider - Modern Pattern

package/dist/providers/openrouter/index.d.ts

@@ -1,6 +1,7 @@
 import { L as LanguageModel } from '../../types-CR8mi9I0.js';
-import { A as AIProvider } from '../../types-DtPQaoJi.js';
+import { A as AIProvider } from '../../types-C0vLXzuw.js';
 import 'zod';
+import '../../base-Di31iy_8.js';
 
 /**
  * OpenRouter Provider - Modern Pattern

package/dist/providers/xai/index.d.mts

@@ -1,6 +1,7 @@
 import { L as LanguageModel } from '../../types-CR8mi9I0.mjs';
-import { X as XAIProviderConfig, A as AIProvider } from '../../types-DoZX2k3v.mjs';
+import { X as XAIProviderConfig, A as AIProvider } from '../../types-VDgiUvH2.mjs';
 import 'zod';
+import '../../base-5n-UuPfS.mjs';
 
 /**
  * xAI Provider - Modern Pattern

package/dist/providers/xai/index.d.ts

@@ -1,6 +1,7 @@
 import { L as LanguageModel } from '../../types-CR8mi9I0.js';
-import { X as XAIProviderConfig, A as AIProvider } from '../../types-DtPQaoJi.js';
+import { X as XAIProviderConfig, A as AIProvider } from '../../types-C0vLXzuw.js';
 import 'zod';
+import '../../base-Di31iy_8.js';
 
 /**
  * xAI Provider - Modern Pattern

package/dist/types-BQl1suAv.d.mts

@@ -0,0 +1,212 @@
+import { L as LLMAdapter } from './base-5n-UuPfS.mjs';
+
+/**
+ * Fallback Chain & Routing Strategy Types
+ */
+
+/**
+ * Pluggable state store for routing strategies.
+ *
+ * Round-robin and other stateful strategies use this to persist
+ * which model was last used. The default implementation is in-memory.
+ *
+ * For multi-instance or serverless deployments, plug in your own:
+ * Redis, Upstash, Cloudflare KV, DynamoDB, etc.
+ *
+ * @example
+ * ```typescript
+ * // Redis-backed store (example — bring your own client)
+ * const redisStore: RoutingStore = {
+ *   async get(key) {
+ *     const val = await redis.get(key);
+ *     return val ? Number(val) : undefined;
+ *   },
+ *   async set(key, value) {
+ *     await redis.set(key, value);
+ *   },
+ * };
+ * ```
+ */
+interface RoutingStore {
+    /** Get the stored value for a key */
+    get(key: string): Promise<number | undefined>;
+    /** Set the stored value for a key */
+    set(key: string, value: number): Promise<void>;
+}
+/**
+ * A single failed model in the fallback chain (after all retries exhausted)
+ */
+interface FallbackFailure {
+    /** Model ID that failed */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** The last error from this model */
+    error: Error;
+    /** Which model in the chain this was (1-based) */
+    attempt: number;
+    /** How many times this model was retried before giving up */
+    retriesAttempted: number;
+}
+/**
+ * Passed to the onFallback callback when a model is abandoned and the next one is tried
+ */
+interface FallbackInfo {
+    /** Model that just failed (after all its retries) */
+    attemptedModel: string;
+    /** Model that will be tried next */
+    nextModel: string;
+    /** The last error from the failed model */
+    error: Error;
+    /** Which model in the chain this was (1-based) */
+    attempt: number;
+}
+/**
+ * Passed to the onRetry callback on each per-model retry attempt
+ */
+interface RetryInfo {
+    /** Model being retried */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** The error that triggered this retry */
+    error: Error;
+    /** Which retry attempt this is (1-based: 1 = first retry after initial failure) */
+    retryAttempt: number;
+    /** Total retries configured for this chain */
+    maxRetries: number;
+    /** How long (ms) we will wait before retrying */
+    delayMs: number;
+}
+/**
+ * How the chain decides which model to try first.
+ *
+ * - `priority` — always try models in defined order (default)
+ * - `round-robin` — rotate starting model evenly across calls
+ */
+type RoutingStrategy = "priority" | "round-robin";
+/**
+ * Backoff strategy between per-model retries.
+ *
+ * - `exponential` — delay doubles on each retry: 500ms → 1000ms → 2000ms (default)
+ * - `fixed`       — same delay every retry: 500ms → 500ms → 500ms
+ */
+type RetryBackoff = "exponential" | "fixed";
+/**
+ * Configuration for createFallbackChain()
+ */
+interface FallbackChainConfig {
+    /**
+     * Ordered list of adapters to try.
+     * On failure, the chain moves to the next adapter in this list.
+     *
+     * @example
+     * ```typescript
+     * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+     * import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+     *
+     * const openai = createOpenAI({ apiKey: '...' });
+     * const anthropic = createAnthropic({ apiKey: '...' });
+     *
+     * const chain = createFallbackChain({
+     *   models: [
+     *     openai.languageModel('gpt-4o'),
+     *     anthropic.languageModel('claude-3-5-sonnet-20241022'),
+     *   ],
+     * });
+     * ```
+     */
+    models: LLMAdapter[];
+    /**
+     * Routing strategy controlling which model is tried first.
+     * @default 'priority'
+     */
+    strategy?: RoutingStrategy;
+    /**
+     * State store for strategies that require persistence (e.g., round-robin).
+     * Defaults to an in-memory store (MemoryRoutingStore).
+     *
+     * Replace with a shared store (Redis, Upstash, etc.) for multi-instance
+     * or serverless deployments where round-robin state must be shared.
+     */
+    store?: RoutingStore;
+    /**
+     * Number of times to retry the same model before moving to the next one.
+     *
+     * LiteLLM equivalent: `num_retries`
+     *
+     * @default 0  (no retries — fail immediately and move to next model)
+     *
+     * @example
+     * ```typescript
+     * // Try each model up to 3 times before falling back
+     * createFallbackChain({ models: [...], retries: 3 })
+     * ```
+     */
+    retries?: number;
+    /**
+     * Base delay in milliseconds between per-model retries.
+     *
+     * With `retryBackoff: 'exponential'` (default):
+     *   retry 1 → retryDelay ms
+     *   retry 2 → retryDelay * 2 ms
+     *   retry 3 → retryDelay * 4 ms
+     *
+     * With `retryBackoff: 'fixed'`:
+     *   every retry → retryDelay ms
+     *
+     * @default 500
+     */
+    retryDelay?: number;
+    /**
+     * Backoff strategy between per-model retries.
+     * @default 'exponential'
+     */
+    retryBackoff?: RetryBackoff;
+    /**
+     * Called on each per-model retry attempt (before the delay).
+     * Use for logging, metrics, or alerting per retry.
+     *
+     * @example
+     * ```typescript
+     * onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
+     *   console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms | ${error.message}`);
+     * }
+     * ```
+     */
+    onRetry?: (info: RetryInfo) => void;
+    /**
+     * Called each time a model is abandoned and the next one is tried.
+     * Use for logging, metrics, or alerting.
+     *
+     * @example
+     * ```typescript
+     * onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
+     *   console.warn(`[fallback] attempt ${attempt}: ${attemptedModel} failed → ${nextModel}`, error.message);
+     * }
+     * ```
+     */
+    onFallback?: (info: FallbackInfo) => void;
+    /**
+     * Custom predicate to decide whether an error should trigger a fallback.
+     *
+     * By default, the following trigger fallback:
+     * - HTTP 5xx server errors
+     * - HTTP 429 rate limit errors
+     * - Network timeouts and connection failures
+     *
+     * The following do NOT trigger fallback by default:
+     * - HTTP 4xx client errors (bad request, invalid API key, etc.)
+     *
+     * Override this to extend or restrict fallback behavior.
+     *
+     * @example
+     * ```typescript
+     * // Also fall back on any error
+     * retryableErrors: () => true,
+     * ```
+     */
+    retryableErrors?: (error: unknown) => boolean;
+}
+
+export type { FallbackChainConfig as F, RoutingStore as R, RoutingStrategy as a, RetryBackoff as b, FallbackFailure as c, FallbackInfo as d, RetryInfo as e };

package/dist/types-C0vLXzuw.d.ts

@@ -0,0 +1,355 @@
+import { L as LLMAdapter, T as ToolDefinition, U as UnifiedToolCall, h as UnifiedToolResult } from './base-Di31iy_8.js';
+
+/**
+ * Provider Types
+ *
+ * Defines interfaces for:
+ * 1. Provider Formatters (for tool transformations in agent loop)
+ * 2. Multi-provider architecture (AIProvider, capabilities, configs)
+ */
+
+/**
+ * Provider formatter interface
+ *
+ * Each provider implements this interface to handle:
+ * - Tool definition transformation
+ * - Tool call parsing from responses
+ * - Tool result formatting
+ * - Stop reason detection
+ */
+interface ProviderFormatter {
+    /**
+     * Transform unified tool definitions to provider format
+     */
+    transformTools(tools: ToolDefinition[]): unknown[];
+    /**
+     * Parse tool calls from provider response
+     */
+    parseToolCalls(response: unknown): UnifiedToolCall[];
+    /**
+     * Format tool results for provider
+     */
+    formatToolResults(results: UnifiedToolResult[]): unknown[];
+    /**
+     * Check if response indicates tool use is requested
+     */
+    isToolUseStop(response: unknown): boolean;
+    /**
+     * Check if response indicates end of turn
+     */
+    isEndTurnStop(response: unknown): boolean;
+    /**
+     * Get stop reason string from response
+     */
+    getStopReason(response: unknown): string;
+    /**
+     * Extract text content from response
+     */
+    extractTextContent(response: unknown): string;
+    /**
+     * Build assistant message with tool calls for conversation history
+     */
+    buildAssistantToolMessage(toolCalls: UnifiedToolCall[], textContent?: string): unknown;
+    /**
+     * Build user message with tool results for conversation history
+     */
+    buildToolResultMessage(results: UnifiedToolResult[]): unknown;
+}
+/**
+ * Anthropic tool definition format
+ */
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Anthropic tool_use block from response
+ */
+interface AnthropicToolUse {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Anthropic tool_result block
+ */
+interface AnthropicToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+}
+/**
+ * OpenAI tool definition format
+ */
+interface OpenAITool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+}
+/**
+ * OpenAI tool call from response
+ */
+interface OpenAIToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * OpenAI tool result message
+ */
+interface OpenAIToolResult {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+}
+/**
+ * Google Gemini function declaration
+ */
+interface GeminiFunctionDeclaration {
+    name: string;
+    description: string;
+    parameters?: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Gemini function call from response
+ */
+interface GeminiFunctionCall {
+    name: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Gemini function response
+ */
+interface GeminiFunctionResponse {
+    name: string;
+    response: Record<string, unknown>;
+}
+/**
+ * Capabilities of a model for UI feature flags
+ * UI components can use this to enable/disable features
+ */
+interface ProviderCapabilities {
+    /** Supports image inputs */
+    supportsVision: boolean;
+    /** Supports tool/function calling */
+    supportsTools: boolean;
+    /** Supports extended thinking (Claude, DeepSeek) */
+    supportsThinking: boolean;
+    /** Supports streaming responses */
+    supportsStreaming: boolean;
+    /** Supports PDF document inputs */
+    supportsPDF: boolean;
+    /** Supports audio inputs */
+    supportsAudio: boolean;
+    /** Supports video inputs */
+    supportsVideo: boolean;
+    /** Maximum context tokens */
+    maxTokens: number;
+    /** Supported image MIME types */
+    supportedImageTypes: string[];
+    /** Supported audio MIME types */
+    supportedAudioTypes?: string[];
+    /** Supported video MIME types */
+    supportedVideoTypes?: string[];
+    /** Supports JSON mode / structured output */
+    supportsJsonMode?: boolean;
+    /** Supports system messages */
+    supportsSystemMessages?: boolean;
+}
+/**
+ * AI Provider interface (object form)
+ *
+ * Wraps existing LLMAdapter with additional metadata:
+ * - Supported models list
+ * - Per-model capabilities
+ * - Provider name
+ */
+interface AIProviderObject {
+    /** Provider name (e.g., 'openai', 'anthropic') */
+    readonly name: string;
+    /** List of supported model IDs */
+    readonly supportedModels: string[];
+    /**
+     * Get a language model adapter for the given model ID
+     * Returns the existing LLMAdapter interface - no breaking changes
+     */
+    languageModel(modelId: string): LLMAdapter;
+    /**
+     * Get capabilities for a specific model
+     * UI components use this to enable/disable features
+     */
+    getCapabilities(modelId: string): ProviderCapabilities;
+    /**
+     * Optional: Get an embedding model (future expansion)
+     */
+    embeddingModel?(modelId: string): EmbeddingModel;
+}
+/**
+ * Callable AI Provider (Vercel AI SDK style)
+ *
+ * A function that returns a LanguageModel when called with a model ID,
+ * but also has properties for provider metadata and methods.
+ *
+ * @example
+ * ```typescript
+ * const openai = createOpenAI({ apiKey: '...' });
+ *
+ * // Callable - returns LanguageModel directly (Vercel AI SDK style)
+ * const model = openai('gpt-4o');
+ *
+ * // Also supports method calls (backward compatible)
+ * const model2 = openai.languageModel('gpt-4o');
+ *
+ * // Check capabilities
+ * const caps = openai.getCapabilities('gpt-4o');
+ * if (caps.supportsVision) {
+ *   // Show image upload button
+ * }
+ * ```
+ */
+interface AIProvider extends AIProviderObject {
+    /**
+     * Call the provider directly with a model ID to get a LanguageModel
+     * This is the Vercel AI SDK style pattern
+     */
+    (modelId: string): LLMAdapter;
+}
+/**
+ * Embedding model interface (for future expansion)
+ */
+interface EmbeddingModel {
+    readonly provider: string;
+    readonly modelId: string;
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Base provider configuration
+ */
+interface BaseProviderConfig {
+    /** API key (falls back to environment variable) */
+    apiKey?: string;
+    /** Custom base URL */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom headers to include */
+    headers?: Record<string, string>;
+}
+/**
+ * OpenAI provider configuration
+ */
+interface OpenAIProviderConfig extends BaseProviderConfig {
+    /** OpenAI organization ID */
+    organization?: string;
+    /** OpenAI project ID */
+    project?: string;
+    /** Vision detail level for images */
+    imageDetail?: "auto" | "low" | "high";
+}
+/**
+ * Anthropic provider configuration
+ */
+interface AnthropicProviderConfig extends BaseProviderConfig {
+    /** Extended thinking budget in tokens (minimum 1024) */
+    thinkingBudget?: number;
+    /** Enable prompt caching */
+    cacheControl?: boolean;
+}
+/**
+ * Google provider configuration
+ */
+interface GoogleProviderConfig extends BaseProviderConfig {
+    /** Safety settings */
+    safetySettings?: GoogleSafetySetting[];
+    /** Grounding configuration (for web search) */
+    groundingConfig?: GoogleGroundingConfig;
+}
+/**
+ * Google safety setting
+ */
+interface GoogleSafetySetting {
+    category: "HARM_CATEGORY_HARASSMENT" | "HARM_CATEGORY_HATE_SPEECH" | "HARM_CATEGORY_SEXUALLY_EXPLICIT" | "HARM_CATEGORY_DANGEROUS_CONTENT";
+    threshold: "BLOCK_NONE" | "BLOCK_LOW_AND_ABOVE" | "BLOCK_MEDIUM_AND_ABOVE" | "BLOCK_HIGH_AND_ABOVE";
+}
+/**
+ * Google grounding configuration
+ */
+interface GoogleGroundingConfig {
+    /** Enable Google Search grounding */
+    googleSearchRetrieval?: boolean;
+}
+/**
+ * xAI provider configuration
+ */
+interface XAIProviderConfig extends BaseProviderConfig {
+}
+/**
+ * Azure OpenAI provider configuration
+ */
+interface AzureProviderConfig extends BaseProviderConfig {
+    /** Azure resource name */
+    resourceName: string;
+    /** Deployment name */
+    deploymentName: string;
+    /** API version (default: 2024-02-15-preview) */
+    apiVersion?: string;
+}
+/**
+ * Ollama model-specific options
+ * These map to Ollama's native API options
+ */
+interface OllamaModelOptions {
+    /** Context window size (default varies by model) */
+    num_ctx?: number;
+    /** Max tokens to predict (-1 = infinite, -2 = fill context) */
+    num_predict?: number;
+    /** Mirostat sampling (0 = disabled, 1 = Mirostat, 2 = Mirostat 2.0) */
+    mirostat?: 0 | 1 | 2;
+    /** Mirostat learning rate (default: 0.1) */
+    mirostat_eta?: number;
+    /** Mirostat target entropy (default: 5.0) */
+    mirostat_tau?: number;
+    /** Repeat penalty (default: 1.1) */
+    repeat_penalty?: number;
+    /** Random seed for reproducibility (-1 = random) */
+    seed?: number;
+    /** Top-k sampling (default: 40) */
+    top_k?: number;
+    /** Top-p (nucleus) sampling (default: 0.9) */
+    top_p?: number;
+    /** Min-p sampling (default: 0.0) */
+    min_p?: number;
+    /** Stop sequences */
+    stop?: string[];
+    /** Temperature override (also available in config) */
+    temperature?: number;
+}
+/**
+ * Ollama provider configuration
+ */
+interface OllamaProviderConfig extends BaseProviderConfig {
+    /** Default Ollama-specific model options */
+    options?: OllamaModelOptions;
+}
+
+export type { AIProvider as A, BaseProviderConfig as B, GoogleProviderConfig as G, OpenAIProviderConfig as O, ProviderCapabilities as P, XAIProviderConfig as X, AnthropicProviderConfig as a, AzureProviderConfig as b, OllamaProviderConfig as c, OllamaModelOptions as d, ProviderFormatter as e, AnthropicTool as f, AnthropicToolUse as g, AnthropicToolResult as h, OpenAITool as i, OpenAIToolCall as j, OpenAIToolResult as k, GeminiFunctionDeclaration as l, GeminiFunctionCall as m, GeminiFunctionResponse as n };