@providerprotocol/ai 0.0.20 → 0.0.21

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-Di9acos2.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-Di9acos2.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-DGQHYE6I.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-DGQHYE6I.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-Pcs3hnbu.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,16 @@ 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;
 }
 /**
  * Options for creating an embedding instance with the embedding() function.
@@ -778,12 +784,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 +821,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 +885,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 +896,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 +973,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 };

package/dist/index.js

@@ -3,9 +3,6 @@ import {
   createTurn,
   emptyUsage
 } from "./chunk-SKY2JLA7.js";
-import {
-  createProvider
-} from "./chunk-MSR5P65T.js";
 import {
   Image
 } from "./chunk-WAKD3OO5.js";
@@ -14,27 +11,31 @@ import {
   Message,
   ToolResultMessage,
   UserMessage,
+  createProvider,
   generateId,
   isAssistantMessage,
   isToolResultMessage,
-  isUserMessage
-} from "./chunk-UMKWXGO3.js";
+  isUserMessage,
+  resolveEmbeddingHandler,
+  resolveImageHandler,
+  resolveLLMHandler
+} from "./chunk-M4BMM5IB.js";
 import {
   ExponentialBackoff,
   LinearBackoff,
   NoRetry,
   RetryAfterStrategy,
   TokenBucket
-} from "./chunk-U4JJC2YX.js";
+} from "./chunk-Z4ILICF5.js";
 import "./chunk-Z7RBRCRN.js";
 import {
   DynamicKey,
   RoundRobinKeys,
   WeightedKeys
-} from "./chunk-P5IRTEM5.js";
+} from "./chunk-Y3GBJNA2.js";
 import {
   UPPError
-} from "./chunk-U3FZWV4U.js";
+} from "./chunk-EDENPF3E.js";
 
 // src/types/stream.ts
 function createStreamResult(generator, turnPromise, abortController) {
@@ -108,9 +109,19 @@ function toolExecutionEnd(toolCallId, toolName, result, isError, timestamp, inde
 // src/core/llm.ts
 var DEFAULT_MAX_ITERATIONS = 10;
 function llm(options) {
-  const { model: modelRef, config = {}, params, system, tools, toolStrategy, structure } = options;
+  const { model: modelRef, config: explicitConfig = {}, params, system, tools, toolStrategy, structure } = options;
+  const providerConfig = modelRef.providerConfig ?? {};
+  const config = {
+    ...providerConfig,
+    ...explicitConfig,
+    headers: {
+      ...providerConfig.headers,
+      ...explicitConfig.headers
+    }
+  };
   const provider = modelRef.provider;
-  if (!provider.modalities.llm) {
+  const llmHandler = resolveLLMHandler(provider, modelRef.options);
+  if (!llmHandler) {
     throw new UPPError(
       `Provider '${provider.name}' does not support LLM modality`,
       "INVALID_REQUEST",
@@ -118,7 +129,6 @@ function llm(options) {
       "llm"
     );
   }
-  const llmHandler = provider.modalities.llm;
   const boundModel = llmHandler.bind(modelRef.modelId);
   const capabilities = boundModel.capabilities;
   if (structure && !capabilities.structuredOutput) {
@@ -309,6 +319,9 @@ function executeStream(model, config, system, params, tools, toolStrategy, struc
   const maxIterations = toolStrategy?.maxIterations ?? DEFAULT_MAX_ITERATIONS;
   async function* generateStream() {
     try {
+      if (abortController.signal.aborted) {
+        throw new UPPError("Stream cancelled", "CANCELLED", model.provider.name, "llm");
+      }
       while (cycles < maxIterations + 1) {
         cycles++;
         const request = {
@@ -539,7 +552,8 @@ function validateMediaCapabilities(messages, capabilities, providerName) {
 function embedding(options) {
   const { model: modelRef, config = {}, params } = options;
   const provider = modelRef.provider;
-  if (!provider.modalities.embedding) {
+  const handler = resolveEmbeddingHandler(provider);
+  if (!handler) {
     throw new UPPError(
       `Provider '${provider.name}' does not support embedding modality`,
       "INVALID_REQUEST",
@@ -547,20 +561,19 @@ function embedding(options) {
       "embedding"
     );
   }
-  const handler = provider.modalities.embedding;
   const boundModel = handler.bind(modelRef.modelId);
-  const instance = {
+  function embed(input, embedOptions) {
+    const inputs = Array.isArray(input) ? input : [input];
+    if (embedOptions?.chunked) {
+      return createChunkedStream(boundModel, inputs, params, config, embedOptions);
+    }
+    return executeEmbed(boundModel, inputs, params, config, embedOptions?.signal);
+  }
+  return {
     model: boundModel,
     params,
-    embed(input, embedOptions) {
-      const inputs = Array.isArray(input) ? input : [input];
-      if (embedOptions?.chunked) {
-        return createChunkedStream(boundModel, inputs, params, config, embedOptions);
-      }
-      return executeEmbed(boundModel, inputs, params, config, embedOptions?.signal);
-    }
+    embed
   };
-  return instance;
 }
 async function executeEmbed(model, inputs, params, config, signal) {
   const response = await model.embed({
@@ -569,12 +582,12 @@ async function executeEmbed(model, inputs, params, config, signal) {
     config: config ?? {},
     signal
   });
-  return normalizeResponse(response);
+  return normalizeResponse(response, model.provider.name);
 }
-function normalizeResponse(response) {
+function normalizeResponse(response, providerName) {
   return {
     embeddings: response.embeddings.map((vec, i) => {
-      const vector = normalizeVector(vec.vector);
+      const vector = normalizeVector(vec.vector, providerName);
       return {
         vector,
         dimensions: vector.length,
@@ -587,20 +600,32 @@ function normalizeResponse(response) {
     metadata: response.metadata
   };
 }
-function normalizeVector(vector) {
+function normalizeVector(vector, providerName) {
   if (Array.isArray(vector)) {
     return vector;
   }
-  return decodeBase64(vector);
+  return decodeBase64(vector, providerName);
 }
-function decodeBase64(b64) {
-  const binary = atob(b64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
+function decodeBase64(b64, providerName) {
+  try {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    const floats = new Float32Array(bytes.buffer);
+    return Array.from(floats);
+  } catch (error) {
+    const cause = error instanceof Error ? error : new Error("Failed to decode base64 vector");
+    throw new UPPError(
+      "Invalid base64 embedding vector",
+      "INVALID_RESPONSE",
+      providerName,
+      "embedding",
+      void 0,
+      cause
+    );
   }
-  const floats = new Float32Array(bytes.buffer);
-  return Array.from(floats);
 }
 function createChunkedStream(model, inputs, params, config, options) {
   const abortController = new AbortController();
@@ -644,7 +669,7 @@ function createChunkedStream(model, inputs, params, config, options) {
         const batchEmbeddings = [];
         for (const response of responses) {
           for (const vec of response.embeddings) {
-            const vector = normalizeVector(vec.vector);
+            const vector = normalizeVector(vec.vector, model.provider.name);
             const emb = {
               vector,
               dimensions: vector.length,
@@ -685,7 +710,8 @@ function createChunkedStream(model, inputs, params, config, options) {
 function image(options) {
   const { model: modelRef, config = {}, params } = options;
   const provider = modelRef.provider;
-  if (!provider.modalities.image) {
+  const imageHandler = resolveImageHandler(provider);
+  if (!imageHandler) {
     throw new UPPError(
       `Provider '${provider.name}' does not support image modality`,
       "INVALID_REQUEST",
@@ -693,19 +719,19 @@ function image(options) {
       "image"
     );
   }
-  const imageHandler = provider.modalities.image;
   const boundModel = imageHandler.bind(modelRef.modelId);
   const capabilities = boundModel.capabilities;
   const instance = {
     model: boundModel,
     params,
     capabilities,
-    async generate(input) {
+    async generate(input, options2) {
       const prompt = normalizeInput(input);
       const response = await boundModel.generate({
         prompt,
         params,
-        config
+        config,
+        signal: options2?.signal
       });
       return {
         images: response.images,
@@ -715,11 +741,11 @@ function image(options) {
     }
   };
   if (capabilities.streaming && boundModel.stream) {
-    const boundModelWithStream = boundModel;
+    const stream = boundModel.stream;
     instance.stream = function(input) {
       const prompt = normalizeInput(input);
       const abortController = new AbortController();
-      const providerStream = boundModelWithStream.stream({
+      const providerStream = stream({
         prompt,
         params,
         config,
@@ -738,9 +764,9 @@ function image(options) {
     };
   }
   if (capabilities.edit && boundModel.edit) {
-    const boundModelWithEdit = boundModel;
+    const edit = boundModel.edit;
     instance.edit = async function(input) {
-      const response = await boundModelWithEdit.edit({
+      const response = await edit({
         image: input.image,
         mask: input.mask,
         prompt: input.prompt,