@yourgpt/llm-sdk 2.1.4-alpha.1 → 2.1.4-alpha.3

package/dist/types-CNL8ZRne.d.ts

@@ -0,0 +1,212 @@
+import { L as LLMAdapter } from './base-Di31iy_8.js';
+
+/**
+ * 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-CR8mi9I0.d.mts

@@ -0,0 +1,417 @@
+import { z } from 'zod';
+
+/**
+ * Core Types for @yourgpt/llm-sdk
+ *
+ * Modern, instance-based types following Vercel AI SDK patterns.
+ */
+
+/**
+ * A language model instance that can generate text.
+ * This is what provider functions like `openai('gpt-4o')` return.
+ */
+interface LanguageModel {
+    /** Provider identifier (e.g., 'openai', 'anthropic') */
+    readonly provider: string;
+    /** Model identifier (e.g., 'gpt-4o', 'claude-3-5-sonnet') */
+    readonly modelId: string;
+    /** Model capabilities for feature detection */
+    readonly capabilities: ModelCapabilities;
+    /**
+     * Generate a complete response (non-streaming)
+     * Used internally by generateText()
+     */
+    doGenerate(params: DoGenerateParams): Promise<DoGenerateResult>;
+    /**
+     * Stream a response
+     * Used internally by streamText()
+     */
+    doStream(params: DoGenerateParams): AsyncGenerator<StreamChunk>;
+}
+/**
+ * Model capabilities for UI feature flags
+ */
+interface ModelCapabilities {
+    /** Supports image inputs */
+    supportsVision: boolean;
+    /** Supports tool/function calling */
+    supportsTools: boolean;
+    /** Supports streaming responses */
+    supportsStreaming: boolean;
+    /** Supports JSON mode / structured output */
+    supportsJsonMode: boolean;
+    /** Supports extended thinking (Claude) */
+    supportsThinking: boolean;
+    /** Supports PDF document inputs */
+    supportsPDF: boolean;
+    /** Maximum context tokens */
+    maxTokens: number;
+    /** Supported image MIME types */
+    supportedImageTypes: string[];
+}
+/**
+ * Default capabilities for unknown models
+ */
+declare const DEFAULT_CAPABILITIES: ModelCapabilities;
+/**
+ * Core message types for LLM conversations
+ */
+type CoreMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+interface SystemMessage {
+    role: "system";
+    content: string;
+}
+interface UserMessage {
+    role: "user";
+    content: string | UserContentPart[];
+}
+interface AssistantMessage {
+    role: "assistant";
+    content: string | null;
+    toolCalls?: ToolCall[];
+}
+interface ToolMessage {
+    role: "tool";
+    toolCallId: string;
+    content: string;
+}
+/**
+ * Content parts for multimodal user messages
+ */
+type UserContentPart = TextPart | ImagePart | FilePart;
+interface TextPart {
+    type: "text";
+    text: string;
+}
+interface ImagePart {
+    type: "image";
+    /** Base64 data or URL */
+    image: string | Uint8Array;
+    /** MIME type (e.g., 'image/png') */
+    mimeType?: string;
+}
+interface FilePart {
+    type: "file";
+    /** Base64 data or URL */
+    data: string;
+    /** MIME type (e.g., 'application/pdf') */
+    mimeType: string;
+}
+/**
+ * Tool definition with Zod schema support
+ */
+interface Tool<TParams = unknown, TResult = unknown> {
+    /** Tool description for the LLM */
+    description: string;
+    /** Zod schema for parameters */
+    parameters: z.ZodType<TParams>;
+    /** Execute function */
+    execute: (params: TParams, context: ToolContext) => Promise<TResult>;
+    /**
+     * Hide this tool's execution from the chat UI.
+     * When true, tool calls and results won't be displayed to the user,
+     * but the tool will still execute normally.
+     * @default false
+     */
+    hidden?: boolean;
+}
+/**
+ * Context passed to tool execute function
+ */
+interface ToolContext {
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Unique tool call ID */
+    toolCallId: string;
+    /** Optional: messages in conversation */
+    messages?: CoreMessage[];
+}
+/**
+ * Tool call from LLM response
+ */
+interface ToolCall {
+    /** Unique ID for this tool call */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Parsed arguments */
+    args: Record<string, unknown>;
+}
+/**
+ * Tool execution result
+ */
+interface ToolResult {
+    /** Tool call ID this result corresponds to */
+    toolCallId: string;
+    /** Result data (will be JSON stringified for LLM) */
+    result: unknown;
+}
+/**
+ * Parameters for model.doGenerate() and model.doStream()
+ */
+interface DoGenerateParams {
+    /** Messages to send to LLM */
+    messages: CoreMessage[];
+    /** Tools available to the LLM (already formatted for provider) */
+    tools?: unknown[];
+    /** Temperature (0-2) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Result from model.doGenerate()
+ */
+interface DoGenerateResult {
+    /** Generated text content */
+    text: string;
+    /** Tool calls requested by the LLM */
+    toolCalls: ToolCall[];
+    /** Why generation stopped */
+    finishReason: FinishReason;
+    /** Token usage */
+    usage: TokenUsage;
+    /** Raw provider response (for debugging) */
+    rawResponse?: unknown;
+}
+/**
+ * Finish reason for generation
+ */
+type FinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown";
+/**
+ * Token usage statistics
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Stream chunk from model.doStream()
+ */
+type StreamChunk = TextDeltaChunk | ToolCallChunk | ToolResultChunk | FinishChunk | ErrorChunk;
+interface TextDeltaChunk {
+    type: "text-delta";
+    text: string;
+}
+interface ToolCallChunk {
+    type: "tool-call";
+    toolCall: ToolCall;
+}
+interface ToolResultChunk {
+    type: "tool-result";
+    toolCallId: string;
+    result: unknown;
+}
+interface FinishChunk {
+    type: "finish";
+    finishReason: FinishReason;
+    usage?: TokenUsage;
+}
+interface ErrorChunk {
+    type: "error";
+    error: Error;
+}
+/**
+ * Parameters for generateText()
+ */
+interface GenerateTextParams {
+    /** Language model to use */
+    model: LanguageModel;
+    /** Simple prompt (converted to user message) */
+    prompt?: string;
+    /** System prompt */
+    system?: string;
+    /** Full message history */
+    messages?: CoreMessage[];
+    /** Tools available to the LLM */
+    tools?: Record<string, Tool>;
+    /** Maximum agentic steps (tool call loops) */
+    maxSteps?: number;
+    /** Temperature (0-2) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Result from generateText()
+ */
+interface GenerateTextResult {
+    /** Final text output */
+    text: string;
+    /** Token usage */
+    usage: TokenUsage;
+    /** Why generation stopped */
+    finishReason: FinishReason;
+    /** All steps taken (for agentic workflows) */
+    steps: GenerateStep[];
+    /** All tool calls made across all steps */
+    toolCalls: ToolCall[];
+    /** All tool results across all steps */
+    toolResults: ToolResult[];
+    /** Final message list including tool interactions */
+    response: {
+        messages: CoreMessage[];
+    };
+}
+/**
+ * A single step in the generation process
+ */
+interface GenerateStep {
+    /** Text generated in this step */
+    text: string;
+    /** Tool calls made in this step */
+    toolCalls: ToolCall[];
+    /** Tool results from this step */
+    toolResults: ToolResult[];
+    /** Finish reason for this step */
+    finishReason: FinishReason;
+    /** Token usage for this step */
+    usage: TokenUsage;
+}
+/**
+ * Parameters for streamText() - same as generateText
+ */
+type StreamTextParams = GenerateTextParams;
+/**
+ * Result from streamText()
+ */
+interface StreamTextResult {
+    /** Async iterable of text chunks only */
+    textStream: AsyncIterable<string>;
+    /** Async iterable of all stream parts */
+    fullStream: AsyncIterable<StreamPart>;
+    /** Promise that resolves to full text when complete */
+    readonly text: Promise<string>;
+    /** Promise that resolves to usage when complete */
+    readonly usage: Promise<TokenUsage>;
+    /** Promise that resolves to finish reason when complete */
+    readonly finishReason: Promise<FinishReason>;
+    /** Convert to plain text streaming Response */
+    toTextStreamResponse(options?: ResponseOptions): Response;
+    /** Convert to data stream Response (SSE with tool calls) */
+    toDataStreamResponse(options?: ResponseOptions): Response;
+}
+/**
+ * Stream part for fullStream
+ */
+type StreamPart = {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "tool-call-start";
+    toolCallId: string;
+    toolName: string;
+} | {
+    type: "tool-call-delta";
+    toolCallId: string;
+    argsText: string;
+} | {
+    type: "tool-call-complete";
+    toolCall: ToolCall;
+} | {
+    type: "tool-result";
+    toolCallId: string;
+    result: unknown;
+} | {
+    type: "step-start";
+    step: number;
+} | {
+    type: "step-finish";
+    step: number;
+    finishReason: FinishReason;
+} | {
+    type: "finish";
+    finishReason: FinishReason;
+    usage: TokenUsage;
+} | {
+    type: "error";
+    error: Error;
+};
+/**
+ * Options for Response helpers
+ */
+interface ResponseOptions {
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Response status (default: 200) */
+    status?: number;
+}
+/**
+ * Message format for storage adapters.
+ * Intentionally simpler than LLM-specific formats — adapters convert as needed.
+ */
+interface StorageMessage {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    toolCalls?: unknown[];
+    toolCallId?: string;
+    /** Content type for the message — determines how it's stored in the backend */
+    contentType?: "text" | "image" | "file";
+    /** URL for image/file attachments */
+    url?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Generic storage adapter interface for session + message persistence.
+ *
+ * `createYourGPT()` is the default implementation for YourGPT platform.
+ * Third-party developers can implement this interface for custom backends.
+ *
+ * @example
+ * ```ts
+ * import { createRuntime } from '@yourgpt/llm-sdk'
+ * import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt'
+ *
+ * const runtime = createRuntime({
+ *   provider: anthropic,
+ *   model: 'claude-haiku-4-5',
+ *   storage: createYourGPT({ apiKey, widgetUid }),
+ * })
+ * // runtime.chat() and runtime.stream() now auto-persist messages
+ * ```
+ */
+interface StorageAdapter {
+    /** Create a new session. Returns session ID to use as threadId. */
+    createSession(data?: {
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Append messages to a session (called sequentially — input before output). */
+    saveMessages(sessionId: string, messages: StorageMessage[]): Promise<void>;
+    /** List sessions (optional — used for thread picker sync in future). */
+    getSessions?(): Promise<{
+        id: string;
+        title?: string;
+        updatedAt?: Date;
+    }[]>;
+    /** Get messages for a session (optional — used for thread restore in future). */
+    getMessages?(sessionId: string): Promise<StorageMessage[]>;
+    /**
+     * Upload a file to storage. Returns a URL the LLM can reference.
+     * When present, the server exposes a /upload endpoint and the client
+     * uses it instead of embedding base64 in the message body.
+     */
+    uploadFile?(file: StorageFile): Promise<{
+        url: string;
+    }>;
+}
+/**
+ * File data for upload via StorageAdapter.uploadFile()
+ */
+interface StorageFile {
+    /** Base64-encoded file data (with or without data URI prefix) */
+    data: string;
+    /** MIME type (e.g., "image/png", "application/pdf") */
+    mimeType: string;
+    /** Original filename */
+    filename?: string;
+}
+
+export { type AssistantMessage as A, type CoreMessage as C, type DoGenerateParams as D, type ErrorChunk as E, type FilePart as F, type GenerateTextParams as G, type ImagePart as I, type LanguageModel as L, type ModelCapabilities as M, type ResponseOptions as R, type StreamTextParams as S, type ToolContext as T, type UserMessage as U, type GenerateTextResult as a, type StreamTextResult as b, type Tool as c, type StorageAdapter as d, type StorageMessage as e, type DoGenerateResult as f, type SystemMessage as g, type ToolMessage as h, type UserContentPart as i, type TextPart as j, type ToolCall as k, type ToolResult as l, type GenerateStep as m, type StreamPart as n, type StreamChunk as o, type TextDeltaChunk as p, type ToolCallChunk as q, type ToolResultChunk as r, type FinishChunk as s, type TokenUsage as t, type FinishReason as u, type StorageFile as v, DEFAULT_CAPABILITIES as w };