@providerprotocol/ai 0.0.27 → 0.0.28

package/dist/index.d.ts

@@ -1,514 +1,8 @@
-import { M as Message, T as Turn, a as MessageType, b as MessageJSON, c as Tool, d as ToolUseStrategy, J as JSONSchema, S as StreamResult, A as AssistantMessage, e as TokenUsage, f as StreamEvent, E as EmbeddingOptions, g as EmbeddingInstance } from './embedding-CK5oa38O.js';
-export { m as AfterCallResult, B as BeforeCallResult, L as EmbedOptions, N as Embedding, R as EmbeddingModelInput, P as EmbeddingProgress, O as EmbeddingResult, Q as EmbeddingStream, y as EventDelta, h as JSONSchemaProperty, i as JSONSchemaPropertyType, t as MessageMetadata, u as MessageOptions, p as MessageRole, z as StreamEventType, j as ToolCall, n as ToolExecution, l as ToolMetadata, k as ToolResult, o as ToolResultMessage, U as UserMessage, x as aggregateUsage, I as contentBlockStart, K as contentBlockStop, C as createStreamResult, v as createTurn, w as emptyUsage, r as isAssistantMessage, s as isToolResultMessage, q as isUserMessage, G as messageStart, H as messageStop, D as textDelta, F as toolCallDelta } from './embedding-CK5oa38O.js';
-import { U as UserContent, A as AssistantContent, P as ProviderIdentity, a as ProviderConfig, C as ContentBlock, L as LLMProvider, I as ImageOptions, b as ImageInstance, c as LLMHandler$1, E as EmbeddingHandler, d as ImageHandler, e as Provider, M as ModelReference } from './provider-6-mJYOOl.js';
-export { l as AudioBlock, B as BinaryBlock, D as BoundEmbeddingModel, a4 as BoundImageModel, n as ContentBlockType, N as EmbeddingInput, y as EmbeddingProvider, F as EmbeddingRequest, G as EmbeddingResponse, J as EmbeddingUsage, H as EmbeddingVector, h as ErrorCode, W as GeneratedImage, f as Image, k as ImageBlock, $ as ImageCapabilities, Q as ImageEditInput, a1 as ImageEditRequest, S as ImageGenerateOptions, a5 as ImageHandler, O as ImageInput, a6 as ImageModelInput, z as ImageProvider, a3 as ImageProviderStreamResult, a0 as ImageRequest, a2 as ImageResponse, Y as ImageResult, m as ImageSource, o as ImageSourceType, Z as ImageStreamEvent, _ as ImageStreamResult, X as ImageUsage, K as KeyStrategy, j as Modality, i as ModalityType, R as ReasoningBlock, x as RetryStrategy, T as TextBlock, g as UPPError, V as VideoBlock, u as isAudioBlock, w as isBinaryBlock, s as isImageBlock, q as isReasoningBlock, p as isTextBlock, v as isVideoBlock, r as reasoning, t as text } from './provider-6-mJYOOl.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-BhX8mIrL.js';
-
-/**
- * @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 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;
-}
-/**
- * LLM Handler interface for providers.
- *
- * Implemented by providers to enable language model capabilities.
- *
- * @typeParam TParams - Provider-specific parameter type
- */
-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;
-}
+import { L as LLMOptions, a as LLMInstance, I as ImageOptions, b as ImageInstance, c as LLMHandler, E as EmbeddingHandler, d as ImageHandler, P as Provider, M as ModelReference, D as DocumentSource, e as DocumentBlock, A as AudioBlock, V as VideoBlock } from './llm-DgDEy9il.js';
+export { S as AfterCallResult, o as AssistantContent, Z as AssistantMessage, Q as BeforeCallResult, B as BinaryBlock, aw as BoundEmbeddingModel, aV as BoundImageModel, aG as BoundLLMModel, C as ContentBlock, p as ContentBlockType, r as DocumentSourceType, aB as EmbeddingInput, au as EmbeddingProvider, ax as EmbeddingRequest, ay as EmbeddingResponse, aA as EmbeddingUsage, az as EmbeddingVector, g as ErrorCode, af as EventDelta, aL as GeneratedImage, f as Image, l as ImageBlock, aQ as ImageCapabilities, aJ as ImageEditInput, aS as ImageEditRequest, aK as ImageGenerateOptions, aI as ImageInput, aW as ImageModelInput, av as ImageProvider, aU as ImageProviderStreamResult, aR as ImageRequest, aT as ImageResponse, aN as ImageResult, m as ImageSource, q as ImageSourceType, aO as ImageStreamEvent, aP as ImageStreamResult, aM as ImageUsage, aH as InferenceInput, J as JSONSchema, j as JSONSchemaProperty, k as JSONSchemaPropertyType, ar as KeyStrategy, aC as LLMCapabilities, at as LLMProvider, aD as LLMRequest, aE as LLMResponse, aF as LLMStreamResult, X as Message, ad as MessageJSON, a4 as MessageMetadata, a5 as MessageOptions, $ as MessageRole, a3 as MessageType, i as Modality, h as ModalityType, aq as ProviderConfig, ap as ProviderIdentity, R as ReasoningBlock, as as RetryStrategy, ae as StreamEvent, ah as StreamEventType, ag as StreamResult, T as TextBlock, ab as Thread, ac as ThreadJSON, a7 as TokenUsage, G as Tool, H as ToolCall, W as ToolExecution, N as ToolMetadata, K as ToolResult, _ as ToolResultMessage, O as ToolUseStrategy, a6 as Turn, U as UPPError, n as UserContent, Y as UserMessage, aa as aggregateUsage, an as contentBlockStart, ao as contentBlockStop, ai as createStreamResult, a8 as createTurn, a9 as emptyUsage, a1 as isAssistantMessage, y as isAudioBlock, F as isBinaryBlock, x as isDocumentBlock, w as isImageBlock, v as isReasoningBlock, u as isTextBlock, a2 as isToolResultMessage, a0 as isUserMessage, z as isVideoBlock, al as messageStart, am as messageStop, s as reasoning, t as text, aj as textDelta, ak as toolCallDelta } from './llm-DgDEy9il.js';
+import { E as EmbeddingOptions, a as EmbeddingInstance } from './embedding-DtyOFIsS.js';
+export { b as EmbedOptions, c as Embedding, g as EmbeddingModelInput, e as EmbeddingProgress, d as EmbeddingResult, f as EmbeddingStream } from './embedding-DtyOFIsS.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-DXLQnTuU.js';
 
 /**
  * @fileoverview LLM instance factory and streaming logic for the Universal Provider Protocol.
@@ -650,7 +144,7 @@ declare function image<TParams = unknown>(options: ImageOptions<TParams>): Image
  */
 interface LLMHandlerResolver<TOptions = unknown> {
     /** Map of mode identifiers to their corresponding LLM handlers */
-    handlers: Record<string, LLMHandler$1>;
+    handlers: Record<string, LLMHandler>;
     /** The default mode when options don't specify one */
     defaultMode: string;
     /** Function to extract the mode from provider options */
@@ -706,7 +200,7 @@ interface CreateProviderOptions<TOptions = unknown> {
     /** Handlers for supported modalities (LLM, embedding, image generation) */
     handlers: {
         /** Handler for language model completions, or resolver for multi-handler providers */
-        llm?: LLMHandler$1 | LLMHandlerResolver<TOptions>;
+        llm?: LLMHandler | LLMHandlerResolver<TOptions>;
         /** Handler for text embeddings */
         embedding?: EmbeddingHandler;
         /** Handler for image generation */
@@ -764,6 +258,428 @@ interface CreateProviderOptions<TOptions = unknown> {
  */
 declare function createProvider<TOptions = unknown>(options: CreateProviderOptions<TOptions>): Provider<TOptions>;
 
+/**
+ * @fileoverview Document content handling for the Universal Provider Protocol.
+ *
+ * Provides a unified Document class for working with documents across different sources
+ * (file paths, URLs, raw text, base64). Supports PDF and plain text documents with
+ * integration into UPP message content blocks.
+ *
+ * @module core/media/Document
+ */
+
+/**
+ * Represents a document that can be used in UPP messages.
+ *
+ * Documents can be created from various sources (files, URLs, text, base64) and
+ * converted to content blocks for provider APIs. The class provides a unified
+ * interface regardless of the underlying source type.
+ *
+ * @example
+ * ```typescript
+ * // Load PDF from file
+ * const pdfDoc = await Document.fromPath('./report.pdf');
+ *
+ * // Reference PDF by URL
+ * const urlDoc = Document.fromUrl('https://example.com/document.pdf');
+ *
+ * // From plain text
+ * const textDoc = Document.fromText('Document content here...');
+ *
+ * // Use in a message
+ * const message = new UserMessage([document.toBlock()]);
+ * ```
+ */
+declare class Document {
+    /** The underlying document source (base64, url, or text) */
+    readonly source: DocumentSource;
+    /** MIME type of the document ('application/pdf' or 'text/plain') */
+    readonly mimeType: string;
+    /** Optional document title (used for citations) */
+    readonly title?: string;
+    private constructor();
+    /**
+     * Whether this document has data loaded in memory.
+     *
+     * Returns `false` for URL-sourced documents that reference external resources.
+     */
+    get hasData(): boolean;
+    /**
+     * Whether this document is a PDF.
+     */
+    get isPdf(): boolean;
+    /**
+     * Whether this document is plain text.
+     */
+    get isText(): boolean;
+    /**
+     * Converts the document to a base64-encoded string.
+     *
+     * @returns The document data as a base64 string
+     * @throws {Error} When the source is a URL or plain text
+     */
+    toBase64(): string;
+    /**
+     * Gets the plain text content for text documents.
+     *
+     * @returns The document text content
+     * @throws {Error} When the source is not plain text
+     */
+    toText(): string;
+    /**
+     * Gets the URL for URL-sourced documents.
+     *
+     * @returns The document URL
+     * @throws {Error} When the source is not a URL
+     */
+    toUrl(): string;
+    /**
+     * Converts this Document to a DocumentBlock for use in UPP messages.
+     *
+     * @returns A DocumentBlock that can be included in message content arrays
+     */
+    toBlock(): DocumentBlock;
+    /**
+     * Creates a Document by reading a file from disk.
+     *
+     * The file is read into memory and base64-encoded. MIME type is automatically
+     * detected from the file extension.
+     *
+     * @param path - Path to the document file
+     * @param title - Optional document title
+     * @returns Promise resolving to a Document with the file contents
+     *
+     * @example
+     * ```typescript
+     * const doc = await Document.fromPath('./reports/annual.pdf');
+     * const docWithTitle = await Document.fromPath('./report.pdf', 'Annual Report 2024');
+     * ```
+     */
+    static fromPath(path: string, title?: string): Promise<Document>;
+    /**
+     * Creates a Document from a URL reference.
+     *
+     * The URL is stored as a reference and not fetched. Providers will handle
+     * URL fetching if needed. Only PDF URLs are supported.
+     * URLs must use the http or https protocol.
+     *
+     * @param url - URL pointing to the PDF document
+     * @param title - Optional document title
+     * @returns A Document referencing the URL
+     *
+     * @example
+     * ```typescript
+     * const doc = Document.fromUrl('https://example.com/report.pdf');
+     * ```
+     */
+    static fromUrl(url: string, title?: string): Document;
+    /**
+     * Creates a Document from base64-encoded data.
+     *
+     * @param base64 - The base64-encoded document data
+     * @param mimeType - The MIME type ('application/pdf' or 'text/plain')
+     * @param title - Optional document title
+     * @returns A Document containing the base64 data
+     *
+     * @example
+     * ```typescript
+     * const doc = Document.fromBase64(pdfBase64, 'application/pdf', 'Contract');
+     * ```
+     */
+    static fromBase64(base64: string, mimeType: string, title?: string): Document;
+    /**
+     * Creates a Document from plain text content.
+     *
+     * @param text - The document text content
+     * @param title - Optional document title
+     * @returns A Document containing the text
+     *
+     * @example
+     * ```typescript
+     * const doc = Document.fromText('This is the document content.', 'Notes');
+     * ```
+     */
+    static fromText(text: string, title?: string): Document;
+    /**
+     * Creates a Document from an existing DocumentBlock.
+     *
+     * Useful for converting content blocks received from providers back
+     * into Document instances for further processing.
+     *
+     * @param block - A DocumentBlock from message content
+     * @returns A Document with the block's source and metadata
+     */
+    static fromBlock(block: DocumentBlock): Document;
+}
+
+/**
+ * @fileoverview Audio content handling for the Universal Provider Protocol.
+ *
+ * Provides a unified Audio class for working with audio across different sources
+ * (file paths, raw bytes, base64). Supports conversion between formats and
+ * integration with UPP message content blocks.
+ *
+ * @module core/media/Audio
+ */
+
+/**
+ * Represents an audio file that can be used in UPP messages.
+ *
+ * Audio can be created from various sources (files, bytes, base64) and
+ * converted to different formats as needed by providers. The class provides
+ * a unified interface regardless of the underlying source type.
+ *
+ * Note: Providers have size limits for inline audio data. Google Gemini
+ * limits inline data to 20MB per request. For larger files, consider using
+ * provider-specific file upload APIs.
+ *
+ * @example
+ * ```typescript
+ * // Load from file
+ * const fileAudio = await Audio.fromPath('./recording.mp3');
+ *
+ * // From raw bytes
+ * const bytesAudio = Audio.fromBytes(uint8Array, 'audio/wav');
+ *
+ * // Use in a message
+ * const message = new UserMessage([audio.toBlock()]);
+ * ```
+ */
+declare class Audio {
+    /** The audio data as raw bytes */
+    readonly data: Uint8Array;
+    /** MIME type of the audio (e.g., 'audio/mp3', 'audio/wav') */
+    readonly mimeType: string;
+    /** Duration in seconds, if known */
+    readonly duration?: number;
+    private constructor();
+    /**
+     * Gets the size of the audio data in bytes.
+     */
+    get size(): number;
+    /**
+     * Converts the audio to a base64-encoded string.
+     *
+     * @returns The audio data as a base64 string
+     */
+    toBase64(): string;
+    /**
+     * Converts the audio to a data URL suitable for embedding.
+     *
+     * @returns A data URL in the format `data:{mimeType};base64,{data}`
+     */
+    toDataUrl(): string;
+    /**
+     * Gets the audio data as raw bytes.
+     *
+     * @returns The audio data as a Uint8Array
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Converts this Audio to an AudioBlock for use in UPP messages.
+     *
+     * @returns An AudioBlock that can be included in message content arrays
+     */
+    toBlock(): AudioBlock;
+    /**
+     * Creates an Audio 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 audio file
+     * @param duration - Optional duration in seconds
+     * @returns Promise resolving to an Audio with the file contents
+     *
+     * @example
+     * ```typescript
+     * const audio = await Audio.fromPath('./recordings/interview.mp3');
+     * ```
+     */
+    static fromPath(path: string, duration?: number): Promise<Audio>;
+    /**
+     * Creates an Audio from raw byte data.
+     *
+     * @param data - The audio data as a Uint8Array
+     * @param mimeType - The MIME type of the audio
+     * @param duration - Optional duration in seconds
+     * @returns An Audio containing the byte data
+     *
+     * @example
+     * ```typescript
+     * const audio = Audio.fromBytes(wavData, 'audio/wav');
+     * ```
+     */
+    static fromBytes(data: Uint8Array, mimeType: string, duration?: number): Audio;
+    /**
+     * Creates an Audio from a base64-encoded string.
+     *
+     * @param base64 - The base64-encoded audio data (without data URL prefix)
+     * @param mimeType - The MIME type of the audio
+     * @param duration - Optional duration in seconds
+     * @returns An Audio containing the decoded data
+     *
+     * @example
+     * ```typescript
+     * const audio = Audio.fromBase64(base64String, 'audio/mp3');
+     * ```
+     */
+    static fromBase64(base64: string, mimeType: string, duration?: number): Audio;
+    /**
+     * Creates an Audio from an existing AudioBlock.
+     *
+     * Useful for converting content blocks received from providers back
+     * into Audio instances for further processing.
+     *
+     * @param block - An AudioBlock from message content
+     * @returns An Audio with the block's data and metadata
+     */
+    static fromBlock(block: AudioBlock): Audio;
+}
+
+/**
+ * @fileoverview Video content handling for the Universal Provider Protocol.
+ *
+ * Provides a unified Video class for working with video across different sources
+ * (file paths, raw bytes, base64). Supports conversion between formats and
+ * integration with UPP message content blocks.
+ *
+ * @module core/media/Video
+ */
+
+/**
+ * Represents a video file that can be used in UPP messages.
+ *
+ * Video can be created from various sources (files, bytes, base64) and
+ * converted to different formats as needed by providers. The class provides
+ * a unified interface regardless of the underlying source type.
+ *
+ * Note: Providers have size limits for inline video data. Google Gemini
+ * limits inline data to 20MB per request. For larger files, consider using
+ * provider-specific file upload APIs.
+ *
+ * @example
+ * ```typescript
+ * // Load from file
+ * const fileVideo = await Video.fromPath('./clip.mp4');
+ *
+ * // From raw bytes
+ * const bytesVideo = Video.fromBytes(uint8Array, 'video/webm');
+ *
+ * // Use in a message
+ * const message = new UserMessage([video.toBlock()]);
+ * ```
+ */
+declare class Video {
+    /** The video data as raw bytes */
+    readonly data: Uint8Array;
+    /** MIME type of the video (e.g., 'video/mp4', 'video/webm') */
+    readonly mimeType: string;
+    /** Duration in seconds, if known */
+    readonly duration?: number;
+    /** Video width in pixels, if known */
+    readonly width?: number;
+    /** Video height in pixels, if known */
+    readonly height?: number;
+    private constructor();
+    /**
+     * Gets the size of the video data in bytes.
+     */
+    get size(): number;
+    /**
+     * Converts the video to a base64-encoded string.
+     *
+     * @returns The video data as a base64 string
+     */
+    toBase64(): string;
+    /**
+     * Converts the video to a data URL suitable for embedding.
+     *
+     * @returns A data URL in the format `data:{mimeType};base64,{data}`
+     */
+    toDataUrl(): string;
+    /**
+     * Gets the video data as raw bytes.
+     *
+     * @returns The video data as a Uint8Array
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Converts this Video to a VideoBlock for use in UPP messages.
+     *
+     * @returns A VideoBlock that can be included in message content arrays
+     */
+    toBlock(): VideoBlock;
+    /**
+     * Creates a Video 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 video file
+     * @param options - Optional metadata (duration, width, height)
+     * @returns Promise resolving to a Video with the file contents
+     *
+     * @example
+     * ```typescript
+     * const video = await Video.fromPath('./clips/demo.mp4');
+     * const videoWithMeta = await Video.fromPath('./clip.mp4', { duration: 30, width: 1920, height: 1080 });
+     * ```
+     */
+    static fromPath(path: string, options?: {
+        duration?: number;
+        width?: number;
+        height?: number;
+    }): Promise<Video>;
+    /**
+     * Creates a Video from raw byte data.
+     *
+     * @param data - The video data as a Uint8Array
+     * @param mimeType - The MIME type of the video
+     * @param options - Optional metadata (duration, width, height)
+     * @returns A Video containing the byte data
+     *
+     * @example
+     * ```typescript
+     * const video = Video.fromBytes(mp4Data, 'video/mp4');
+     * const videoWithMeta = Video.fromBytes(data, 'video/mp4', { duration: 60 });
+     * ```
+     */
+    static fromBytes(data: Uint8Array, mimeType: string, options?: {
+        duration?: number;
+        width?: number;
+        height?: number;
+    }): Video;
+    /**
+     * Creates a Video from a base64-encoded string.
+     *
+     * @param base64 - The base64-encoded video data (without data URL prefix)
+     * @param mimeType - The MIME type of the video
+     * @param options - Optional metadata (duration, width, height)
+     * @returns A Video containing the decoded data
+     *
+     * @example
+     * ```typescript
+     * const video = Video.fromBase64(base64String, 'video/mp4');
+     * ```
+     */
+    static fromBase64(base64: string, mimeType: string, options?: {
+        duration?: number;
+        width?: number;
+        height?: number;
+    }): Video;
+    /**
+     * Creates a Video from an existing VideoBlock.
+     *
+     * Useful for converting content blocks received from providers back
+     * into Video instances for further processing.
+     *
+     * @param block - A VideoBlock from message content
+     * @returns A Video with the block's data and metadata
+     */
+    static fromBlock(block: VideoBlock): Video;
+}
+
 /**
  * @fileoverview Unified Provider Protocol (UPP) - A unified interface for AI model inference
  *
@@ -822,4 +738,4 @@ declare const ai: {
     image: typeof image;
 };
 
-export { AssistantContent, AssistantMessage, type BoundLLMModel, ContentBlock, EmbeddingHandler, EmbeddingInstance, EmbeddingOptions, ImageInstance, ImageOptions, type InferenceInput, JSONSchema, type LLMCapabilities, type LLMHandler, type LLMInstance, type LLMOptions, LLMProvider, type LLMRequest, type LLMResponse, type LLMStreamResult, Message, MessageJSON, MessageType, ModelReference, Provider, ProviderConfig, ProviderIdentity, StreamEvent, StreamResult, Thread, type ThreadJSON, TokenUsage, Tool, ToolUseStrategy, Turn, UserContent, ai, createProvider, embedding, image, llm };
+export { Audio, AudioBlock, Document, DocumentBlock, DocumentSource, EmbeddingHandler, EmbeddingInstance, EmbeddingOptions, ImageHandler, ImageInstance, ImageOptions, LLMHandler, LLMInstance, LLMOptions, ModelReference, Provider, Video, VideoBlock, ai, createProvider, embedding, image, llm };