@providerprotocol/ai 0.0.12 → 0.0.14

package/dist/retry-BatS2hjD.d.ts

@@ -0,0 +1,508 @@
+import { K as KeyStrategy, P as ProviderConfig, d as Modality, R as RetryStrategy, U as UPPError } from './provider-Bi0nyNhA.js';
+
+/**
+ * API key management strategies for load balancing and dynamic key selection.
+ * @module http/keys
+ */
+
+/**
+ * Distributes API requests across multiple keys using round-robin selection.
+ *
+ * Each call to {@link getKey} returns the next key in sequence, cycling back to
+ * the first key after reaching the end. This provides even distribution of requests
+ * across all available keys, which is useful for:
+ * - Spreading rate limits across multiple API keys
+ * - Load balancing between different accounts
+ * - Maximizing throughput when multiple keys are available
+ *
+ * @implements {KeyStrategy}
+ *
+ * @example
+ * ```typescript
+ * const keys = new RoundRobinKeys([
+ *   'sk-key-1',
+ *   'sk-key-2',
+ *   'sk-key-3'
+ * ]);
+ *
+ * keys.getKey(); // Returns 'sk-key-1'
+ * keys.getKey(); // Returns 'sk-key-2'
+ * keys.getKey(); // Returns 'sk-key-3'
+ * keys.getKey(); // Returns 'sk-key-1' (cycles back)
+ * ```
+ */
+declare class RoundRobinKeys implements KeyStrategy {
+    private keys;
+    private index;
+    /**
+     * Creates a new RoundRobinKeys instance.
+     *
+     * @param keys - Array of API keys to rotate through
+     * @throws {Error} When the keys array is empty
+     */
+    constructor(keys: string[]);
+    /**
+     * Returns the next key in the rotation sequence.
+     *
+     * @returns The next API key in round-robin order
+     */
+    getKey(): string;
+}
+/**
+ * Selects API keys using weighted random probability.
+ *
+ * Each key is assigned a weight that determines its probability of being selected.
+ * Higher weights mean higher selection probability. This is useful for:
+ * - Preferring higher-tier API keys with better rate limits
+ * - Gradually migrating traffic between old and new keys
+ * - A/B testing different API accounts
+ * - Directing more traffic to keys with higher quotas
+ *
+ * The selection probability for each key is: weight / totalWeight
+ *
+ * @implements {KeyStrategy}
+ *
+ * @example
+ * ```typescript
+ * const keys = new WeightedKeys([
+ *   { key: 'sk-premium', weight: 70 },   // 70% of requests
+ *   { key: 'sk-standard', weight: 20 },  // 20% of requests
+ *   { key: 'sk-backup', weight: 10 }     // 10% of requests
+ * ]);
+ *
+ * // Configure provider with weighted key selection
+ * const provider = createOpenAI({
+ *   apiKey: keys
+ * });
+ * ```
+ */
+declare class WeightedKeys implements KeyStrategy {
+    private entries;
+    private totalWeight;
+    /**
+     * Creates a new WeightedKeys instance.
+     *
+     * @param keys - Array of key-weight pairs defining selection probabilities
+     * @throws {Error} When the keys array is empty
+     */
+    constructor(keys: Array<{
+        key: string;
+        weight: number;
+    }>);
+    /**
+     * Returns a randomly selected key based on configured weights.
+     *
+     * @returns An API key selected with probability proportional to its weight
+     */
+    getKey(): string;
+}
+/**
+ * Provides dynamic key selection using custom logic.
+ *
+ * This strategy delegates key selection to a user-provided function, enabling
+ * advanced scenarios such as:
+ * - Fetching keys from a secrets manager (AWS Secrets Manager, HashiCorp Vault)
+ * - Rotating keys based on external state or configuration
+ * - Selecting keys based on request context or time of day
+ * - Implementing custom load balancing algorithms
+ *
+ * The selector function can be synchronous or asynchronous.
+ *
+ * @implements {KeyStrategy}
+ *
+ * @example
+ * ```typescript
+ * // Fetch key from environment based on current mode
+ * const dynamicKey = new DynamicKey(() => {
+ *   return process.env.NODE_ENV === 'production'
+ *     ? process.env.PROD_API_KEY!
+ *     : process.env.DEV_API_KEY!;
+ * });
+ *
+ * // Async key fetching from a secrets manager
+ * const vaultKey = new DynamicKey(async () => {
+ *   const secret = await vault.read('secret/openai');
+ *   return secret.data.apiKey;
+ * });
+ *
+ * // Time-based key rotation
+ * const timedKey = new DynamicKey(() => {
+ *   const hour = new Date().getHours();
+ *   return hour < 12 ? morningKey : afternoonKey;
+ * });
+ * ```
+ */
+declare class DynamicKey implements KeyStrategy {
+    private selector;
+    /**
+     * Creates a new DynamicKey instance.
+     *
+     * @param selector - Function that returns an API key (sync or async)
+     */
+    constructor(selector: () => string | Promise<string>);
+    /**
+     * Invokes the selector function to retrieve the current key.
+     *
+     * @returns Promise resolving to the selected API key
+     */
+    getKey(): Promise<string>;
+}
+/**
+ * Resolves an API key from provider configuration with multiple fallback options.
+ *
+ * This function handles various key specification methods in priority order:
+ * 1. Direct string key in config.apiKey
+ * 2. Function returning a key (sync or async) in config.apiKey
+ * 3. KeyStrategy instance in config.apiKey (RoundRobinKeys, WeightedKeys, DynamicKey)
+ * 4. Environment variable fallback (if envVar parameter is provided)
+ *
+ * @param config - Provider configuration containing the apiKey option
+ * @param envVar - Optional environment variable name to check as fallback
+ * @param provider - Provider identifier for error context (default: 'unknown')
+ * @param modality - Request modality for error context (default: 'llm')
+ * @returns The resolved API key string
+ *
+ * @throws {UPPError} AUTHENTICATION_FAILED - When no valid key is found
+ *
+ * @example
+ * ```typescript
+ * // Direct key in config
+ * const key1 = await resolveApiKey({ apiKey: 'sk-...' }, 'OPENAI_API_KEY', 'openai');
+ *
+ * // Function-based key
+ * const key2 = await resolveApiKey({ apiKey: () => getKeyFromVault() }, undefined, 'anthropic');
+ *
+ * // KeyStrategy instance
+ * const key3 = await resolveApiKey({
+ *   apiKey: new RoundRobinKeys(['sk-1', 'sk-2', 'sk-3'])
+ * }, 'OPENAI_API_KEY', 'openai');
+ *
+ * // Environment variable fallback
+ * const key4 = await resolveApiKey({}, 'ANTHROPIC_API_KEY', 'anthropic');
+ * ```
+ */
+declare function resolveApiKey(config: ProviderConfig, envVar?: string, provider?: string, modality?: Modality): Promise<string>;
+
+/**
+ * Retry strategies for handling transient failures in HTTP requests.
+ * @module http/retry
+ */
+
+/**
+ * Implements exponential backoff with optional jitter for retry delays.
+ *
+ * The delay between retries doubles with each attempt, helping to:
+ * - Avoid overwhelming servers during outages
+ * - Reduce thundering herd effects when many clients retry simultaneously
+ * - Give transient issues time to resolve
+ *
+ * Delay formula: min(baseDelay * 2^(attempt-1), maxDelay)
+ * With jitter: delay * random(0.5, 1.0)
+ *
+ * Only retries on transient errors: RATE_LIMITED, NETWORK_ERROR, TIMEOUT, PROVIDER_ERROR
+ *
+ * @implements {RetryStrategy}
+ *
+ * @example
+ * ```typescript
+ * // Default configuration (3 retries, 1s base, 30s max, jitter enabled)
+ * const retry = new ExponentialBackoff();
+ *
+ * // Custom configuration
+ * const customRetry = new ExponentialBackoff({
+ *   maxAttempts: 5,     // Up to 5 retry attempts
+ *   baseDelay: 500,     // Start with 500ms delay
+ *   maxDelay: 60000,    // Cap at 60 seconds
+ *   jitter: false       // Disable random jitter
+ * });
+ *
+ * // Use with provider
+ * const provider = createOpenAI({
+ *   retryStrategy: customRetry
+ * });
+ * ```
+ */
+declare class ExponentialBackoff implements RetryStrategy {
+    private maxAttempts;
+    private baseDelay;
+    private maxDelay;
+    private jitter;
+    /**
+     * Creates a new ExponentialBackoff instance.
+     *
+     * @param options - Configuration options
+     * @param options.maxAttempts - Maximum number of retry attempts (default: 3)
+     * @param options.baseDelay - Initial delay in milliseconds (default: 1000)
+     * @param options.maxDelay - Maximum delay cap in milliseconds (default: 30000)
+     * @param options.jitter - Whether to add random jitter to delays (default: true)
+     */
+    constructor(options?: {
+        maxAttempts?: number;
+        baseDelay?: number;
+        maxDelay?: number;
+        jitter?: boolean;
+    });
+    /**
+     * Determines whether to retry and calculates the delay.
+     *
+     * @param error - The error that triggered the retry
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns Delay in milliseconds before next retry, or null to stop retrying
+     */
+    onRetry(error: UPPError, attempt: number): number | null;
+    /**
+     * Checks if an error is eligible for retry.
+     *
+     * @param error - The error to evaluate
+     * @returns True if the error is transient and retryable
+     */
+    private isRetryable;
+}
+/**
+ * Implements linear backoff where delays increase proportionally with each attempt.
+ *
+ * Unlike exponential backoff, linear backoff increases delays at a constant rate:
+ * - Attempt 1: delay * 1 (e.g., 1000ms)
+ * - Attempt 2: delay * 2 (e.g., 2000ms)
+ * - Attempt 3: delay * 3 (e.g., 3000ms)
+ *
+ * This strategy is simpler and more predictable than exponential backoff,
+ * suitable for scenarios where gradual delay increase is preferred over
+ * aggressive backoff.
+ *
+ * Only retries on transient errors: RATE_LIMITED, NETWORK_ERROR, TIMEOUT, PROVIDER_ERROR
+ *
+ * @implements {RetryStrategy}
+ *
+ * @example
+ * ```typescript
+ * // Default configuration (3 retries, 1s delay increment)
+ * const retry = new LinearBackoff();
+ *
+ * // Custom configuration
+ * const customRetry = new LinearBackoff({
+ *   maxAttempts: 4,  // Up to 4 retry attempts
+ *   delay: 2000      // 2s, 4s, 6s, 8s delays
+ * });
+ *
+ * // Use with provider
+ * const provider = createAnthropic({
+ *   retryStrategy: customRetry
+ * });
+ * ```
+ */
+declare class LinearBackoff implements RetryStrategy {
+    private maxAttempts;
+    private delay;
+    /**
+     * Creates a new LinearBackoff instance.
+     *
+     * @param options - Configuration options
+     * @param options.maxAttempts - Maximum number of retry attempts (default: 3)
+     * @param options.delay - Base delay multiplier in milliseconds (default: 1000)
+     */
+    constructor(options?: {
+        maxAttempts?: number;
+        delay?: number;
+    });
+    /**
+     * Determines whether to retry and calculates the linear delay.
+     *
+     * @param error - The error that triggered the retry
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns Delay in milliseconds (delay * attempt), or null to stop retrying
+     */
+    onRetry(error: UPPError, attempt: number): number | null;
+    /**
+     * Checks if an error is eligible for retry.
+     *
+     * @param error - The error to evaluate
+     * @returns True if the error is transient and retryable
+     */
+    private isRetryable;
+}
+/**
+ * Disables all retry behavior, failing immediately on any error.
+ *
+ * Use this strategy when:
+ * - Retries are handled at a higher level in your application
+ * - You want immediate failure feedback
+ * - The operation is not idempotent
+ * - Time sensitivity requires fast failure
+ *
+ * @implements {RetryStrategy}
+ *
+ * @example
+ * ```typescript
+ * // Disable retries for time-sensitive operations
+ * const provider = createOpenAI({
+ *   retryStrategy: new NoRetry()
+ * });
+ * ```
+ */
+declare class NoRetry implements RetryStrategy {
+    /**
+     * Always returns null to indicate no retry should be attempted.
+     *
+     * @returns Always returns null
+     */
+    onRetry(): null;
+}
+/**
+ * Implements token bucket rate limiting with automatic refill.
+ *
+ * The token bucket algorithm provides smooth rate limiting by:
+ * - Maintaining a bucket of tokens that replenish over time
+ * - Consuming one token per request
+ * - Delaying requests when the bucket is empty
+ * - Allowing burst traffic up to the bucket capacity
+ *
+ * This is particularly useful for:
+ * - Client-side rate limiting to avoid hitting API rate limits
+ * - Smoothing request patterns to maintain consistent throughput
+ * - Preventing accidental API abuse
+ *
+ * Unlike other retry strategies, TokenBucket implements {@link beforeRequest}
+ * to proactively delay requests before they are made.
+ *
+ * @implements {RetryStrategy}
+ *
+ * @example
+ * ```typescript
+ * // Allow 10 requests burst, refill 1 token per second
+ * const bucket = new TokenBucket({
+ *   maxTokens: 10,    // Burst capacity
+ *   refillRate: 1,    // Tokens per second
+ *   maxAttempts: 3    // Retry attempts on rate limit
+ * });
+ *
+ * // Aggressive rate limiting: 5 req/s sustained
+ * const strictBucket = new TokenBucket({
+ *   maxTokens: 5,
+ *   refillRate: 5
+ * });
+ *
+ * // Use with provider
+ * const provider = createOpenAI({
+ *   retryStrategy: bucket
+ * });
+ * ```
+ */
+declare class TokenBucket implements RetryStrategy {
+    private tokens;
+    private maxTokens;
+    private refillRate;
+    private lastRefill;
+    private maxAttempts;
+    /**
+     * Creates a new TokenBucket instance.
+     *
+     * @param options - Configuration options
+     * @param options.maxTokens - Maximum bucket capacity (default: 10)
+     * @param options.refillRate - Tokens added per second (default: 1)
+     * @param options.maxAttempts - Maximum retry attempts on rate limit (default: 3)
+     */
+    constructor(options?: {
+        maxTokens?: number;
+        refillRate?: number;
+        maxAttempts?: number;
+    });
+    /**
+     * Called before each request to consume a token or calculate wait time.
+     *
+     * Refills the bucket based on elapsed time, then either:
+     * - Returns 0 if a token is available (consumed immediately)
+     * - Returns the wait time in milliseconds until the next token
+     *
+     * @returns Delay in milliseconds before the request can proceed
+     */
+    beforeRequest(): number;
+    /**
+     * Handles retry logic for rate-limited requests.
+     *
+     * Only retries on RATE_LIMITED errors, waiting for bucket refill.
+     *
+     * @param error - The error that triggered the retry
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns Delay in milliseconds (time for 2 tokens), or null to stop
+     */
+    onRetry(error: UPPError, attempt: number): number | null;
+    /**
+     * Resets the bucket to full capacity.
+     *
+     * Called automatically on successful requests to restore available tokens.
+     */
+    reset(): void;
+    /**
+     * Refills the bucket based on elapsed time since last refill.
+     */
+    private refill;
+}
+/**
+ * Respects server-provided Retry-After headers for optimal retry timing.
+ *
+ * When servers return a 429 (Too Many Requests) response, they often include
+ * a Retry-After header indicating when the client should retry. This strategy
+ * uses that information for precise retry timing.
+ *
+ * Benefits over fixed backoff strategies:
+ * - Follows server recommendations for optimal retry timing
+ * - Avoids retrying too early and wasting requests
+ * - Adapts to dynamic rate limit windows
+ *
+ * If no Retry-After header is provided, falls back to a configurable delay.
+ * Only retries on RATE_LIMITED errors.
+ *
+ * @implements {RetryStrategy}
+ *
+ * @example
+ * ```typescript
+ * // Use server-recommended retry timing
+ * const retryAfter = new RetryAfterStrategy({
+ *   maxAttempts: 5,       // Retry up to 5 times
+ *   fallbackDelay: 10000  // 10s fallback if no header
+ * });
+ *
+ * // The doFetch function automatically calls setRetryAfter
+ * // when a Retry-After header is present in the response
+ *
+ * const provider = createOpenAI({
+ *   retryStrategy: retryAfter
+ * });
+ * ```
+ */
+declare class RetryAfterStrategy implements RetryStrategy {
+    private maxAttempts;
+    private fallbackDelay;
+    private lastRetryAfter?;
+    /**
+     * Creates a new RetryAfterStrategy instance.
+     *
+     * @param options - Configuration options
+     * @param options.maxAttempts - Maximum number of retry attempts (default: 3)
+     * @param options.fallbackDelay - Delay in ms when no Retry-After header (default: 5000)
+     */
+    constructor(options?: {
+        maxAttempts?: number;
+        fallbackDelay?: number;
+    });
+    /**
+     * Sets the retry delay from a Retry-After header value.
+     *
+     * Called by doFetch when a Retry-After header is present in the response.
+     * The value is used for the next onRetry call and then cleared.
+     *
+     * @param seconds - The Retry-After value in seconds
+     */
+    setRetryAfter(seconds: number): void;
+    /**
+     * Determines retry delay using Retry-After header or fallback.
+     *
+     * @param error - The error that triggered the retry
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns Delay from Retry-After header or fallback, null to stop
+     */
+    onRetry(error: UPPError, attempt: number): number | null;
+}
+
+export { DynamicKey as D, ExponentialBackoff as E, LinearBackoff as L, NoRetry as N, RoundRobinKeys as R, TokenBucket as T, WeightedKeys as W, RetryAfterStrategy as a, resolveApiKey as r };

package/dist/xai/index.d.ts

@@ -1,8 +1,23 @@
-import { b as Provider, M as ModelReference, a as LLMHandler } from '../provider-CUJWjgNl.js';
+import { b as Provider, M as ModelReference, a as LLMHandler } from '../provider-Bi0nyNhA.js';
 
 /**
- * xAI Chat Completions API parameters (OpenAI-compatible)
- * These are passed through to the /v1/chat/completions endpoint
+ * xAI Chat Completions API parameters (OpenAI-compatible).
+ *
+ * These parameters are passed through to the xAI `/v1/chat/completions` endpoint.
+ * The API is fully compatible with OpenAI's Chat Completions API, allowing seamless
+ * migration between providers.
+ *
+ * @example
+ * ```typescript
+ * const params: XAICompletionsParams = {
+ *   max_tokens: 1000,
+ *   temperature: 0.7,
+ *   reasoning_effort: 'high', // Grok 3 Mini only
+ * };
+ * ```
+ *
+ * @see {@link XAIResponsesParams} for Responses API parameters
+ * @see {@link XAIMessagesParams} for Messages API parameters
  */
 interface XAICompletionsParams {
     /** Maximum number of tokens to generate */
@@ -51,8 +66,24 @@ interface XAICompletionsParams {
     search_parameters?: XAISearchParameters;
 }
 /**
- * xAI Responses API parameters (OpenAI Responses-compatible)
- * These are passed through to the /v1/responses endpoint
+ * xAI Responses API parameters (OpenAI Responses-compatible).
+ *
+ * These parameters are passed through to the xAI `/v1/responses` endpoint.
+ * The Responses API provides stateful conversation support with features like
+ * `previous_response_id` for continuing conversations across requests.
+ *
+ * @example
+ * ```typescript
+ * const params: XAIResponsesParams = {
+ *   max_output_tokens: 1000,
+ *   temperature: 0.7,
+ *   store: true, // Enable stateful storage
+ *   previous_response_id: 'resp_123...', // Continue previous conversation
+ * };
+ * ```
+ *
+ * @see {@link XAICompletionsParams} for Chat Completions API parameters
+ * @see {@link XAIMessagesParams} for Messages API parameters
  */
 interface XAIResponsesParams {
     /** Maximum output tokens */
@@ -88,8 +119,23 @@ interface XAIResponsesParams {
     search_parameters?: XAISearchParameters;
 }
 /**
- * xAI Messages API parameters (Anthropic-compatible)
- * These are passed through to the /v1/messages endpoint
+ * xAI Messages API parameters (Anthropic-compatible).
+ *
+ * These parameters are passed through to the xAI `/v1/messages` endpoint.
+ * The API is compatible with Anthropic's Messages API, allowing developers
+ * migrating from Anthropic to use familiar patterns.
+ *
+ * @example
+ * ```typescript
+ * const params: XAIMessagesParams = {
+ *   max_tokens: 1000,
+ *   temperature: 0.7,
+ *   thinking: { type: 'enabled', budget_tokens: 500 }, // Extended thinking
+ * };
+ * ```
+ *
+ * @see {@link XAICompletionsParams} for Chat Completions API parameters
+ * @see {@link XAIResponsesParams} for Responses API parameters
  */
 interface XAIMessagesParams {
     /** Maximum number of tokens to generate */
@@ -113,32 +159,42 @@ interface XAIMessagesParams {
     };
 }
 /**
- * API mode for xAI provider
+ * API mode selector for the xAI provider.
+ *
+ * xAI supports three distinct API modes, each with different capabilities:
+ * - `completions`: OpenAI Chat Completions compatible (recommended, default)
+ * - `responses`: OpenAI Responses compatible with stateful conversations
+ * - `messages`: Anthropic Messages compatible for easy migration
  */
 type XAIAPIMode = 'completions' | 'responses' | 'messages';
 /**
- * Model options when creating a model reference
+ * Options for configuring an xAI model reference.
  */
 interface XAIModelOptions {
-    /** Which API to use */
+    /** The API mode to use for this model */
     api?: XAIAPIMode;
 }
 /**
- * Model reference with xAI-specific options
+ * A reference to an xAI model with optional configuration.
  */
 interface XAIModelReference {
+    /** The xAI model identifier (e.g., 'grok-4', 'grok-3-mini') */
     modelId: string;
+    /** Optional model-specific options */
     options?: XAIModelOptions;
 }
 /**
- * xAI provider configuration
+ * Configuration options for the xAI provider.
  */
 interface XAIConfig {
-    /** Which API to use: 'completions', 'responses', or 'messages' */
+    /** The API mode to use (defaults to 'completions') */
     api?: XAIAPIMode;
 }
 /**
- * Live Search parameters (deprecated)
+ * Live Search parameters for real-time web search integration.
+ *
+ * @deprecated Live Search API will be removed on December 15, 2025.
+ * Use the Agent Tools API with `web_search` tool instead.
  */
 interface XAISearchParameters {
     /** Search mode */
@@ -153,13 +209,26 @@ interface XAISearchParameters {
     max_search_results?: number;
 }
 /**
- * Server-side agentic tools
+ * Server-side agentic tool configuration.
+ *
+ * These tools run on xAI's servers and provide capabilities like
+ * web search, X (Twitter) search, and code execution.
+ *
+ * @example
+ * ```typescript
+ * const tool: XAIAgentTool = { type: 'web_search' };
+ * ```
  */
 interface XAIAgentTool {
+    /** The type of server-side tool to enable */
     type: 'web_search' | 'x_search' | 'code_execution';
 }
 /**
- * Response format
+ * Specifies the output format for structured responses.
+ *
+ * - `{ type: 'text' }`: Plain text output (default)
+ * - `{ type: 'json_object' }`: JSON output with flexible schema
+ * - `{ type: 'json_schema', ... }`: JSON output with strict schema validation
  */
 type XAIResponseFormat = {
     type: 'text';
@@ -175,17 +244,23 @@ type XAIResponseFormat = {
     };
 };
 
-/** Union type for modalities interface */
+/**
+ * Union type for LLM parameters across all xAI API modes.
+ * This type enables the provider to handle parameters from any of the three APIs.
+ */
 type XAILLMParamsUnion = XAICompletionsParams | XAIResponsesParams | XAIMessagesParams;
 /**
- * xAI provider options
+ * Configuration options for creating xAI model references.
  */
 interface XAIProviderOptions {
     /**
-     * Which API to use:
-     * - 'completions': Chat Completions API (OpenAI-compatible, default)
-     * - 'responses': Responses API (OpenAI Responses-compatible, stateful)
-     * - 'messages': Messages API (Anthropic-compatible)
+     * The API mode to use for this model.
+     *
+     * - `'completions'`: Chat Completions API (OpenAI-compatible, default, recommended)
+     * - `'responses'`: Responses API (OpenAI Responses-compatible, supports stateful conversations)
+     * - `'messages'`: Messages API (Anthropic-compatible, for easy migration from Anthropic)
+     *
+     * @default 'completions'
      */
     api?: XAIAPIMode;
 }