ai-functions 2.1.3 → 2.3.0

package/src/retry.ts

@@ -9,9 +9,17 @@
  * - Error classification for intelligent retry decisions
  * - Partial retry for batch operations
  *
+ * Per-model policy data (which models retry how, who falls back to whom,
+ * which batch tiers each model supports) lives in `language-models`'s
+ * `policyFor()`. The classes in this file are the *machinery* that reads
+ * that policy. See `RetryPolicy.forModel`, `CircuitBreaker.forModel`,
+ * `FallbackChain.forModel`.
+ *
  * @packageDocumentation
  */
 
+import { policyFor, type ModelPolicy, type ErrorCategoryName } from 'language-models'
+
 // ============================================================================
 // ERROR TYPES AND CLASSIFICATION
 // ============================================================================
@@ -83,13 +91,18 @@ export class RateLimitError extends RetryableError {
   constructor(message: string, options?: { retryAfter?: number }) {
     super(message, ErrorCategory.RateLimit)
     this.name = 'RateLimitError'
-    this.retryAfter = options?.retryAfter
+    if (options?.retryAfter !== undefined) {
+      this.retryAfter = options.retryAfter
+    }
   }
 
   /**
    * Create RateLimitError from HTTP response
    */
-  static fromResponse(response: { status: number; headers?: Record<string, string> }): RateLimitError {
+  static fromResponse(response: {
+    status: number
+    headers?: Record<string, string>
+  }): RateLimitError {
     const retryAfterHeader = response.headers?.['retry-after']
     let retryAfter: number | undefined
 
@@ -100,7 +113,10 @@ export class RateLimitError extends RetryableError {
       }
     }
 
-    return new RateLimitError(`Rate limited (${response.status})`, { retryAfter })
+    return new RateLimitError(
+      `Rate limited (${response.status})`,
+      retryAfter !== undefined ? { retryAfter } : undefined
+    )
   }
 }
 
@@ -116,6 +132,11 @@ export class CircuitOpenError extends Error {
   }
 }
 
+/** Error with status property (e.g., HTTP errors) */
+interface ErrorWithStatus extends Error {
+  status?: number
+}
+
 /**
  * Classify an error into a category for retry decisions
  */
@@ -125,7 +146,7 @@ export function classifyError(error: unknown): ErrorCategory {
   }
 
   const message = error.message.toLowerCase()
-  const status = (error as any).status as number | undefined
+  const status = (error as ErrorWithStatus).status
 
   // Network errors
   if (
@@ -309,9 +330,20 @@ export interface BatchItemResult<T, R> {
 
 /**
  * Retry policy for executing operations with exponential backoff
+ *
+ * @deprecated Phase C Week 3 — `RetryPolicy` has 1 real production caller
+ * (audited 2026-05-06; see `bd show aip-ibid`):
+ *   `ai-database/src/cascade-orchestrator.ts:1235` (loose coupling — dynamic
+ *    import + graceful try/catch fallback when ai-functions not available).
+ * AI SDK 6's `customProvider({ retryPolicy })` and `wrapLanguageModel(model,
+ * retryMiddleware)` cover the same surface. Migration tracked in aip-ibid;
+ * the one callsite can move on a separate commit. Will be removed in the
+ * Phase C semver bump.
  */
 export class RetryPolicy {
-  private readonly options: Required<Omit<RetryOptions, 'shouldRetry'>> & { shouldRetry?: (error: unknown) => boolean }
+  private readonly options: Required<Omit<RetryOptions, 'shouldRetry'>> & {
+    shouldRetry?: (error: unknown) => boolean
+  }
 
   constructor(options: RetryOptions = {}) {
     this.options = {
@@ -322,16 +354,55 @@ export class RetryPolicy {
       jitter: options.jitter ?? 0,
       jitterStrategy: options.jitterStrategy ?? 'equal',
       respectRetryAfter: options.respectRetryAfter ?? true,
-      shouldRetry: options.shouldRetry,
+      ...(options.shouldRetry !== undefined && { shouldRetry: options.shouldRetry }),
     }
   }
 
+  /**
+   * Build a RetryPolicy from a model's `ModelPolicy` (loaded via
+   * `language-models`). Per-call `overrides` win over policy data.
+   *
+   * @example
+   * ```ts
+   * const policy = RetryPolicy.forModel('sonnet')
+   * // Uses retry settings derived for anthropic/claude-sonnet-4.5
+   * ```
+   */
+  static forModel(alias: string, overrides: RetryOptions = {}): RetryPolicy {
+    const policy = policyFor(alias)
+    return RetryPolicy.fromPolicy(policy, overrides)
+  }
+
+  /**
+   * Build a RetryPolicy directly from a `ModelPolicy`. Useful when the policy
+   * is already in hand (e.g. from a request context).
+   */
+  static fromPolicy(policy: ModelPolicy, overrides: RetryOptions = {}): RetryPolicy {
+    const retryable = new Set<ErrorCategoryName>(policy.retry.retryableCategories)
+    const shouldRetry = (error: unknown): boolean => {
+      // Honour error's own retryable property when present.
+      if (error && typeof error === 'object' && 'retryable' in error) {
+        const flag = (error as { retryable: boolean }).retryable
+        if (flag === false) return false
+      }
+      const category = classifyError(error)
+      return retryable.has(category as ErrorCategoryName)
+    }
+    return new RetryPolicy({
+      maxRetries: policy.retry.maxRetries,
+      baseDelay: policy.retry.baseDelay,
+      maxDelay: policy.retry.maxDelay,
+      multiplier: policy.retry.multiplier,
+      jitter: policy.retry.jitter,
+      shouldRetry,
+      ...overrides,
+    })
+  }
+
   /**
    * Execute an operation with retry logic
    */
-  async execute<T>(
-    operation: (info: RetryInfo) => Promise<T>
-  ): Promise<T> {
+  async execute<T>(operation: (info: RetryInfo) => Promise<T>): Promise<T> {
     let lastError: unknown
     let previousDelay = this.options.baseDelay
 
@@ -386,7 +457,7 @@ export class RetryPolicy {
     const attemptCounts = new Map<T, number>()
 
     // Initialize attempt counts
-    items.forEach(item => attemptCounts.set(item, 0))
+    items.forEach((item) => attemptCounts.set(item, 0))
 
     for (let round = 0; round <= this.options.maxRetries && pendingItems.length > 0; round++) {
       // Wait before retry (not on first attempt)
@@ -427,7 +498,7 @@ export class RetryPolicy {
     }
 
     // Return results in original order
-    return items.map(item => finalResults.get(item)!)
+    return items.map((item) => finalResults.get(item)!)
   }
 
   private isRetryable(error: unknown): boolean {
@@ -438,7 +509,7 @@ export class RetryPolicy {
 
     // Check error's own retryable property
     if (error && typeof error === 'object' && 'retryable' in error) {
-      return (error as any).retryable === true
+      return (error as { retryable: boolean }).retryable === true
     }
 
     // Classify error and determine retryability
@@ -452,7 +523,7 @@ export class RetryPolicy {
   }
 
   private sleep(ms: number): Promise<void> {
-    return new Promise(resolve => setTimeout(resolve, ms))
+    return new Promise((resolve) => setTimeout(resolve, ms))
   }
 }
 
@@ -497,6 +568,12 @@ export interface CircuitBreakerMetrics {
  * - CLOSED: Normal operation, failures tracked
  * - OPEN: Fail fast, reject all requests
  * - HALF-OPEN: Allow single test request
+ *
+ * @deprecated Phase C Week 3 — `CircuitBreaker` has zero real callers in
+ * primitives.org.ai (audited 2026-05-06; only comment-only references in
+ * `language-models/src/index.ts`; see `bd show aip-ibid`). AI SDK 6's
+ * `wrapLanguageModel(model, circuitMiddleware)` replacement is the going-
+ * forward primitive. Will be removed in the Phase C semver bump.
  */
 export class CircuitBreaker {
   private _state: CircuitState = 'closed'
@@ -517,6 +594,20 @@ export class CircuitBreaker {
     }
   }
 
+  /**
+   * Build a CircuitBreaker for a specific model, using its `ModelPolicy`.
+   * Per-call overrides win over policy data.
+   */
+  static forModel(alias: string, overrides: CircuitBreakerOptions = {}): CircuitBreaker {
+    const policy = policyFor(alias)
+    return new CircuitBreaker({
+      failureThreshold: policy.circuitBreaker.failureThreshold,
+      resetTimeout: policy.circuitBreaker.resetTimeout,
+      successThreshold: policy.circuitBreaker.successThreshold,
+      ...overrides,
+    })
+  }
+
   /**
    * Current circuit state
    */
@@ -658,6 +749,14 @@ export interface FallbackMetrics {
  *
  * Tries models in order until one succeeds:
  * sonnet -> opus -> gpt-4o -> gemini
+ *
+ * @deprecated Phase C Week 3 — `FallbackChain` (LLM model failover) has
+ * zero real callers in primitives.org.ai (audited 2026-05-06; the
+ * `human-in-the-loop` package's `FallbackChain` is a different class for
+ * HITL fallback resolution, not LLM failover). AI SDK 4.3+ ships native
+ * `customProvider({ fallbackProvider })` which is the going-forward
+ * primitive. See `bd show aip-ibid`. Will be removed in the Phase C
+ * semver bump.
  */
 export class FallbackChain<T = unknown, P = unknown> {
   private readonly models: FallbackModel<T, P>[]
@@ -672,6 +771,33 @@ export class FallbackChain<T = unknown, P = unknown> {
     this.options = options
   }
 
+  /**
+   * Build a FallbackChain from a model's `ModelPolicy`. The caller supplies
+   * an `executor` that takes a model id and returns a promise — the chain
+   * applies it to the primary model first, then to each fallback in order.
+   *
+   * @example
+   * ```ts
+   * const chain = FallbackChain.forModel('sonnet', (modelId, params) =>
+   *   ai({ model: modelId, prompt: params!.prompt })
+   * )
+   * await chain.execute({ prompt: 'Hello' })
+   * ```
+   */
+  static forModel<T = unknown, P = unknown>(
+    alias: string,
+    executor: (modelId: string, params?: P) => Promise<T>,
+    options: FallbackOptions = {}
+  ): FallbackChain<T, P> {
+    const policy = policyFor(alias)
+    const ids = [policy.$id, ...policy.fallbackChain]
+    const models: FallbackModel<T, P>[] = ids.map((id) => ({
+      name: id,
+      execute: (params?: P) => executor(id, params),
+    }))
+    return new FallbackChain<T, P>(models, options)
+  }
+
   /**
    * Execute the fallback chain
    */
@@ -758,15 +884,15 @@ export class FallbackChain<T = unknown, P = unknown> {
  * const response = await reliableFetch('https://api.example.com')
  * ```
  */
-export function withRetry<T extends (...args: any[]) => Promise<any>>(
-  fn: T,
+export function withRetry<TArgs extends unknown[], TResult>(
+  fn: (...args: TArgs) => Promise<TResult>,
   options: RetryOptions = {}
-): T {
+): (...args: TArgs) => Promise<TResult> {
   const policy = new RetryPolicy(options)
 
-  return (async (...args: Parameters<T>) => {
+  return async (...args: TArgs): Promise<TResult> => {
     return policy.execute(() => fn(...args))
-  }) as T
+  }
 }
 
 // ============================================================================

package/src/schema.ts

@@ -15,18 +15,18 @@
  */
 
 import { z, type ZodTypeAny } from 'zod'
-import { isZodSchema } from '@org.ai/core'
+import { isZodSchema } from './type-guards.js'
 
 /**
  * Simplified schema types
  */
 export type SimpleSchema =
-  | string                           // z.string().describe(value)
-  | [string]                         // z.array(z.string()).describe(value)
-  | [number]                         // z.array(z.number()).describe(value)
-  | [SimpleSchema]                   // z.array(converted).describe(value)
-  | { [key: string]: SimpleSchema }  // z.object() recursively
-  | ZodTypeAny                       // Pass-through for actual Zod schemas
+  | string // z.string().describe(value)
+  | [string] // z.array(z.string()).describe(value)
+  | [number] // z.array(z.number()).describe(value)
+  | [SimpleSchema] // z.array(converted).describe(value)
+  | { [key: string]: SimpleSchema } // z.object() recursively
+  | ZodTypeAny // Pass-through for actual Zod schemas
 
 /**
  * Convert a simplified schema to a Zod schema
@@ -64,7 +64,7 @@ function convertToZod(input: SimpleSchema): ZodTypeAny {
   if (typeof input === 'string') {
     // Enum syntax: 'option1 | option2 | option3'
     if (input.includes(' | ')) {
-      const options = input.split(' | ').map(s => s.trim())
+      const options = input.split(' | ').map((s) => s.trim())
       return z.enum(options as [string, ...string[]])
     }