@providerprotocol/ai 0.0.20 → 0.0.21

package/dist/provider-DGQHYE6I.d.ts

@@ -0,0 +1,1319 @@
+/**
+ * @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 variants for ImageBlock.
+ *
+ * Images can be provided as base64-encoded strings, URLs, or raw bytes.
+ *
+ * @example
+ * ```typescript
+ * // Base64 encoded image
+ * const base64Source: ImageSource = {
+ *   type: 'base64',
+ *   data: 'iVBORw0KGgo...'
+ * };
+ *
+ * // URL reference
+ * const urlSource: ImageSource = {
+ *   type: 'url',
+ *   url: 'https://example.com/image.png'
+ * };
+ *
+ * // Raw bytes
+ * const bytesSource: ImageSource = {
+ *   type: 'bytes',
+ *   data: new Uint8Array([...])
+ * };
+ * ```
+ */
+type ImageSource = {
+    type: 'base64';
+    data: string;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'bytes';
+    data: Uint8Array;
+};
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Contains audio data with its metadata.
+ *
+ * @example
+ * ```typescript
+ * const audioBlock: AudioBlock = {
+ *   type: 'audio',
+ *   data: audioBytes,
+ *   mimeType: 'audio/mp3',
+ *   duration: 120.5
+ * };
+ * ```
+ */
+interface AudioBlock {
+    /** Discriminator for audio blocks */
+    type: 'audio';
+    /** Raw audio data */
+    data: Uint8Array;
+    /** MIME type of the audio (e.g., 'audio/mp3', 'audio/wav') */
+    mimeType: string;
+    /** Duration in seconds */
+    duration?: number;
+}
+/**
+ * Video content block.
+ *
+ * Contains video data with its metadata.
+ *
+ * @example
+ * ```typescript
+ * const videoBlock: VideoBlock = {
+ *   type: 'video',
+ *   data: videoBytes,
+ *   mimeType: 'video/mp4',
+ *   duration: 30,
+ *   width: 1920,
+ *   height: 1080
+ * };
+ * ```
+ */
+interface VideoBlock {
+    /** Discriminator for video blocks */
+    type: 'video';
+    /** Raw video data */
+    data: Uint8Array;
+    /** MIME type of the video (e.g., 'video/mp4', 'video/webm') */
+    mimeType: string;
+    /** Duration in seconds */
+    duration?: number;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+}
+/**
+ * Binary content block for arbitrary data.
+ *
+ * A generic block type for data that doesn't fit other categories.
+ *
+ * @example
+ * ```typescript
+ * const binaryBlock: BinaryBlock = {
+ *   type: 'binary',
+ *   data: pdfBytes,
+ *   mimeType: 'application/pdf',
+ *   metadata: { filename: 'document.pdf', pages: 10 }
+ * };
+ * ```
+ */
+interface BinaryBlock {
+    /** Discriminator for binary blocks */
+    type: 'binary';
+    /** Raw binary data */
+    data: Uint8Array;
+    /** MIME type of the data */
+    mimeType: string;
+    /** Additional metadata about the binary content */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Union of all content block types.
+ *
+ * Used when a function or property can accept any type of content block.
+ */
+type ContentBlock = TextBlock | ImageBlock | AudioBlock | VideoBlock | BinaryBlock;
+/**
+ * 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.
+ *
+ * Assistants can generate text and media but not arbitrary binary data.
+ */
+type AssistantContent = TextBlock | ImageBlock | AudioBlock | VideoBlock;
+/**
+ * Creates a text content block from a string.
+ *
+ * @param content - The text content
+ * @returns A TextBlock containing the provided text
+ *
+ * @example
+ * ```typescript
+ * const block = text('Hello, world!');
+ * // { type: 'text', text: 'Hello, world!' }
+ * ```
+ */
+declare function text(content: string): TextBlock;
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is an AudioBlock
+ *
+ * @example
+ * ```typescript
+ * if (isAudioBlock(block)) {
+ *   console.log(block.mimeType, block.duration);
+ * }
+ * ```
+ */
+declare function isAudioBlock(block: ContentBlock): block is AudioBlock;
+/**
+ * Type guard for VideoBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a VideoBlock
+ *
+ * @example
+ * ```typescript
+ * if (isVideoBlock(block)) {
+ *   console.log(block.mimeType, block.duration);
+ * }
+ * ```
+ */
+declare function isVideoBlock(block: ContentBlock): block is VideoBlock;
+/**
+ * Type guard for BinaryBlock.
+ *
+ * @param block - The content block to check
+ * @returns True if the block is a BinaryBlock
+ *
+ * @example
+ * ```typescript
+ * if (isBinaryBlock(block)) {
+ *   console.log(block.mimeType, block.metadata);
+ * }
+ * ```
+ */
+declare function isBinaryBlock(block: ContentBlock): block is BinaryBlock;
+
+/**
+ * @fileoverview Error types for the Unified Provider Protocol.
+ *
+ * Provides normalized error codes and a unified error class for handling
+ * errors across different AI providers in a consistent manner.
+ *
+ * @module types/errors
+ */
+/**
+ * Normalized error codes for cross-provider error handling.
+ *
+ * These codes provide a consistent way to identify and handle errors
+ * regardless of which AI provider generated them.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await llm.generate('Hello');
+ * } catch (error) {
+ *   if (error instanceof UPPError) {
+ *     switch (error.code) {
+ *       case 'RATE_LIMITED':
+ *         await delay(error.retryAfter);
+ *         break;
+ *       case 'AUTHENTICATION_FAILED':
+ *         throw new Error('Invalid API key');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type ErrorCode = 
+/** API key is invalid or expired */
+'AUTHENTICATION_FAILED'
+/** Rate limit exceeded, retry after delay */
+ | 'RATE_LIMITED'
+/** Input exceeds model's context window */
+ | 'CONTEXT_LENGTH_EXCEEDED'
+/** Requested model does not exist */
+ | 'MODEL_NOT_FOUND'
+/** Request parameters are malformed */
+ | 'INVALID_REQUEST'
+/** Provider returned an unexpected response format */
+ | 'INVALID_RESPONSE'
+/** Content was blocked by safety filters */
+ | 'CONTENT_FILTERED'
+/** Account quota or credits exhausted */
+ | 'QUOTA_EXCEEDED'
+/** Provider-specific error not covered by other codes */
+ | 'PROVIDER_ERROR'
+/** Network connectivity issue */
+ | 'NETWORK_ERROR'
+/** Request exceeded timeout limit */
+ | 'TIMEOUT'
+/** Request was cancelled via AbortSignal */
+ | 'CANCELLED';
+/**
+ * Modality types supported by UPP.
+ *
+ * Each modality represents a different type of AI capability that
+ * can be provided by a UPP-compatible provider.
+ */
+type Modality = 
+/** Large language model for text generation */
+'llm'
+/** Text/image embedding model */
+ | 'embedding'
+/** Image generation model */
+ | 'image'
+/** Audio processing/generation model */
+ | 'audio'
+/** Video processing/generation model */
+ | 'video';
+/**
+ * Unified Provider Protocol Error.
+ *
+ * All provider-specific errors are normalized to this type, providing
+ * a consistent interface for error handling across different AI providers.
+ *
+ * @example
+ * ```typescript
+ * throw new UPPError(
+ *   'API key is invalid',
+ *   'AUTHENTICATION_FAILED',
+ *   'openai',
+ *   'llm',
+ *   401
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Wrapping a provider error
+ * try {
+ *   await openai.chat.completions.create({ ... });
+ * } catch (err) {
+ *   throw new UPPError(
+ *     'OpenAI request failed',
+ *     'PROVIDER_ERROR',
+ *     'openai',
+ *     'llm',
+ *     err.status,
+ *     err
+ *   );
+ * }
+ * ```
+ */
+declare class UPPError extends Error {
+    /** Normalized error code for programmatic handling */
+    readonly code: ErrorCode;
+    /** Name of the provider that generated the error */
+    readonly provider: string;
+    /** The modality that was being used when the error occurred */
+    readonly modality: Modality;
+    /** HTTP status code from the provider's response, if available */
+    readonly statusCode?: number;
+    /** The original error that caused this UPPError, if wrapping another error */
+    readonly cause?: Error;
+    /** Error class name, always 'UPPError' */
+    readonly name = "UPPError";
+    /**
+     * Creates a new UPPError instance.
+     *
+     * @param message - Human-readable error description
+     * @param code - Normalized error code for programmatic handling
+     * @param provider - Name of the provider that generated the error
+     * @param modality - The modality that was being used
+     * @param statusCode - HTTP status code from the provider's response
+     * @param cause - The original error being wrapped
+     */
+    constructor(message: string, code: ErrorCode, provider: string, modality: Modality, statusCode?: number, cause?: Error);
+    /**
+     * Creates a string representation of the error.
+     *
+     * @returns Formatted error string including code, message, provider, and modality
+     */
+    toString(): string;
+    /**
+     * Converts the error to a JSON-serializable object.
+     *
+     * @returns Plain object representation suitable for logging or transmission
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * @fileoverview Image content handling for the Universal Provider Protocol.
+ *
+ * Provides a unified Image class for working with images across different sources
+ * (file paths, URLs, raw bytes, base64). Supports conversion between formats and
+ * integration with UPP message content blocks.
+ *
+ * @module core/media/Image
+ */
+
+/**
+ * Represents an image that can be used in UPP messages.
+ *
+ * Images can be created from various sources (files, URLs, bytes, base64) and
+ * converted to different formats as needed by providers. The class provides
+ * a unified interface regardless of the underlying source type.
+ *
+ * @example
+ * ```typescript
+ * // Load from file
+ * const fileImage = await Image.fromPath('./photo.jpg');
+ *
+ * // Reference by URL
+ * const urlImage = Image.fromUrl('https://example.com/image.png');
+ *
+ * // From raw bytes
+ * const bytesImage = Image.fromBytes(uint8Array, 'image/png');
+ *
+ * // Use in a message
+ * const message = new UserMessage([image.toBlock()]);
+ * ```
+ */
+declare class Image {
+    /** The underlying image source (bytes, base64, or URL) */
+    readonly source: ImageSource;
+    /** MIME type of the image (e.g., 'image/jpeg', 'image/png') */
+    readonly mimeType: string;
+    /** Image width in pixels, if known */
+    readonly width?: number;
+    /** Image height in pixels, if known */
+    readonly height?: number;
+    private constructor();
+    /**
+     * Whether this image has data loaded in memory.
+     *
+     * Returns `false` for URL-sourced images that reference external resources.
+     * These must be fetched before their data can be accessed.
+     */
+    get hasData(): boolean;
+    /**
+     * Converts the image to a base64-encoded string.
+     *
+     * @returns The image data as a base64 string
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toBase64(): string;
+    /**
+     * Converts the image to a data URL suitable for embedding in HTML or CSS.
+     *
+     * @returns A data URL in the format `data:{mimeType};base64,{data}`
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toDataUrl(): string;
+    /**
+     * Gets the image data as raw bytes.
+     *
+     * @returns The image data as a Uint8Array
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Gets the URL for URL-sourced images.
+     *
+     * @returns The image URL
+     * @throws {Error} When the source is not a URL
+     */
+    toUrl(): string;
+    /**
+     * Converts this Image to an ImageBlock for use in UPP messages.
+     *
+     * @returns An ImageBlock that can be included in message content arrays
+     */
+    toBlock(): ImageBlock;
+    /**
+     * Creates an Image by reading a file from disk.
+     *
+     * The file is read into memory as bytes. MIME type is automatically
+     * detected from the file extension.
+     *
+     * @param path - Path to the image file
+     * @returns Promise resolving to an Image with the file contents
+     *
+     * @example
+     * ```typescript
+     * const image = await Image.fromPath('./photos/vacation.jpg');
+     * ```
+     */
+    static fromPath(path: string): Promise<Image>;
+    /**
+     * Creates an Image from a URL reference.
+     *
+     * The URL is stored as a reference and not fetched. Providers will handle
+     * URL-to-data conversion if needed. MIME type is detected from the URL
+     * path if not provided.
+     *
+     * @param url - URL pointing to the image
+     * @param mimeType - Optional MIME type override
+     * @returns An Image referencing the URL
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromUrl('https://example.com/logo.png');
+     * ```
+     */
+    static fromUrl(url: string, mimeType?: string): Image;
+    /**
+     * Creates an Image from raw byte data.
+     *
+     * @param data - The image data as a Uint8Array
+     * @param mimeType - The MIME type of the image
+     * @returns An Image containing the byte data
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromBytes(pngData, 'image/png');
+     * ```
+     */
+    static fromBytes(data: Uint8Array, mimeType: string): Image;
+    /**
+     * Creates an Image from a base64-encoded string.
+     *
+     * @param base64 - The base64-encoded image data (without data URL prefix)
+     * @param mimeType - The MIME type of the image
+     * @returns An Image containing the base64 data
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromBase64(base64String, 'image/jpeg');
+     * ```
+     */
+    static fromBase64(base64: string, mimeType: string): Image;
+    /**
+     * Creates an Image from an existing ImageBlock.
+     *
+     * Useful for converting content blocks received from providers back
+     * into Image instances for further processing.
+     *
+     * @param block - An ImageBlock from message content
+     * @returns An Image with the block's source and metadata
+     */
+    static fromBlock(block: ImageBlock): Image;
+}
+
+/**
+ * @fileoverview Image generation types for the Universal Provider Protocol.
+ *
+ * Defines the interfaces for configuring and executing image generation operations,
+ * including options, instances, requests, responses, streaming, and capabilities.
+ *
+ * @module types/image
+ */
+
+/**
+ * Structural type for image model input.
+ * Uses structural typing to avoid generic variance issues with Provider generics.
+ *
+ * @remarks
+ * This type mirrors {@link ModelReference} while keeping provider options
+ * structurally compatible across providers.
+ *
+ * @see ModelReference
+ */
+interface ImageModelInput {
+    readonly modelId: string;
+    readonly provider: ProviderIdentity;
+}
+/**
+ * Options for creating an image instance with the image() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const options: ImageOptions<OpenAIImageParams> = {
+ *   model: openai('dall-e-3'),
+ *   config: { apiKey: process.env.OPENAI_API_KEY },
+ *   params: { size: '1024x1024', quality: 'hd' }
+ * };
+ * ```
+ */
+interface ImageOptions<TParams = unknown> {
+    /** A model reference from a provider factory */
+    model: ImageModelInput;
+    /** Provider infrastructure configuration */
+    config?: ProviderConfig;
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+}
+/**
+ * Options for image generation.
+ */
+interface ImageGenerateOptions {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Input type for generate() - either a string prompt or object with prompt.
+ */
+type ImageInput = string | {
+    prompt: string;
+};
+/**
+ * Input for edit() operations.
+ */
+interface ImageEditInput {
+    /** Base image to edit */
+    image: Image;
+    /** Mask indicating edit region (interpretation varies by provider) */
+    mask?: Image;
+    /** Edit instruction prompt */
+    prompt: string;
+}
+/**
+ * A single generated image with optional metadata.
+ */
+interface GeneratedImage {
+    /** The generated image */
+    image: Image;
+    /** Provider-specific per-image metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usage statistics for image generation.
+ * Fields are optional because providers report usage differently.
+ */
+interface ImageUsage {
+    /** Number of images generated */
+    imagesGenerated?: number;
+    /** Input tokens consumed (token-based pricing) */
+    inputTokens?: number;
+    /** Output tokens consumed (token-based pricing) */
+    outputTokens?: number;
+    /** Provider-reported cost (credits, dollars, etc.) */
+    cost?: number;
+}
+/**
+ * Result from generate() or edit() calls.
+ */
+interface ImageResult {
+    /** Generated images */
+    images: GeneratedImage[];
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+    /** Usage/billing information */
+    usage?: ImageUsage;
+}
+/**
+ * Stream events for image generation.
+ */
+type ImageStreamEvent = {
+    type: 'preview';
+    image: Image;
+    index: number;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'complete';
+    image: GeneratedImage;
+    index: number;
+};
+/**
+ * Async iterable stream with final result accessor.
+ * Returned when stream() is called.
+ */
+interface ImageStreamResult extends AsyncIterable<ImageStreamEvent> {
+    /** Promise resolving to complete result after streaming */
+    readonly result: Promise<ImageResult>;
+    /** Abort the generation */
+    abort(): void;
+}
+/**
+ * Image generation capabilities.
+ */
+interface ImageCapabilities {
+    /** Supports text-to-image generation */
+    generate: boolean;
+    /** Supports streaming with partial previews */
+    streaming: boolean;
+    /** Supports image editing/inpainting */
+    edit: boolean;
+    /** Maximum images per request (if known) */
+    maxImages?: number;
+}
+/**
+ * Image instance returned by the image() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const dalle = image({ model: openai('dall-e-3') });
+ *
+ * // Simple generation
+ * const result = await dalle.generate('A sunset over mountains');
+ *
+ * // Streaming (if supported)
+ * if (dalle.capabilities.streaming && dalle.stream) {
+ *   const stream = dalle.stream('A cyberpunk cityscape');
+ *   for await (const event of stream) {
+ *     // Handle preview/complete events
+ *   }
+ * }
+ * ```
+ */
+interface ImageInstance<TParams = unknown> {
+    /**
+     * Generate images from a text prompt.
+     *
+     * @param input - The prompt string or object with prompt
+     * @param options - Optional generation options
+     * @returns Promise resolving to the generated images
+     */
+    generate(input: ImageInput, options?: ImageGenerateOptions): Promise<ImageResult>;
+    /**
+     * Generate with streaming progress (if supported).
+     * Only available when capabilities.streaming is true.
+     *
+     * @param input - The prompt string or object with prompt
+     * @returns ImageStreamResult with events and final result
+     */
+    stream?(input: ImageInput): ImageStreamResult;
+    /**
+     * Edit an existing image (if supported).
+     * Only available when capabilities.edit is true.
+     *
+     * @param input - Edit input with image, optional mask, and prompt
+     * @returns Promise resolving to the edited images
+     */
+    edit?(input: ImageEditInput): Promise<ImageResult>;
+    /** The bound image model */
+    readonly model: BoundImageModel<TParams>;
+    /** Current parameters */
+    readonly params: TParams | undefined;
+    /** Model capabilities */
+    readonly capabilities: ImageCapabilities;
+}
+/**
+ * Request passed from image() core to providers for generation.
+ * @internal
+ */
+interface ImageRequest<TParams = unknown> {
+    /** Generation prompt */
+    prompt: string;
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Request passed to providers for edit operations.
+ * @internal
+ */
+interface ImageEditRequest<TParams = unknown> {
+    /** Base image to edit */
+    image: Image;
+    /** Edit mask */
+    mask?: Image;
+    /** Edit instruction prompt */
+    prompt: string;
+    /** Provider-specific parameters */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Response from provider's generate or edit method.
+ * @internal
+ */
+interface ImageResponse {
+    /** Generated images */
+    images: GeneratedImage[];
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+    /** Usage information */
+    usage?: ImageUsage;
+}
+/**
+ * Raw provider stream result.
+ * An async iterable of ImageStreamEvent with a response promise.
+ * @internal
+ */
+interface ImageProviderStreamResult extends AsyncIterable<ImageStreamEvent> {
+    /** Promise resolving to the complete response */
+    readonly response: Promise<ImageResponse>;
+}
+/**
+ * Bound image model - full definition.
+ *
+ * Represents an image model bound to a specific provider and model ID,
+ * ready to execute generation requests.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundImageModel<TParams = unknown> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: ImageProvider<TParams>;
+    /** Model capabilities */
+    readonly capabilities: ImageCapabilities;
+    /**
+     * Generate images from a prompt.
+     *
+     * @param request - The generation request
+     * @returns Promise resolving to the response
+     */
+    generate(request: ImageRequest<TParams>): Promise<ImageResponse>;
+    /**
+     * Stream image generation (optional).
+     *
+     * @param request - The generation request
+     * @returns Stream result with events and final response
+     */
+    stream?(request: ImageRequest<TParams>): ImageProviderStreamResult;
+    /**
+     * Edit an image (optional).
+     *
+     * @param request - The edit request
+     * @returns Promise resolving to the response
+     */
+    edit?(request: ImageEditRequest<TParams>): Promise<ImageResponse>;
+}
+/**
+ * Image Handler interface for providers.
+ *
+ * Implemented by providers to enable image generation capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface ImageHandler$1<TParams = unknown> {
+    /**
+     * Binds a model ID to create an executable image model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound image model ready for generation
+     */
+    bind(modelId: string): BoundImageModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     * Called by createProvider() after the provider is constructed.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: ImageProvider<TParams>): void;
+}
+
+/**
+ * @fileoverview Provider types for AI service integrations.
+ *
+ * Defines the interfaces for provider factories, modality handlers,
+ * and configuration options for connecting to various AI providers.
+ *
+ * @module types/provider
+ */
+
+/**
+ * API key strategy interface for managing multiple keys.
+ *
+ * Implement this interface to provide custom key rotation or
+ * selection logic when working with multiple API keys.
+ *
+ * @example
+ * ```typescript
+ * class RoundRobinKeys implements KeyStrategy {
+ *   private keys: string[];
+ *   private index = 0;
+ *
+ *   constructor(keys: string[]) {
+ *     this.keys = keys;
+ *   }
+ *
+ *   getKey(): string {
+ *     const key = this.keys[this.index];
+ *     this.index = (this.index + 1) % this.keys.length;
+ *     return key;
+ *   }
+ * }
+ * ```
+ */
+interface KeyStrategy {
+    /**
+     * Gets the next API key to use for a request.
+     *
+     * @returns The API key string, or a Promise resolving to it
+     */
+    getKey(): string | Promise<string>;
+}
+/**
+ * Retry strategy interface for handling request failures.
+ *
+ * Implement this interface to provide custom retry logic for
+ * handling rate limits, transient errors, and other failures.
+ *
+ * @example
+ * ```typescript
+ * class ExponentialBackoff implements RetryStrategy {
+ *   private maxAttempts = 5;
+ *   private baseDelay = 1000;
+ *
+ *   onRetry(error: UPPError, attempt: number): number | null {
+ *     if (attempt > this.maxAttempts) return null;
+ *     if (error.code !== 'RATE_LIMITED') return null;
+ *     return this.baseDelay * Math.pow(2, attempt - 1);
+ *   }
+ * }
+ * ```
+ */
+interface RetryStrategy {
+    /**
+     * Called when a request fails with a retryable error.
+     *
+     * @param error - The error that occurred
+     * @param attempt - The attempt number (1 = first retry)
+     * @returns Delay in ms before retrying, or null to stop retrying
+     */
+    onRetry(error: UPPError, attempt: number): number | null | Promise<number | null>;
+    /**
+     * Called before each request. Can be used to implement pre-emptive rate limiting.
+     *
+     * @returns Delay in ms to wait before making the request, or 0 to proceed immediately
+     */
+    beforeRequest?(): number | Promise<number>;
+    /**
+     * Reset the strategy state (e.g., after a successful request).
+     */
+    reset?(): void;
+}
+/**
+ * Provider identity shape for structural typing.
+ *
+ * Used in model input types to accept any provider instance
+ * without generic variance constraints.
+ */
+interface ProviderIdentity {
+    /** Provider name (e.g., 'openai', 'anthropic') */
+    readonly name: string;
+    /** Provider version string */
+    readonly version: string;
+}
+/**
+ * Provider configuration for infrastructure and connection settings.
+ *
+ * These settings control how requests are made to the provider's API,
+ * including authentication, timeouts, and retry behavior.
+ *
+ * @example
+ * ```typescript
+ * const config: ProviderConfig = {
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   timeout: 30000,
+ *   retryStrategy: new ExponentialBackoff()
+ * };
+ *
+ * // Or with a key strategy for key rotation
+ * const config: ProviderConfig = {
+ *   apiKey: new RoundRobinKeys(['sk-1', 'sk-2', 'sk-3']),
+ *   baseUrl: 'https://custom-proxy.example.com'
+ * };
+ * ```
+ */
+interface ProviderConfig {
+    /**
+     * API key for authentication.
+     * Can be a string, async function, or KeyStrategy for advanced use cases.
+     */
+    apiKey?: string | (() => string | Promise<string>) | KeyStrategy;
+    /** Override the base API URL (for proxies, local models) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation (for logging, caching, custom TLS) */
+    fetch?: typeof fetch;
+    /** API version override (provider-specific) */
+    apiVersion?: string;
+    /** Retry strategy for handling failures and rate limits */
+    retryStrategy?: RetryStrategy;
+    /**
+     * Custom headers to include in API requests.
+     *
+     * Use this to pass provider-specific headers such as:
+     * - Anthropic: `anthropic-beta` for beta features
+     * - OpenAI: `OpenAI-Organization`, `OpenAI-Project`
+     * - OpenRouter: `HTTP-Referer`, `X-Title` for attribution
+     * - Ollama: Proxy authentication headers
+     *
+     * @example
+     * ```typescript
+     * const config: ProviderConfig = {
+     *   headers: { 'anthropic-beta': 'extended-cache-ttl-2025-04-11' }
+     * };
+     * ```
+     */
+    headers?: Record<string, string | undefined>;
+}
+/**
+ * A reference to a model, created by a provider factory.
+ *
+ * Model references are lightweight objects that identify a model
+ * and its provider, used as input to the llm() function.
+ *
+ * @typeParam TOptions - Provider-specific options type
+ *
+ * @example
+ * ```typescript
+ * const model = openai('gpt-4');
+ * console.log(model.modelId); // 'gpt-4'
+ * console.log(model.provider.name); // 'openai'
+ * ```
+ */
+interface ModelReference<TOptions = unknown> {
+    /** The model identifier (e.g., 'gpt-4', 'claude-3-opus') */
+    readonly modelId: string;
+    /** The provider that created this reference */
+    readonly provider: Provider<TOptions>;
+    /**
+     * Optional provider-specific configuration that gets merged into request config.
+     *
+     * This allows providers to store options set at model reference creation time
+     * (e.g., `anthropic('model', { betas: [...] })`) that should be applied to all requests.
+     * The `llm()` factory will merge these into the request config, with explicit config
+     * values taking precedence.
+     */
+    readonly providerConfig?: Partial<ProviderConfig>;
+    /**
+     * The original options passed when creating this model reference.
+     *
+     * Used by providers with multiple LLM handlers (e.g., OpenAI with responses/completions APIs)
+     * to resolve the correct handler at request time, avoiding race conditions from shared state.
+     */
+    readonly options?: TOptions;
+}
+/**
+ * LLM handler interface for providers.
+ *
+ * Implemented by providers to enable language model capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface LLMHandler<TParams = unknown> {
+    /**
+     * Binds a model ID to create an executable model instance.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound LLM model ready for inference
+     */
+    bind(modelId: string): BoundLLMModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     * Called by createProvider() after the provider is constructed.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: LLMProvider<TParams>): void;
+}
+/**
+ * Embedding handler interface for providers.
+ *
+ * Implemented by providers to enable embedding capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface EmbeddingHandler<TParams = unknown> {
+    /** Supported input types for embeddings */
+    readonly supportedInputs: ('text' | 'image')[];
+    /**
+     * Binds a model ID to create an executable embedding model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound embedding model ready for use
+     */
+    bind(modelId: string): BoundEmbeddingModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: EmbeddingProvider<TParams>): void;
+}
+/**
+ * Image handler interface for providers.
+ *
+ * Implemented by providers to enable image generation capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface ImageHandler<TParams = unknown> {
+    /**
+     * Binds a model ID to create an executable image model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound image model ready for generation
+     */
+    bind(modelId: string): BoundImageModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: ImageProvider<TParams>): void;
+}
+/**
+ * Bound LLM model interface (forward declaration).
+ *
+ * Full definition is in llm.ts to avoid circular dependencies.
+ *
+ * @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>;
+}
+/**
+ * Bound embedding model interface.
+ *
+ * Represents an embedding model bound to a specific model ID,
+ * ready to generate embeddings.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundEmbeddingModel<TParams = unknown> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: EmbeddingProvider<TParams>;
+    /** Maximum number of inputs per batch request */
+    readonly maxBatchSize: number;
+    /** Maximum length of input text in tokens */
+    readonly maxInputLength: number;
+    /** Output embedding dimensions */
+    readonly dimensions: number;
+    /**
+     * Execute embedding request.
+     *
+     * @param request - The embedding request
+     * @returns Promise resolving to embedding response
+     */
+    embed(request: EmbeddingRequest<TParams>): Promise<EmbeddingResponse>;
+}
+/**
+ * Request passed to provider's embed method.
+ * @internal
+ */
+interface EmbeddingRequest<TParams = unknown> {
+    /** Inputs to embed */
+    inputs: EmbeddingInput[];
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Response from provider's embed method.
+ * @internal
+ */
+interface EmbeddingResponse {
+    /** Embedding vectors */
+    embeddings: EmbeddingVector[];
+    /** Aggregate usage */
+    usage: EmbeddingUsage;
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Single vector from provider response.
+ * @internal
+ */
+interface EmbeddingVector {
+    /** The embedding vector (floats or base64 string) */
+    vector: number[] | string;
+    /** Index in input array */
+    index: number;
+    /** Token count for this input */
+    tokens?: number;
+    /** Provider-specific per-embedding metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usage statistics for embedding operations.
+ */
+interface EmbeddingUsage {
+    /** Total tokens processed */
+    totalTokens: number;
+}
+/**
+ * Valid input types for embedding.
+ */
+type EmbeddingInput = string | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: unknown;
+    mimeType: string;
+};
+/**
+ * Bound image model interface.
+ *
+ * Represents an image generation model bound to a specific model ID.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+/**
+ * Provider factory function with metadata and modality handlers.
+ *
+ * The Provider interface represents a callable function that creates
+ * model references, along with metadata and modality-specific handlers.
+ *
+ * @typeParam TOptions - Provider-specific options passed to the factory
+ *
+ * @example
+ * ```typescript
+ * // Using a provider
+ * const model = openai('gpt-4', { temperature: 0.7 });
+ *
+ * // Accessing provider metadata
+ * console.log(openai.name); // 'openai'
+ * console.log(openai.version); // '1.0.0'
+ * ```
+ *
+ * @remarks
+ * Providers are intended to be used with `llm()`, `embedding()`, or `image()`.
+ * Direct handler access is not part of the public API.
+ */
+interface Provider<TOptions = unknown> extends ProviderIdentity {
+    /**
+     * Creates a model reference with optional provider-specific options.
+     *
+     * @param modelId - The model identifier
+     * @param options - Provider-specific options
+     * @returns A model reference for use with llm() or other functions
+     */
+    (modelId: string, options?: TOptions): ModelReference<TOptions>;
+    /** Provider name (e.g., 'openai', 'anthropic') */
+    readonly name: string;
+    /** Provider version string */
+    readonly version: string;
+}
+/**
+ * Provider with LLM modality support.
+ *
+ * Type alias for providers that support language model inference.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type LLMProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
+    /** @internal */
+    readonly __params?: TParams;
+};
+/**
+ * Provider with Embedding modality support.
+ *
+ * Type alias for providers that support embedding generation.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type EmbeddingProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
+    /** @internal */
+    readonly __params?: TParams;
+};
+/**
+ * Provider with Image modality support.
+ *
+ * Type alias for providers that support image generation.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type ImageProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> & {
+    /** @internal */
+    readonly __params?: TParams;
+};
+
+export { type ImageHandler$1 as $, type AssistantContent as A, type BoundEmbeddingModel as B, type ContentBlock as C, type ImageInput as D, type EmbeddingInput as E, type ImageEditInput as F, type ImageGenerateOptions as G, type GeneratedImage as H, type ImageOptions as I, type ImageUsage as J, type KeyStrategy as K, type LLMProvider as L, type ModelReference as M, type ImageResult as N, type ImageStreamEvent as O, type ProviderIdentity as P, type ImageStreamResult as Q, type RetryStrategy as R, type ImageCapabilities as S, type TextBlock as T, type UserContent as U, type VideoBlock as V, type ImageRequest as W, type ImageEditRequest as X, type ImageResponse as Y, type ImageProviderStreamResult as Z, type BoundImageModel as _, type ProviderConfig as a, type ImageModelInput as a0, type EmbeddingUsage as b, type ImageInstance as c, type LLMHandler as d, type EmbeddingHandler as e, type ImageHandler as f, type Provider as g, Image as h, UPPError as i, type ErrorCode as j, type Modality as k, type ImageBlock as l, type AudioBlock as m, type BinaryBlock as n, type ImageSource as o, isTextBlock as p, isImageBlock as q, isAudioBlock as r, isVideoBlock as s, text as t, isBinaryBlock as u, type EmbeddingProvider as v, type ImageProvider as w, type EmbeddingRequest as x, type EmbeddingResponse as y, type EmbeddingVector as z };