@providerprotocol/ai 0.0.11 → 0.0.13

package/dist/index.d.ts

@@ -1,12 +1,41 @@
-import { M as ModelReference, P as ProviderConfig, L as LLMProvider, a as LLMHandler$1, E as EmbeddingHandler, I as ImageHandler, b as Provider } from './provider-CUJWjgNl.js';
-export { B as BoundEmbeddingModel, g as BoundImageModel, e as EmbeddingProvider, c as ErrorCode, f as ImageProvider, K as KeyStrategy, d as Modality, R as RetryStrategy, U as UPPError } from './provider-CUJWjgNl.js';
-export { D as DynamicKey, E as ExponentialBackoff, L as LinearBackoff, N as NoRetry, a as RetryAfterStrategy, R as RoundRobinKeys, T as TokenBucket, W as WeightedKeys } from './retry-I2661_rv.js';
+import { M as ModelReference, P as ProviderConfig, L as LLMProvider, a as LLMHandler$1, E as EmbeddingHandler, I as ImageHandler, b as Provider } from './provider-mKkz7Q9U.js';
+export { B as BoundEmbeddingModel, g as BoundImageModel, e as EmbeddingProvider, c as ErrorCode, f as ImageProvider, K as KeyStrategy, d as Modality, R as RetryStrategy, U as UPPError } from './provider-mKkz7Q9U.js';
+export { D as DynamicKey, E as ExponentialBackoff, L as LinearBackoff, N as NoRetry, a as RetryAfterStrategy, R as RoundRobinKeys, T as TokenBucket, W as WeightedKeys } from './retry-Dh70lgr0.js';
 
 /**
- * Content block types for messages
+ * @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
  */
 /**
- * Image source types
+ * 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';
@@ -19,186 +48,639 @@ type ImageSource = {
     data: Uint8Array;
 };
 /**
- * Text content block
+ * 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;
 }
 /**
- * Image content block
+ * 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;
 }
 /**
- * Audio content block
+ * 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
+ * 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
+ * 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>;
 }
 /**
- * All content block types
+ * Union of all content block types.
+ *
+ * Used when a function or property can accept any type of content block.
  */
 type ContentBlock = TextBlock | ImageBlock | AudioBlock | VideoBlock | BinaryBlock;
 /**
- * Content types allowed in user messages
+ * Content types allowed in user messages.
+ *
+ * Users can send any type of content block including binary data.
  */
 type UserContent = TextBlock | ImageBlock | AudioBlock | VideoBlock | BinaryBlock;
 /**
- * Content types allowed in assistant messages
+ * Content types allowed in assistant messages.
+ *
+ * Assistants can generate text and media but not arbitrary binary data.
  */
 type AssistantContent = TextBlock | ImageBlock | AudioBlock | VideoBlock;
 /**
- * Helper to create a text block
+ * 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;
 /**
- * Type guard for TextBlock
+ * 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 ImageBlock
+ * 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 AudioBlock
+ * 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
+ * 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
+ * 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;
 
 /**
- * JSON Schema types for tool parameters and structured outputs
+ * @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
  */
-type JSONSchemaPropertyType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
 /**
- * JSON Schema property definition
+ * 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;
 }
 /**
- * JSON Schema for tool parameters or structured outputs
+ * 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;
 }
 
 /**
- * Tool call requested by the model
+ * @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
+ * 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
+ * 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 a llm() instance) */
+    /** Tool name (must be unique within an llm() instance) */
     name: string;
-    /** Human-readable description for the model */
+    /** Human-readable description for the model to understand when to use this tool */
     description: string;
-    /** JSON Schema defining parameters */
+    /** JSON Schema defining the tool's parameters */
     parameters: JSONSchema;
-    /** Tool execution function */
+    /**
+     * 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 */
+    /**
+     * 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>;
 }
 /**
- * Strategy for tool execution
+ * 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 tool execution rounds (default: 10) */
+    /** Maximum number of tool execution rounds (default: 10) */
     maxIterations?: number;
-    /** Called when the model requests a tool call */
+    /**
+     * 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, return false to skip */
-    onBeforeCall?(tool: Tool, params: unknown): boolean | Promise<boolean>;
-    /** Called after tool execution */
-    onAfterCall?(tool: Tool, params: unknown, result: unknown): void | Promise<void>;
-    /** Called on tool execution error */
+    /**
+     * 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 max iterations reached */
+    /**
+     * 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 tool execution
+ * 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 {
-    /** The tool that was called */
+    /** Name of the tool that was called */
     toolName: string;
-    /** Tool call ID */
+    /** Unique identifier for this tool call */
     toolCallId: string;
-    /** Arguments passed to the tool */
+    /** Arguments that were passed to the tool */
     arguments: Record<string, unknown>;
     /** Result returned by the tool */
     result: unknown;
@@ -206,146 +688,334 @@ interface ToolExecution {
     isError: boolean;
     /** Execution duration in milliseconds */
     duration: number;
-    /** Whether approval was required and granted */
+    /** Whether approval was required and granted (undefined if no approval handler) */
     approved?: boolean;
 }
 
 /**
- * Message type discriminator
+ * @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 type discriminator.
+ *
+ * Used to distinguish between different message types in a conversation.
  */
 type MessageType = 'user' | 'assistant' | 'tool_result';
 /**
- * Provider-namespaced metadata
- * Each provider uses its own namespace
+ * 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 message construction
+ * Options for constructing messages.
  */
 interface MessageOptions {
+    /** Custom message ID (auto-generated if not provided) */
     id?: string;
+    /** Provider-specific metadata */
     metadata?: MessageMetadata;
 }
 /**
- * Base message class
- * All messages inherit from this
+ * 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 */
+    /** Timestamp when the message was created */
     readonly timestamp: Date;
-    /** Provider-specific metadata, namespaced by provider */
+    /** Provider-specific metadata, namespaced by provider name */
     readonly metadata?: MessageMetadata;
-    /** Message type discriminator */
+    /** Message type discriminator (implemented by subclasses) */
     abstract readonly type: MessageType;
-    /** Raw content - implemented by subclasses */
+    /**
+     * 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);
     /**
-     * Convenience accessor for text content
-     * Concatenates all text blocks with '\n\n'
+     * Concatenated text content from all text blocks.
+     * Blocks are joined with double newlines.
      */
     get text(): string;
     /**
-     * Convenience accessor for image content blocks
+     * All image content blocks in this message.
      */
     get images(): ImageBlock[];
     /**
-     * Convenience accessor for audio content blocks
+     * All audio content blocks in this message.
      */
     get audio(): AudioBlock[];
     /**
-     * Convenience accessor for video content blocks
+     * All video content blocks in this message.
      */
     get video(): VideoBlock[];
 }
 /**
- * User input message
+ * 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
- * May contain text, media, and/or tool calls
+ * 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 - Message ID and metadata
+     * @param options - Optional message ID and metadata
      */
     constructor(content: string | AssistantContent[], toolCalls?: ToolCall[], options?: MessageOptions);
     protected getContent(): ContentBlock[];
-    /** Check if this message requests tool execution */
+    /**
+     * Whether this message contains tool call requests.
+     */
     get hasToolCalls(): boolean;
 }
 /**
- * Result of tool execution (sent back to model)
+ * 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 - Message ID and metadata
+     * @param options - Optional message ID and metadata
      */
     constructor(results: ToolResult[], options?: MessageOptions);
     protected getContent(): ContentBlock[];
 }
 /**
- * Type guard for UserMessage
+ * 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
+ * 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
+ * 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;
 
 /**
- * Token usage information
+ * @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 },
+ *     { inputTokens: 50, outputTokens: 20 }
+ *   ]
+ * };
+ * ```
  */
 interface TokenUsage {
-    /** Input tokens across all cycles */
+    /** Total input tokens across all cycles */
     inputTokens: number;
-    /** Output tokens across all cycles */
+    /** Total output tokens across all cycles */
     outputTokens: number;
-    /** Total tokens */
+    /** Sum of input and output tokens */
     totalTokens: number;
-    /** Per-cycle breakdown (if available) */
+    /**
+     * 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;
     }>;
 }
 /**
- * A Turn represents the complete result of one inference call,
- * including all messages produced during tool execution loops.
+ * 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.
-     * Types: UserMessage, AssistantMessage (may include toolCalls), ToolResultMessage
+     * Includes UserMessage, AssistantMessage (may include toolCalls), and ToolResultMessage.
      */
     readonly messages: Message[];
-    /** The final assistant response (convenience accessor) */
+    /** The final assistant response (last AssistantMessage in the turn) */
     readonly response: AssistantMessage;
     /** Tool executions that occurred during this turn */
     readonly toolExecutions: ToolExecution[];
@@ -354,120 +1024,320 @@ interface Turn<TData = unknown> {
     /** Total number of inference cycles (1 + number of tool rounds) */
     readonly cycles: number;
     /**
-     * Structured output data (if structure was provided).
+     * Structured output data (if a structure schema was provided).
      * Type is inferred from the schema when using TypeScript.
      */
     readonly data?: TData;
 }
 /**
- * Create a Turn from accumulated data
+ * 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>;
 /**
- * Create empty token usage
+ * 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;
 /**
- * Aggregate token usage from multiple cycles
+ * 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;
 
 /**
- * Stream event types
+ * @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
  */
-type StreamEventType = 'text_delta' | 'reasoning_delta' | 'image_delta' | 'audio_delta' | 'video_delta' | 'tool_call_delta' | 'tool_execution_start' | 'tool_execution_end' | 'message_start' | 'message_stop' | 'content_block_start' | 'content_block_stop';
+
 /**
- * Event delta data (type-specific)
+ * Stream event type discriminators.
+ *
+ * Each event type represents a different kind of streaming update
+ * from the LLM provider.
+ */
+type StreamEventType = 
+/** Incremental text output */
+'text_delta'
+/** Incremental reasoning/thinking output */
+ | 'reasoning_delta'
+/** Incremental image data */
+ | 'image_delta'
+/** Incremental audio data */
+ | 'audio_delta'
+/** Incremental video data */
+ | 'video_delta'
+/** Incremental tool call data (arguments being streamed) */
+ | 'tool_call_delta'
+/** Tool execution has started */
+ | 'tool_execution_start'
+/** Tool execution has completed */
+ | 'tool_execution_end'
+/** Beginning of a message */
+ | 'message_start'
+/** End of a message */
+ | 'message_stop'
+/** Beginning of a content block */
+ | 'content_block_start'
+/** End of a content block */
+ | 'content_block_stop';
+/**
+ * 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 errored (for tool_execution_end) */
+    /** Whether tool execution resulted in an error (for tool_execution_end) */
     isError?: boolean;
-    /** Timestamp in ms (for tool_execution_start/end) */
+    /** Timestamp in milliseconds (for tool_execution_start/end) */
     timestamp?: number;
 }
 /**
- * A streaming event
+ * 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
+ * for await (const event of stream) {
+ *   if (event.type === 'text_delta') {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   } else if (event.type === 'tool_call_delta') {
+ *     console.log('Tool:', event.delta.toolName);
+ *   }
+ * }
+ * ```
  */
 interface StreamEvent {
-    /** Event type */
+    /** Event type discriminator */
     type: StreamEventType;
     /** Index of the content block this event belongs to */
     index: number;
-    /** Event data (type-specific) */
+    /** Event-specific data payload */
     delta: EventDelta;
 }
 /**
- * Stream result - async iterable that also provides final turn
+ * 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
+ * const stream = instance.stream('Tell me a story');
+ *
+ * // Consume streaming events
+ * for await (const event of stream) {
+ *   if (event.type === 'text_delta') {
+ *     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> {
     /**
-     * Get the complete Turn after streaming finishes.
-     * Resolves when the stream completes.
+     * Promise that resolves to the complete Turn after streaming finishes.
      */
     readonly turn: Promise<Turn<TData>>;
-    /** Abort the stream */
+    /**
+     * Aborts the stream, stopping further events and cancelling the request.
+     */
     abort(): void;
 }
 /**
- * Create a stream result from an async generator and completion promise
+ * 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 turnPromise - Promise 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>, turnPromise: Promise<Turn<TData>>, abortController: AbortController): StreamResult<TData>;
 /**
- * Create a text delta event
+ * 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;
 /**
- * Create a tool call delta event
+ * 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;
 /**
- * Create a message start event
+ * Creates a message start stream event.
+ *
+ * @returns A message_start StreamEvent
  */
 declare function messageStart(): StreamEvent;
 /**
- * Create a message stop event
+ * Creates a message stop stream event.
+ *
+ * @returns A message_stop StreamEvent
  */
 declare function messageStop(): StreamEvent;
 /**
- * Create a content block start event
+ * 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;
 /**
- * Create a content block stop event
+ * 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;
 
 /**
- * Serialized message format
+ * @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
+ */
+
+/**
+ * Serialized message format for JSON storage.
+ *
+ * Used when persisting messages to storage or transmitting over the network.
  */
 interface MessageJSON {
+    /** Unique message identifier */
     id: string;
+    /** Message type discriminator */
     type: MessageType;
+    /** Content blocks in the message */
     content: ContentBlock[];
+    /** Tool calls (for assistant messages) */
     toolCalls?: ToolCall[];
+    /** Tool results (for tool result messages) */
     results?: ToolResult[];
+    /** Provider-specific metadata */
     metadata?: MessageMetadata;
+    /** ISO timestamp string */
     timestamp: string;
 }
 /**
- * Serialized thread format
+ * Serialized thread format for JSON storage.
+ *
+ * Contains all data needed to reconstruct a Thread instance.
  */
 interface ThreadJSON {
+    /** Unique thread identifier */
     id: string;
+    /** Serialized messages */
     messages: MessageJSON[];
+    /** ISO timestamp of thread creation */
     createdAt: string;
+    /** ISO timestamp of last update */
     updatedAt: string;
 }
 /**
- * Thread - A utility class for managing conversation history
- * Users control their own history; Thread is optional
+ * 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 */
@@ -479,78 +1349,188 @@ declare class Thread {
     /** Last update timestamp */
     private _updatedAt;
     /**
-     * Create a new thread, optionally with initial messages
+     * Creates a new thread instance.
+     *
+     * @param messages - Optional initial messages to populate the thread
      */
     constructor(messages?: Message[]);
-    /** All messages in the thread (readonly) */
+    /**
+     * All messages in the thread (readonly).
+     */
     get messages(): readonly Message[];
-    /** Number of messages */
+    /**
+     * Number of messages in the thread.
+     */
     get length(): number;
     /**
-     * Append messages from a turn
+     * 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;
     /**
-     * Add raw messages
+     * Adds raw messages to the thread.
+     *
+     * @param messages - Messages to add
+     * @returns This thread instance for chaining
      */
     push(...messages: Message[]): this;
     /**
-     * Add a user message
+     * 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;
     /**
-     * Add an assistant message
+     * 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;
     /**
-     * Get messages by type
+     * 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[];
     /**
-     * Get the last N messages
+     * 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[];
     /**
-     * Create a new thread with a subset of messages
+     * 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;
     /**
-     * Clear all messages
+     * Removes all messages from the thread.
+     *
+     * @returns This thread instance for chaining
      */
     clear(): this;
     /**
-     * Convert to plain message array
+     * Converts the thread to a plain message array.
+     *
+     * @returns Copy of the internal message array
      */
     toMessages(): Message[];
     /**
-     * Serialize to JSON
+     * 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;
     /**
-     * Deserialize from JSON
+     * 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;
     /**
-     * Iterate over messages
+     * 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>;
     /**
-     * Convert a message to JSON
+     * Converts a message to JSON format.
      */
     private messageToJSON;
     /**
-     * Reconstruct a message from JSON
+     * Reconstructs a message from JSON format.
      */
     private static messageFromJSON;
 }
 
 /**
- * LLMCapabilities declares what the provider's API supports, not individual model capabilities.
+ * @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
+ */
+
+/**
+ * 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—this is expected behavior.
+ * the provider's API will return an error.
  *
- * Capabilities are static - they are constant for the lifetime of the provider instance
- * and do not vary per-request or per-model.
+ * 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 */
@@ -559,19 +1539,37 @@ interface LLMCapabilities {
     tools: boolean;
     /** Provider API supports native structured output (JSON schema) */
     structuredOutput: boolean;
-    /** Provider API supports image input */
+    /** Provider API supports image input in messages */
     imageInput: boolean;
-    /** Provider API supports video input */
+    /** Provider API supports video input in messages */
     videoInput: boolean;
-    /** Provider API supports audio input */
+    /** Provider API supports audio input in messages */
     audioInput: boolean;
 }
 /**
- * Input types for inference
+ * 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 llm() function
+ * 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 */
@@ -580,8 +1578,16 @@ interface LLMOptions<TParams = unknown> {
     config?: ProviderConfig;
     /** Model-specific parameters (temperature, max_tokens, etc.) */
     params?: TParams;
-    /** System prompt for all inferences */
-    system?: string;
+    /**
+     * 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 */
@@ -590,54 +1596,84 @@ interface LLMOptions<TParams = unknown> {
     structure?: JSONSchema;
 }
 /**
- * LLM instance returned by llm()
+ * 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
+ * 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 === 'text_delta') {
+ *     process.stdout.write(event.delta.text ?? '');
+ *   }
+ * }
+ * const finalTurn = await stream.turn;
+ * ```
  */
 interface LLMInstance<TParams = unknown> {
     /**
-     * Execute inference and return complete Turn
+     * Executes inference and returns the complete Turn.
      *
-     * @overload No history - single input
-     * generate(input: InferenceInput): Promise<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')`
      *
-     * @overload No history - multiple inputs
-     * generate(...inputs: InferenceInput[]): Promise<Turn>
-     *
-     * @overload With history
-     * generate(history: Message[] | Thread, ...inputs: InferenceInput[]): Promise<Turn>
+     * @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>;
     /**
-     * Execute streaming inference
-     *
-     * @overload No history - single input
-     * stream(input: InferenceInput): StreamResult
+     * Executes streaming inference.
      *
-     * @overload No history - multiple inputs
-     * stream(...inputs: InferenceInput[]): StreamResult
+     * Returns an async iterable of stream events that can also
+     * be awaited for the final Turn.
      *
-     * @overload With history
-     * stream(history: Message[] | Thread, ...inputs: InferenceInput[]): StreamResult
+     * @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 */
+    /** The bound model instance */
     readonly model: BoundLLMModel<TParams>;
-    /** Current system prompt */
-    readonly system: string | undefined;
-    /** Current parameters */
+    /** 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 llm() core to providers
- * Note: config is required here because llm() core resolves defaults
- * before passing to providers
+ * 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 */
-    system?: string;
+    /**
+     * 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 */
@@ -650,28 +1686,44 @@ interface LLMRequest<TParams = unknown> {
     signal?: AbortSignal;
 }
 /**
- * Raw provider response (single cycle, no tool loop)
+ * 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 the provider
-     * successfully extracted the data (via tool call or native JSON mode).
-     * Providers handle their own extraction logic - core just uses this value.
+     * Present when a structure schema was requested and successfully extracted.
      */
     data?: unknown;
 }
 /**
- * Raw provider stream result
+ * 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
+ * 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 */
@@ -680,131 +1732,363 @@ interface BoundLLMModel<TParams = unknown> {
     readonly provider: LLMProvider<TParams>;
     /** Provider API capabilities */
     readonly capabilities: LLMCapabilities;
-    /** Execute a single non-streaming inference request */
+    /**
+     * Executes a single non-streaming inference request.
+     *
+     * @param request - The inference request
+     * @returns Promise resolving to the response
+     */
     complete(request: LLMRequest<TParams>): Promise<LLMResponse>;
-    /** Execute a single streaming inference request */
+    /**
+     * Executes a single streaming inference request.
+     *
+     * @param request - The inference request
+     * @returns Stream result with events and final response
+     */
     stream(request: LLMRequest<TParams>): LLMStreamResult;
 }
 /**
- * LLM Handler for providers
+ * LLM Handler interface for providers.
+ *
+ * Implemented by providers to enable language model capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
  */
 interface LLMHandler<TParams = unknown> {
-    /** Bind model ID to create executable model */
+    /**
+     * 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>;
     /**
-     * Internal: Set the parent provider reference.
+     * Sets the parent provider reference.
      * Called by createProvider() after the provider is constructed.
-     * This allows bind() to return models with the correct provider reference.
+     *
+     * @param provider - The parent provider
      * @internal
      */
     _setProvider?(provider: LLMProvider<TParams>): void;
 }
 
 /**
- * Create an LLM instance
+ * @fileoverview LLM instance factory and streaming logic for the Universal Provider Protocol.
+ *
+ * This module provides the core functionality for creating and managing LLM instances,
+ * including support for tool execution, streaming responses, and structured output.
+ *
+ * @module core/llm
+ */
+
+/**
+ * Creates an LLM instance configured with the specified options.
+ *
+ * This is the primary factory function for creating LLM instances. It validates
+ * provider capabilities, binds the model, and returns an instance with `generate`
+ * and `stream` methods for inference.
+ *
+ * @typeParam TParams - Provider-specific parameter type for model configuration
+ * @param options - Configuration options for the LLM instance
+ * @returns A configured LLM instance ready for inference
+ * @throws {UPPError} When the provider does not support the LLM modality
+ * @throws {UPPError} When structured output is requested but not supported
+ * @throws {UPPError} When tools are provided but not supported
+ *
+ * @example
+ * ```typescript
+ * import { llm } from 'upp';
+ * import { anthropic } from 'upp/providers/anthropic';
+ *
+ * const assistant = llm({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   system: 'You are a helpful assistant.',
+ *   tools: [myTool],
+ * });
+ *
+ * const turn = await assistant.generate('Hello, world!');
+ * console.log(turn.text);
+ * ```
  */
 declare function llm<TParams = unknown>(options: LLMOptions<TParams>): LLMInstance<TParams>;
 
 /**
- * Options for creating a provider
+ * @fileoverview Base provider interface and factory for the Universal Provider Protocol.
+ *
+ * This module provides the foundation for creating AI providers that conform to the
+ * UPP specification. Providers are callable functions that create model references
+ * and expose modality handlers (LLM, embedding, image).
+ *
+ * @module core/provider
+ */
+
+/**
+ * Configuration options for creating a new provider.
+ *
+ * @example
+ * ```typescript
+ * const options: CreateProviderOptions = {
+ *   name: 'my-provider',
+ *   version: '1.0.0',
+ *   modalities: {
+ *     llm: createLLMHandler(),
+ *     embedding: createEmbeddingHandler(),
+ *   },
+ * };
+ * ```
  */
 interface CreateProviderOptions {
+    /** Unique identifier for the provider */
     name: string;
+    /** Semantic version string for the provider implementation */
     version: string;
+    /** Handlers for supported modalities (LLM, embedding, image generation) */
     modalities: {
+        /** Handler for language model completions */
         llm?: LLMHandler$1;
+        /** Handler for text embeddings */
         embedding?: EmbeddingHandler;
+        /** Handler for image generation */
         image?: ImageHandler;
     };
 }
 /**
- * Create a provider factory function
+ * Creates a provider factory function with attached modality handlers.
+ *
+ * The returned provider is a callable function that creates model references
+ * when invoked with a model ID. It also exposes `name`, `version`, and
+ * `modalities` properties for introspection.
  *
  * @typeParam TOptions - Provider-specific options type (defaults to unknown)
- * @param options - Provider configuration
- * @returns Provider function with modalities attached
+ * @param options - Provider configuration including name, version, and handlers
+ * @returns A callable Provider with modalities attached
  *
  * @example
- * ```ts
- * // Basic provider without options
+ * ```typescript
+ * // Create a basic provider
  * const anthropic = createProvider({
  *   name: 'anthropic',
  *   version: '1.0.0',
  *   modalities: { llm: createLLMHandler() },
  * });
  *
- * // Provider with custom options (typically needs custom factory)
- * interface MyProviderOptions { api?: 'v1' | 'v2' }
- * const myProvider = createProvider<MyProviderOptions>({
+ * // Use the provider to create a model reference
+ * const model = anthropic('claude-sonnet-4-20250514');
+ *
+ * // Provider with custom options type
+ * interface MyOptions { apiVersion?: 'v1' | 'v2' }
+ * const myProvider = createProvider<MyOptions>({
  *   name: 'my-provider',
  *   version: '1.0.0',
- *   modalities: { llm: createLLMHandler() },
+ *   modalities: { llm: handler },
  * });
  * ```
  */
 declare function createProvider<TOptions = unknown>(options: CreateProviderOptions): Provider<TOptions>;
 
 /**
- * Image class for handling images in UPP
+ * @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/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();
     /**
-     * Check if this image has data loaded (false for URL sources)
+     * 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;
     /**
-     * Convert to base64 string (throws if source is URL)
+     * 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;
     /**
-     * Convert to data URL (throws if source is URL)
+     * 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;
     /**
-     * Get raw bytes (throws if source is URL)
+     * 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;
     /**
-     * Get the URL (only for URL sources)
+     * Gets the URL for URL-sourced images.
+     *
+     * @returns The image URL
+     * @throws {Error} When the source is not a URL
      */
     toUrl(): string;
     /**
-     * Convert to ImageBlock for use in messages
+     * Converts this Image to an ImageBlock for use in UPP messages.
+     *
+     * @returns An ImageBlock that can be included in message content arrays
      */
     toBlock(): ImageBlock;
     /**
-     * Create from file path (reads file into memory)
+     * 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>;
     /**
-     * Create from URL reference (does not fetch - providers handle URL conversion)
+     * 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;
     /**
-     * Create from raw bytes
+     * 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;
     /**
-     * Create from base64 string
+     * 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;
     /**
-     * Create from an existing ImageBlock
+     * 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;
 }
 
 /**
- * UPP namespace object
- * Provides ai.llm(), ai.embedding(), ai.image() style access
+ * @fileoverview Unified Provider Protocol (UPP) - A unified interface for AI model inference
+ *
+ * UPP provides a consistent API for interacting with multiple AI providers including
+ * Anthropic, OpenAI, Google, Ollama, OpenRouter, and xAI. The library handles provider-specific
+ * transformations, streaming, tool execution, and error handling.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { llm, anthropic } from '@providerprotocol/ai';
+ *
+ * const model = llm({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   params: { max_tokens: 1000 }
+ * });
+ *
+ * const turn = await model.generate('Hello!');
+ * console.log(turn.response.text);
+ * ```
+ *
+ * @example Streaming
+ * ```typescript
+ * for await (const event of model.stream('Tell me a story')) {
+ *   if (event.type === 'text') {
+ *     process.stdout.write(event.delta.text);
+ *   }
+ * }
+ * ```
+ *
+ * @module @providerprotocol/ai
+ * @packageDocumentation
+ */
+/** LLM instance factory for creating model-bound inference functions */
+
+/**
+ * UPP namespace object providing alternative import style.
+ *
+ * @example
+ * ```typescript
+ * import { ai } from '@providerprotocol/ai';
+ *
+ * const model = ai.llm({
+ *   model: openai('gpt-4o'),
+ *   params: { max_tokens: 1000 }
+ * });
+ * ```
  */
 declare const ai: {
+    /** LLM instance factory */
     llm: typeof llm;
 };
 
-export { type AssistantContent, AssistantMessage, type AudioBlock, type BinaryBlock, type BoundLLMModel, type ContentBlock, EmbeddingHandler, type EventDelta, Image, type ImageBlock, ImageHandler, type ImageSource, type InferenceInput, type JSONSchema, type JSONSchemaProperty, type JSONSchemaPropertyType, type LLMCapabilities, type LLMHandler, type LLMInstance, type LLMOptions, LLMProvider, type LLMRequest, type LLMResponse, type LLMStreamResult, Message, type MessageJSON, type MessageMetadata, type MessageOptions, type MessageType, ModelReference, Provider, ProviderConfig, type StreamEvent, type StreamEventType, type StreamResult, type TextBlock, Thread, type ThreadJSON, type TokenUsage, type Tool, type ToolCall, type ToolExecution, type ToolResult, ToolResultMessage, type ToolUseStrategy, type Turn, type UserContent, UserMessage, type VideoBlock, aggregateUsage, ai, contentBlockStart, contentBlockStop, createProvider, createStreamResult, createTurn, emptyUsage, isAssistantMessage, isAudioBlock, isBinaryBlock, isImageBlock, isTextBlock, isToolResultMessage, isUserMessage, isVideoBlock, llm, messageStart, messageStop, text, textDelta, toolCallDelta };
+export { type AfterCallResult, type AssistantContent, AssistantMessage, type AudioBlock, type BeforeCallResult, type BinaryBlock, type BoundLLMModel, type ContentBlock, EmbeddingHandler, type EventDelta, Image, type ImageBlock, ImageHandler, type ImageSource, type InferenceInput, type JSONSchema, type JSONSchemaProperty, type JSONSchemaPropertyType, type LLMCapabilities, type LLMHandler, type LLMInstance, type LLMOptions, LLMProvider, type LLMRequest, type LLMResponse, type LLMStreamResult, Message, type MessageJSON, type MessageMetadata, type MessageOptions, type MessageType, ModelReference, Provider, ProviderConfig, type StreamEvent, type StreamEventType, type StreamResult, type TextBlock, Thread, type ThreadJSON, type TokenUsage, type Tool, type ToolCall, type ToolExecution, type ToolMetadata, type ToolResult, ToolResultMessage, type ToolUseStrategy, type Turn, type UserContent, UserMessage, type VideoBlock, aggregateUsage, ai, contentBlockStart, contentBlockStop, createProvider, createStreamResult, createTurn, emptyUsage, isAssistantMessage, isAudioBlock, isBinaryBlock, isImageBlock, isTextBlock, isToolResultMessage, isUserMessage, isVideoBlock, llm, messageStart, messageStop, text, textDelta, toolCallDelta };