@providerprotocol/ai 0.0.18 → 0.0.20

package/dist/index.d.ts

@@ -1,8 +1,12 @@
-import { M as Message, T as Turn, U as UserContent, A as AssistantContent, a as MessageType, b as MessageJSON, c as Tool, d as ToolUseStrategy, J as JSONSchema, C as ContentBlock, S as StreamResult, e as AssistantMessage, f as TokenUsage, g as StreamEvent, I as ImageSource, h as ImageBlock } from './stream-BjyVzBxV.js';
-export { w as AfterCallResult, l as AudioBlock, v as BeforeCallResult, B as BinaryBlock, P as EventDelta, i as JSONSchemaProperty, j as JSONSchemaPropertyType, G as MessageMetadata, H as MessageOptions, O as StreamEventType, k as TextBlock, r as ToolCall, x as ToolExecution, u as ToolMetadata, s as ToolResult, z as ToolResultMessage, y as UserMessage, V as VideoBlock, N as aggregateUsage, Z as contentBlockStart, _ as contentBlockStop, Q as createStreamResult, K as createTurn, L as emptyUsage, E as isAssistantMessage, o as isAudioBlock, q as isBinaryBlock, n as isImageBlock, m as isTextBlock, F as isToolResultMessage, D as isUserMessage, p as isVideoBlock, X as messageStart, Y as messageStop, t as text, R as textDelta, W as toolCallDelta } from './stream-BjyVzBxV.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';
+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';
 
 /**
  * @fileoverview Thread class for managing conversation history.
@@ -737,6 +741,43 @@ interface EmbeddingInstance<TParams = unknown> {
  */
 declare function embedding<TParams = unknown>(options: EmbeddingOptions<TParams>): EmbeddingInstance<TParams>;
 
+/**
+ * @fileoverview Image generation instance factory for the Universal Provider Protocol.
+ *
+ * This module provides the core functionality for creating image generation instances,
+ * including support for text-to-image generation, streaming, and image editing.
+ *
+ * @module core/image
+ */
+
+/**
+ * Creates an image generation instance configured with the specified options.
+ *
+ * This is the primary factory function for creating image generation instances.
+ * It validates provider capabilities, binds the model, and returns an instance
+ * with `generate`, `stream`, and `edit` methods.
+ *
+ * @typeParam TParams - Provider-specific parameter type for model configuration
+ * @param options - Configuration options for the image instance
+ * @returns A configured image instance ready for generation
+ * @throws {UPPError} When the provider does not support the image modality
+ *
+ * @example
+ * ```typescript
+ * import { image } from 'upp';
+ * import { openai } from 'upp/providers/openai';
+ *
+ * const dalle = image({
+ *   model: openai('dall-e-3'),
+ *   params: { size: '1024x1024', quality: 'hd' }
+ * });
+ *
+ * const result = await dalle.generate('A sunset over mountains');
+ * console.log(result.images.length);
+ * ```
+ */
+declare function image<TParams = unknown>(options: ImageOptions<TParams>): ImageInstance<TParams>;
+
 /**
  * @fileoverview Base provider interface and factory for the Universal Provider Protocol.
  *
@@ -811,159 +852,6 @@ interface CreateProviderOptions {
  */
 declare function createProvider<TOptions = unknown>(options: CreateProviderOptions): Provider<TOptions>;
 
-/**
- * @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/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 Unified Provider Protocol (UPP) - A unified interface for AI model inference
  *
@@ -971,6 +859,12 @@ declare class Image {
  * Anthropic, OpenAI, Google, Ollama, OpenRouter, and xAI. The library handles provider-specific
  * transformations, streaming, tool execution, and error handling.
  *
+ * @module @providerprotocol/ai
+ * @packageDocumentation
+ */
+/**
+ * LLM instance factory for creating model-bound inference functions.
+ *
  * @example Basic usage
  * ```typescript
  * import { llm, anthropic } from '@providerprotocol/ai';
@@ -992,11 +886,7 @@ declare class Image {
  *   }
  * }
  * ```
- *
- * @module @providerprotocol/ai
- * @packageDocumentation
  */
-/** LLM instance factory for creating model-bound inference functions */
 
 /**
  * UPP namespace object providing alternative import style.
@@ -1016,6 +906,8 @@ declare const ai: {
     llm: typeof llm;
     /** Embedding instance factory */
     embedding: typeof embedding;
+    /** Image generation instance factory */
+    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, Image, ImageBlock, ImageHandler, ImageSource, 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, 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, Provider, ProviderConfig, StreamEvent, StreamResult, Thread, type ThreadJSON, TokenUsage, Tool, ToolUseStrategy, Turn, UserContent, ai, createProvider, embedding, image, llm };

package/dist/index.js

@@ -6,6 +6,9 @@ import {
 import {
   createProvider
 } from "./chunk-MSR5P65T.js";
+import {
+  Image
+} from "./chunk-WAKD3OO5.js";
 import {
   AssistantMessage,
   Message,
@@ -28,10 +31,10 @@ import {
   DynamicKey,
   RoundRobinKeys,
   WeightedKeys
-} from "./chunk-5FEAOEXV.js";
+} from "./chunk-P5IRTEM5.js";
 import {
   UPPError
-} from "./chunk-DZQHVGNV.js";
+} from "./chunk-U3FZWV4U.js";
 
 // src/types/stream.ts
 function createStreamResult(generator, turnPromise, abortController) {
@@ -679,223 +682,85 @@ function createChunkedStream(model, inputs, params, config, options) {
 }
 
 // src/core/image.ts
-var Image = class _Image {
-  /** The underlying image source (bytes, base64, or URL) */
-  source;
-  /** MIME type of the image (e.g., 'image/jpeg', 'image/png') */
-  mimeType;
-  /** Image width in pixels, if known */
-  width;
-  /** Image height in pixels, if known */
-  height;
-  constructor(source, mimeType, width, height) {
-    this.source = source;
-    this.mimeType = mimeType;
-    this.width = width;
-    this.height = height;
-  }
-  /**
-   * 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() {
-    return this.source.type !== "url";
-  }
-  /**
-   * 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() {
-    if (this.source.type === "base64") {
-      return this.source.data;
-    }
-    if (this.source.type === "bytes") {
-      return btoa(
-        Array.from(this.source.data).map((b) => String.fromCharCode(b)).join("")
-      );
-    }
-    throw new Error("Cannot convert URL image to base64. Fetch the image first.");
-  }
-  /**
-   * 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() {
-    const base64 = this.toBase64();
-    return `data:${this.mimeType};base64,${base64}`;
-  }
-  /**
-   * 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() {
-    if (this.source.type === "bytes") {
-      return this.source.data;
-    }
-    if (this.source.type === "base64") {
-      const binaryString = atob(this.source.data);
-      const bytes = new Uint8Array(binaryString.length);
-      for (let i = 0; i < binaryString.length; i++) {
-        bytes[i] = binaryString.charCodeAt(i);
-      }
-      return bytes;
-    }
-    throw new Error("Cannot get bytes from URL image. Fetch the image first.");
+function image(options) {
+  const { model: modelRef, config = {}, params } = options;
+  const provider = modelRef.provider;
+  if (!provider.modalities.image) {
+    throw new UPPError(
+      `Provider '${provider.name}' does not support image modality`,
+      "INVALID_REQUEST",
+      provider.name,
+      "image"
+    );
   }
-  /**
-   * Gets the URL for URL-sourced images.
-   *
-   * @returns The image URL
-   * @throws {Error} When the source is not a URL
-   */
-  toUrl() {
-    if (this.source.type === "url") {
-      return this.source.url;
+  const imageHandler = provider.modalities.image;
+  const boundModel = imageHandler.bind(modelRef.modelId);
+  const capabilities = boundModel.capabilities;
+  const instance = {
+    model: boundModel,
+    params,
+    capabilities,
+    async generate(input) {
+      const prompt = normalizeInput(input);
+      const response = await boundModel.generate({
+        prompt,
+        params,
+        config
+      });
+      return {
+        images: response.images,
+        metadata: response.metadata,
+        usage: response.usage
+      };
     }
-    throw new Error("This image does not have a URL source.");
-  }
-  /**
-   * Converts this Image to an ImageBlock for use in UPP messages.
-   *
-   * @returns An ImageBlock that can be included in message content arrays
-   */
-  toBlock() {
-    return {
-      type: "image",
-      source: this.source,
-      mimeType: this.mimeType,
-      width: this.width,
-      height: this.height
+  };
+  if (capabilities.streaming && boundModel.stream) {
+    const boundModelWithStream = boundModel;
+    instance.stream = function(input) {
+      const prompt = normalizeInput(input);
+      const abortController = new AbortController();
+      const providerStream = boundModelWithStream.stream({
+        prompt,
+        params,
+        config,
+        signal: abortController.signal
+      });
+      const resultPromise = providerStream.response.then((response) => ({
+        images: response.images,
+        metadata: response.metadata,
+        usage: response.usage
+      }));
+      return {
+        [Symbol.asyncIterator]: () => providerStream[Symbol.asyncIterator](),
+        result: resultPromise,
+        abort: () => abortController.abort()
+      };
     };
   }
-  /**
-   * 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 async fromPath(path) {
-    const { readFile } = await import("fs/promises");
-    const data = await readFile(path);
-    const mimeType = detectMimeType(path);
-    return new _Image(
-      { type: "bytes", data: new Uint8Array(data) },
-      mimeType
-    );
-  }
-  /**
-   * 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, mimeType) {
-    const detected = mimeType || detectMimeTypeFromUrl(url);
-    return new _Image({ type: "url", url }, detected);
-  }
-  /**
-   * 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, mimeType) {
-    return new _Image({ type: "bytes", data }, mimeType);
-  }
-  /**
-   * 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, mimeType) {
-    return new _Image({ type: "base64", data: base64 }, mimeType);
-  }
-  /**
-   * 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) {
-    return new _Image(
-      block.source,
-      block.mimeType,
-      block.width,
-      block.height
-    );
-  }
-};
-function detectMimeType(path) {
-  const ext = path.split(".").pop()?.toLowerCase();
-  switch (ext) {
-    case "jpg":
-    case "jpeg":
-      return "image/jpeg";
-    case "png":
-      return "image/png";
-    case "gif":
-      return "image/gif";
-    case "webp":
-      return "image/webp";
-    case "svg":
-      return "image/svg+xml";
-    case "bmp":
-      return "image/bmp";
-    case "ico":
-      return "image/x-icon";
-    default:
-      return "application/octet-stream";
+  if (capabilities.edit && boundModel.edit) {
+    const boundModelWithEdit = boundModel;
+    instance.edit = async function(input) {
+      const response = await boundModelWithEdit.edit({
+        image: input.image,
+        mask: input.mask,
+        prompt: input.prompt,
+        params,
+        config
+      });
+      return {
+        images: response.images,
+        metadata: response.metadata,
+        usage: response.usage
+      };
+    };
   }
+  return instance;
 }
-function detectMimeTypeFromUrl(url) {
-  try {
-    const pathname = new URL(url).pathname;
-    return detectMimeType(pathname);
-  } catch {
-    return "application/octet-stream";
+function normalizeInput(input) {
+  if (typeof input === "string") {
+    return input;
   }
+  return input.prompt;
 }
 
 // src/types/content.ts
@@ -1176,7 +1041,9 @@ var ai = {
   /** LLM instance factory */
   llm,
   /** Embedding instance factory */
-  embedding
+  embedding,
+  /** Image generation instance factory */
+  image
 };
 export {
   AssistantMessage,
@@ -1203,6 +1070,7 @@ export {
   createTurn,
   embedding,
   emptyUsage,
+  image,
   isAssistantMessage,
   isAudioBlock,
   isBinaryBlock,