@providerprotocol/ai 0.0.26 → 0.0.28

package/dist/llm-DgDEy9il.d.ts

@@ -0,0 +1,3118 @@
+/**
+ * @fileoverview Content block types for multimodal messages.
+ *
+ * Defines the various content block types that can be included in
+ * user and assistant messages, supporting text, images, audio, video,
+ * and arbitrary binary data.
+ *
+ * @module types/content
+ */
+/**
+ * Content block type constants.
+ *
+ * Use these constants instead of raw strings for type-safe content handling:
+ *
+ * @example
+ * ```typescript
+ * import { ContentBlockType } from 'upp';
+ *
+ * if (block.type === ContentBlockType.Text) {
+ *   console.log(block.text);
+ * } else if (block.type === ContentBlockType.Image) {
+ *   console.log(block.mimeType);
+ * }
+ * ```
+ */
+declare const ContentBlockType: {
+    /** Text content */
+    readonly Text: "text";
+    /** Reasoning/thinking content from extended thinking models */
+    readonly Reasoning: "reasoning";
+    /** Image content */
+    readonly Image: "image";
+    /** Document content (PDFs, text files) */
+    readonly Document: "document";
+    /** Audio content */
+    readonly Audio: "audio";
+    /** Video content */
+    readonly Video: "video";
+    /** Binary/arbitrary data content */
+    readonly Binary: "binary";
+};
+/**
+ * Content block type discriminator union.
+ *
+ * This type is derived from {@link ContentBlockType} constants.
+ */
+type ContentBlockType = (typeof ContentBlockType)[keyof typeof ContentBlockType];
+/**
+ * Image source type constants.
+ *
+ * @example
+ * ```typescript
+ * import { ImageSourceType } from 'upp';
+ *
+ * if (source.type === ImageSourceType.Base64) {
+ *   // Handle base64 encoded image
+ * } else if (source.type === ImageSourceType.Url) {
+ *   // Handle URL reference
+ * }
+ * ```
+ */
+declare const ImageSourceType: {
+    /** Base64-encoded image data */
+    readonly Base64: "base64";
+    /** URL reference to image */
+    readonly Url: "url";
+    /** Raw bytes image data */
+    readonly Bytes: "bytes";
+};
+/**
+ * Image source type discriminator union.
+ *
+ * This type is derived from {@link ImageSourceType} constants.
+ */
+type ImageSourceType = (typeof ImageSourceType)[keyof typeof ImageSourceType];
+/**
+ * Image source variants for ImageBlock.
+ *
+ * Images can be provided as base64-encoded strings, URLs, or raw bytes.
+ *
+ * @example
+ * ```typescript
+ * // Base64 encoded image
+ * const base64Source: ImageSource = {
+ *   type: 'base64',
+ *   data: 'iVBORw0KGgo...'
+ * };
+ *
+ * // URL reference
+ * const urlSource: ImageSource = {
+ *   type: 'url',
+ *   url: 'https://example.com/image.png'
+ * };
+ *
+ * // Raw bytes
+ * const bytesSource: ImageSource = {
+ *   type: 'bytes',
+ *   data: new Uint8Array([...])
+ * };
+ * ```
+ */
+type ImageSource = {
+    type: 'base64';
+    data: string;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'bytes';
+    data: Uint8Array;
+};
+/**
+ * Document source type constants.
+ *
+ * @example
+ * ```typescript
+ * import { DocumentSourceType } from 'upp';
+ *
+ * if (source.type === DocumentSourceType.Base64) {
+ *   // Handle base64 encoded document (PDF)
+ * } else if (source.type === DocumentSourceType.Url) {
+ *   // Handle URL reference (PDF)
+ * } else if (source.type === DocumentSourceType.Text) {
+ *   // Handle plain text document
+ * }
+ * ```
+ */
+declare const DocumentSourceType: {
+    /** Base64-encoded document data (for PDFs) */
+    readonly Base64: "base64";
+    /** URL reference to document (for PDFs) */
+    readonly Url: "url";
+    /** Plain text document content */
+    readonly Text: "text";
+};
+/**
+ * Document source type discriminator union.
+ *
+ * This type is derived from {@link DocumentSourceType} constants.
+ */
+type DocumentSourceType = (typeof DocumentSourceType)[keyof typeof DocumentSourceType];
+/**
+ * Document source variants for DocumentBlock.
+ *
+ * Documents can be provided as base64-encoded data (PDFs), URLs (PDFs), or plain text.
+ *
+ * @example
+ * ```typescript
+ * // Base64 encoded PDF
+ * const base64Source: DocumentSource = {
+ *   type: 'base64',
+ *   data: 'JVBERi0xLjQK...'
+ * };
+ *
+ * // URL reference to PDF
+ * const urlSource: DocumentSource = {
+ *   type: 'url',
+ *   url: 'https://example.com/document.pdf'
+ * };
+ *
+ * // Plain text document
+ * const textSource: DocumentSource = {
+ *   type: 'text',
+ *   data: 'This is the document content...'
+ * };
+ * ```
+ */
+type DocumentSource = {
+    type: 'base64';
+    data: string;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'text';
+    data: string;
+};
+/**
+ * Text content block.
+ *
+ * The most common content block type, containing plain text content.
+ *
+ * @example
+ * ```typescript
+ * const textBlock: TextBlock = {
+ *   type: 'text',
+ *   text: 'Hello, world!'
+ * };
+ * ```
+ */
+interface TextBlock {
+    /** Discriminator for text blocks */
+    type: 'text';
+    /** The text content */
+    text: string;
+}
+/**
+ * Reasoning content block.
+ *
+ * Contains model reasoning/thinking from extended thinking or chain-of-thought.
+ * This content represents the model's internal reasoning process.
+ *
+ * @example
+ * ```typescript
+ * const reasoningBlock: ReasoningBlock = {
+ *   type: 'reasoning',
+ *   text: 'Let me think about this step by step...'
+ * };
+ * ```
+ */
+interface ReasoningBlock {
+    /** Discriminator for reasoning blocks */
+    type: 'reasoning';
+    /** The reasoning/thinking text */
+    text: string;
+}
+/**
+ * Image content block.
+ *
+ * Contains an image with its source data and metadata.
+ *
+ * @example
+ * ```typescript
+ * const imageBlock: ImageBlock = {
+ *   type: 'image',
+ *   source: { type: 'url', url: 'https://example.com/photo.jpg' },
+ *   mimeType: 'image/jpeg',
+ *   width: 1920,
+ *   height: 1080
+ * };
+ * ```
+ */
+interface ImageBlock {
+    /** Discriminator for image blocks */
+    type: 'image';
+    /** The image data source */
+    source: ImageSource;
+    /** MIME type of the image (e.g., 'image/png', 'image/jpeg') */
+    mimeType: string;
+    /** Image width in pixels */
+    width?: number;
+    /** Image height in pixels */
+    height?: number;
+}
+/**
+ * Document content block.
+ *
+ * Contains a document (PDF or plain text) with its source and metadata.
+ * Supports PDF documents via base64 encoding or URL, and plain text content.
+ *
+ * @example
+ * ```typescript
+ * // PDF document from base64
+ * const pdfBlock: DocumentBlock = {
+ *   type: 'document',
+ *   source: { type: 'base64', data: 'JVBERi0xLjQK...' },
+ *   mimeType: 'application/pdf',
+ *   title: 'Annual Report'
+ * };
+ *
+ * // Plain text document
+ * const textDoc: DocumentBlock = {
+ *   type: 'document',
+ *   source: { type: 'text', data: 'Document contents here...' },
+ *   mimeType: 'text/plain'
+ * };
+ * ```
+ */
+interface DocumentBlock {
+    /** Discriminator for document blocks */
+    type: 'document';
+    /** The document data source */
+    source: DocumentSource;
+    /** MIME type of the document ('application/pdf' or 'text/plain') */
+    mimeType: string;
+    /** Optional document title (used for citations) */
+    title?: string;
+}
+/**
+ * Audio content block.
+ *
+ * Contains audio data with its metadata.
+ *
+ * @example
+ * ```typescript
+ * const audioBlock: AudioBlock = {
+ *   type: 'audio',
+ *   data: audioBytes,
+ *   mimeType: 'audio/mp3',
+ *   duration: 120.5
+ * };
+ * ```
+ */
+interface AudioBlock {
+    /** Discriminator for audio blocks */
+    type: 'audio';
+    /** Raw audio data */
+    data: Uint8Array;
+    /** MIME type of the audio (e.g., 'audio/mp3', 'audio/wav') */
+    mimeType: string;
+    /** Duration in seconds */
+    duration?: number;
+}
+/**
+ * Video content block.
+ *
+ * Contains video data with its metadata.
+ *
+ * @example
+ * ```typescript
+ * const videoBlock: VideoBlock = {
+ *   type: 'video',
+ *   data: videoBytes,
+ *   mimeType: 'video/mp4',
+ *   duration: 30,
+ *   width: 1920,
+ *   height: 1080
+ * };
+ * ```
+ */
+interface VideoBlock {
+    /** Discriminator for video blocks */
+    type: 'video';
+    /** Raw video data */
+    data: Uint8Array;
+    /** MIME type of the video (e.g., 'video/mp4', 'video/webm') */
+    mimeType: string;
+    /** Duration in seconds */
+    duration?: number;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+}
+/**
+ * Binary content block for arbitrary data.
+ *
+ * A generic block type for data that doesn't fit other categories.
+ *
+ * @example
+ * ```typescript
+ * const binaryBlock: BinaryBlock = {
+ *   type: 'binary',
+ *   data: pdfBytes,
+ *   mimeType: 'application/pdf',
+ *   metadata: { filename: 'document.pdf', pages: 10 }
+ * };
+ * ```
+ */
+interface BinaryBlock {
+    /** Discriminator for binary blocks */
+    type: 'binary';
+    /** Raw binary data */
+    data: Uint8Array;
+    /** MIME type of the data */
+    mimeType: string;
+    /** Additional metadata about the binary content */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Union of all content block types.
+ *
+ * Used when a function or property can accept any type of content block.
+ */
+type ContentBlock = TextBlock | ReasoningBlock | ImageBlock | DocumentBlock | AudioBlock | VideoBlock | BinaryBlock;
+/**
+ * Content types allowed in user messages.
+ *
+ * Users can send any type of content block including binary data.
+ */
+type UserContent = TextBlock | ImageBlock | DocumentBlock | AudioBlock | VideoBlock | BinaryBlock;
+/**
+ * Content types allowed in assistant messages.
+ *
+ * Assistants can generate text and media but not arbitrary binary data.
+ */
+type AssistantContent = TextBlock | ReasoningBlock | ImageBlock | AudioBlock | VideoBlock;
+/**
+ * Creates a text content block from a string.
+ *
+ * @param content - The text content
+ * @returns A TextBlock containing the provided text
+ *
+ * @example
+ * ```typescript
+ * const block = text('Hello, world!');
+ * // { type: 'text', text: 'Hello, world!' }
+ * ```
+ */
+declare function text(content: string): TextBlock;
+/**
+ * Creates a reasoning content block from a string.
+ *
+ * @param content - The reasoning/thinking content
+ * @returns A ReasoningBlock containing the provided text
+ *
+ * @example
+ * ```typescript
+ * const block = reasoning('Let me think step by step...');
+ * // { type: 'reasoning', text: 'Let me think step by step...' }
+ * ```
+ */
+declare function reasoning(content: string): ReasoningBlock;
+/**
+ * Type guard for TextBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a TextBlock
+ *
+ * @example
+ * ```typescript
+ * if (isTextBlock(block)) {
+ *   console.log(block.text);
+ * }
+ * ```
+ */
+declare function isTextBlock(block: ContentBlock): block is TextBlock;
+/**
+ * Type guard for ReasoningBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a ReasoningBlock
+ *
+ * @example
+ * ```typescript
+ * if (isReasoningBlock(block)) {
+ *   console.log(block.text);
+ * }
+ * ```
+ */
+declare function isReasoningBlock(block: ContentBlock): block is ReasoningBlock;
+/**
+ * Type guard for ImageBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is an ImageBlock
+ *
+ * @example
+ * ```typescript
+ * if (isImageBlock(block)) {
+ *   console.log(block.mimeType, block.width, block.height);
+ * }
+ * ```
+ */
+declare function isImageBlock(block: ContentBlock): block is ImageBlock;
+/**
+ * Type guard for DocumentBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a DocumentBlock
+ *
+ * @example
+ * ```typescript
+ * if (isDocumentBlock(block)) {
+ *   console.log(block.mimeType, block.title);
+ * }
+ * ```
+ */
+declare function isDocumentBlock(block: ContentBlock): block is DocumentBlock;
+/**
+ * Type guard for AudioBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is an AudioBlock
+ *
+ * @example
+ * ```typescript
+ * if (isAudioBlock(block)) {
+ *   console.log(block.mimeType, block.duration);
+ * }
+ * ```
+ */
+declare function isAudioBlock(block: ContentBlock): block is AudioBlock;
+/**
+ * Type guard for VideoBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a VideoBlock
+ *
+ * @example
+ * ```typescript
+ * if (isVideoBlock(block)) {
+ *   console.log(block.mimeType, block.duration);
+ * }
+ * ```
+ */
+declare function isVideoBlock(block: ContentBlock): block is VideoBlock;
+/**
+ * Type guard for BinaryBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a BinaryBlock
+ *
+ * @example
+ * ```typescript
+ * if (isBinaryBlock(block)) {
+ *   console.log(block.mimeType, block.metadata);
+ * }
+ * ```
+ */
+declare function isBinaryBlock(block: ContentBlock): block is BinaryBlock;
+
+/**
+ * @fileoverview JSON Schema types for tool parameters and structured outputs.
+ *
+ * Provides TypeScript interfaces for defining JSON Schema objects used in
+ * LLM tool definitions and structured output specifications.
+ *
+ * @module types/schema
+ */
+/**
+ * Primitive and composite JSON Schema property types.
+ *
+ * These types correspond to the JSON Schema specification's allowed type values.
+ */
+type JSONSchemaPropertyType = 
+/** String values */
+'string'
+/** Floating point numbers */
+ | 'number'
+/** Whole numbers */
+ | 'integer'
+/** Boolean true/false values */
+ | 'boolean'
+/** Ordered lists of values */
+ | 'array'
+/** Key-value mappings */
+ | 'object'
+/** Explicit null value */
+ | 'null';
+/**
+ * JSON Schema property definition.
+ *
+ * Describes a single property within a JSON Schema object, including
+ * type constraints, validation rules, and nested structure definitions.
+ *
+ * @example
+ * ```typescript
+ * const nameProperty: JSONSchemaProperty = {
+ *   type: 'string',
+ *   description: 'User name',
+ *   minLength: 1,
+ *   maxLength: 100
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const tagsProperty: JSONSchemaProperty = {
+ *   type: 'array',
+ *   description: 'List of tags',
+ *   items: { type: 'string' },
+ *   minItems: 1,
+ *   uniqueItems: true
+ * };
+ * ```
+ */
+interface JSONSchemaProperty {
+    /** The JSON type of this property */
+    type: JSONSchemaPropertyType;
+    /** Human-readable description for the LLM */
+    description?: string;
+    /** Allowed values (enumeration) */
+    enum?: unknown[];
+    /** Constant value this property must equal */
+    const?: unknown;
+    /** Default value if not provided */
+    default?: unknown;
+    /** Minimum string length (string type only) */
+    minLength?: number;
+    /** Maximum string length (string type only) */
+    maxLength?: number;
+    /** Regular expression pattern for validation (string type only) */
+    pattern?: string;
+    /** Semantic format hint (string type only) */
+    format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid';
+    /** Minimum value inclusive (number/integer types only) */
+    minimum?: number;
+    /** Maximum value inclusive (number/integer types only) */
+    maximum?: number;
+    /** Minimum value exclusive (number/integer types only) */
+    exclusiveMinimum?: number;
+    /** Maximum value exclusive (number/integer types only) */
+    exclusiveMaximum?: number;
+    /** Value must be divisible by this (number/integer types only) */
+    multipleOf?: number;
+    /** Schema for array elements (array type only) */
+    items?: JSONSchemaProperty;
+    /** Minimum array length (array type only) */
+    minItems?: number;
+    /** Maximum array length (array type only) */
+    maxItems?: number;
+    /** Whether array elements must be unique (array type only) */
+    uniqueItems?: boolean;
+    /** Nested property definitions (object type only) */
+    properties?: Record<string, JSONSchemaProperty>;
+    /** List of required property names (object type only) */
+    required?: string[];
+    /** Whether additional properties are allowed (object type only) */
+    additionalProperties?: boolean;
+}
+/**
+ * Root JSON Schema for tool parameters or structured outputs.
+ *
+ * This is the top-level schema definition used when defining tool
+ * parameters or requesting structured output from an LLM.
+ *
+ * @example
+ * ```typescript
+ * const weatherToolSchema: JSONSchema = {
+ *   type: 'object',
+ *   description: 'Parameters for getting weather information',
+ *   properties: {
+ *     location: {
+ *       type: 'string',
+ *       description: 'City name or coordinates'
+ *     },
+ *     units: {
+ *       type: 'string',
+ *       enum: ['celsius', 'fahrenheit'],
+ *       description: 'Temperature units'
+ *     }
+ *   },
+ *   required: ['location']
+ * };
+ * ```
+ */
+interface JSONSchema {
+    /** Root schemas are always objects */
+    type: 'object';
+    /** Property definitions for the object */
+    properties: Record<string, JSONSchemaProperty>;
+    /** List of required property names */
+    required?: string[];
+    /** Whether additional properties are allowed beyond those defined */
+    additionalProperties?: boolean;
+    /** Human-readable description of the schema's purpose */
+    description?: string;
+}
+
+/**
+ * @fileoverview Tool types for LLM function calling.
+ *
+ * Defines the interfaces for registering tools with LLMs, handling
+ * tool calls from the model, and managing tool execution strategies.
+ *
+ * @module types/tool
+ */
+
+/**
+ * Provider-namespaced metadata for tools.
+ *
+ * Each provider can attach its own metadata under its namespace,
+ * enabling provider-specific features like caching, strict mode, etc.
+ *
+ * @example
+ * ```typescript
+ * const metadata: ToolMetadata = {
+ *   anthropic: { cache_control: { type: 'ephemeral' } },
+ *   openrouter: { cache_control: { type: 'ephemeral', ttl: '1h' } }
+ * };
+ * ```
+ */
+interface ToolMetadata {
+    [provider: string]: Record<string, unknown> | undefined;
+}
+/**
+ * Tool call requested by the model.
+ *
+ * Represents a single function call request from the LLM, including
+ * the tool name and parsed arguments.
+ *
+ * @example
+ * ```typescript
+ * const toolCall: ToolCall = {
+ *   toolCallId: 'call_abc123',
+ *   toolName: 'get_weather',
+ *   arguments: { location: 'San Francisco', units: 'celsius' }
+ * };
+ * ```
+ */
+interface ToolCall {
+    /** Unique identifier for this tool call, used to match results */
+    toolCallId: string;
+    /** Name of the tool being called */
+    toolName: string;
+    /** Parsed arguments for the tool call */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Result of tool execution.
+ *
+ * Returned after executing a tool, containing the result data
+ * and whether an error occurred.
+ *
+ * @example
+ * ```typescript
+ * const result: ToolResult = {
+ *   toolCallId: 'call_abc123',
+ *   result: { temperature: 72, conditions: 'sunny' }
+ * };
+ *
+ * // Error result
+ * const errorResult: ToolResult = {
+ *   toolCallId: 'call_abc123',
+ *   result: 'Location not found',
+ *   isError: true
+ * };
+ * ```
+ */
+interface ToolResult {
+    /** The tool call ID this result corresponds to */
+    toolCallId: string;
+    /** The result data (can be any serializable value) */
+    result: unknown;
+    /** Whether the tool execution resulted in an error */
+    isError?: boolean;
+}
+/**
+ * Tool definition for LLM function calling.
+ *
+ * Defines a tool that can be called by the LLM, including its
+ * name, description, parameter schema, and execution function.
+ *
+ * @typeParam TParams - The type of parameters the tool accepts
+ * @typeParam TResult - The type of result the tool returns
+ *
+ * @example
+ * ```typescript
+ * const weatherTool: Tool<{ location: string }, WeatherData> = {
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a location',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       location: { type: 'string', description: 'City name' }
+ *     },
+ *     required: ['location']
+ *   },
+ *   run: async (params) => {
+ *     return fetchWeather(params.location);
+ *   }
+ * };
+ * ```
+ */
+interface Tool<TParams = unknown, TResult = unknown> {
+    /** Tool name (must be unique within an llm() instance) */
+    name: string;
+    /** Human-readable description for the model to understand when to use this tool */
+    description: string;
+    /** JSON Schema defining the tool's parameters */
+    parameters: JSONSchema;
+    /**
+     * Provider-specific metadata, namespaced by provider name.
+     *
+     * Used for provider-specific features like prompt caching:
+     * @example
+     * ```typescript
+     * const tool: Tool = {
+     *   name: 'search_docs',
+     *   description: 'Search documentation',
+     *   parameters: {...},
+     *   run: async (params) => {...},
+     *   metadata: {
+     *     anthropic: { cache_control: { type: 'ephemeral' } }
+     *   }
+     * };
+     * ```
+     */
+    metadata?: ToolMetadata;
+    /**
+     * Executes the tool with the provided parameters.
+     *
+     * @param params - The parameters passed by the model
+     * @returns The tool result, synchronously or as a Promise
+     */
+    run(params: TParams): TResult | Promise<TResult>;
+    /**
+     * Optional approval handler for sensitive operations.
+     *
+     * If provided, this function is called before the tool executes.
+     * Return false to prevent execution.
+     *
+     * @param params - The parameters the tool would be called with
+     * @returns Whether to approve the execution
+     */
+    approval?(params: TParams): boolean | Promise<boolean>;
+}
+/**
+ * Result from onBeforeCall hook indicating whether to proceed and optionally transformed params.
+ */
+interface BeforeCallResult {
+    /** Whether to proceed with tool execution */
+    proceed: boolean;
+    /** Transformed parameters to use instead of the original (optional) */
+    params?: unknown;
+}
+/**
+ * Result from onAfterCall hook optionally containing a transformed result.
+ */
+interface AfterCallResult {
+    /** Transformed result to use instead of the original */
+    result: unknown;
+}
+/**
+ * Strategy for controlling tool execution behavior.
+ *
+ * Provides hooks for monitoring, controlling, and transforming the tool execution
+ * loop during LLM inference.
+ *
+ * @example
+ * ```typescript
+ * const strategy: ToolUseStrategy = {
+ *   maxIterations: 5,
+ *   onToolCall: (tool, params) => {
+ *     console.log(`Calling ${tool.name} with`, params);
+ *   },
+ *   // Transform input parameters
+ *   onBeforeCall: (tool, params) => {
+ *     if (tool.name === 'search') {
+ *       return { proceed: true, params: { ...params, limit: 10 } };
+ *     }
+ *     return true;
+ *   },
+ *   // Transform output results
+ *   onAfterCall: (tool, params, result) => {
+ *     if (tool.name === 'fetch_data') {
+ *       return { result: sanitize(result) };
+ *     }
+ *   },
+ *   onMaxIterations: (iterations) => {
+ *     console.warn(`Reached max iterations: ${iterations}`);
+ *   }
+ * };
+ * ```
+ */
+interface ToolUseStrategy {
+    /** Maximum number of tool execution rounds (default: 10) */
+    maxIterations?: number;
+    /**
+     * Called when the model requests a tool call.
+     *
+     * @param tool - The tool being called
+     * @param params - The parameters for the call
+     */
+    onToolCall?(tool: Tool, params: unknown): void | Promise<void>;
+    /**
+     * Called before tool execution. Can skip execution or transform parameters.
+     *
+     * @param tool - The tool about to be executed
+     * @param params - The parameters for the call
+     * @returns One of:
+     *   - `false` to skip execution
+     *   - `true` to proceed with original params
+     *   - `BeforeCallResult` object to control execution and optionally transform params
+     */
+    onBeforeCall?(tool: Tool, params: unknown): boolean | BeforeCallResult | Promise<boolean | BeforeCallResult>;
+    /**
+     * Called after tool execution completes. Can transform the result.
+     *
+     * @param tool - The tool that was executed
+     * @param params - The parameters that were used
+     * @param result - The result from the tool
+     * @returns Void to use original result, or `AfterCallResult` to transform it
+     */
+    onAfterCall?(tool: Tool, params: unknown, result: unknown): void | AfterCallResult | Promise<void | AfterCallResult>;
+    /**
+     * Called when a tool execution throws an error.
+     *
+     * @param tool - The tool that failed
+     * @param params - The parameters that were used
+     * @param error - The error that was thrown
+     */
+    onError?(tool: Tool, params: unknown, error: Error): void | Promise<void>;
+    /**
+     * Called when the maximum iteration limit is reached.
+     *
+     * @param iterations - The number of iterations that were performed
+     */
+    onMaxIterations?(iterations: number): void | Promise<void>;
+}
+/**
+ * Record of a completed tool execution.
+ *
+ * Contains all information about a tool call that was executed,
+ * including timing and result data.
+ *
+ * @example
+ * ```typescript
+ * const execution: ToolExecution = {
+ *   toolName: 'get_weather',
+ *   toolCallId: 'call_abc123',
+ *   arguments: { location: 'San Francisco' },
+ *   result: { temperature: 72 },
+ *   isError: false,
+ *   duration: 150,
+ *   approved: true
+ * };
+ * ```
+ */
+interface ToolExecution {
+    /** Name of the tool that was called */
+    toolName: string;
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Arguments that were passed to the tool */
+    arguments: Record<string, unknown>;
+    /** Result returned by the tool */
+    result: unknown;
+    /** Whether the tool execution resulted in an error */
+    isError: boolean;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Whether approval was required and granted (undefined if no approval handler) */
+    approved?: boolean;
+}
+
+/**
+ * @fileoverview Message types for conversation history.
+ *
+ * Defines the message classes used to represent conversation turns
+ * between users and assistants, including support for multimodal
+ * content and tool calls.
+ *
+ * @module types/messages
+ */
+
+/**
+ * Message serialized to JSON format.
+ * Picks common fields from Message, converts timestamp to string.
+ */
+type MessageJSON = Pick<Message, 'id' | 'type' | 'metadata'> & {
+    timestamp: string;
+    content: ContentBlock[];
+    toolCalls?: ToolCall[];
+    results?: ToolResult[];
+};
+/**
+ * Message type discriminator union.
+ *
+ * This type is derived from {@link MessageRole} constants. The name `MessageType`
+ * is kept for backward compatibility; `MessageRole` works as both the const
+ * object and this type.
+ */
+type MessageType = (typeof MessageRole)[keyof typeof MessageRole];
+/**
+ * Message role/type constants.
+ *
+ * Use these constants instead of raw strings for type-safe message handling:
+ *
+ * @example
+ * ```typescript
+ * import { MessageRole, isUserMessage } from 'upp';
+ *
+ * if (message.type === MessageRole.User) {
+ *   console.log('User said:', message.text);
+ * } else if (message.type === MessageRole.Assistant) {
+ *   console.log('Assistant replied:', message.text);
+ * }
+ * ```
+ */
+declare const MessageRole: {
+    /** User message */
+    readonly User: "user";
+    /** Assistant/model response */
+    readonly Assistant: "assistant";
+    /** Tool execution result */
+    readonly ToolResult: "tool_result";
+};
+/**
+ * Type alias for MessageType, allowing `MessageRole` to work as both const and type.
+ */
+type MessageRole = MessageType;
+/**
+ * Provider-namespaced metadata for messages.
+ *
+ * Each provider can attach its own metadata under its namespace,
+ * preventing conflicts between different providers.
+ *
+ * @example
+ * ```typescript
+ * const metadata: MessageMetadata = {
+ *   openai: { model: 'gpt-4', finishReason: 'stop' },
+ *   anthropic: { model: 'claude-3', stopReason: 'end_turn' }
+ * };
+ * ```
+ */
+interface MessageMetadata {
+    [provider: string]: Record<string, unknown> | undefined;
+}
+/**
+ * Options for constructing messages.
+ */
+interface MessageOptions {
+    /** Custom message ID (auto-generated if not provided) */
+    id?: string;
+    /** Provider-specific metadata */
+    metadata?: MessageMetadata;
+}
+/**
+ * Abstract base class for all message types.
+ *
+ * Provides common functionality for user, assistant, and tool result
+ * messages, including content accessors and metadata handling.
+ *
+ * @example
+ * ```typescript
+ * // Access text content from any message
+ * const text = message.text;
+ *
+ * // Access images
+ * const images = message.images;
+ * ```
+ */
+declare abstract class Message {
+    /** Unique message identifier */
+    readonly id: string;
+    /** Timestamp when the message was created */
+    readonly timestamp: Date;
+    /** Provider-specific metadata, namespaced by provider name */
+    readonly metadata?: MessageMetadata;
+    /** Message type discriminator (implemented by subclasses) */
+    abstract readonly type: MessageType;
+    /**
+     * Returns the content blocks for this message.
+     * Implemented by subclasses to provide type-specific content.
+     */
+    protected abstract getContent(): ContentBlock[];
+    /**
+     * Creates a new message instance.
+     *
+     * @param options - Optional message ID and metadata
+     */
+    constructor(options?: MessageOptions);
+    /**
+     * Concatenated text content from all text blocks.
+     * Blocks are joined with double newlines.
+     */
+    get text(): string;
+    /**
+     * All image content blocks in this message.
+     */
+    get images(): ImageBlock[];
+    /**
+     * All document content blocks in this message.
+     */
+    get documents(): DocumentBlock[];
+    /**
+     * All audio content blocks in this message.
+     */
+    get audio(): AudioBlock[];
+    /**
+     * All video content blocks in this message.
+     */
+    get video(): VideoBlock[];
+    /**
+     * All reasoning/thinking content blocks in this message.
+     * Available when using extended thinking models.
+     */
+    get reasoning(): ReasoningBlock[];
+}
+/**
+ * User input message.
+ *
+ * Represents a message from the user, which can contain text and/or
+ * multimodal content like images, audio, or video.
+ *
+ * @example
+ * ```typescript
+ * // Simple text message
+ * const msg = new UserMessage('Hello, world!');
+ *
+ * // Multimodal message
+ * const msg = new UserMessage([
+ *   { type: 'text', text: 'What is in this image?' },
+ *   { type: 'image', source: { type: 'url', url: '...' }, mimeType: 'image/png' }
+ * ]);
+ * ```
+ */
+declare class UserMessage extends Message {
+    /** Message type discriminator */
+    readonly type: "user";
+    /** Content blocks in this message */
+    readonly content: UserContent[];
+    /**
+     * Creates a new user message.
+     *
+     * @param content - String (converted to TextBlock) or array of content blocks
+     * @param options - Optional message ID and metadata
+     */
+    constructor(content: string | UserContent[], options?: MessageOptions);
+    protected getContent(): ContentBlock[];
+}
+/**
+ * Assistant response message.
+ *
+ * Represents a response from the AI assistant, which may contain
+ * text, media content, and/or tool call requests.
+ *
+ * @example
+ * ```typescript
+ * // Simple text response
+ * const msg = new AssistantMessage('Hello! How can I help?');
+ *
+ * // Response with tool calls
+ * const msg = new AssistantMessage(
+ *   'Let me check the weather...',
+ *   [{ toolCallId: 'call_1', toolName: 'get_weather', arguments: { location: 'NYC' } }]
+ * );
+ * ```
+ */
+declare class AssistantMessage extends Message {
+    /** Message type discriminator */
+    readonly type: "assistant";
+    /** Content blocks in this message */
+    readonly content: AssistantContent[];
+    /** Tool calls requested by the model (if any) */
+    readonly toolCalls?: ToolCall[];
+    /**
+     * Creates a new assistant message.
+     *
+     * @param content - String (converted to TextBlock) or array of content blocks
+     * @param toolCalls - Tool calls requested by the model
+     * @param options - Optional message ID and metadata
+     */
+    constructor(content: string | AssistantContent[], toolCalls?: ToolCall[], options?: MessageOptions);
+    protected getContent(): ContentBlock[];
+    /**
+     * Whether this message contains tool call requests.
+     */
+    get hasToolCalls(): boolean;
+}
+/**
+ * Tool execution result message.
+ *
+ * Contains the results of executing one or more tool calls,
+ * sent back to the model for further processing.
+ *
+ * @example
+ * ```typescript
+ * const msg = new ToolResultMessage([
+ *   { toolCallId: 'call_1', result: { temperature: 72, conditions: 'sunny' } },
+ *   { toolCallId: 'call_2', result: 'File not found', isError: true }
+ * ]);
+ * ```
+ */
+declare class ToolResultMessage extends Message {
+    /** Message type discriminator */
+    readonly type: "tool_result";
+    /** Results from tool executions */
+    readonly results: ToolResult[];
+    /**
+     * Creates a new tool result message.
+     *
+     * @param results - Array of tool execution results
+     * @param options - Optional message ID and metadata
+     */
+    constructor(results: ToolResult[], options?: MessageOptions);
+    protected getContent(): ContentBlock[];
+}
+/**
+ * Type guard for UserMessage.
+ *
+ * @param msg - The message to check
+ * @returns True if the message is a UserMessage
+ *
+ * @example
+ * ```typescript
+ * if (isUserMessage(msg)) {
+ *   console.log('User said:', msg.text);
+ * }
+ * ```
+ */
+declare function isUserMessage(msg: Message): msg is UserMessage;
+/**
+ * Type guard for AssistantMessage.
+ *
+ * @param msg - The message to check
+ * @returns True if the message is an AssistantMessage
+ *
+ * @example
+ * ```typescript
+ * if (isAssistantMessage(msg)) {
+ *   console.log('Assistant said:', msg.text);
+ *   if (msg.hasToolCalls) {
+ *     console.log('Tool calls:', msg.toolCalls);
+ *   }
+ * }
+ * ```
+ */
+declare function isAssistantMessage(msg: Message): msg is AssistantMessage;
+/**
+ * Type guard for ToolResultMessage.
+ *
+ * @param msg - The message to check
+ * @returns True if the message is a ToolResultMessage
+ *
+ * @example
+ * ```typescript
+ * if (isToolResultMessage(msg)) {
+ *   for (const result of msg.results) {
+ *     console.log(`Tool ${result.toolCallId}:`, result.result);
+ *   }
+ * }
+ * ```
+ */
+declare function isToolResultMessage(msg: Message): msg is ToolResultMessage;
+
+/**
+ * @fileoverview Turn types for inference results.
+ *
+ * A Turn represents the complete result of one inference call, including
+ * all messages produced during tool execution loops, token usage, and
+ * optional structured output data.
+ *
+ * @module types/turn
+ */
+
+/**
+ * Token usage information for an inference request.
+ *
+ * Tracks input and output tokens across all inference cycles,
+ * with optional per-cycle breakdown and cache metrics.
+ *
+ * @example
+ * ```typescript
+ * const usage: TokenUsage = {
+ *   inputTokens: 150,
+ *   outputTokens: 50,
+ *   totalTokens: 200,
+ *   cacheReadTokens: 100,
+ *   cacheWriteTokens: 50,
+ *   cycles: [
+ *     { inputTokens: 100, outputTokens: 30, cacheReadTokens: 0, cacheWriteTokens: 50 },
+ *     { inputTokens: 50, outputTokens: 20, cacheReadTokens: 100, cacheWriteTokens: 0 }
+ *   ]
+ * };
+ * ```
+ */
+interface TokenUsage {
+    /** Total input tokens across all cycles */
+    inputTokens: number;
+    /** Total output tokens across all cycles */
+    outputTokens: number;
+    /** Sum of input and output tokens */
+    totalTokens: number;
+    /**
+     * Tokens read from cache (cache hits).
+     * Returns 0 for providers that don't support or report cache metrics.
+     */
+    cacheReadTokens: number;
+    /**
+     * Tokens written to cache (cache misses that were cached).
+     * Only Anthropic reports this metric; returns 0 for other providers.
+     */
+    cacheWriteTokens: number;
+    /** Per-cycle token breakdown (if multiple cycles occurred) */
+    cycles?: Array<{
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    }>;
+}
+/**
+ * A Turn represents the complete result of one inference call.
+ *
+ * Includes all messages produced during tool execution loops,
+ * the final assistant response, token usage, and optional
+ * structured output data.
+ *
+ * @typeParam TData - Type of the structured output data
+ *
+ * @example
+ * ```typescript
+ * const turn = await instance.generate('Hello');
+ * console.log(turn.response.text);
+ * console.log(`Used ${turn.usage.totalTokens} tokens in ${turn.cycles} cycles`);
+ *
+ * // With structured output
+ * interface WeatherData { temperature: number; conditions: string; }
+ * const turn = await instance.generate<WeatherData>('Get weather');
+ * console.log(turn.data?.temperature);
+ * ```
+ */
+interface Turn<TData = unknown> {
+    /**
+     * All messages produced during this inference, in chronological order.
+     * Includes UserMessage, AssistantMessage (may include toolCalls), and ToolResultMessage.
+     */
+    readonly messages: Message[];
+    /** The final assistant response (last AssistantMessage in the turn) */
+    readonly response: AssistantMessage;
+    /**
+     * Tool executions that occurred during this turn.
+     *
+     * Execution order reflects completion timing, not call order.
+     * Correlate with tool calls using toolCallId.
+     */
+    readonly toolExecutions: ToolExecution[];
+    /** Aggregate token usage for the entire turn */
+    readonly usage: TokenUsage;
+    /** Total number of inference cycles (1 + number of tool rounds) */
+    readonly cycles: number;
+    /**
+     * Structured output data (if a structure schema was provided).
+     * Type is inferred from the schema when using TypeScript.
+     */
+    readonly data?: TData;
+}
+/**
+ * Turn serialized to JSON format.
+ * Messages are converted to MessageJSON, response is omitted (computed from messages).
+ *
+ * @remarks
+ * This type is derived from {@link Turn} and should stay in sync with it.
+ */
+type TurnJSON = Omit<Turn, 'messages' | 'response'> & {
+    messages: MessageJSON[];
+};
+/**
+ * Creates a Turn from accumulated inference data.
+ *
+ * @typeParam TData - Type of the structured output data
+ * @param messages - All messages produced during the inference
+ * @param toolExecutions - Record of all tool executions
+ * @param usage - Aggregate token usage
+ * @param cycles - Number of inference cycles
+ * @param data - Optional structured output data
+ * @returns A complete Turn object
+ * @throws Error if no assistant message is found in the messages
+ *
+ * @example
+ * ```typescript
+ * const turn = createTurn(
+ *   [userMsg, assistantMsg],
+ *   [],
+ *   { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+ *   1
+ * );
+ * ```
+ */
+declare function createTurn<TData = unknown>(messages: Message[], toolExecutions: ToolExecution[], usage: TokenUsage, cycles: number, data?: TData): Turn<TData>;
+/**
+ * Creates an empty TokenUsage object.
+ *
+ * @returns A TokenUsage with all values set to zero
+ *
+ * @example
+ * ```typescript
+ * const usage = emptyUsage();
+ * // { inputTokens: 0, outputTokens: 0, totalTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, cycles: [] }
+ * ```
+ */
+declare function emptyUsage(): TokenUsage;
+/**
+ * Aggregates token usage from multiple inference cycles.
+ *
+ * @param usages - Array of TokenUsage objects to aggregate
+ * @returns Combined TokenUsage with per-cycle breakdown
+ *
+ * @example
+ * ```typescript
+ * const cycle1 = { inputTokens: 100, outputTokens: 30, totalTokens: 130, cacheReadTokens: 50, cacheWriteTokens: 0 };
+ * const cycle2 = { inputTokens: 150, outputTokens: 40, totalTokens: 190, cacheReadTokens: 100, cacheWriteTokens: 0 };
+ * const total = aggregateUsage([cycle1, cycle2]);
+ * // { inputTokens: 250, outputTokens: 70, totalTokens: 320, cacheReadTokens: 150, cacheWriteTokens: 0, cycles: [...] }
+ * ```
+ */
+declare function aggregateUsage(usages: TokenUsage[]): TokenUsage;
+
+/**
+ * @fileoverview Streaming types for real-time LLM responses.
+ *
+ * Defines the event types and interfaces for streaming LLM inference,
+ * including text deltas, tool call deltas, and control events.
+ *
+ * @module types/stream
+ */
+
+/**
+ * Stream event type constants.
+ *
+ * Use these constants instead of raw strings for type-safe event handling:
+ *
+ * @example
+ * ```typescript
+ * import { StreamEventType } from 'upp';
+ *
+ * for await (const event of stream) {
+ *   if (event.type === StreamEventType.TextDelta) {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   }
+ * }
+ * ```
+ */
+declare const StreamEventType: {
+    /** Incremental text output */
+    readonly TextDelta: "text_delta";
+    /** Incremental reasoning/thinking output */
+    readonly ReasoningDelta: "reasoning_delta";
+    /** Incremental image data */
+    readonly ImageDelta: "image_delta";
+    /** Incremental audio data */
+    readonly AudioDelta: "audio_delta";
+    /** Incremental video data */
+    readonly VideoDelta: "video_delta";
+    /** Incremental tool call data (arguments being streamed) */
+    readonly ToolCallDelta: "tool_call_delta";
+    /** Tool execution has started (may be emitted after completion in some implementations) */
+    readonly ToolExecutionStart: "tool_execution_start";
+    /** Tool execution has completed */
+    readonly ToolExecutionEnd: "tool_execution_end";
+    /** Beginning of a message */
+    readonly MessageStart: "message_start";
+    /** End of a message */
+    readonly MessageStop: "message_stop";
+    /** Beginning of a content block */
+    readonly ContentBlockStart: "content_block_start";
+    /** End of a content block */
+    readonly ContentBlockStop: "content_block_stop";
+};
+/**
+ * Stream event type discriminator union.
+ *
+ * This type is derived from {@link StreamEventType} constants. Use `StreamEventType.TextDelta`
+ * for constants or `type MyType = StreamEventType` for type annotations.
+ */
+type StreamEventType = (typeof StreamEventType)[keyof typeof StreamEventType];
+/**
+ * Event delta data payload.
+ *
+ * Contains the type-specific data for a streaming event.
+ * Different fields are populated depending on the event type.
+ */
+interface EventDelta {
+    /** Incremental text content (for text_delta, reasoning_delta) */
+    text?: string;
+    /** Incremental binary data (for image_delta, audio_delta, video_delta) */
+    data?: Uint8Array;
+    /** Tool call identifier (for tool_call_delta, tool_execution_start/end) */
+    toolCallId?: string;
+    /** Tool name (for tool_call_delta, tool_execution_start/end) */
+    toolName?: string;
+    /** Incremental JSON arguments string (for tool_call_delta) */
+    argumentsJson?: string;
+    /** Tool execution result (for tool_execution_end) */
+    result?: unknown;
+    /** Whether tool execution resulted in an error (for tool_execution_end) */
+    isError?: boolean;
+    /** Timestamp in milliseconds (for tool_execution_start/end) */
+    timestamp?: number;
+}
+/**
+ * A single streaming event from the LLM.
+ *
+ * Events are emitted in order as the model generates output,
+ * allowing for real-time display of responses.
+ *
+ * @example
+ * ```typescript
+ * import { StreamEventType } from 'upp';
+ *
+ * for await (const event of stream) {
+ *   if (event.type === StreamEventType.TextDelta) {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   } else if (event.type === StreamEventType.ToolCallDelta) {
+ *     console.log('Tool:', event.delta.toolName);
+ *   }
+ * }
+ * ```
+ */
+interface StreamEvent {
+    /** Event type discriminator */
+    type: StreamEventType;
+    /** Index of the content block this event belongs to */
+    index: number;
+    /** Event-specific data payload */
+    delta: EventDelta;
+}
+/**
+ * Stream result - an async iterable that also provides the final turn.
+ *
+ * Allows consuming streaming events while also awaiting the complete
+ * Turn result after streaming finishes.
+ *
+ * @typeParam TData - Type of the structured output data
+ *
+ * @example
+ * ```typescript
+ * import { StreamEventType } from 'upp';
+ *
+ * const stream = instance.stream('Tell me a story');
+ *
+ * // Consume streaming events
+ * for await (const event of stream) {
+ *   if (event.type === StreamEventType.TextDelta) {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   }
+ * }
+ *
+ * // Get the complete turn after streaming
+ * const turn = await stream.turn;
+ * console.log('\n\nTokens used:', turn.usage.totalTokens);
+ * ```
+ */
+interface StreamResult<TData = unknown> extends AsyncIterable<StreamEvent> {
+    /**
+     * Promise that resolves to the complete Turn after streaming finishes.
+     * Rejects if the stream is aborted or terminated early.
+     */
+    readonly turn: Promise<Turn<TData>>;
+    /**
+     * Aborts the stream, stopping further events and cancelling the request.
+     * This will cause {@link StreamResult.turn} to reject.
+     */
+    abort(): void;
+}
+/**
+ * Creates a StreamResult from an async generator and completion promise.
+ *
+ * @typeParam TData - Type of the structured output data
+ * @param generator - Async generator that yields stream events
+ * @param turnPromiseOrFactory - Promise or factory that resolves to the complete Turn
+ * @param abortController - Controller for aborting the stream
+ * @returns A StreamResult that can be iterated and awaited
+ *
+ * @example
+ * ```typescript
+ * const abortController = new AbortController();
+ * const stream = createStreamResult(
+ *   eventGenerator(),
+ *   turnPromise,
+ *   abortController
+ * );
+ * ```
+ */
+declare function createStreamResult<TData = unknown>(generator: AsyncGenerator<StreamEvent, void, unknown>, turnPromiseOrFactory: Promise<Turn<TData>> | (() => Promise<Turn<TData>>), abortController: AbortController): StreamResult<TData>;
+/**
+ * Creates a text delta stream event.
+ *
+ * @param text - The incremental text content
+ * @param index - Content block index (default: 0)
+ * @returns A text_delta StreamEvent
+ */
+declare function textDelta(text: string, index?: number): StreamEvent;
+/**
+ * Creates a tool call delta stream event.
+ *
+ * @param toolCallId - Unique identifier for the tool call
+ * @param toolName - Name of the tool being called
+ * @param argumentsJson - Incremental JSON arguments string
+ * @param index - Content block index (default: 0)
+ * @returns A tool_call_delta StreamEvent
+ */
+declare function toolCallDelta(toolCallId: string, toolName: string, argumentsJson: string, index?: number): StreamEvent;
+/**
+ * Creates a message start stream event.
+ *
+ * @returns A message_start StreamEvent
+ */
+declare function messageStart(): StreamEvent;
+/**
+ * Creates a message stop stream event.
+ *
+ * @returns A message_stop StreamEvent
+ */
+declare function messageStop(): StreamEvent;
+/**
+ * Creates a content block start stream event.
+ *
+ * @param index - The content block index starting
+ * @returns A content_block_start StreamEvent
+ */
+declare function contentBlockStart(index: number): StreamEvent;
+/**
+ * Creates a content block stop stream event.
+ *
+ * @param index - The content block index stopping
+ * @returns A content_block_stop StreamEvent
+ */
+declare function contentBlockStop(index: number): StreamEvent;
+
+/**
+ * @fileoverview Error types for the Unified Provider Protocol.
+ *
+ * Provides normalized error codes and a unified error class for handling
+ * errors across different AI providers in a consistent manner.
+ *
+ * @module types/errors
+ */
+/**
+ * Error code constants for cross-provider error handling.
+ *
+ * Use these constants instead of raw strings for type-safe error handling:
+ *
+ * @example
+ * ```typescript
+ * import { ErrorCode } from 'upp';
+ *
+ * try {
+ *   await llm.generate('Hello');
+ * } catch (error) {
+ *   if (error instanceof UPPError) {
+ *     switch (error.code) {
+ *       case ErrorCode.RateLimited:
+ *         await delay(error.retryAfter);
+ *         break;
+ *       case ErrorCode.AuthenticationFailed:
+ *         throw new Error('Invalid API key');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare const ErrorCode: {
+    /** API key is invalid or expired */
+    readonly AuthenticationFailed: "AUTHENTICATION_FAILED";
+    /** Rate limit exceeded, retry after delay */
+    readonly RateLimited: "RATE_LIMITED";
+    /** Input exceeds model's context window */
+    readonly ContextLengthExceeded: "CONTEXT_LENGTH_EXCEEDED";
+    /** Requested model does not exist */
+    readonly ModelNotFound: "MODEL_NOT_FOUND";
+    /** Request parameters are malformed */
+    readonly InvalidRequest: "INVALID_REQUEST";
+    /** Provider returned an unexpected response format */
+    readonly InvalidResponse: "INVALID_RESPONSE";
+    /** Content was blocked by safety filters */
+    readonly ContentFiltered: "CONTENT_FILTERED";
+    /** Account quota or credits exhausted */
+    readonly QuotaExceeded: "QUOTA_EXCEEDED";
+    /** Provider-specific error not covered by other codes */
+    readonly ProviderError: "PROVIDER_ERROR";
+    /** Network connectivity issue */
+    readonly NetworkError: "NETWORK_ERROR";
+    /** Request exceeded timeout limit */
+    readonly Timeout: "TIMEOUT";
+    /** Request was cancelled via AbortSignal */
+    readonly Cancelled: "CANCELLED";
+};
+/**
+ * Error code discriminator union.
+ *
+ * This type is derived from {@link ErrorCode} constants. Use `ErrorCode.RateLimited`
+ * for constants or `type MyCode = ErrorCode` for type annotations.
+ */
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Modality type discriminator union.
+ *
+ * This type is derived from {@link ModalityType} constants. The name `Modality`
+ * is kept for backward compatibility; `ModalityType` works as both the const
+ * object and this type.
+ */
+type Modality = (typeof ModalityType)[keyof typeof ModalityType];
+/**
+ * Modality type constants.
+ *
+ * Use these constants for type-safe modality handling:
+ *
+ * @example
+ * ```typescript
+ * import { ModalityType } from 'upp';
+ *
+ * if (provider.modality === ModalityType.LLM) {
+ *   // Handle LLM provider
+ * }
+ * ```
+ */
+declare const ModalityType: {
+    /** Large language model for text generation */
+    readonly LLM: "llm";
+    /** Text/image embedding model */
+    readonly Embedding: "embedding";
+    /** Image generation model */
+    readonly Image: "image";
+    /** Audio processing/generation model */
+    readonly Audio: "audio";
+    /** Video processing/generation model */
+    readonly Video: "video";
+};
+/**
+ * Type alias for Modality, allowing `ModalityType` to work as both const and type.
+ */
+type ModalityType = Modality;
+/**
+ * Unified Provider Protocol Error.
+ *
+ * All provider-specific errors are normalized to this type, providing
+ * a consistent interface for error handling across different AI providers.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorCode, ModalityType } from 'upp';
+ *
+ * throw new UPPError(
+ *   'API key is invalid',
+ *   ErrorCode.AuthenticationFailed,
+ *   'openai',
+ *   ModalityType.LLM,
+ *   401
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { ErrorCode, ModalityType } from 'upp';
+ *
+ * // Wrapping a provider error
+ * try {
+ *   await openai.chat.completions.create({ ... });
+ * } catch (err) {
+ *   throw new UPPError(
+ *     'OpenAI request failed',
+ *     ErrorCode.ProviderError,
+ *     'openai',
+ *     ModalityType.LLM,
+ *     err.status,
+ *     err
+ *   );
+ * }
+ * ```
+ */
+declare class UPPError extends Error {
+    /** Normalized error code for programmatic handling */
+    readonly code: ErrorCode;
+    /** Name of the provider that generated the error */
+    readonly provider: string;
+    /** The modality that was being used when the error occurred */
+    readonly modality: Modality;
+    /** HTTP status code from the provider's response, if available */
+    readonly statusCode?: number;
+    /** The original error that caused this UPPError, if wrapping another error */
+    readonly cause?: Error;
+    /** Error class name, always 'UPPError' */
+    readonly name = "UPPError";
+    /**
+     * Creates a new UPPError instance.
+     *
+     * @param message - Human-readable error description
+     * @param code - Normalized error code for programmatic handling
+     * @param provider - Name of the provider that generated the error
+     * @param modality - The modality that was being used
+     * @param statusCode - HTTP status code from the provider's response
+     * @param cause - The original error being wrapped
+     */
+    constructor(message: string, code: ErrorCode, provider: string, modality: Modality, statusCode?: number, cause?: Error);
+    /**
+     * Creates a string representation of the error.
+     *
+     * @returns Formatted error string including code, message, provider, and modality
+     */
+    toString(): string;
+    /**
+     * Converts the error to a JSON-serializable object.
+     *
+     * @returns Plain object representation suitable for logging or transmission
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * @fileoverview Image content handling for the Universal Provider Protocol.
+ *
+ * Provides a unified Image class for working with images across different sources
+ * (file paths, URLs, raw bytes, base64). Supports conversion between formats and
+ * integration with UPP message content blocks.
+ *
+ * @module core/media/Image
+ */
+
+/**
+ * Represents an image that can be used in UPP messages.
+ *
+ * Images can be created from various sources (files, URLs, bytes, base64) and
+ * converted to different formats as needed by providers. The class provides
+ * a unified interface regardless of the underlying source type.
+ *
+ * @example
+ * ```typescript
+ * // Load from file
+ * const fileImage = await Image.fromPath('./photo.jpg');
+ *
+ * // Reference by URL
+ * const urlImage = Image.fromUrl('https://example.com/image.png');
+ *
+ * // From raw bytes
+ * const bytesImage = Image.fromBytes(uint8Array, 'image/png');
+ *
+ * // Use in a message
+ * const message = new UserMessage([image.toBlock()]);
+ * ```
+ */
+declare class Image {
+    /** The underlying image source (bytes, base64, or URL) */
+    readonly source: ImageSource;
+    /** MIME type of the image (e.g., 'image/jpeg', 'image/png') */
+    readonly mimeType: string;
+    /** Image width in pixels, if known */
+    readonly width?: number;
+    /** Image height in pixels, if known */
+    readonly height?: number;
+    private constructor();
+    /**
+     * Whether this image has data loaded in memory.
+     *
+     * Returns `false` for URL-sourced images that reference external resources.
+     * These must be fetched before their data can be accessed.
+     */
+    get hasData(): boolean;
+    /**
+     * Converts the image to a base64-encoded string.
+     *
+     * @returns The image data as a base64 string
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toBase64(): string;
+    /**
+     * Converts the image to a data URL suitable for embedding in HTML or CSS.
+     *
+     * @returns A data URL in the format `data:{mimeType};base64,{data}`
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toDataUrl(): string;
+    /**
+     * Gets the image data as raw bytes.
+     *
+     * @returns The image data as a Uint8Array
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Gets the URL for URL-sourced images.
+     *
+     * @returns The image URL
+     * @throws {Error} When the source is not a URL
+     */
+    toUrl(): string;
+    /**
+     * Converts this Image to an ImageBlock for use in UPP messages.
+     *
+     * @returns An ImageBlock that can be included in message content arrays
+     */
+    toBlock(): ImageBlock;
+    /**
+     * Creates an Image by reading a file from disk.
+     *
+     * The file is read into memory as bytes. MIME type is automatically
+     * detected from the file extension.
+     *
+     * @param path - Path to the image file
+     * @returns Promise resolving to an Image with the file contents
+     *
+     * @example
+     * ```typescript
+     * const image = await Image.fromPath('./photos/vacation.jpg');
+     * ```
+     */
+    static fromPath(path: string): Promise<Image>;
+    /**
+     * Creates an Image from a URL reference.
+     *
+     * The URL is stored as a reference and not fetched. Providers will handle
+     * URL-to-data conversion if needed. MIME type is detected from the URL
+     * path if not provided.
+     *
+     * @param url - URL pointing to the image
+     * @param mimeType - Optional MIME type override
+     * @returns An Image referencing the URL
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromUrl('https://example.com/logo.png');
+     * ```
+     */
+    static fromUrl(url: string, mimeType?: string): Image;
+    /**
+     * Creates an Image from raw byte data.
+     *
+     * @param data - The image data as a Uint8Array
+     * @param mimeType - The MIME type of the image
+     * @returns An Image containing the byte data
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromBytes(pngData, 'image/png');
+     * ```
+     */
+    static fromBytes(data: Uint8Array, mimeType: string): Image;
+    /**
+     * Creates an Image from a base64-encoded string.
+     *
+     * @param base64 - The base64-encoded image data (without data URL prefix)
+     * @param mimeType - The MIME type of the image
+     * @returns An Image containing the base64 data
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromBase64(base64String, 'image/jpeg');
+     * ```
+     */
+    static fromBase64(base64: string, mimeType: string): Image;
+    /**
+     * Creates an Image from an existing ImageBlock.
+     *
+     * Useful for converting content blocks received from providers back
+     * into Image instances for further processing.
+     *
+     * @param block - An ImageBlock from message content
+     * @returns An Image with the block's source and metadata
+     */
+    static fromBlock(block: ImageBlock): Image;
+}
+
+/**
+ * @fileoverview Image generation types for the Universal Provider Protocol.
+ *
+ * Defines the interfaces for configuring and executing image generation operations,
+ * including options, instances, requests, responses, streaming, and capabilities.
+ *
+ * @module types/image
+ */
+
+/**
+ * Structural type for image model input.
+ * Uses structural typing to avoid generic variance issues with Provider generics.
+ *
+ * @remarks
+ * This type mirrors {@link ModelReference} while keeping provider options
+ * structurally compatible across providers.
+ *
+ * @see ModelReference
+ */
+interface ImageModelInput {
+    readonly modelId: string;
+    readonly provider: ProviderIdentity;
+    /** Optional provider configuration merged into requests */
+    readonly providerConfig?: Partial<ProviderConfig>;
+}
+/**
+ * Options for creating an image instance with the image() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const options: ImageOptions<OpenAIImageParams> = {
+ *   model: openai('dall-e-3'),
+ *   config: { apiKey: process.env.OPENAI_API_KEY },
+ *   params: { size: '1024x1024', quality: 'hd' }
+ * };
+ * ```
+ */
+interface ImageOptions<TParams = unknown> {
+    /** A model reference from a provider factory */
+    model: ImageModelInput;
+    /** Provider infrastructure configuration */
+    config?: ProviderConfig;
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+}
+/**
+ * Options for image generation.
+ */
+interface ImageGenerateOptions {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Input type for generate() - either a string prompt or object with prompt.
+ */
+type ImageInput = string | {
+    prompt: string;
+};
+/**
+ * Input for edit() operations.
+ */
+interface ImageEditInput {
+    /** Base image to edit */
+    image: Image;
+    /** Mask indicating edit region (interpretation varies by provider) */
+    mask?: Image;
+    /** Edit instruction prompt */
+    prompt: string;
+}
+/**
+ * A single generated image with optional metadata.
+ */
+interface GeneratedImage {
+    /** The generated image */
+    image: Image;
+    /** Provider-specific per-image metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usage statistics for image generation.
+ * Fields are optional because providers report usage differently.
+ */
+interface ImageUsage {
+    /** Number of images generated */
+    imagesGenerated?: number;
+    /** Input tokens consumed (token-based pricing) */
+    inputTokens?: number;
+    /** Output tokens consumed (token-based pricing) */
+    outputTokens?: number;
+    /** Provider-reported cost (credits, dollars, etc.) */
+    cost?: number;
+}
+/**
+ * Result from generate() or edit() calls.
+ */
+interface ImageResult {
+    /** Generated images */
+    images: GeneratedImage[];
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+    /** Usage/billing information */
+    usage?: ImageUsage;
+}
+/**
+ * Stream events for image generation.
+ */
+type ImageStreamEvent = {
+    type: 'preview';
+    image: Image;
+    index: number;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'complete';
+    image: GeneratedImage;
+    index: number;
+};
+/**
+ * Async iterable stream with final result accessor.
+ * Returned when stream() is called.
+ */
+interface ImageStreamResult extends AsyncIterable<ImageStreamEvent> {
+    /** Promise resolving to complete result after streaming */
+    readonly result: Promise<ImageResult>;
+    /** Abort the generation */
+    abort(): void;
+}
+/**
+ * Image generation capabilities.
+ */
+interface ImageCapabilities {
+    /** Supports text-to-image generation */
+    generate: boolean;
+    /** Supports streaming with partial previews */
+    streaming: boolean;
+    /** Supports image editing/inpainting */
+    edit: boolean;
+    /** Maximum images per request (if known) */
+    maxImages?: number;
+}
+/**
+ * Image instance returned by the image() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const dalle = image({ model: openai('dall-e-3') });
+ *
+ * // Simple generation
+ * const result = await dalle.generate('A sunset over mountains');
+ *
+ * // Streaming (if supported)
+ * if (dalle.capabilities.streaming && dalle.stream) {
+ *   const stream = dalle.stream('A cyberpunk cityscape');
+ *   for await (const event of stream) {
+ *     // Handle preview/complete events
+ *   }
+ * }
+ * ```
+ */
+interface ImageInstance<TParams = unknown> {
+    /**
+     * Generate images from a text prompt.
+     *
+     * @param input - The prompt string or object with prompt
+     * @param options - Optional generation options
+     * @returns Promise resolving to the generated images
+     */
+    generate(input: ImageInput, options?: ImageGenerateOptions): Promise<ImageResult>;
+    /**
+     * Generate with streaming progress (if supported).
+     * Only available when capabilities.streaming is true.
+     *
+     * @param input - The prompt string or object with prompt
+     * @returns ImageStreamResult with events and final result
+     */
+    stream?(input: ImageInput): ImageStreamResult;
+    /**
+     * Edit an existing image (if supported).
+     * Only available when capabilities.edit is true.
+     *
+     * @param input - Edit input with image, optional mask, and prompt
+     * @returns Promise resolving to the edited images
+     */
+    edit?(input: ImageEditInput): Promise<ImageResult>;
+    /** The bound image model */
+    readonly model: BoundImageModel<TParams>;
+    /** Current parameters */
+    readonly params: TParams | undefined;
+    /** Model capabilities */
+    readonly capabilities: ImageCapabilities;
+}
+/**
+ * Request passed from image() core to providers for generation.
+ * @internal
+ */
+interface ImageRequest<TParams = unknown> {
+    /** Generation prompt */
+    prompt: string;
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Request passed to providers for edit operations.
+ * @internal
+ */
+interface ImageEditRequest<TParams = unknown> {
+    /** Base image to edit */
+    image: Image;
+    /** Edit mask */
+    mask?: Image;
+    /** Edit instruction prompt */
+    prompt: string;
+    /** Provider-specific parameters */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Response from provider's generate or edit method.
+ * @internal
+ */
+interface ImageResponse {
+    /** Generated images */
+    images: GeneratedImage[];
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+    /** Usage information */
+    usage?: ImageUsage;
+}
+/**
+ * Raw provider stream result.
+ * An async iterable of ImageStreamEvent with a response promise.
+ * @internal
+ */
+interface ImageProviderStreamResult extends AsyncIterable<ImageStreamEvent> {
+    /** Promise resolving to the complete response */
+    readonly response: Promise<ImageResponse>;
+}
+/**
+ * Bound image model - full definition.
+ *
+ * Represents an image model bound to a specific provider and model ID,
+ * ready to execute generation requests.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundImageModel<TParams = unknown> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: ImageProvider<TParams>;
+    /** Model capabilities */
+    readonly capabilities: ImageCapabilities;
+    /**
+     * Generate images from a prompt.
+     *
+     * @param request - The generation request
+     * @returns Promise resolving to the response
+     */
+    generate(request: ImageRequest<TParams>): Promise<ImageResponse>;
+    /**
+     * Stream image generation (optional).
+     *
+     * @param request - The generation request
+     * @returns Stream result with events and final response
+     */
+    stream?(request: ImageRequest<TParams>): ImageProviderStreamResult;
+    /**
+     * Edit an image (optional).
+     *
+     * @param request - The edit request
+     * @returns Promise resolving to the response
+     */
+    edit?(request: ImageEditRequest<TParams>): Promise<ImageResponse>;
+}
+
+/**
+ * @fileoverview Provider types for AI service integrations.
+ *
+ * Defines the interfaces for provider factories, modality handlers,
+ * and configuration options for connecting to various AI providers.
+ *
+ * @module types/provider
+ */
+
+/**
+ * API key strategy interface for managing multiple keys.
+ *
+ * Implement this interface to provide custom key rotation or
+ * selection logic when working with multiple API keys.
+ *
+ * @example
+ * ```typescript
+ * class RoundRobinKeys implements KeyStrategy {
+ *   private keys: string[];
+ *   private index = 0;
+ *
+ *   constructor(keys: string[]) {
+ *     this.keys = keys;
+ *   }
+ *
+ *   getKey(): string {
+ *     const key = this.keys[this.index];
+ *     this.index = (this.index + 1) % this.keys.length;
+ *     return key;
+ *   }
+ * }
+ * ```
+ */
+interface KeyStrategy {
+    /**
+     * Gets the next API key to use for a request.
+     *
+     * @returns The API key string, or a Promise resolving to it
+     */
+    getKey(): string | Promise<string>;
+}
+/**
+ * Retry strategy interface for handling request failures.
+ *
+ * Implement this interface to provide custom retry logic for
+ * handling rate limits, transient errors, and other failures.
+ *
+ * @example
+ * ```typescript
+ * class ExponentialBackoff implements RetryStrategy {
+ *   private maxAttempts = 5;
+ *   private baseDelay = 1000;
+ *
+ *   onRetry(error: UPPError, attempt: number): number | null {
+ *     if (attempt > this.maxAttempts) return null;
+ *     if (error.code !== 'RATE_LIMITED') return null;
+ *     return this.baseDelay * Math.pow(2, attempt - 1);
+ *   }
+ * }
+ * ```
+ */
+interface RetryStrategy {
+    /**
+     * Called when a request fails with a retryable error.
+     *
+     * @param error - The error that occurred
+     * @param attempt - The attempt number (1 = first retry)
+     * @returns Delay in ms before retrying, or null to stop retrying
+     */
+    onRetry(error: UPPError, attempt: number): number | null | Promise<number | null>;
+    /**
+     * Called before each request. Can be used to implement pre-emptive rate limiting.
+     *
+     * @returns Delay in ms to wait before making the request, or 0 to proceed immediately
+     */
+    beforeRequest?(): number | Promise<number>;
+    /**
+     * Reset the strategy state (e.g., after a successful request).
+     */
+    reset?(): void;
+}
+/**
+ * Provider identity shape for structural typing.
+ *
+ * Used in model input types to accept any provider instance
+ * without generic variance constraints.
+ */
+interface ProviderIdentity {
+    /** Provider name (e.g., 'openai', 'anthropic') */
+    readonly name: string;
+    /** Provider version string */
+    readonly version: string;
+}
+/**
+ * Provider configuration for infrastructure and connection settings.
+ *
+ * These settings control how requests are made to the provider's API,
+ * including authentication, timeouts, and retry behavior.
+ *
+ * @example
+ * ```typescript
+ * const config: ProviderConfig = {
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   timeout: 30000,
+ *   retryStrategy: new ExponentialBackoff()
+ * };
+ *
+ * // Or with a key strategy for key rotation
+ * const config: ProviderConfig = {
+ *   apiKey: new RoundRobinKeys(['sk-1', 'sk-2', 'sk-3']),
+ *   baseUrl: 'https://custom-proxy.example.com'
+ * };
+ * ```
+ */
+interface ProviderConfig {
+    /**
+     * API key for authentication.
+     * Can be a string, async function, or KeyStrategy for advanced use cases.
+     */
+    apiKey?: string | (() => string | Promise<string>) | KeyStrategy;
+    /** Override the base API URL (for proxies, local models) */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * Applied per attempt; total wall time can exceed this when retries are enabled.
+     */
+    timeout?: number;
+    /** Custom fetch implementation (for logging, caching, custom TLS) */
+    fetch?: typeof fetch;
+    /** API version override (provider-specific) */
+    apiVersion?: string;
+    /** Retry strategy for handling failures and rate limits */
+    retryStrategy?: RetryStrategy;
+    /**
+     * Custom headers to include in API requests.
+     *
+     * Use this to pass provider-specific headers such as:
+     * - Anthropic: `anthropic-beta` for beta features
+     * - OpenAI: `OpenAI-Organization`, `OpenAI-Project`
+     * - OpenRouter: `HTTP-Referer`, `X-Title` for attribution
+     * - Ollama: Proxy authentication headers
+     *
+     * @example
+     * ```typescript
+     * const config: ProviderConfig = {
+     *   headers: { 'anthropic-beta': 'extended-cache-ttl-2025-04-11' }
+     * };
+     * ```
+     */
+    headers?: Record<string, string | undefined>;
+    /**
+     * Maximum Retry-After delay in seconds when honoring server headers.
+     * Defaults to 3600 seconds (1 hour).
+     */
+    retryAfterMaxSeconds?: number;
+}
+/**
+ * A reference to a model, created by a provider factory.
+ *
+ * Model references are lightweight objects that identify a model
+ * and its provider, used as input to the llm() function.
+ *
+ * @typeParam TOptions - Provider-specific options type
+ *
+ * @example
+ * ```typescript
+ * const model = openai('gpt-4');
+ * console.log(model.modelId); // 'gpt-4'
+ * console.log(model.provider.name); // 'openai'
+ * ```
+ */
+interface ModelReference<TOptions = unknown> {
+    /** The model identifier (e.g., 'gpt-4', 'claude-3-opus') */
+    readonly modelId: string;
+    /** The provider that created this reference */
+    readonly provider: Provider<TOptions>;
+    /**
+     * Optional provider-specific configuration that gets merged into request config.
+     *
+     * This allows providers to store options set at model reference creation time
+     * (e.g., `anthropic('model', { betas: [...] })`) that should be applied to all requests.
+     * The `llm()` factory will merge these into the request config, with explicit config
+     * values taking precedence.
+     */
+    readonly providerConfig?: Partial<ProviderConfig>;
+    /**
+     * The original options passed when creating this model reference.
+     *
+     * Used by providers with multiple LLM handlers (e.g., OpenAI with responses/completions APIs)
+     * to resolve the correct handler at request time, avoiding race conditions from shared state.
+     */
+    readonly options?: TOptions;
+}
+/**
+ * LLM handler interface for providers.
+ *
+ * Implemented by providers to enable language model capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface LLMHandler<TParams = unknown> {
+    /**
+     * Binds a model ID to create an executable model instance.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound LLM model ready for inference
+     */
+    bind(modelId: string): BoundLLMModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     * Called by createProvider() after the provider is constructed.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: LLMProvider<TParams>): void;
+}
+/**
+ * Embedding handler interface for providers.
+ *
+ * Implemented by providers to enable embedding capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface EmbeddingHandler<TParams = unknown> {
+    /** Supported input types for embeddings */
+    readonly supportedInputs: ('text' | 'image')[];
+    /**
+     * Binds a model ID to create an executable embedding model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound embedding model ready for use
+     */
+    bind(modelId: string): BoundEmbeddingModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: EmbeddingProvider<TParams>): void;
+}
+/**
+ * Image handler interface for providers.
+ *
+ * Implemented by providers to enable image generation capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface ImageHandler<TParams = unknown> {
+    /**
+     * Binds a model ID to create an executable image model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound image model ready for generation
+     */
+    bind(modelId: string): BoundImageModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: ImageProvider<TParams>): void;
+}
+/**
+ * Bound embedding model interface.
+ *
+ * Represents an embedding model bound to a specific model ID,
+ * ready to generate embeddings.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundEmbeddingModel<TParams = unknown> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: EmbeddingProvider<TParams>;
+    /** Maximum number of inputs per batch request */
+    readonly maxBatchSize: number;
+    /** Maximum length of input text in tokens */
+    readonly maxInputLength: number;
+    /** Output embedding dimensions */
+    readonly dimensions: number;
+    /**
+     * Execute embedding request.
+     *
+     * @param request - The embedding request
+     * @returns Promise resolving to embedding response
+     */
+    embed(request: EmbeddingRequest<TParams>): Promise<EmbeddingResponse>;
+}
+/**
+ * Request passed to provider's embed method.
+ * @internal
+ */
+interface EmbeddingRequest<TParams = unknown> {
+    /** Inputs to embed */
+    inputs: EmbeddingInput[];
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Response from provider's embed method.
+ * @internal
+ */
+interface EmbeddingResponse {
+    /** Embedding vectors */
+    embeddings: EmbeddingVector[];
+    /** Aggregate usage */
+    usage: EmbeddingUsage;
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Single vector from provider response.
+ * @internal
+ */
+interface EmbeddingVector {
+    /** The embedding vector (floats or base64 string) */
+    vector: number[] | string;
+    /** Index in input array */
+    index: number;
+    /** Token count for this input */
+    tokens?: number;
+    /** Provider-specific per-embedding metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usage statistics for embedding operations.
+ */
+interface EmbeddingUsage {
+    /** Total tokens processed */
+    totalTokens: number;
+}
+/**
+ * Valid input types for embedding.
+ */
+type EmbeddingInput = string | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: unknown;
+    mimeType: string;
+};
+/**
+ * Bound image model interface.
+ *
+ * Represents an image generation model bound to a specific model ID.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+/**
+ * Provider factory function with metadata and modality handlers.
+ *
+ * The Provider interface represents a callable function that creates
+ * model references, along with metadata and modality-specific handlers.
+ *
+ * @typeParam TOptions - Provider-specific options passed to the factory
+ *
+ * @example
+ * ```typescript
+ * // Using a provider
+ * const model = openai('gpt-4', { temperature: 0.7 });
+ *
+ * // Accessing provider metadata
+ * console.log(openai.name); // 'openai'
+ * console.log(openai.version); // '1.0.0'
+ * ```
+ *
+ * @remarks
+ * Providers are intended to be used with `llm()`, `embedding()`, or `image()`.
+ * Direct handler access is not part of the public API.
+ */
+interface Provider<TOptions = unknown> extends ProviderIdentity {
+    /**
+     * Creates a model reference with optional provider-specific options.
+     *
+     * @param modelId - The model identifier
+     * @param options - Provider-specific options
+     * @returns A model reference for use with llm() or other functions
+     */
+    (modelId: string, options?: TOptions): ModelReference<TOptions>;
+    /** Provider name (e.g., 'openai', 'anthropic') */
+    readonly name: string;
+    /** Provider version string */
+    readonly version: string;
+}
+/**
+ * Provider with LLM modality support.
+ *
+ * Type alias for providers that support language model inference.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type LLMProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
+    /** @internal */
+    readonly __params?: TParams;
+};
+/**
+ * Provider with Embedding modality support.
+ *
+ * Type alias for providers that support embedding generation.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type EmbeddingProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
+    /** @internal */
+    readonly __params?: TParams;
+};
+/**
+ * Provider with Image modality support.
+ *
+ * Type alias for providers that support image generation.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type ImageProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
+    /** @internal */
+    readonly __params?: TParams;
+};
+
+/**
+ * @fileoverview Thread class for managing conversation history.
+ *
+ * Provides a utility class for building and manipulating conversation
+ * message sequences, with support for serialization and deserialization.
+ *
+ * @module types/thread
+ */
+
+/**
+ * Thread serialized to JSON format.
+ * Picks id from Thread, converts dates to strings.
+ */
+type ThreadJSON = Pick<Thread, 'id'> & {
+    messages: MessageJSON[];
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * Thread - A utility class for managing conversation history.
+ *
+ * Provides methods for building, manipulating, and persisting
+ * conversation message sequences. This class is optional; users
+ * can also manage their own `Message[]` arrays directly.
+ *
+ * @example
+ * ```typescript
+ * // Create a new thread and add messages
+ * const thread = new Thread();
+ * thread.user('Hello!');
+ * thread.assistant('Hi there! How can I help?');
+ *
+ * // Use with LLM inference
+ * const turn = await instance.generate(thread, 'What is 2+2?');
+ * thread.append(turn);
+ *
+ * // Serialize for storage
+ * const json = thread.toJSON();
+ * localStorage.setItem('chat', JSON.stringify(json));
+ *
+ * // Restore from storage
+ * const restored = Thread.fromJSON(JSON.parse(localStorage.getItem('chat')));
+ * ```
+ */
+declare class Thread {
+    /** Unique thread identifier */
+    readonly id: string;
+    /** Internal message storage */
+    private _messages;
+    /** Creation timestamp */
+    private _createdAt;
+    /** Last update timestamp */
+    private _updatedAt;
+    /**
+     * Creates a new thread instance.
+     *
+     * @param messages - Optional initial messages to populate the thread
+     */
+    constructor(messages?: Message[]);
+    /**
+     * All messages in the thread (readonly).
+     */
+    get messages(): readonly Message[];
+    /**
+     * Number of messages in the thread.
+     */
+    get length(): number;
+    /**
+     * Appends all messages from a Turn to the thread.
+     *
+     * @param turn - The Turn containing messages to append
+     * @returns This thread instance for chaining
+     */
+    append(turn: Turn): this;
+    /**
+     * Adds raw messages to the thread.
+     *
+     * @param messages - Messages to add
+     * @returns This thread instance for chaining
+     */
+    push(...messages: Message[]): this;
+    /**
+     * Adds a user message to the thread.
+     *
+     * @param content - String or array of content blocks
+     * @returns This thread instance for chaining
+     *
+     * @example
+     * ```typescript
+     * thread.user('Hello, world!');
+     * thread.user([
+     *   { type: 'text', text: 'Describe this image:' },
+     *   { type: 'image', source: { type: 'url', url: '...' }, mimeType: 'image/png' }
+     * ]);
+     * ```
+     */
+    user(content: string | UserContent[]): this;
+    /**
+     * Adds an assistant message to the thread.
+     *
+     * @param content - String or array of content blocks
+     * @returns This thread instance for chaining
+     *
+     * @example
+     * ```typescript
+     * thread.assistant('I can help with that!');
+     * ```
+     */
+    assistant(content: string | AssistantContent[]): this;
+    /**
+     * Filters messages by type.
+     *
+     * @param type - The message type to filter by
+     * @returns Array of messages matching the type
+     *
+     * @example
+     * ```typescript
+     * const userMessages = thread.filter('user');
+     * const assistantMessages = thread.filter('assistant');
+     * ```
+     */
+    filter(type: MessageType): Message[];
+    /**
+     * Returns the last N messages from the thread.
+     *
+     * @param count - Number of messages to return
+     * @returns Array of the last N messages
+     *
+     * @example
+     * ```typescript
+     * const recent = thread.tail(5);
+     * ```
+     */
+    tail(count: number): Message[];
+    /**
+     * Creates a new thread with a subset of messages.
+     *
+     * @param start - Start index (inclusive)
+     * @param end - End index (exclusive)
+     * @returns New Thread containing the sliced messages
+     *
+     * @example
+     * ```typescript
+     * const subset = thread.slice(0, 10);
+     * ```
+     */
+    slice(start?: number, end?: number): Thread;
+    /**
+     * Removes all messages from the thread.
+     *
+     * @returns This thread instance for chaining
+     */
+    clear(): this;
+    /**
+     * Converts the thread to a plain message array.
+     *
+     * @returns Copy of the internal message array
+     */
+    toMessages(): Message[];
+    /**
+     * Serializes the thread to JSON format.
+     *
+     * @returns JSON-serializable representation of the thread
+     *
+     * @example
+     * ```typescript
+     * const json = thread.toJSON();
+     * localStorage.setItem('thread', JSON.stringify(json));
+     * ```
+     */
+    toJSON(): ThreadJSON;
+    /**
+     * Deserializes a thread from JSON format.
+     *
+     * @param json - The JSON representation to deserialize
+     * @returns Reconstructed Thread instance
+     *
+     * @example
+     * ```typescript
+     * const json = JSON.parse(localStorage.getItem('thread'));
+     * const thread = Thread.fromJSON(json);
+     * ```
+     */
+    static fromJSON(json: ThreadJSON): Thread;
+    /**
+     * Enables iteration over messages with for...of loops.
+     *
+     * @returns Iterator over the thread's messages
+     *
+     * @example
+     * ```typescript
+     * for (const message of thread) {
+     *   console.log(message.text);
+     * }
+     * ```
+     */
+    [Symbol.iterator](): Iterator<Message>;
+    /**
+     * Converts a message to JSON format.
+     */
+    private messageToJSON;
+    /**
+     * Reconstructs a message from JSON format.
+     */
+    private static messageFromJSON;
+}
+
+/**
+ * @fileoverview LLM types for language model inference.
+ *
+ * Defines the interfaces for configuring and executing LLM inference,
+ * including options, instances, requests, responses, and capabilities.
+ *
+ * @module types/llm
+ */
+
+/**
+ * Structural type for model input that accepts any ModelReference.
+ * Uses structural typing to avoid generic variance issues with Provider generics.
+ * The nested types use `unknown` to accept any provider parameter types.
+ *
+ * @remarks
+ * This type mirrors {@link ModelReference} while keeping provider options
+ * structurally compatible across providers.
+ *
+ * @see ModelReference
+ */
+type ModelInput = {
+    readonly modelId: string;
+    readonly provider: ProviderIdentity;
+    /**
+     * Optional provider-specific configuration that gets merged into request config.
+     * Set when creating a model reference with provider-specific options.
+     */
+    readonly providerConfig?: Partial<ProviderConfig>;
+    /**
+     * The original options passed when creating this model reference.
+     * Used by providers with multiple LLM handlers to resolve the correct handler.
+     */
+    readonly options?: unknown;
+};
+/**
+ * LLM capabilities declare what a provider's API supports.
+ *
+ * These are API-level capabilities, not individual model capabilities.
+ * If a user attempts to use a feature with a model that doesn't support it,
+ * the provider's API will return an error.
+ *
+ * Capabilities are static and do not vary per-request or per-model.
+ *
+ * @example
+ * ```typescript
+ * const capabilities: LLMCapabilities = {
+ *   streaming: true,
+ *   tools: true,
+ *   structuredOutput: true,
+ *   imageInput: true,
+ *   videoInput: false,
+ *   audioInput: false
+ * };
+ * ```
+ */
+interface LLMCapabilities {
+    /** Provider API supports streaming responses */
+    streaming: boolean;
+    /** Provider API supports tool/function calling */
+    tools: boolean;
+    /** Provider API supports native structured output (JSON schema) */
+    structuredOutput: boolean;
+    /** Provider API supports image input in messages */
+    imageInput: boolean;
+    /** Provider API supports document input in messages (PDFs, text files) */
+    documentInput: boolean;
+    /** Provider API supports video input in messages */
+    videoInput: boolean;
+    /** Provider API supports audio input in messages */
+    audioInput: boolean;
+    /** Provider API supports image generation output (via image() or built-in tools) */
+    imageOutput?: boolean;
+}
+/**
+ * Valid input types for inference.
+ *
+ * Inference input can be a simple string, a Message object, or
+ * a raw ContentBlock for multimodal input.
+ */
+type InferenceInput = string | Message | ContentBlock;
+/**
+ * Options for creating an LLM instance with the llm() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const options: LLMOptions = {
+ *   model: openai('gpt-4'),
+ *   system: 'You are a helpful assistant.',
+ *   params: { temperature: 0.7, max_tokens: 1000 },
+ *   tools: [weatherTool, searchTool],
+ *   toolStrategy: { maxIterations: 5 }
+ * };
+ *
+ * const instance = llm(options);
+ * ```
+ */
+interface LLMOptions<TParams = unknown> {
+    /** A model reference from a provider factory */
+    model: ModelInput;
+    /** Provider infrastructure configuration (optional - uses env vars if omitted) */
+    config?: ProviderConfig;
+    /** Model-specific parameters (temperature, max_tokens, etc.) */
+    params?: TParams;
+    /**
+     * System prompt for all inferences.
+     *
+     * Can be a simple string or a provider-specific array format:
+     * - Anthropic: `[{type: 'text', text: '...', cache_control?: {...}}]`
+     * - Google: `[{text: '...'}, {text: '...'}]` (parts array)
+     *
+     * Array formats are passed through directly to the provider.
+     */
+    system?: string | unknown[];
+    /** Tools available to the model */
+    tools?: Tool[];
+    /** Tool execution strategy */
+    toolStrategy?: ToolUseStrategy;
+    /** Structured output schema (JSON Schema) */
+    structure?: JSONSchema;
+}
+/**
+ * LLM instance returned by the llm() function.
+ *
+ * Provides methods for generating responses and streaming output,
+ * with access to the bound model and capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * import { llm, openai, StreamEventType } from 'provider-protocol';
+ *
+ * const instance = llm({ model: openai('gpt-4') });
+ *
+ * // Simple generation
+ * const turn = await instance.generate('Hello!');
+ * console.log(turn.response.text);
+ *
+ * // Streaming
+ * const stream = instance.stream('Tell me a story');
+ * for await (const event of stream) {
+ *   if (event.type === StreamEventType.TextDelta) {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   }
+ * }
+ * const finalTurn = await stream.turn;
+ * ```
+ */
+interface LLMInstance<TParams = unknown> {
+    /**
+     * Executes inference and returns the complete Turn.
+     *
+     * Supports multiple calling patterns:
+     * - Single input: `generate('Hello')`
+     * - Multiple inputs: `generate('Context...', 'Question?')`
+     * - With history: `generate(messages, 'Follow-up?')`
+     * - With thread: `generate(thread, 'Next message')`
+     *
+     * @param historyOrInput - History (Message[] or Thread) or first input
+     * @param input - Additional inputs to include in the request
+     * @returns Promise resolving to the complete Turn
+     */
+    generate(historyOrInput: Message[] | Thread | InferenceInput, ...input: InferenceInput[]): Promise<Turn>;
+    /**
+     * Executes streaming inference.
+     *
+     * Returns an async iterable of stream events that can also
+     * be awaited for the final Turn.
+     *
+     * @param historyOrInput - History (Message[] or Thread) or first input
+     * @param input - Additional inputs to include in the request
+     * @returns StreamResult that yields events and resolves to Turn
+     */
+    stream(historyOrInput: Message[] | Thread | InferenceInput, ...input: InferenceInput[]): StreamResult;
+    /** The bound model instance */
+    readonly model: BoundLLMModel<TParams>;
+    /** Current system prompt (string or provider-specific array format) */
+    readonly system: string | unknown[] | undefined;
+    /** Current model parameters */
+    readonly params: TParams | undefined;
+    /** Provider API capabilities */
+    readonly capabilities: LLMCapabilities;
+}
+/**
+ * Request passed from the llm() core to providers.
+ *
+ * Contains all information needed by a provider to execute inference.
+ * The config is required here because llm() resolves defaults before
+ * passing to providers.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface LLMRequest<TParams = unknown> {
+    /** All messages for this request (history + new input) */
+    messages: Message[];
+    /**
+     * System prompt - string or provider-specific array format.
+     * Arrays are passed through directly to the provider.
+     */
+    system?: string | unknown[];
+    /** Model-specific parameters (passed through unchanged) */
+    params?: TParams;
+    /** Tools available for this request */
+    tools?: Tool[];
+    /** Structured output schema (if requested) */
+    structure?: JSONSchema;
+    /** Provider infrastructure config (resolved by llm() core) */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Raw provider response from a single inference cycle.
+ *
+ * Does not include tool loop handling - that's managed by llm() core.
+ *
+ * @internal
+ */
+interface LLMResponse {
+    /** The assistant's response message */
+    message: AssistantMessage;
+    /** Token usage for this cycle */
+    usage: TokenUsage;
+    /** Stop reason from the provider */
+    stopReason: string;
+    /**
+     * Structured output data extracted by the provider.
+     * Present when a structure schema was requested and successfully extracted.
+     */
+    data?: unknown;
+}
+/**
+ * Raw provider stream result.
+ *
+ * An async iterable of stream events with a Promise that resolves
+ * to the complete response after streaming finishes.
+ *
+ * @internal
+ */
+interface LLMStreamResult extends AsyncIterable<StreamEvent> {
+    /** Promise resolving to the complete response */
+    readonly response: Promise<LLMResponse>;
+}
+/**
+ * Bound LLM model - full definition.
+ *
+ * Represents a model bound to a specific provider and model ID,
+ * ready to execute inference requests.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundLLMModel<TParams = unknown> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: LLMProvider<TParams>;
+    /** Provider API capabilities */
+    readonly capabilities: LLMCapabilities;
+    /**
+     * Executes a single non-streaming inference request.
+     *
+     * @param request - The inference request
+     * @returns Promise resolving to the response
+     */
+    complete(request: LLMRequest<TParams>): Promise<LLMResponse>;
+    /**
+     * Executes a single streaming inference request.
+     *
+     * @param request - The inference request
+     * @returns Stream result with events and final response
+     */
+    stream(request: LLMRequest<TParams>): LLMStreamResult;
+}
+
+export { MessageRole as $, type AudioBlock as A, type BinaryBlock as B, type ContentBlock as C, type DocumentSource as D, type EmbeddingHandler as E, isBinaryBlock as F, type Tool as G, type ToolCall as H, type ImageOptions as I, type JSONSchema as J, type ToolResult as K, type LLMOptions as L, type ModelReference as M, type ToolMetadata as N, type ToolUseStrategy as O, type Provider as P, type BeforeCallResult as Q, type ReasoningBlock as R, type AfterCallResult as S, type TextBlock as T, UPPError as U, type VideoBlock as V, type ToolExecution as W, Message as X, UserMessage as Y, AssistantMessage as Z, ToolResultMessage as _, type LLMInstance as a, isUserMessage as a0, isAssistantMessage as a1, isToolResultMessage as a2, type MessageType as a3, type MessageMetadata as a4, type MessageOptions as a5, type Turn as a6, type TokenUsage as a7, createTurn as a8, emptyUsage as a9, type EmbeddingUsage as aA, type EmbeddingInput as aB, type LLMCapabilities as aC, type LLMRequest as aD, type LLMResponse as aE, type LLMStreamResult as aF, type BoundLLMModel as aG, type InferenceInput as aH, type ImageInput as aI, type ImageEditInput as aJ, type ImageGenerateOptions as aK, type GeneratedImage as aL, type ImageUsage as aM, type ImageResult as aN, type ImageStreamEvent as aO, type ImageStreamResult as aP, type ImageCapabilities as aQ, type ImageRequest as aR, type ImageEditRequest as aS, type ImageResponse as aT, type ImageProviderStreamResult as aU, type BoundImageModel as aV, type ImageModelInput as aW, type TurnJSON as aX, aggregateUsage as aa, Thread as ab, type ThreadJSON as ac, type MessageJSON as ad, type StreamEvent as ae, type EventDelta as af, type StreamResult as ag, StreamEventType as ah, createStreamResult as ai, textDelta as aj, toolCallDelta as ak, messageStart as al, messageStop as am, contentBlockStart as an, contentBlockStop as ao, type ProviderIdentity as ap, type ProviderConfig as aq, type KeyStrategy as ar, type RetryStrategy as as, type LLMProvider as at, type EmbeddingProvider as au, type ImageProvider as av, type BoundEmbeddingModel as aw, type EmbeddingRequest as ax, type EmbeddingResponse as ay, type EmbeddingVector as az, type ImageInstance as b, type LLMHandler as c, type ImageHandler as d, type DocumentBlock as e, Image as f, ErrorCode as g, ModalityType as h, type Modality as i, type JSONSchemaProperty as j, type JSONSchemaPropertyType as k, type ImageBlock as l, type ImageSource as m, type UserContent as n, type AssistantContent as o, ContentBlockType as p, ImageSourceType as q, DocumentSourceType as r, reasoning as s, text as t, isTextBlock as u, isReasoningBlock as v, isImageBlock as w, isDocumentBlock as x, isAudioBlock as y, isVideoBlock as z };