@providerprotocol/ai 0.0.21 → 0.0.23

package/dist/{provider-DGQHYE6I.d.ts → provider-DR1yins0.d.ts}

@@ -7,6 +7,68 @@
  *
  * @module types/content
  */
+/**
+ * Content block type constants.
+ *
+ * Use these constants instead of raw strings for type-safe content handling:
+ *
+ * @example
+ * ```typescript
+ * import { ContentBlockType } from 'upp';
+ *
+ * if (block.type === ContentBlockType.Text) {
+ *   console.log(block.text);
+ * } else if (block.type === ContentBlockType.Image) {
+ *   console.log(block.mimeType);
+ * }
+ * ```
+ */
+declare const ContentBlockType: {
+    /** Text content */
+    readonly Text: "text";
+    /** Image content */
+    readonly Image: "image";
+    /** Audio content */
+    readonly Audio: "audio";
+    /** Video content */
+    readonly Video: "video";
+    /** Binary/arbitrary data content */
+    readonly Binary: "binary";
+};
+/**
+ * Content block type discriminator union.
+ *
+ * This type is derived from {@link ContentBlockType} constants.
+ */
+type ContentBlockType = (typeof ContentBlockType)[keyof typeof ContentBlockType];
+/**
+ * Image source type constants.
+ *
+ * @example
+ * ```typescript
+ * import { ImageSourceType } from 'upp';
+ *
+ * if (source.type === ImageSourceType.Base64) {
+ *   // Handle base64 encoded image
+ * } else if (source.type === ImageSourceType.Url) {
+ *   // Handle URL reference
+ * }
+ * ```
+ */
+declare const ImageSourceType: {
+    /** Base64-encoded image data */
+    readonly Base64: "base64";
+    /** URL reference to image */
+    readonly Url: "url";
+    /** Raw bytes image data */
+    readonly Bytes: "bytes";
+};
+/**
+ * Image source type discriminator union.
+ *
+ * This type is derived from {@link ImageSourceType} constants.
+ */
+type ImageSourceType = (typeof ImageSourceType)[keyof typeof ImageSourceType];
 /**
  * Image source variants for ImageBlock.
  *
@@ -282,70 +344,100 @@ declare function isBinaryBlock(block: ContentBlock): block is BinaryBlock;
  * @module types/errors
  */
 /**
- * Normalized error codes for cross-provider error handling.
+ * Error code constants for cross-provider error handling.
  *
- * These codes provide a consistent way to identify and handle errors
- * regardless of which AI provider generated them.
+ * Use these constants instead of raw strings for type-safe error handling:
  *
  * @example
  * ```typescript
+ * import { ErrorCode } from 'upp';
+ *
  * try {
  *   await llm.generate('Hello');
  * } catch (error) {
  *   if (error instanceof UPPError) {
  *     switch (error.code) {
- *       case 'RATE_LIMITED':
+ *       case ErrorCode.RateLimited:
  *         await delay(error.retryAfter);
  *         break;
- *       case 'AUTHENTICATION_FAILED':
+ *       case ErrorCode.AuthenticationFailed:
  *         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';
+declare const ErrorCode: {
+    /** API key is invalid or expired */
+    readonly AuthenticationFailed: "AUTHENTICATION_FAILED";
+    /** Rate limit exceeded, retry after delay */
+    readonly RateLimited: "RATE_LIMITED";
+    /** Input exceeds model's context window */
+    readonly ContextLengthExceeded: "CONTEXT_LENGTH_EXCEEDED";
+    /** Requested model does not exist */
+    readonly ModelNotFound: "MODEL_NOT_FOUND";
+    /** Request parameters are malformed */
+    readonly InvalidRequest: "INVALID_REQUEST";
+    /** Provider returned an unexpected response format */
+    readonly InvalidResponse: "INVALID_RESPONSE";
+    /** Content was blocked by safety filters */
+    readonly ContentFiltered: "CONTENT_FILTERED";
+    /** Account quota or credits exhausted */
+    readonly QuotaExceeded: "QUOTA_EXCEEDED";
+    /** Provider-specific error not covered by other codes */
+    readonly ProviderError: "PROVIDER_ERROR";
+    /** Network connectivity issue */
+    readonly NetworkError: "NETWORK_ERROR";
+    /** Request exceeded timeout limit */
+    readonly Timeout: "TIMEOUT";
+    /** Request was cancelled via AbortSignal */
+    readonly Cancelled: "CANCELLED";
+};
+/**
+ * Error code discriminator union.
+ *
+ * This type is derived from {@link ErrorCode} constants. Use `ErrorCode.RateLimited`
+ * for constants or `type MyCode = ErrorCode` for type annotations.
+ */
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Modality type discriminator union.
+ *
+ * This type is derived from {@link ModalityType} constants. The name `Modality`
+ * is kept for backward compatibility; `ModalityType` works as both the const
+ * object and this type.
+ */
+type Modality = (typeof ModalityType)[keyof typeof ModalityType];
+/**
+ * Modality type constants.
+ *
+ * Use these constants for type-safe modality handling:
+ *
+ * @example
+ * ```typescript
+ * import { ModalityType } from 'upp';
+ *
+ * if (provider.modality === ModalityType.LLM) {
+ *   // Handle LLM provider
+ * }
+ * ```
+ */
+declare const ModalityType: {
+    /** Large language model for text generation */
+    readonly LLM: "llm";
+    /** Text/image embedding model */
+    readonly Embedding: "embedding";
+    /** Image generation model */
+    readonly Image: "image";
+    /** Audio processing/generation model */
+    readonly Audio: "audio";
+    /** Video processing/generation model */
+    readonly Video: "video";
+};
+/**
+ * Type alias for Modality, allowing `ModalityType` to work as both const and type.
+ */
+type ModalityType = Modality;
 /**
  * Unified Provider Protocol Error.
  *
@@ -354,26 +446,30 @@ type Modality =
  *
  * @example
  * ```typescript
+ * import { ErrorCode, ModalityType } from 'upp';
+ *
  * throw new UPPError(
  *   'API key is invalid',
- *   'AUTHENTICATION_FAILED',
+ *   ErrorCode.AuthenticationFailed,
  *   'openai',
- *   'llm',
+ *   ModalityType.LLM,
  *   401
  * );
  * ```
  *
  * @example
  * ```typescript
+ * import { ErrorCode, ModalityType } from 'upp';
+ *
  * // Wrapping a provider error
  * try {
  *   await openai.chat.completions.create({ ... });
  * } catch (err) {
  *   throw new UPPError(
  *     'OpenAI request failed',
- *     'PROVIDER_ERROR',
+ *     ErrorCode.ProviderError,
  *     'openai',
- *     'llm',
+ *     ModalityType.LLM,
  *     err.status,
  *     err
  *   );
@@ -593,6 +689,8 @@ declare class Image {
 interface ImageModelInput {
     readonly modelId: string;
     readonly provider: ProviderIdentity;
+    /** Optional provider configuration merged into requests */
+    readonly providerConfig?: Partial<ProviderConfig>;
 }
 /**
  * Options for creating an image instance with the image() function.
@@ -1000,7 +1098,10 @@ interface ProviderConfig {
     apiKey?: string | (() => string | Promise<string>) | KeyStrategy;
     /** Override the base API URL (for proxies, local models) */
     baseUrl?: string;
-    /** Request timeout in milliseconds */
+    /**
+     * Request timeout in milliseconds.
+     * Applied per attempt; total wall time can exceed this when retries are enabled.
+     */
     timeout?: number;
     /** Custom fetch implementation (for logging, caching, custom TLS) */
     fetch?: typeof fetch;
@@ -1025,6 +1126,11 @@ interface ProviderConfig {
      * ```
      */
     headers?: Record<string, string | undefined>;
+    /**
+     * Maximum Retry-After delay in seconds when honoring server headers.
+     * Defaults to 3600 seconds (1 hour).
+     */
+    retryAfterMaxSeconds?: number;
 }
 /**
  * A reference to a model, created by a provider factory.
@@ -1316,4 +1422,4 @@ type ImageProvider<TParams = unknown, TOptions = unknown> = Provider<TOptions> &
     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 };
+export { type ImageResponse as $, type AssistantContent as A, type BoundEmbeddingModel as B, type ContentBlock as C, type EmbeddingRequest as D, type EmbeddingInput as E, type EmbeddingResponse as F, type EmbeddingVector as G, type ImageInput as H, type ImageOptions as I, type ImageEditInput as J, type KeyStrategy as K, type LLMProvider as L, type ModelReference as M, type ImageGenerateOptions as N, type GeneratedImage as O, type ProviderIdentity as P, type ImageUsage as Q, type RetryStrategy as R, type ImageResult as S, type TextBlock as T, type UserContent as U, type VideoBlock as V, type ImageStreamEvent as W, type ImageStreamResult as X, type ImageCapabilities as Y, type ImageRequest as Z, type ImageEditRequest as _, type ProviderConfig as a, type ImageProviderStreamResult as a0, type BoundImageModel as a1, type ImageHandler$1 as a2, type ImageModelInput as a3, 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, ErrorCode as j, ModalityType as k, type Modality as l, type ImageBlock as m, type AudioBlock as n, type BinaryBlock as o, type ImageSource as p, ContentBlockType as q, ImageSourceType as r, isTextBlock as s, text as t, isImageBlock as u, isAudioBlock as v, isVideoBlock as w, isBinaryBlock as x, type EmbeddingProvider as y, type ImageProvider as z };

package/dist/proxy/index.d.ts

@@ -1,5 +1,5 @@
-import { g as Provider, M as ModelReference } from '../provider-DGQHYE6I.js';
-import { M as Message, b as MessageJSON, T as Turn, H as TurnJSON, f as StreamEvent, S as StreamResult, J as JSONSchema, k as ToolMetadata, c as Tool } from '../stream-Di9acos2.js';
+import { g as Provider, M as ModelReference } from '../provider-DR1yins0.js';
+import { M as Message, b as MessageJSON, T as Turn, I as TurnJSON, f as StreamEvent, S as StreamResult, J as JSONSchema, k as ToolMetadata, c as Tool } from '../stream-BuTrqt_j.js';
 
 /**
  * @fileoverview Proxy provider types.

package/dist/proxy/index.js

@@ -1,18 +1,24 @@
 import {
   emptyUsage
-} from "../chunk-SKY2JLA7.js";
+} from "../chunk-MKDLXV4O.js";
+import {
+  parseJsonResponse
+} from "../chunk-Z6DKC37J.js";
 import {
   AssistantMessage,
   ToolResultMessage,
   UserMessage,
   createProvider
-} from "../chunk-M4BMM5IB.js";
+} from "../chunk-MF5ETY5O.js";
 import {
+  ErrorCode,
+  ModalityType,
   UPPError,
   doFetch,
   doStreamFetch,
-  normalizeHttpError
-} from "../chunk-EDENPF3E.js";
+  normalizeHttpError,
+  toError
+} from "../chunk-QNJO7DSD.js";
 
 // src/providers/proxy/serialization.ts
 function serializeMessage(m) {
@@ -50,7 +56,12 @@ function deserializeMessage(json) {
     case "tool_result":
       return new ToolResultMessage(json.results ?? [], options);
     default:
-      throw new Error(`Unknown message type: ${json.type}`);
+      throw new UPPError(
+        `Unknown message type: ${json.type}`,
+        ErrorCode.InvalidResponse,
+        "proxy",
+        ModalityType.LLM
+      );
   }
 }
 function serializeTurn(turn) {
@@ -109,9 +120,9 @@ function createLLMHandler(options) {
       if (!providerRef) {
         throw new UPPError(
           "Provider reference not set. Handler must be used with createProvider().",
-          "INVALID_REQUEST",
+          ErrorCode.InvalidRequest,
           "proxy",
-          "llm"
+          ModalityType.LLM
         );
       }
       const model = {
@@ -139,7 +150,7 @@ function createLLMHandler(options) {
             "proxy",
             "llm"
           );
-          const data = await response.json();
+          const data = await parseJsonResponse(response, "proxy", "llm");
           return turnJSONToLLMResponse(data);
         },
         stream(request) {
@@ -175,9 +186,9 @@ function createLLMHandler(options) {
               if (!response.body) {
                 throw new UPPError(
                   "Response body is null",
-                  "PROVIDER_ERROR",
+                  ErrorCode.ProviderError,
                   "proxy",
-                  "llm"
+                  ModalityType.LLM
                 );
               }
               const reader = response.body.getReader();
@@ -191,8 +202,36 @@ function createLLMHandler(options) {
                 buffer = lines.pop() ?? "";
                 for (const line of lines) {
                   if (!line.trim() || line.startsWith(":")) continue;
-                  if (line.startsWith("data: ")) {
-                    const data = line.slice(6);
+                  if (line.startsWith("data:")) {
+                    let data = line.slice(5);
+                    if (data.startsWith(" ")) {
+                      data = data.slice(1);
+                    }
+                    if (data === "[DONE]") continue;
+                    try {
+                      const parsed = JSON.parse(data);
+                      if ("messages" in parsed && "usage" in parsed && "cycles" in parsed) {
+                        resolveResponse(turnJSONToLLMResponse(parsed));
+                      } else {
+                        yield deserializeStreamEvent(parsed);
+                      }
+                    } catch {
+                    }
+                  }
+                }
+              }
+              const remaining = decoder.decode();
+              if (remaining) {
+                buffer += remaining;
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines) {
+                  if (!line.trim() || line.startsWith(":")) continue;
+                  if (line.startsWith("data:")) {
+                    let data = line.slice(5);
+                    if (data.startsWith(" ")) {
+                      data = data.slice(1);
+                    }
                     if (data === "[DONE]") continue;
                     try {
                       const parsed = JSON.parse(data);
@@ -207,7 +246,7 @@ function createLLMHandler(options) {
                 }
               }
             } catch (error) {
-              rejectResponse(error instanceof Error ? error : new Error(String(error)));
+              rejectResponse(toError(error));
               throw error;
             }
           };
@@ -249,13 +288,117 @@ function mergeHeaders(requestHeaders, defaultHeaders) {
 function turnJSONToLLMResponse(data) {
   const messages = data.messages.map(deserializeMessage);
   const lastAssistant = messages.filter((m) => m.type === "assistant").pop();
+  const stopReason = deriveStopReason(lastAssistant);
   return {
     message: lastAssistant ?? new AssistantMessage(""),
     usage: data.usage ?? emptyUsage(),
-    stopReason: "stop",
+    stopReason,
     data: data.data
   };
 }
+function deriveStopReason(message) {
+  if (!message) {
+    return "end_turn";
+  }
+  if (message.toolCalls && message.toolCalls.length > 0) {
+    return "tool_use";
+  }
+  const metadata = message.metadata;
+  const openaiMeta = metadata?.openai;
+  if (openaiMeta?.status) {
+    if (openaiMeta.status === "failed") {
+      return "error";
+    }
+    if (openaiMeta.status === "completed") {
+      return "end_turn";
+    }
+  }
+  if (openaiMeta?.finish_reason) {
+    return mapCompletionStopReason(openaiMeta.finish_reason);
+  }
+  const openrouterMeta = metadata?.openrouter;
+  if (openrouterMeta?.finish_reason) {
+    return mapCompletionStopReason(openrouterMeta.finish_reason);
+  }
+  const xaiMeta = metadata?.xai;
+  if (xaiMeta?.status) {
+    if (xaiMeta.status === "failed") {
+      return "error";
+    }
+    if (xaiMeta.status === "completed") {
+      return "end_turn";
+    }
+  }
+  if (xaiMeta?.finish_reason) {
+    return mapCompletionStopReason(xaiMeta.finish_reason);
+  }
+  const anthropicMeta = metadata?.anthropic;
+  if (anthropicMeta?.stop_reason) {
+    return mapAnthropicStopReason(anthropicMeta.stop_reason);
+  }
+  const googleMeta = metadata?.google;
+  if (googleMeta?.finishReason) {
+    return mapGoogleStopReason(googleMeta.finishReason);
+  }
+  const ollamaMeta = metadata?.ollama;
+  if (ollamaMeta?.done_reason) {
+    return mapOllamaStopReason(ollamaMeta.done_reason);
+  }
+  return "end_turn";
+}
+function mapCompletionStopReason(reason) {
+  switch (reason) {
+    case "stop":
+      return "end_turn";
+    case "length":
+      return "max_tokens";
+    case "tool_calls":
+      return "tool_use";
+    case "content_filter":
+      return "content_filter";
+    default:
+      return "end_turn";
+  }
+}
+function mapAnthropicStopReason(reason) {
+  switch (reason) {
+    case "tool_use":
+      return "tool_use";
+    case "max_tokens":
+      return "max_tokens";
+    case "end_turn":
+      return "end_turn";
+    case "stop_sequence":
+      return "end_turn";
+    default:
+      return "end_turn";
+  }
+}
+function mapGoogleStopReason(reason) {
+  switch (reason) {
+    case "STOP":
+      return "end_turn";
+    case "MAX_TOKENS":
+      return "max_tokens";
+    case "SAFETY":
+      return "content_filter";
+    case "RECITATION":
+      return "content_filter";
+    case "OTHER":
+      return "end_turn";
+    default:
+      return "end_turn";
+  }
+}
+function mapOllamaStopReason(reason) {
+  if (reason === "length") {
+    return "max_tokens";
+  }
+  if (reason === "stop") {
+    return "end_turn";
+  }
+  return "end_turn";
+}
 
 // src/providers/proxy/server/express.ts
 function sendJSON(turn, res) {
@@ -417,6 +560,24 @@ function parseBody(body) {
   if (!Array.isArray(data.messages)) {
     throw new Error("Request body must have a messages array");
   }
+  for (const message of data.messages) {
+    if (!message || typeof message !== "object") {
+      throw new Error("Each message must be an object");
+    }
+    const msg = message;
+    if (typeof msg.id !== "string") {
+      throw new Error("Each message must have a string id");
+    }
+    if (typeof msg.type !== "string") {
+      throw new Error("Each message must have a string type");
+    }
+    if (typeof msg.timestamp !== "string") {
+      throw new Error("Each message must have a string timestamp");
+    }
+    if ((msg.type === "user" || msg.type === "assistant") && !Array.isArray(msg.content)) {
+      throw new Error("User and assistant messages must have a content array");
+    }
+  }
   return {
     messages: data.messages.map(deserializeMessage),
     system: data.system,
@@ -466,7 +627,7 @@ function toSSE(stream) {
     }
   });
 }
-function toError(message, status = 500) {
+function toError2(message, status = 500) {
   return new Response(JSON.stringify({ error: message }), {
     status,
     headers: { "Content-Type": "application/json" }
@@ -486,7 +647,7 @@ var webapi = {
   parseBody,
   toJSON,
   toSSE,
-  toError,
+  toError: toError2,
   bindTools
 };
 
@@ -529,7 +690,7 @@ export {
   serializeStreamEvent,
   serializeTurn,
   server,
-  toError,
+  toError2 as toError,
   toJSON,
   toSSE,
   webapi