@providerprotocol/ai 0.0.20 → 0.0.22

package/dist/index.d.ts

@@ -1,12 +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 } from './stream-DRHy6q1a.js';
-export { l as AfterCallResult, B as BeforeCallResult, E as EventDelta, g as JSONSchemaProperty, h as JSONSchemaPropertyType, r as MessageMetadata, s as MessageOptions, w as StreamEventType, i as ToolCall, m as ToolExecution, k as ToolMetadata, j as ToolResult, n as ToolResultMessage, U as UserMessage, v as aggregateUsage, F as contentBlockStart, G as contentBlockStop, x as createStreamResult, t as createTurn, u as emptyUsage, p as isAssistantMessage, q as isToolResultMessage, o as isUserMessage, C as messageStart, D as messageStop, y as textDelta, z as toolCallDelta } from './stream-DRHy6q1a.js';
-import { U as UserContent, A as AssistantContent, C as ContentBlock } from './content-DEl3z_W2.js';
-export { a as AudioBlock, B as BinaryBlock, I as ImageBlock, b as ImageSource, T as TextBlock, V as VideoBlock, d as isAudioBlock, f as isBinaryBlock, c as isImageBlock, i as isTextBlock, e as isVideoBlock, t as text } from './content-DEl3z_W2.js';
-import { P as ProviderConfig, L as LLMProvider, E as EmbeddingInput, a as EmbeddingUsage, B as BoundEmbeddingModel, b as LLMHandler$1, c as EmbeddingHandler, I as ImageHandler, d as Provider } from './provider-BBMBZuGn.js';
-export { g as EmbeddingProvider, i as EmbeddingRequest, j as EmbeddingResponse, k as EmbeddingVector, e as ErrorCode, h as ImageProvider, K as KeyStrategy, M as Modality, f as ModelReference, R as RetryStrategy, U as UPPError } from './provider-BBMBZuGn.js';
-import { I as ImageOptions, a as ImageInstance } from './image-Dhq-Yuq4.js';
-export { B as BoundImageModel, G as GeneratedImage, b as Image, i as ImageCapabilities, d as ImageEditInput, k as ImageEditRequest, n as ImageHandler, c as ImageInput, o as ImageModelInput, m as ImageProviderStreamResult, j as ImageRequest, l as ImageResponse, f as ImageResult, g as ImageStreamEvent, h as ImageStreamResult, e as ImageUsage } from './image-Dhq-Yuq4.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-DR7YRJDz.js';
+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 } from './stream-DbkLOIbJ.js';
+export { l as AfterCallResult, B as BeforeCallResult, E as EventDelta, g as JSONSchemaProperty, h as JSONSchemaPropertyType, r as MessageMetadata, s as MessageOptions, w as StreamEventType, i as ToolCall, m as ToolExecution, k as ToolMetadata, j as ToolResult, n as ToolResultMessage, U as UserMessage, v as aggregateUsage, F as contentBlockStart, G as contentBlockStop, x as createStreamResult, t as createTurn, u as emptyUsage, p as isAssistantMessage, q as isToolResultMessage, o as isUserMessage, C as messageStart, D as messageStop, y as textDelta, z as toolCallDelta } from './stream-DbkLOIbJ.js';
+import { U as UserContent, A as AssistantContent, P as ProviderIdentity, a as ProviderConfig, C as ContentBlock, L as LLMProvider, E as EmbeddingInput, b as EmbeddingUsage, B as BoundEmbeddingModel, I as ImageOptions, c as ImageInstance, d as LLMHandler$1, e as EmbeddingHandler, f as ImageHandler, g as Provider, M as ModelReference } from './provider-DWEAzeM5.js';
+export { m as AudioBlock, n as BinaryBlock, _ as BoundImageModel, v as EmbeddingProvider, x as EmbeddingRequest, y as EmbeddingResponse, z as EmbeddingVector, j as ErrorCode, H as GeneratedImage, h as Image, l as ImageBlock, S as ImageCapabilities, F as ImageEditInput, X as ImageEditRequest, G as ImageGenerateOptions, $ as ImageHandler, D as ImageInput, a0 as ImageModelInput, w as ImageProvider, Z as ImageProviderStreamResult, W as ImageRequest, Y as ImageResponse, N as ImageResult, o as ImageSource, O as ImageStreamEvent, Q as ImageStreamResult, J as ImageUsage, K as KeyStrategy, k as Modality, R as RetryStrategy, T as TextBlock, i as UPPError, V as VideoBlock, r as isAudioBlock, u as isBinaryBlock, q as isImageBlock, p as isTextBlock, s as isVideoBlock, t as text } from './provider-DWEAzeM5.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-DmPmqZL6.js';
 
 /**
  * @fileoverview Thread class for managing conversation history.
@@ -228,16 +224,26 @@ declare class Thread {
  * 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: {
-        readonly name: string;
-        readonly version: string;
-        readonly modalities: {
-            llm?: unknown;
-        };
-    };
+    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.
@@ -273,7 +279,7 @@ interface LLMCapabilities {
     videoInput: boolean;
     /** Provider API supports audio input in messages */
     audioInput: boolean;
-    /** Provider API supports image generation output (via modalities or built-in tools) */
+    /** Provider API supports image generation output (via image() or built-in tools) */
     imageOutput?: boolean;
 }
 /**
@@ -554,16 +560,18 @@ declare function llm<TParams = unknown>(options: LLMOptions<TParams>): LLMInstan
 /**
  * Structural type for embedding 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 EmbeddingModelInput {
     readonly modelId: string;
-    readonly provider: {
-        readonly name: string;
-        readonly version: string;
-        readonly modalities: {
-            embedding?: unknown;
-        };
-    };
+    readonly provider: ProviderIdentity;
+    /** Optional provider configuration merged into requests */
+    readonly providerConfig?: Partial<ProviderConfig>;
 }
 /**
  * Options for creating an embedding instance with the embedding() function.
@@ -778,12 +786,36 @@ declare function embedding<TParams = unknown>(options: EmbeddingOptions<TParams>
  */
 declare function image<TParams = unknown>(options: ImageOptions<TParams>): ImageInstance<TParams>;
 
+/**
+ * @fileoverview Internal handler registry and resolver utilities.
+ *
+ * @module core/provider-handlers
+ */
+
+/**
+ * Resolver for dynamically selecting LLM handlers based on model options.
+ *
+ * Used by providers that support multiple API modes (e.g., OpenAI with responses/completions).
+ * The resolver eliminates shared mutable state by storing the mode on the ModelReference
+ * and resolving the correct handler at request time.
+ *
+ * @typeParam TOptions - Provider-specific options type
+ */
+interface LLMHandlerResolver<TOptions = unknown> {
+    /** Map of mode identifiers to their corresponding LLM handlers */
+    handlers: Record<string, LLMHandler$1>;
+    /** The default mode when options don't specify one */
+    defaultMode: string;
+    /** Function to extract the mode from provider options */
+    getMode: (options: TOptions | undefined) => string;
+}
+
 /**
  * @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).
+ * and register internal handlers for LLM, embedding, and image modalities.
  *
  * @module core/provider
  */
@@ -791,43 +823,63 @@ declare function image<TParams = unknown>(options: ImageOptions<TParams>): Image
 /**
  * Configuration options for creating a new provider.
  *
+ * @typeParam TOptions - Provider-specific options type
+ *
  * @example
  * ```typescript
+ * // Simple provider with single handler
  * const options: CreateProviderOptions = {
  *   name: 'my-provider',
  *   version: '1.0.0',
- *   modalities: {
+ *   handlers: {
  *     llm: createLLMHandler(),
  *     embedding: createEmbeddingHandler(),
  *   },
  * };
+ *
+ * // Provider with multiple LLM handlers (API modes)
+ * const options: CreateProviderOptions<OpenAIOptions> = {
+ *   name: 'openai',
+ *   version: '1.0.0',
+ *   handlers: {
+ *     llm: {
+ *       handlers: { responses: handler1, completions: handler2 },
+ *       defaultMode: 'responses',
+ *       getMode: (opts) => opts?.api ?? 'responses',
+ *     },
+ *   },
+ * };
  * ```
  */
-interface CreateProviderOptions {
+interface CreateProviderOptions<TOptions = unknown> {
     /** 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;
+    handlers: {
+        /** Handler for language model completions, or resolver for multi-handler providers */
+        llm?: LLMHandler$1 | LLMHandlerResolver<TOptions>;
         /** Handler for text embeddings */
         embedding?: EmbeddingHandler;
         /** Handler for image generation */
         image?: ImageHandler;
     };
+    /**
+     * Custom function to create model references from options.
+     * Use this to map provider options to providerConfig (e.g., betas to headers).
+     */
+    createModelReference?: (modelId: string, options: TOptions | undefined, provider: Provider<TOptions>) => ModelReference<TOptions>;
 }
 /**
- * Creates a provider factory function with attached modality handlers.
+ * Creates a provider factory function with registered 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.
+ * when invoked with a model ID. It exposes `name` and `version` metadata.
  *
  * @typeParam TOptions - Provider-specific options type (defaults to unknown)
  * @param options - Provider configuration including name, version, and handlers
- * @returns A callable Provider with modalities attached
+ * @returns A callable Provider with handlers registered internally
  *
  * @example
  * ```typescript
@@ -835,7 +887,7 @@ interface CreateProviderOptions {
  * const anthropic = createProvider({
  *   name: 'anthropic',
  *   version: '1.0.0',
- *   modalities: { llm: createLLMHandler() },
+ *   handlers: { llm: createLLMHandler() },
  * });
  *
  * // Use the provider to create a model reference
@@ -846,11 +898,24 @@ interface CreateProviderOptions {
  * const myProvider = createProvider<MyOptions>({
  *   name: 'my-provider',
  *   version: '1.0.0',
- *   modalities: { llm: handler },
+ *   handlers: { llm: handler },
+ * });
+ *
+ * // Provider with multiple LLM handlers (API modes)
+ * const openai = createProvider<OpenAIOptions>({
+ *   name: 'openai',
+ *   version: '1.0.0',
+ *   handlers: {
+ *     llm: {
+ *       handlers: { responses: responsesHandler, completions: completionsHandler },
+ *       defaultMode: 'responses',
+ *       getMode: (opts) => opts?.api ?? 'responses',
+ *     },
+ *   },
  * });
  * ```
  */
-declare function createProvider<TOptions = unknown>(options: CreateProviderOptions): Provider<TOptions>;
+declare function createProvider<TOptions = unknown>(options: CreateProviderOptions<TOptions>): Provider<TOptions>;
 
 /**
  * @fileoverview Unified Provider Protocol (UPP) - A unified interface for AI model inference
@@ -910,4 +975,4 @@ declare const ai: {
     image: typeof image;
 };
 
-export { AssistantContent, AssistantMessage, BoundEmbeddingModel, type BoundLLMModel, ContentBlock, type EmbedOptions, type Embedding, EmbeddingHandler, EmbeddingInput, type EmbeddingInstance, type EmbeddingModelInput, type EmbeddingOptions, type EmbeddingProgress, type EmbeddingResult, type EmbeddingStream, EmbeddingUsage, ImageInstance, ImageOptions, type InferenceInput, JSONSchema, type LLMCapabilities, type LLMHandler, type LLMInstance, type LLMOptions, LLMProvider, type LLMRequest, type LLMResponse, type LLMStreamResult, Message, MessageJSON, MessageType, Provider, ProviderConfig, StreamEvent, StreamResult, Thread, type ThreadJSON, TokenUsage, Tool, ToolUseStrategy, Turn, UserContent, ai, createProvider, embedding, image, llm };
+export { AssistantContent, AssistantMessage, BoundEmbeddingModel, type BoundLLMModel, ContentBlock, type EmbedOptions, type Embedding, EmbeddingHandler, EmbeddingInput, type EmbeddingInstance, type EmbeddingModelInput, type EmbeddingOptions, type EmbeddingProgress, type EmbeddingResult, type EmbeddingStream, EmbeddingUsage, 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 };