@providerprotocol/ai 0.0.11 → 0.0.13

package/dist/provider-mKkz7Q9U.d.ts

@@ -0,0 +1,488 @@
+/**
+ * @fileoverview Error types for the Unified Provider Protocol.
+ *
+ * Provides normalized error codes and a unified error class for handling
+ * errors across different AI providers in a consistent manner.
+ *
+ * @module types/errors
+ */
+/**
+ * Normalized error codes for cross-provider error handling.
+ *
+ * These codes provide a consistent way to identify and handle errors
+ * regardless of which AI provider generated them.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await llm.generate('Hello');
+ * } catch (error) {
+ *   if (error instanceof UPPError) {
+ *     switch (error.code) {
+ *       case 'RATE_LIMITED':
+ *         await delay(error.retryAfter);
+ *         break;
+ *       case 'AUTHENTICATION_FAILED':
+ *         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';
+/**
+ * Unified Provider Protocol Error.
+ *
+ * All provider-specific errors are normalized to this type, providing
+ * a consistent interface for error handling across different AI providers.
+ *
+ * @example
+ * ```typescript
+ * throw new UPPError(
+ *   'API key is invalid',
+ *   'AUTHENTICATION_FAILED',
+ *   'openai',
+ *   'llm',
+ *   401
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Wrapping a provider error
+ * try {
+ *   await openai.chat.completions.create({ ... });
+ * } catch (err) {
+ *   throw new UPPError(
+ *     'OpenAI request failed',
+ *     'PROVIDER_ERROR',
+ *     'openai',
+ *     'llm',
+ *     err.status,
+ *     err
+ *   );
+ * }
+ * ```
+ */
+declare class UPPError extends Error {
+    /** Normalized error code for programmatic handling */
+    readonly code: ErrorCode;
+    /** Name of the provider that generated the error */
+    readonly provider: string;
+    /** The modality that was being used when the error occurred */
+    readonly modality: Modality;
+    /** HTTP status code from the provider's response, if available */
+    readonly statusCode?: number;
+    /** The original error that caused this UPPError, if wrapping another error */
+    readonly cause?: Error;
+    /** Error class name, always 'UPPError' */
+    readonly name = "UPPError";
+    /**
+     * Creates a new UPPError instance.
+     *
+     * @param message - Human-readable error description
+     * @param code - Normalized error code for programmatic handling
+     * @param provider - Name of the provider that generated the error
+     * @param modality - The modality that was being used
+     * @param statusCode - HTTP status code from the provider's response
+     * @param cause - The original error being wrapped
+     */
+    constructor(message: string, code: ErrorCode, provider: string, modality: Modality, statusCode?: number, cause?: Error);
+    /**
+     * Creates a string representation of the error.
+     *
+     * @returns Formatted error string including code, message, provider, and modality
+     */
+    toString(): string;
+    /**
+     * Converts the error to a JSON-serializable object.
+     *
+     * @returns Plain object representation suitable for logging or transmission
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * @fileoverview Provider types for AI service integrations.
+ *
+ * Defines the interfaces for provider factories, modality handlers,
+ * and configuration options for connecting to various AI providers.
+ *
+ * @module types/provider
+ */
+
+/**
+ * API key strategy interface for managing multiple keys.
+ *
+ * Implement this interface to provide custom key rotation or
+ * selection logic when working with multiple API keys.
+ *
+ * @example
+ * ```typescript
+ * class RoundRobinKeys implements KeyStrategy {
+ *   private keys: string[];
+ *   private index = 0;
+ *
+ *   constructor(keys: string[]) {
+ *     this.keys = keys;
+ *   }
+ *
+ *   getKey(): string {
+ *     const key = this.keys[this.index];
+ *     this.index = (this.index + 1) % this.keys.length;
+ *     return key;
+ *   }
+ * }
+ * ```
+ */
+interface KeyStrategy {
+    /**
+     * Gets the next API key to use for a request.
+     *
+     * @returns The API key string, or a Promise resolving to it
+     */
+    getKey(): string | Promise<string>;
+}
+/**
+ * Retry strategy interface for handling request failures.
+ *
+ * Implement this interface to provide custom retry logic for
+ * handling rate limits, transient errors, and other failures.
+ *
+ * @example
+ * ```typescript
+ * class ExponentialBackoff implements RetryStrategy {
+ *   private maxAttempts = 5;
+ *   private baseDelay = 1000;
+ *
+ *   onRetry(error: UPPError, attempt: number): number | null {
+ *     if (attempt > this.maxAttempts) return null;
+ *     if (error.code !== 'RATE_LIMITED') return null;
+ *     return this.baseDelay * Math.pow(2, attempt - 1);
+ *   }
+ * }
+ * ```
+ */
+interface RetryStrategy {
+    /**
+     * Called when a request fails with a retryable error.
+     *
+     * @param error - The error that occurred
+     * @param attempt - The attempt number (1 = first retry)
+     * @returns Delay in ms before retrying, or null to stop retrying
+     */
+    onRetry(error: UPPError, attempt: number): number | null | Promise<number | null>;
+    /**
+     * Called before each request. Can be used to implement pre-emptive rate limiting.
+     *
+     * @returns Delay in ms to wait before making the request, or 0 to proceed immediately
+     */
+    beforeRequest?(): number | Promise<number>;
+    /**
+     * Reset the strategy state (e.g., after a successful request).
+     */
+    reset?(): void;
+}
+/**
+ * Provider configuration for infrastructure and connection settings.
+ *
+ * These settings control how requests are made to the provider's API,
+ * including authentication, timeouts, and retry behavior.
+ *
+ * @example
+ * ```typescript
+ * const config: ProviderConfig = {
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   timeout: 30000,
+ *   retryStrategy: new ExponentialBackoff()
+ * };
+ *
+ * // Or with a key strategy for key rotation
+ * const config: ProviderConfig = {
+ *   apiKey: new RoundRobinKeys(['sk-1', 'sk-2', 'sk-3']),
+ *   baseUrl: 'https://custom-proxy.example.com'
+ * };
+ * ```
+ */
+interface ProviderConfig {
+    /**
+     * API key for authentication.
+     * Can be a string, async function, or KeyStrategy for advanced use cases.
+     */
+    apiKey?: string | (() => string | Promise<string>) | KeyStrategy;
+    /** Override the base API URL (for proxies, local models) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation (for logging, caching, custom TLS) */
+    fetch?: typeof fetch;
+    /** API version override (provider-specific) */
+    apiVersion?: string;
+    /** Retry strategy for handling failures and rate limits */
+    retryStrategy?: RetryStrategy;
+}
+/**
+ * A reference to a model, created by a provider factory.
+ *
+ * Model references are lightweight objects that identify a model
+ * and its provider, used as input to the llm() function.
+ *
+ * @typeParam TOptions - Provider-specific options type
+ *
+ * @example
+ * ```typescript
+ * const model = openai('gpt-4');
+ * console.log(model.modelId); // 'gpt-4'
+ * console.log(model.provider.name); // 'openai'
+ * ```
+ */
+interface ModelReference<TOptions = unknown> {
+    /** The model identifier (e.g., 'gpt-4', 'claude-3-opus') */
+    readonly modelId: string;
+    /** The provider that created this reference */
+    readonly provider: Provider<TOptions>;
+}
+/**
+ * LLM handler interface for providers.
+ *
+ * Implemented by providers to enable language model capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface LLMHandler<TParams = any> {
+    /**
+     * Binds a model ID to create an executable model instance.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound LLM model ready for inference
+     */
+    bind(modelId: string): BoundLLMModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     * Called by createProvider() after the provider is constructed.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: LLMProvider<TParams>): void;
+}
+/**
+ * Embedding handler interface for providers.
+ *
+ * Implemented by providers to enable embedding capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface EmbeddingHandler<TParams = any> {
+    /** Supported input types for embeddings */
+    readonly supportedInputs: ('text' | 'image')[];
+    /**
+     * Binds a model ID to create an executable embedding model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound embedding model ready for use
+     */
+    bind(modelId: string): BoundEmbeddingModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: EmbeddingProvider<TParams>): void;
+}
+/**
+ * Image handler interface for providers.
+ *
+ * Implemented by providers to enable image generation capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ * @internal
+ */
+interface ImageHandler<TParams = any> {
+    /**
+     * Binds a model ID to create an executable image model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound image model ready for generation
+     */
+    bind(modelId: string): BoundImageModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: ImageProvider<TParams>): void;
+}
+/**
+ * Bound LLM model interface (forward declaration).
+ *
+ * Full definition is in llm.ts to avoid circular dependencies.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundLLMModel<TParams = any> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: LLMProvider<TParams>;
+}
+/**
+ * Bound embedding model interface.
+ *
+ * Represents an embedding model bound to a specific model ID,
+ * ready to generate embeddings.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundEmbeddingModel<TParams = any> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: EmbeddingProvider<TParams>;
+    /** Maximum number of inputs per batch request */
+    readonly maxBatchSize: number;
+    /** Maximum length of input text in tokens */
+    readonly maxInputLength: number;
+    /** Output embedding dimensions */
+    readonly dimensions: number;
+}
+/**
+ * Bound image model interface.
+ *
+ * Represents an image generation model bound to a specific model ID.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundImageModel<TParams = any> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: ImageProvider<TParams>;
+}
+/**
+ * Provider factory function with metadata and modality handlers.
+ *
+ * The Provider interface represents a callable function that creates
+ * model references, along with metadata and modality-specific handlers.
+ *
+ * @typeParam TOptions - Provider-specific options passed to the factory
+ *
+ * @example
+ * ```typescript
+ * // Using a provider
+ * const model = openai('gpt-4', { temperature: 0.7 });
+ *
+ * // Accessing provider metadata
+ * console.log(openai.name); // 'openai'
+ * console.log(openai.version); // '1.0.0'
+ *
+ * // Accessing modality handlers
+ * const llmHandler = openai.modalities.llm;
+ * ```
+ */
+interface Provider<TOptions = unknown> {
+    /**
+     * Creates a model reference with optional provider-specific options.
+     *
+     * @param modelId - The model identifier
+     * @param options - Provider-specific options
+     * @returns A model reference for use with llm() or other functions
+     */
+    (modelId: string, options?: TOptions): ModelReference<TOptions>;
+    /** Provider name (e.g., 'openai', 'anthropic') */
+    readonly name: string;
+    /** Provider version string */
+    readonly version: string;
+    /** Supported modalities and their handlers */
+    readonly modalities: {
+        llm?: LLMHandler;
+        embedding?: EmbeddingHandler;
+        image?: ImageHandler;
+    };
+}
+/**
+ * Provider with LLM modality support.
+ *
+ * Type alias for providers that support language model inference.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type LLMProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
+    readonly modalities: {
+        llm: LLMHandler<TParams>;
+    };
+};
+/**
+ * Provider with Embedding modality support.
+ *
+ * Type alias for providers that support embedding generation.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type EmbeddingProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
+    readonly modalities: {
+        embedding: EmbeddingHandler<TParams>;
+    };
+};
+/**
+ * Provider with Image modality support.
+ *
+ * Type alias for providers that support image generation.
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+type ImageProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
+    readonly modalities: {
+        image: ImageHandler<TParams>;
+    };
+};
+
+export { type BoundEmbeddingModel as B, type EmbeddingHandler as E, type ImageHandler as I, type KeyStrategy as K, type LLMProvider as L, type ModelReference as M, type ProviderConfig as P, type RetryStrategy as R, UPPError as U, type LLMHandler as a, type Provider as b, type ErrorCode as c, type Modality as d, type EmbeddingProvider as e, type ImageProvider as f, type BoundImageModel as g };