@providerprotocol/ai 0.0.15 → 0.0.17

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { M as ModelReference, P as ProviderConfig, L as LLMProvider, a as LLMHandler$1, E as EmbeddingHandler, I as ImageHandler, b as Provider } from './provider-Bi0nyNhA.js';
-export { B as BoundEmbeddingModel, g as BoundImageModel, e as EmbeddingProvider, c as ErrorCode, f as ImageProvider, K as KeyStrategy, d as Modality, R as RetryStrategy, U as UPPError } from './provider-Bi0nyNhA.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-BatS2hjD.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-D5MO3-pS.js';
+export { i as BoundImageModel, g as EmbeddingProvider, j as EmbeddingRequest, k as EmbeddingResponse, l 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-D5MO3-pS.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-DZ4Sqmxp.js';
 
 /**
  * @fileoverview Content block types for multimodal messages.
@@ -1513,6 +1513,21 @@ declare class Thread {
  * @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.
+ */
+type ModelInput = {
+    readonly modelId: string;
+    readonly provider: {
+        readonly name: string;
+        readonly version: string;
+        readonly modalities: {
+            llm?: unknown;
+        };
+    };
+};
 /**
  * LLM capabilities declare what a provider's API supports.
  *
@@ -1547,6 +1562,8 @@ 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) */
+    imageOutput?: boolean;
 }
 /**
  * Valid input types for inference.
@@ -1575,7 +1592,7 @@ type InferenceInput = string | Message | ContentBlock;
  */
 interface LLMOptions<TParams = unknown> {
     /** A model reference from a provider factory */
-    model: ModelReference<any>;
+    model: ModelInput;
     /** Provider infrastructure configuration (optional - uses env vars if omitted) */
     config?: ProviderConfig;
     /** Model-specific parameters (temperature, max_tokens, etc.) */
@@ -1814,6 +1831,205 @@ interface LLMHandler<TParams = unknown> {
  */
 declare function llm<TParams = unknown>(options: LLMOptions<TParams>): LLMInstance<TParams>;
 
+/**
+ * @fileoverview Embedding types for vector embedding generation.
+ *
+ * Defines the interfaces for configuring and executing embedding operations,
+ * including options, instances, requests, responses, and streaming progress.
+ *
+ * @module types/embedding
+ */
+
+/**
+ * Structural type for embedding model input.
+ * Uses structural typing to avoid generic variance issues with Provider generics.
+ */
+interface EmbeddingModelInput {
+    readonly modelId: string;
+    readonly provider: {
+        readonly name: string;
+        readonly version: string;
+        readonly modalities: {
+            embedding?: unknown;
+        };
+    };
+}
+/**
+ * Options for creating an embedding instance with the embedding() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const options: EmbeddingOptions<OpenAIEmbedParams> = {
+ *   model: openai('text-embedding-3-large'),
+ *   config: { apiKey: process.env.OPENAI_API_KEY },
+ *   params: { dimensions: 1536 }
+ * };
+ * ```
+ */
+interface EmbeddingOptions<TParams = unknown> {
+    /** A model reference from a provider factory */
+    model: EmbeddingModelInput;
+    /** Provider infrastructure configuration */
+    config?: ProviderConfig;
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+}
+/**
+ * Options for embed() calls.
+ */
+interface EmbedOptions {
+    /**
+     * Enable chunked processing with progress for large input sets.
+     * When true, returns EmbeddingStream instead of Promise.
+     */
+    chunked?: boolean;
+    /** Inputs per batch when chunked (default: provider max) */
+    batchSize?: number;
+    /** Concurrent batch limit when chunked (default: 1) */
+    concurrency?: number;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Single embedding vector result.
+ */
+interface Embedding {
+    /** The embedding vector */
+    vector: number[];
+    /** Vector dimensionality */
+    dimensions: number;
+    /** Index corresponding to input array position */
+    index: number;
+    /** Token count for this input (if provider reports) */
+    tokens?: number;
+    /** Provider-specific per-embedding metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from embed() call.
+ */
+interface EmbeddingResult {
+    /** Embeddings in same order as inputs */
+    embeddings: Embedding[];
+    /** Usage statistics */
+    usage: EmbeddingUsage;
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Progress update when using chunked mode.
+ */
+interface EmbeddingProgress {
+    /** Embeddings from the latest batch */
+    embeddings: Embedding[];
+    /** Total embeddings completed so far */
+    completed: number;
+    /** Total number of inputs */
+    total: number;
+    /** Percentage complete (0-100) */
+    percent: number;
+}
+/**
+ * Async iterable stream with final result accessor.
+ * Returned when embed() is called with { chunked: true }.
+ */
+interface EmbeddingStream extends AsyncIterable<EmbeddingProgress> {
+    /** Promise resolving to complete result after iteration */
+    readonly result: Promise<EmbeddingResult>;
+    /** Abort the operation */
+    abort(): void;
+}
+/**
+ * Embedding instance returned by the embedding() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const embedder = embedding({ model: openai('text-embedding-3-large') });
+ *
+ * // Single input
+ * const result = await embedder.embed('Hello world');
+ *
+ * // Batch input
+ * const batch = await embedder.embed(['doc1', 'doc2', 'doc3']);
+ *
+ * // Large-scale with progress
+ * const stream = embedder.embed(documents, { chunked: true });
+ * for await (const progress of stream) {
+ *   console.log(`${progress.percent}% complete`);
+ * }
+ * ```
+ */
+interface EmbeddingInstance<TParams = unknown> {
+    /**
+     * Generate embeddings for one or more inputs.
+     *
+     * @param input - Single input or array of inputs
+     * @param options - Optional embed options
+     * @returns Promise<EmbeddingResult> or EmbeddingStream if chunked
+     */
+    embed(input: EmbeddingInput | EmbeddingInput[], options?: EmbedOptions & {
+        chunked?: false;
+    }): Promise<EmbeddingResult>;
+    embed(input: EmbeddingInput[], options: EmbedOptions & {
+        chunked: true;
+    }): EmbeddingStream;
+    embed(input: EmbeddingInput | EmbeddingInput[], options?: EmbedOptions): Promise<EmbeddingResult> | EmbeddingStream;
+    /** The bound embedding model */
+    readonly model: BoundEmbeddingModel<TParams>;
+    /** Current parameters */
+    readonly params: TParams | undefined;
+}
+
+/**
+ * @fileoverview Embedding instance factory for the Universal Provider Protocol.
+ *
+ * This module provides the core functionality for creating embedding instances
+ * that generate vector embeddings from text or other content.
+ *
+ * @module core/embedding
+ */
+
+/**
+ * Creates an embedding instance configured with the specified options.
+ *
+ * This is the primary factory function for creating embedding instances.
+ * It validates provider capabilities, binds the model, and returns an
+ * instance with an `embed` method for generating embeddings.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @param options - Configuration options for the embedding instance
+ * @returns A configured embedding instance ready for use
+ * @throws {UPPError} When the provider does not support the embedding modality
+ *
+ * @example
+ * ```typescript
+ * import { embedding } from 'upp';
+ * import { openai } from 'upp/openai';
+ *
+ * const embedder = embedding({
+ *   model: openai('text-embedding-3-large'),
+ *   params: { dimensions: 1536 }
+ * });
+ *
+ * // Single input
+ * const result = await embedder.embed('Hello world');
+ *
+ * // Batch input
+ * const batch = await embedder.embed(['doc1', 'doc2', 'doc3']);
+ *
+ * // Large-scale with progress
+ * const stream = embedder.embed(documents, { chunked: true });
+ * for await (const progress of stream) {
+ *   console.log(`${progress.percent}% complete`);
+ * }
+ * ```
+ */
+declare function embedding<TParams = unknown>(options: EmbeddingOptions<TParams>): EmbeddingInstance<TParams>;
+
 /**
  * @fileoverview Base provider interface and factory for the Universal Provider Protocol.
  *
@@ -2091,6 +2307,8 @@ declare class Image {
 declare const ai: {
     /** LLM instance factory */
     llm: typeof llm;
+    /** Embedding instance factory */
+    embedding: typeof embedding;
 };
 
-export { type AfterCallResult, type AssistantContent, AssistantMessage, type AudioBlock, type BeforeCallResult, type BinaryBlock, type BoundLLMModel, type ContentBlock, EmbeddingHandler, type EventDelta, Image, type ImageBlock, ImageHandler, type ImageSource, type InferenceInput, type JSONSchema, type JSONSchemaProperty, type JSONSchemaPropertyType, type LLMCapabilities, type LLMHandler, type LLMInstance, type LLMOptions, LLMProvider, type LLMRequest, type LLMResponse, type LLMStreamResult, Message, type MessageJSON, type MessageMetadata, type MessageOptions, type MessageType, ModelReference, Provider, ProviderConfig, type StreamEvent, type StreamEventType, type StreamResult, type TextBlock, Thread, type ThreadJSON, type TokenUsage, type Tool, type ToolCall, type ToolExecution, type ToolMetadata, type ToolResult, ToolResultMessage, type ToolUseStrategy, type Turn, type UserContent, UserMessage, type VideoBlock, aggregateUsage, ai, contentBlockStart, contentBlockStop, createProvider, createStreamResult, createTurn, emptyUsage, isAssistantMessage, isAudioBlock, isBinaryBlock, isImageBlock, isTextBlock, isToolResultMessage, isUserMessage, isVideoBlock, llm, messageStart, messageStop, text, textDelta, toolCallDelta };
+export { type AfterCallResult, type AssistantContent, AssistantMessage, type AudioBlock, type BeforeCallResult, type BinaryBlock, BoundEmbeddingModel, type BoundLLMModel, type ContentBlock, type EmbedOptions, type Embedding, EmbeddingHandler, EmbeddingInput, type EmbeddingInstance, type EmbeddingModelInput, type EmbeddingOptions, type EmbeddingProgress, type EmbeddingResult, type EmbeddingStream, EmbeddingUsage, type EventDelta, Image, type ImageBlock, ImageHandler, type ImageSource, type InferenceInput, type JSONSchema, type JSONSchemaProperty, type JSONSchemaPropertyType, type LLMCapabilities, type LLMHandler, type LLMInstance, type LLMOptions, LLMProvider, type LLMRequest, type LLMResponse, type LLMStreamResult, Message, type MessageJSON, type MessageMetadata, type MessageOptions, type MessageType, Provider, ProviderConfig, type StreamEvent, type StreamEventType, type StreamResult, type TextBlock, Thread, type ThreadJSON, type TokenUsage, type Tool, type ToolCall, type ToolExecution, type ToolMetadata, type ToolResult, ToolResultMessage, type ToolUseStrategy, type Turn, type UserContent, UserMessage, type VideoBlock, aggregateUsage, ai, contentBlockStart, contentBlockStop, createProvider, createStreamResult, createTurn, embedding, emptyUsage, isAssistantMessage, isAudioBlock, isBinaryBlock, isImageBlock, isTextBlock, isToolResultMessage, isUserMessage, isVideoBlock, llm, messageStart, messageStop, text, textDelta, toolCallDelta };

package/dist/index.js

@@ -161,7 +161,8 @@ function llm(options) {
       "llm"
     );
   }
-  const boundModel = provider.modalities.llm.bind(modelRef.modelId);
+  const llmHandler = provider.modalities.llm;
+  const boundModel = llmHandler.bind(modelRef.modelId);
   const capabilities = boundModel.capabilities;
   if (structure && !capabilities.structuredOutput) {
     throw new UPPError(
@@ -577,6 +578,152 @@ function validateMediaCapabilities(messages, capabilities, providerName) {
   }
 }
 
+// src/core/embedding.ts
+function embedding(options) {
+  const { model: modelRef, config = {}, params } = options;
+  const provider = modelRef.provider;
+  if (!provider.modalities.embedding) {
+    throw new UPPError(
+      `Provider '${provider.name}' does not support embedding modality`,
+      "INVALID_REQUEST",
+      provider.name,
+      "embedding"
+    );
+  }
+  const handler = provider.modalities.embedding;
+  const boundModel = handler.bind(modelRef.modelId);
+  const instance = {
+    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);
+    }
+  };
+  return instance;
+}
+async function executeEmbed(model, inputs, params, config, signal) {
+  const response = await model.embed({
+    inputs,
+    params,
+    config: config ?? {},
+    signal
+  });
+  return normalizeResponse(response);
+}
+function normalizeResponse(response) {
+  return {
+    embeddings: response.embeddings.map((vec, i) => {
+      const vector = normalizeVector(vec.vector);
+      return {
+        vector,
+        dimensions: vector.length,
+        index: vec.index ?? i,
+        tokens: vec.tokens,
+        metadata: vec.metadata
+      };
+    }),
+    usage: response.usage,
+    metadata: response.metadata
+  };
+}
+function normalizeVector(vector) {
+  if (Array.isArray(vector)) {
+    return vector;
+  }
+  return decodeBase64(vector);
+}
+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);
+  }
+  const floats = new Float32Array(bytes.buffer);
+  return Array.from(floats);
+}
+function createChunkedStream(model, inputs, params, config, options) {
+  const abortController = new AbortController();
+  const batchSize = options.batchSize ?? model.maxBatchSize;
+  const concurrency = options.concurrency ?? 1;
+  let resolveResult;
+  let rejectResult;
+  const resultPromise = new Promise((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+  async function* generate() {
+    const total = inputs.length;
+    const allEmbeddings = [];
+    let totalTokens = 0;
+    const batches = [];
+    for (let i = 0; i < inputs.length; i += batchSize) {
+      batches.push(inputs.slice(i, i + batchSize));
+    }
+    try {
+      for (let i = 0; i < batches.length; i += concurrency) {
+        if (abortController.signal.aborted || options.signal?.aborted) {
+          throw new UPPError(
+            "Embedding cancelled",
+            "CANCELLED",
+            model.provider.name,
+            "embedding"
+          );
+        }
+        const chunk = batches.slice(i, i + concurrency);
+        const responses = await Promise.all(
+          chunk.map(
+            (batch) => model.embed({
+              inputs: batch,
+              params,
+              config: config ?? {},
+              signal: abortController.signal
+            })
+          )
+        );
+        const batchEmbeddings = [];
+        for (const response of responses) {
+          for (const vec of response.embeddings) {
+            const vector = normalizeVector(vec.vector);
+            const emb = {
+              vector,
+              dimensions: vector.length,
+              index: allEmbeddings.length + batchEmbeddings.length,
+              tokens: vec.tokens,
+              metadata: vec.metadata
+            };
+            batchEmbeddings.push(emb);
+          }
+          totalTokens += response.usage.totalTokens;
+        }
+        allEmbeddings.push(...batchEmbeddings);
+        yield {
+          embeddings: batchEmbeddings,
+          completed: allEmbeddings.length,
+          total,
+          percent: allEmbeddings.length / total * 100
+        };
+      }
+      resolveResult({
+        embeddings: allEmbeddings,
+        usage: { totalTokens }
+      });
+    } catch (error) {
+      rejectResult(error);
+      throw error;
+    }
+  }
+  const generator = generate();
+  return {
+    [Symbol.asyncIterator]: () => generator,
+    result: resultPromise,
+    abort: () => abortController.abort()
+  };
+}
+
 // src/core/image.ts
 import { readFile } from "fs/promises";
 var Image = class _Image {
@@ -1073,7 +1220,9 @@ var Thread = class _Thread {
 // src/index.ts
 var ai = {
   /** LLM instance factory */
-  llm
+  llm,
+  /** Embedding instance factory */
+  embedding
 };
 export {
   AssistantMessage,
@@ -1098,6 +1247,7 @@ export {
   createProvider,
   createStreamResult,
   createTurn,
+  embedding,
   emptyUsage,
   isAssistantMessage,
   isAudioBlock,