@yourgpt/llm-sdk 2.5.0 → 2.5.1-beta.0

package/dist/{base-iGi9Va6Z.d.ts → types-BkQCSiIt.d.ts}

@@ -1,4 +1,4 @@
-import { t as TokenUsage } from './types-CR8mi9I0.js';
+import { z } from 'zod';
 
 /**
  * Stream event types for llm-sdk
@@ -228,17 +228,35 @@ interface DoneEvent extends BaseEvent {
  * Union of all stream events
  */
 type StreamEvent = MessageStartEvent | MessageDeltaEvent | MessageEndEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent | ActionStartEvent | ActionArgsEvent | ActionEndEvent | ToolCallsEvent | ToolResultEvent | CitationEvent | LoopIterationEvent | LoopCompleteEvent | ErrorEvent | ThreadCreatedEvent | DoneEvent;
+/**
+ * Structured-output / JSON-mode request format.
+ *
+ * Uses OpenAI's `response_format` shape as the unified surface; each adapter
+ * translates to its provider's native field (Anthropic `output_config`,
+ * Gemini `responseJsonSchema`, Ollama `format`, etc.).
+ */
+type ResponseFormat = {
+    type: "json_object";
+} | {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+};
 /**
  * LLM configuration
  */
 interface LLMConfig {
     temperature?: number;
     maxTokens?: number;
+    responseFormat?: ResponseFormat;
 }
 /**
  * Tool call format (OpenAI style)
  */
-interface ToolCall {
+interface ToolCall$1 {
     id: string;
     type: "function";
     function: {
@@ -279,7 +297,7 @@ interface Message {
     thread_id?: string;
     role: MessageRole;
     content: string | null;
-    tool_calls?: ToolCall[];
+    tool_calls?: ToolCall$1[];
     tool_call_id?: string;
     metadata?: MessageMetadata;
     created_at?: Date;
@@ -329,7 +347,7 @@ interface ToolResponse<T = unknown> {
 /**
  * Tool context passed to handlers
  */
-interface ToolContext {
+interface ToolContext$1 {
     userId?: string;
     threadId?: string;
     [key: string]: unknown;
@@ -370,7 +388,7 @@ interface ToolDefinition<TParams = Record<string, unknown>> {
     group?: string;
     title?: string | ((args: TParams) => string);
     inputSchema?: ToolInputSchema;
-    handler?: (params: TParams, context?: ToolContext) => unknown | Promise<unknown>;
+    handler?: (params: TParams, context?: ToolContext$1) => unknown | Promise<unknown>;
     render?: (props: unknown) => unknown;
     available?: boolean;
     /**
@@ -531,258 +549,415 @@ interface KnowledgeBaseConfig {
 }
 
 /**
- * Request-level LLM configuration overrides
- */
-interface RequestLLMConfig {
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-}
-/**
- * Chat completion request
+ * A language model instance that can generate text.
+ * This is what provider functions like `openai('gpt-4o')` return.
  */
-interface ChatCompletionRequest {
-    /** Conversation messages */
-    messages: Message[];
+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;
     /**
-     * Raw provider-formatted messages (for agent loop with tool calls)
-     * When provided, these are used instead of converting from Message[]
-     * This allows passing messages with tool_calls and tool role
+     * Generate a complete response (non-streaming)
+     * Used internally by generateText()
      */
-    rawMessages?: Array<Record<string, unknown>>;
-    /** Available actions/tools */
-    actions?: ActionDefinition[];
-    /** Full tool definitions for provider-native tool search / deferred loading paths. */
-    toolDefinitions?: ToolDefinition[];
-    /** System prompt */
-    systemPrompt?: string;
-    /** LLM configuration overrides */
-    config?: RequestLLMConfig;
-    /** Abort signal for cancellation */
-    signal?: AbortSignal;
+    doGenerate(params: DoGenerateParams): Promise<DoGenerateResult>;
     /**
-     * Enable native web search for the provider.
-     * When true or configured, the provider's native search is enabled.
+     * Stream a response
+     * Used internally by streamText()
      */
-    webSearch?: boolean | WebSearchConfig;
-    /** Optional provider-specific tool policy hints derived from runtime selection. */
-    providerToolOptions?: ProviderToolRuntimeOptions;
-    /** Enable adapter-level provider payload logging. */
-    debug?: boolean;
+    doStream(params: DoGenerateParams): AsyncGenerator<StreamChunk>;
 }
 /**
- * Non-streaming completion result
+ * 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
  */
-interface CompletionResult {
-    /** Text content */
+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;
-    /** Tool calls */
-    toolCalls: Array<{
-        id: string;
-        name: string;
-        args: Record<string, unknown>;
-        /** Provider-specific metadata (e.g. Gemini 3 thought_signature in extra_content.google) */
-        extra_content?: Record<string, unknown>;
-    }>;
-    /** Thinking content (if extended thinking enabled) */
-    thinking?: string;
-    /** Token usage for billing/tracking */
-    usage?: TokenUsage;
-    /** Raw provider response for debugging */
-    rawResponse: Record<string, unknown>;
 }
 /**
- * Base LLM adapter interface
+ * Content parts for multimodal user messages
  */
-interface LLMAdapter {
-    /** Provider name */
-    readonly provider: string;
-    /** Model name */
-    readonly model: string;
-    /**
-     * Stream a chat completion
-     */
-    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+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>;
     /**
-     * Non-streaming chat completion (for debugging/comparison)
+     * 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
      */
-    complete?(request: ChatCompletionRequest): Promise<CompletionResult>;
+    hidden?: boolean;
 }
 /**
- * Adapter factory function type
+ * Context passed to tool execute function
  */
-type AdapterFactory = (config: LLMConfig) => LLMAdapter;
+interface ToolContext {
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Unique tool call ID */
+    toolCallId: string;
+    /** Optional: messages in conversation */
+    messages?: CoreMessage[];
+}
 /**
- * Convert messages to provider format (simple text only)
+ * Tool call from LLM response
  */
-declare function formatMessages(messages: Message[], systemPrompt?: string): Array<{
-    role: string;
-    content: string;
-}>;
+interface ToolCall {
+    /** Unique ID for this tool call */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Parsed arguments */
+    args: Record<string, unknown>;
+}
 /**
- * Convert actions to OpenAI tool format
+ * Tool execution result
  */
-declare function formatTools(actions: ActionDefinition[]): Array<{
-    type: "function";
-    function: {
-        name: string;
-        description: string;
-        parameters: object;
-    };
-}>;
+interface ToolResult {
+    /** Tool call ID this result corresponds to */
+    toolCallId: string;
+    /** Result data (will be JSON stringified for LLM) */
+    result: unknown;
+}
 /**
- * Content block types for multimodal messages
+ * Parameters for model.doGenerate() and model.doStream()
  */
-type AnthropicContentBlock = {
-    type: "text";
-    text: string;
-} | {
-    type: "image";
-    source: {
-        type: "base64";
-        media_type: string;
-        data: string;
-    } | {
-        type: "url";
-        url: string;
-    };
-} | {
-    type: "document";
-    source: {
-        type: "base64";
-        media_type: string;
-        data: string;
-    } | {
-        type: "url";
-        url: string;
-    };
-};
-type OpenAIContentBlock = {
-    type: "text";
-    text: string;
-} | {
-    type: "image_url";
-    image_url: {
-        url: string;
-        detail?: "low" | "high" | "auto";
-    };
-};
+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;
+    /** Structured-output / JSON-mode request format (provider-translated) */
+    responseFormat?: ResponseFormat;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
 /**
- * Check if a message has image attachments
- * Supports both new format (metadata.attachments) and legacy (attachments)
+ * Result from model.doGenerate()
  */
-declare function hasImageAttachments(message: Message): boolean;
+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;
+}
 /**
- * Check if a message has media attachments (images or PDFs)
+ * Finish reason for generation
  */
-declare function hasMediaAttachments(message: Message): boolean;
+type FinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown";
 /**
- * Convert MessageAttachment to Anthropic image content block
- *
- * Anthropic format:
- * {
- *   type: "image",
- *   source: {
- *     type: "base64",
- *     media_type: "image/png",
- *     data: "base64data..."
- *   }
- * }
- */
-declare function attachmentToAnthropicImage(attachment: MessageAttachment): AnthropicContentBlock | null;
-/**
- * Convert MessageAttachment to OpenAI image_url content block
- *
- * OpenAI format:
- * {
- *   type: "image_url",
- *   image_url: {
- *     url: "data:image/png;base64,..."
- *   }
- * }
+ * Token usage statistics
  */
-declare function attachmentToOpenAIImage(attachment: MessageAttachment): OpenAIContentBlock | null;
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
 /**
- * Convert MessageAttachment (PDF) to Anthropic document content block
- *
- * Anthropic format:
- * {
- *   type: "document",
- *   source: {
- *     type: "base64",
- *     media_type: "application/pdf",
- *     data: "base64data..."
- *   }
- * }
+ * Stream chunk from model.doStream()
  */
-declare function attachmentToAnthropicDocument(attachment: MessageAttachment): AnthropicContentBlock | null;
+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;
+}
 /**
- * Convert a Message to Anthropic multimodal content blocks
+ * Parameters for generateText()
  */
-declare function messageToAnthropicContent(message: Message): string | AnthropicContentBlock[];
+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;
+    /** Structured-output / JSON-mode request format */
+    responseFormat?: ResponseFormat;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
 /**
- * Convert a Message to OpenAI multimodal content blocks
+ * Result from generateText()
  */
-declare function messageToOpenAIContent(message: Message): string | OpenAIContentBlock[];
+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[];
+    };
+}
 /**
- * Anthropic content block types (extended for tools)
+ * A single step in the generation process
  */
-type AnthropicToolUseBlock = {
-    type: "tool_use";
-    id: string;
-    name: string;
-    input: Record<string, unknown>;
-};
-type AnthropicToolResultBlock = {
-    type: "tool_result";
-    tool_use_id: string;
-    content: string;
+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;
 };
-type AnthropicMessageContent = string | Array<AnthropicContentBlock | AnthropicToolUseBlock | AnthropicToolResultBlock>;
 /**
- * Format messages for Anthropic with full tool support
- * Handles: text, images, tool_use, and tool_result
- *
- * Key differences from OpenAI:
- * - tool_calls become tool_use blocks in assistant content
- * - tool results become tool_result blocks in user content
- */
-declare function formatMessagesForAnthropic(messages: Message[], systemPrompt?: string): {
-    system: string;
-    messages: Array<{
-        role: "user" | "assistant";
-        content: AnthropicMessageContent;
-    }>;
-};
+ * Options for Response helpers
+ */
+interface ResponseOptions {
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Response status (default: 200) */
+    status?: number;
+}
 /**
- * OpenAI message format with tool support
+ * Message format for storage adapters.
+ * Intentionally simpler than LLM-specific formats — adapters convert as needed.
  */
-type OpenAIMessage = {
-    role: "system";
+interface StorageMessage {
+    role: "user" | "assistant" | "system" | "tool";
     content: string;
-} | {
-    role: "user";
-    content: string | OpenAIContentBlock[];
-} | {
-    role: "assistant";
-    content: string | null;
-    tool_calls?: Array<{
+    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;
-        type: "function";
-        function: {
-            name: string;
-            arguments: string;
-        };
     }>;
-} | {
-    role: "tool";
-    content: string;
-    tool_call_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;
+    }>;
+}
 /**
- * Format messages for OpenAI with full tool support
- * Handles: text, images, tool_calls, and tool results
+ * File data for upload via StorageAdapter.uploadFile()
  */
-declare function formatMessagesForOpenAI(messages: Message[], systemPrompt?: string): OpenAIMessage[];
+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 ActionDefinition as A, type AnthropicContentBlock as B, type ChatCompletionRequest as C, type DoneEventMessage as D, type OpenAIContentBlock as E, type KnowledgeBaseConfig as K, type LLMAdapter as L, type Message as M, type OpenAIToolSelectionHints as O, type ProviderToolRuntimeOptions as P, type StreamEvent as S, type ToolDefinition as T, type UnifiedToolCall as U, type WebSearchConfig as W, type ToolProfile as a, type ToolCallInfo as b, type TokenUsageRaw as c, type ToolResponse as d, type AdapterFactory as e, type LLMConfig as f, type ToolLocation as g, type UnifiedToolResult as h, type ToolExecution as i, type AnthropicToolSelectionHints as j, type ToolNativeProviderHints as k, type OpenAIProviderToolOptions as l, type AnthropicProviderToolOptions as m, type Citation as n, type CompletionResult as o, formatMessages as p, formatTools as q, formatMessagesForAnthropic as r, formatMessagesForOpenAI as s, messageToAnthropicContent as t, messageToOpenAIContent as u, hasImageAttachments as v, hasMediaAttachments as w, attachmentToAnthropicImage as x, attachmentToAnthropicDocument as y, attachmentToOpenAIImage as z };
+export { type ToolExecution as $, type ActionDefinition as A, type ToolResultChunk as B, type CoreMessage as C, type DoneEventMessage as D, type FinishChunk as E, type FilePart as F, type GenerateTextParams as G, type ErrorChunk as H, type ImagePart as I, type TokenUsage as J, type KnowledgeBaseConfig as K, type LanguageModel as L, type Message as M, type FinishReason as N, type ResponseOptions as O, type ProviderToolRuntimeOptions as P, type StorageFile as Q, type ResponseFormat as R, type StreamTextParams as S, type ToolContext as T, type UserMessage as U, DEFAULT_CAPABILITIES as V, type WebSearchConfig as W, type LLMConfig as X, type ToolLocation as Y, type UnifiedToolCall as Z, type UnifiedToolResult as _, type GenerateTextResult as a, type OpenAIToolSelectionHints as a0, type AnthropicToolSelectionHints as a1, type ToolNativeProviderHints as a2, type OpenAIProviderToolOptions as a3, type AnthropicProviderToolOptions as a4, type Citation as a5, type MessageAttachment as a6, type StreamTextResult as b, type Tool as c, type ToolDefinition as d, type ToolProfile as e, type StorageAdapter as f, type StreamEvent as g, type ToolCallInfo as h, type TokenUsageRaw as i, type ToolResponse as j, type StorageMessage as k, type ModelCapabilities as l, type DoGenerateParams as m, type DoGenerateResult as n, type SystemMessage as o, type AssistantMessage as p, type ToolMessage as q, type UserContentPart as r, type TextPart as s, type ToolCall as t, type ToolResult as u, type GenerateStep as v, type StreamPart as w, type StreamChunk as x, type TextDeltaChunk as y, type ToolCallChunk as z };