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

package/dist/base-5n-UuPfS.d.mts

@@ -0,0 +1,768 @@
+import { t as TokenUsage } from './types-CR8mi9I0.mjs';
+
+/**
+ * Stream event types for llm-sdk
+ * These types are used internally by the SDK for streaming responses
+ */
+/**
+ * Stream event types
+ */
+type StreamEventType = "message:start" | "message:delta" | "message:end" | "thinking:start" | "thinking:delta" | "thinking:end" | "action:start" | "action:args" | "action:end" | "tool_calls" | "tool:result" | "citation" | "loop:iteration" | "loop:complete" | "error" | "done";
+/**
+ * Base event interface
+ */
+interface BaseEvent {
+    type: StreamEventType;
+}
+/**
+ * Message started streaming
+ */
+interface MessageStartEvent extends BaseEvent {
+    type: "message:start";
+    id: string;
+}
+/**
+ * Message content delta (incremental update)
+ */
+interface MessageDeltaEvent extends BaseEvent {
+    type: "message:delta";
+    content: string;
+}
+/**
+ * Message finished streaming
+ */
+interface MessageEndEvent extends BaseEvent {
+    type: "message:end";
+}
+/**
+ * Thinking/reasoning started (for models like Claude, DeepSeek)
+ */
+interface ThinkingStartEvent extends BaseEvent {
+    type: "thinking:start";
+}
+/**
+ * Thinking content delta
+ */
+interface ThinkingDeltaEvent extends BaseEvent {
+    type: "thinking:delta";
+    content: string;
+}
+/**
+ * Thinking finished
+ */
+interface ThinkingEndEvent extends BaseEvent {
+    type: "thinking:end";
+}
+/**
+ * Action/tool execution started
+ */
+interface ActionStartEvent extends BaseEvent {
+    type: "action:start";
+    id: string;
+    name: string;
+    /** Whether this tool should be hidden from UI */
+    hidden?: boolean;
+}
+/**
+ * Action arguments (streaming)
+ */
+interface ActionArgsEvent extends BaseEvent {
+    type: "action:args";
+    id: string;
+    args: string;
+}
+/**
+ * Action execution completed
+ */
+interface ActionEndEvent extends BaseEvent {
+    type: "action:end";
+    id: string;
+    name?: string;
+    result?: unknown;
+    error?: string;
+}
+/**
+ * Error event
+ */
+interface ErrorEvent extends BaseEvent {
+    type: "error";
+    message: string;
+    code?: string;
+}
+/**
+ * Tool call information
+ */
+interface ToolCallInfo {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    /** Whether this tool should be hidden from UI */
+    hidden?: boolean;
+}
+/**
+ * Assistant message with tool calls
+ */
+interface AssistantToolMessage {
+    role: "assistant";
+    content: string | null;
+    tool_calls: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+/**
+ * Tool calls event - client should execute and send results
+ */
+interface ToolCallsEvent extends BaseEvent {
+    type: "tool_calls";
+    toolCalls: ToolCallInfo[];
+    assistantMessage: AssistantToolMessage;
+}
+/**
+ * Tool result event
+ */
+interface ToolResultEvent extends BaseEvent {
+    type: "tool:result";
+    id: string;
+    name: string;
+    result: ToolResponse;
+}
+/**
+ * Loop iteration event
+ */
+interface LoopIterationEvent extends BaseEvent {
+    type: "loop:iteration";
+    iteration: number;
+    maxIterations: number;
+}
+/**
+ * Loop complete event
+ */
+interface LoopCompleteEvent extends BaseEvent {
+    type: "loop:complete";
+    iterations: number;
+    aborted?: boolean;
+    maxIterationsReached?: boolean;
+}
+/**
+ * Citation from web search (unified format for all providers)
+ */
+interface Citation {
+    /** Unique citation index (1-based) */
+    index: number;
+    /** Source URL */
+    url: string;
+    /** Page title */
+    title: string;
+    /** Cited text snippet (optional) */
+    citedText?: string;
+    /** Source domain (extracted from URL) */
+    domain?: string;
+    /** Favicon URL (generated from domain) */
+    favicon?: string;
+}
+/**
+ * Citation event - web search returned citations
+ */
+interface CitationEvent extends BaseEvent {
+    type: "citation";
+    citations: Citation[];
+}
+/**
+ * Message format for done event (API format with snake_case)
+ */
+interface DoneEventMessage {
+    role: "assistant" | "tool";
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+}
+/**
+ * Token usage (snake_case for API compatibility)
+ */
+interface TokenUsageRaw {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+}
+/**
+ * Stream completed
+ */
+interface DoneEvent extends BaseEvent {
+    type: "done";
+    requiresAction?: boolean;
+    messages?: DoneEventMessage[];
+    /** Token usage (server-side only, stripped before sending to client) */
+    usage?: TokenUsageRaw;
+    /** Session ID — present when storage adapter created a session for this request */
+    threadId?: string;
+}
+/**
+ * Union of all stream events
+ */
+type StreamEvent = MessageStartEvent | MessageDeltaEvent | MessageEndEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent | ActionStartEvent | ActionArgsEvent | ActionEndEvent | ToolCallsEvent | ToolResultEvent | CitationEvent | LoopIterationEvent | LoopCompleteEvent | ErrorEvent | DoneEvent;
+/**
+ * LLM configuration
+ */
+interface LLMConfig {
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Tool call format (OpenAI style)
+ */
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Message role
+ */
+type MessageRole = "system" | "user" | "assistant" | "tool";
+/**
+ * Message attachment
+ */
+interface MessageAttachment {
+    type: "image" | "file" | "audio" | "video";
+    data?: string;
+    url?: string;
+    mimeType: string;
+    filename?: string;
+}
+/**
+ * Message metadata
+ */
+interface MessageMetadata {
+    thinking?: string;
+    attachments?: MessageAttachment[];
+    toolName?: string;
+    [key: string]: unknown;
+}
+/**
+ * Message type (simplified for llm-sdk)
+ */
+interface Message {
+    id: string;
+    thread_id?: string;
+    role: MessageRole;
+    content: string | null;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    metadata?: MessageMetadata;
+    created_at?: Date;
+}
+/**
+ * Action parameter definition
+ */
+interface ActionParameter {
+    type: string;
+    description?: string;
+    required?: boolean;
+    enum?: string[];
+    items?: ActionParameter;
+    properties?: Record<string, ActionParameter>;
+}
+/**
+ * Action definition for tool calling
+ */
+interface ActionDefinition<TParams = Record<string, unknown>> {
+    name: string;
+    description: string;
+    parameters?: Record<string, ActionParameter>;
+    handler: (params: TParams) => unknown | Promise<unknown>;
+}
+/**
+ * Tool location (server or client)
+ */
+type ToolLocation = "server" | "client";
+/**
+ * Tool execution status
+ */
+type ToolExecutionStatus = "pending" | "executing" | "completed" | "error";
+/**
+ * Tool response
+ */
+interface ToolResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    /** Internal: AI response mode override */
+    _aiResponseMode?: AIResponseMode;
+    /** Internal: AI content for multimodal response (images, etc.) */
+    _aiContent?: AIContent[];
+    /** Internal: AI context string override */
+    _aiContext?: string;
+}
+/**
+ * Tool context passed to handlers
+ */
+interface ToolContext {
+    userId?: string;
+    threadId?: string;
+    [key: string]: unknown;
+}
+/**
+ * AI response mode for tool results
+ */
+type AIResponseMode = "none" | "brief" | "full";
+/**
+ * AI content structure
+ */
+interface AIContent {
+    type?: "text" | "image";
+    text?: string;
+    mediaType?: string;
+    data?: string;
+    summary?: string;
+    details?: string;
+}
+/**
+ * JSON Schema for tool input
+ */
+interface ToolInputSchema {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+}
+/**
+ * Tool definition
+ */
+interface ToolDefinition<TParams = Record<string, unknown>> {
+    name: string;
+    description: string;
+    location: ToolLocation;
+    /** Optional logical category for tool search and selective loading. */
+    category?: string;
+    /** Optional group label for related tools. */
+    group?: string;
+    title?: string | ((args: TParams) => string);
+    inputSchema?: ToolInputSchema;
+    handler?: (params: TParams, context?: ToolContext) => unknown | Promise<unknown>;
+    render?: (props: unknown) => unknown;
+    available?: boolean;
+    /**
+     * 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;
+    needsApproval?: boolean;
+    approvalMessage?: string | ((params: TParams) => string);
+    /** AI response mode for this tool (none, brief, full) */
+    aiResponseMode?: AIResponseMode;
+    /** AI context string or function to generate context */
+    aiContext?: string | ((result: ToolResponse, args: Record<string, unknown>) => string);
+    /** Hint that this tool should be loaded lazily when dynamic selection is active. */
+    deferLoading?: boolean;
+    /** Named profiles this tool belongs to (for example "coding" or "search"). */
+    profiles?: string[];
+    /** Extra keywords used by lightweight tool search/ranking. */
+    searchKeywords?: string[];
+}
+interface ToolProfile {
+    include?: string[];
+    exclude?: string[];
+}
+interface OpenAIToolSelectionHints {
+    /**
+     * "single" forces the selected tool when exactly one tool remains after selection.
+     * Otherwise the adapter falls back to automatic tool choice.
+     */
+    toolChoice?: "auto" | "required" | "single";
+    /** Set false to disable parallel tool calls on OpenAI-compatible providers. */
+    parallelToolCalls?: boolean;
+}
+interface AnthropicToolSelectionHints {
+    /**
+     * "single" forces the selected tool when exactly one tool remains after selection.
+     * Otherwise the adapter falls back to Anthropic's automatic tool choice.
+     */
+    toolChoice?: "auto" | "any" | "single";
+    /** Disable parallel tool use when supported by the Anthropic API. */
+    disableParallelToolUse?: boolean;
+}
+interface ToolNativeProviderHints {
+    openai?: OpenAIToolSelectionHints;
+    anthropic?: AnthropicToolSelectionHints;
+}
+interface OpenAIProviderToolOptions {
+    toolChoice?: "auto" | "required" | {
+        type: "function";
+        name: string;
+    };
+    parallelToolCalls?: boolean;
+    nativeToolSearch?: {
+        enabled: boolean;
+        useResponsesApi?: boolean;
+    };
+}
+interface AnthropicProviderToolOptions {
+    toolChoice?: "auto" | "any" | {
+        type: "tool";
+        name: string;
+    };
+    disableParallelToolUse?: boolean;
+    nativeToolSearch?: {
+        enabled: boolean;
+        variant: "bm25" | "regex";
+    };
+}
+interface ProviderToolRuntimeOptions {
+    openai?: OpenAIProviderToolOptions;
+    anthropic?: AnthropicProviderToolOptions;
+}
+/**
+ * Web search configuration for native provider search
+ *
+ * Enables native web search for supported providers:
+ * - Anthropic: Uses Claude's built-in web search tool
+ * - OpenAI: Uses GPT's web search preview
+ * - Google: Uses Gemini's Google Search grounding
+ *
+ * @example
+ * ```typescript
+ * const runtime = createRuntime({
+ *   provider: createAnthropic({ apiKey: '...' }),
+ *   model: 'claude-sonnet-4-20250514',
+ *   webSearch: true, // Enable with defaults
+ * });
+ *
+ * // Or with configuration
+ * const runtime = createRuntime({
+ *   provider: createOpenAI({ apiKey: '...' }),
+ *   model: 'gpt-4o',
+ *   webSearch: {
+ *     maxUses: 5,
+ *     allowedDomains: ['docs.anthropic.com', 'openai.com'],
+ *   },
+ * });
+ * ```
+ */
+interface WebSearchConfig {
+    /** Maximum number of search uses per request (default: unlimited) */
+    maxUses?: number;
+    /** Only search these domains (provider-specific support) */
+    allowedDomains?: string[];
+    /** Exclude these domains from search (provider-specific support) */
+    blockedDomains?: string[];
+    /** User location for localized results (Anthropic only) */
+    userLocation?: {
+        type: "approximate";
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+    };
+}
+/**
+ * Unified tool call format
+ */
+interface UnifiedToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Unified tool result format
+ */
+interface UnifiedToolResult {
+    toolCallId: string;
+    content: string;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Tool execution state
+ */
+interface ToolExecution {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    status: ToolExecutionStatus;
+    result?: ToolResponse;
+}
+/**
+ * Knowledge base provider
+ */
+type KnowledgeBaseProvider = "pinecone" | "qdrant" | "weaviate" | "custom";
+/**
+ * Knowledge base configuration
+ */
+interface KnowledgeBaseConfig {
+    id: string;
+    name?: string;
+    provider: KnowledgeBaseProvider;
+    apiKey?: string;
+    index?: string;
+}
+
+/**
+ * Request-level LLM configuration overrides
+ */
+interface RequestLLMConfig {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Chat completion request
+ */
+interface ChatCompletionRequest {
+    /** Conversation messages */
+    messages: Message[];
+    /**
+     * 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
+     */
+    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;
+    /**
+     * Enable native web search for the provider.
+     * When true or configured, the provider's native search is enabled.
+     */
+    webSearch?: boolean | WebSearchConfig;
+    /** Optional provider-specific tool policy hints derived from runtime selection. */
+    providerToolOptions?: ProviderToolRuntimeOptions;
+    /** Enable adapter-level provider payload logging. */
+    debug?: boolean;
+}
+/**
+ * Non-streaming completion result
+ */
+interface CompletionResult {
+    /** Text content */
+    content: string;
+    /** Tool calls */
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        args: 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
+ */
+interface LLMAdapter {
+    /** Provider name */
+    readonly provider: string;
+    /** Model name */
+    readonly model: string;
+    /**
+     * Stream a chat completion
+     */
+    stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming chat completion (for debugging/comparison)
+     */
+    complete?(request: ChatCompletionRequest): Promise<CompletionResult>;
+}
+/**
+ * Adapter factory function type
+ */
+type AdapterFactory = (config: LLMConfig) => LLMAdapter;
+/**
+ * Convert messages to provider format (simple text only)
+ */
+declare function formatMessages(messages: Message[], systemPrompt?: string): Array<{
+    role: string;
+    content: string;
+}>;
+/**
+ * Convert actions to OpenAI tool format
+ */
+declare function formatTools(actions: ActionDefinition[]): Array<{
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: object;
+    };
+}>;
+/**
+ * Content block types for multimodal messages
+ */
+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";
+    };
+};
+/**
+ * Check if a message has image attachments
+ * Supports both new format (metadata.attachments) and legacy (attachments)
+ */
+declare function hasImageAttachments(message: Message): boolean;
+/**
+ * Check if a message has media attachments (images or PDFs)
+ */
+declare function hasMediaAttachments(message: Message): boolean;
+/**
+ * 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,..."
+ *   }
+ * }
+ */
+declare function attachmentToOpenAIImage(attachment: MessageAttachment): OpenAIContentBlock | null;
+/**
+ * Convert MessageAttachment (PDF) to Anthropic document content block
+ *
+ * Anthropic format:
+ * {
+ *   type: "document",
+ *   source: {
+ *     type: "base64",
+ *     media_type: "application/pdf",
+ *     data: "base64data..."
+ *   }
+ * }
+ */
+declare function attachmentToAnthropicDocument(attachment: MessageAttachment): AnthropicContentBlock | null;
+/**
+ * Convert a Message to Anthropic multimodal content blocks
+ */
+declare function messageToAnthropicContent(message: Message): string | AnthropicContentBlock[];
+/**
+ * Convert a Message to OpenAI multimodal content blocks
+ */
+declare function messageToOpenAIContent(message: Message): string | OpenAIContentBlock[];
+/**
+ * Anthropic content block types (extended for tools)
+ */
+type AnthropicToolUseBlock = {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type AnthropicToolResultBlock = {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+};
+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;
+    }>;
+};
+/**
+ * OpenAI message format with tool support
+ */
+type OpenAIMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | OpenAIContentBlock[];
+} | {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+} | {
+    role: "tool";
+    content: string;
+    tool_call_id: string;
+};
+/**
+ * Format messages for OpenAI with full tool support
+ * Handles: text, images, tool_calls, and tool results
+ */
+declare function formatMessagesForOpenAI(messages: Message[], systemPrompt?: string): OpenAIMessage[];
+
+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 };