@od-oneapp/ai-platform 0.1.0

package/src/agents/experimental/types.ts

@@ -0,0 +1,212 @@
+/**
+ * @fileoverview Type definitions for the Experimental Agent module.
+ *
+ * SDK-aligned types for agent configuration, messages, tool definitions,
+ * and execution results. All SDK types are re-exported from the canonical
+ * shared module to maintain a single source of truth.
+ *
+ * @module agents/experimental/types
+ */
+
+import type {
+  ModelRef,
+  TokenUsage,
+  SDKToolChoice,
+  SDKTextPart,
+  SDKFilePart,
+  SDKToolCallPart,
+  SDKToolResultPart,
+  SDKToolApprovalResponse,
+  SDKToolSet,
+  MessageRole,
+  CoreMessageRole,
+  StepFinishReason,
+  AgentFinishReason,
+} from '../../shared';
+import type { z } from 'zod';
+
+// -----------------------------------------------------------------------------
+// Types (SDK-Aligned)
+// -----------------------------------------------------------------------------
+
+/**
+ * Model reference - LanguageModel instance from AI SDK.
+ * Re-exported from ai-types for convenience.
+ */
+export type { ModelRef };
+
+/**
+ * Tool choice options.
+ * Aligned with AI SDK v6's ToolChoice type.
+ * @see SDKToolChoice for the SDK's native type
+ */
+export type ToolChoice = SDKToolChoice<SDKToolSet>;
+
+/**
+ * Token usage tracking.
+ * Re-exported from ai-types for convenience.
+ * @see TokenUsage in ai-types.ts
+ */
+export type { TokenUsage };
+
+/**
+ * Text part - SDK-aligned type for text content in messages.
+ */
+export type TextPart = SDKTextPart;
+
+/**
+ * Tool call part - SDK-aligned type for tool invocations.
+ */
+export type ToolCallPart = SDKToolCallPart;
+
+/**
+ * Tool result part - SDK-aligned type for tool execution results.
+ */
+export type ToolResultPart = SDKToolResultPart;
+
+/**
+ * Message part types union.
+ * Directly uses AI SDK v6 part types for full compatibility.
+ */
+export type MessagePart =
+  | TextPart
+  | SDKFilePart
+  | ToolCallPart
+  | ToolResultPart
+  | SDKToolApprovalResponse;
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | { [key: string]: JsonValue }
+  | JsonValue[];
+
+export type AssistantPart = Exclude<MessagePart, SDKToolApprovalResponse>;
+
+/** Tool definition */
+export interface ToolDefinition<TInput = unknown, TOutput = unknown> {
+  readonly description: string;
+  readonly inputSchema: z.ZodSchema<TInput>;
+  readonly execute: (
+    input: TInput,
+    context: ToolExecutionContext,
+  ) => Promise<TOutput> | AsyncIterable<TOutput>;
+  readonly strict?: boolean;
+  readonly inputExamples?: Array<{ input: TInput }>;
+  readonly needsApproval?: boolean | ((input: TInput) => Promise<boolean>);
+}
+
+/** Tool execution context */
+export interface ToolExecutionContext {
+  readonly toolCallId: string;
+  readonly messages: AgentMessage[];
+  readonly abortSignal?: AbortSignal;
+  readonly context?: Record<string, unknown>;
+}
+
+/**
+ * Agent message (SDK-aligned).
+ * Uses SDK message part types for content and MessageRole type.
+ */
+export interface AgentMessage {
+  readonly id: string;
+  readonly role: MessageRole;
+  readonly content: string | MessagePart[];
+  readonly createdAt?: Date;
+}
+
+/**
+ * Step result from agent execution.
+ * Uses SDK-aligned StepFinishReason type.
+ */
+export interface AgentStepResult {
+  readonly stepNumber: number;
+  readonly message: AgentMessage;
+  readonly toolCalls?: Array<{
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+    output: ToolResultPart['output'];
+    duration?: number;
+  }>;
+  readonly usage?: TokenUsage;
+  readonly finishReason?: StepFinishReason;
+}
+
+/** Base agent configuration for experimental agent */
+export interface ExperimentalAgentBaseConfig<
+  TTools extends Record<string, ToolDefinition> = Record<string, ToolDefinition>,
+> {
+  /** Primary model for agent */
+  readonly model: ModelRef;
+  /** System prompt */
+  readonly system?: string;
+  /** Available tools */
+  readonly tools?: TTools;
+  /** Default tool choice behavior */
+  readonly toolChoice?: ToolChoice;
+  /** Maximum generation steps (default: 10) */
+  readonly maxSteps?: number;
+  /** Custom context passed to tools */
+  readonly context?: Record<string, unknown>;
+  /** Abort signal for cancellation */
+  readonly abortSignal?: AbortSignal;
+}
+
+/** PrepareStep hook input */
+export interface PrepareStepInput {
+  readonly stepNumber: number;
+  readonly messages: AgentMessage[];
+  readonly usage?: TokenUsage[];
+  readonly toolHistory?: Array<{ toolName: string; output: unknown }>;
+}
+
+/** PrepareStep hook output */
+export interface PrepareStepOutput {
+  /** Override model for this step */
+  readonly model?: ModelRef;
+  /** Trimmed/modified messages */
+  readonly messages?: AgentMessage[];
+  /** Override tool choice for this step */
+  readonly toolChoice?: ToolChoice;
+  /** Active tools (subset of available tools) */
+  readonly activeTools?: string[];
+  /** Additional system prompt */
+  readonly appendSystem?: string;
+}
+
+/** Agent with prepareStep hook */
+export interface ExperimentalAgentConfig<
+  TTools extends Record<string, ToolDefinition> = Record<string, ToolDefinition>,
+> extends ExperimentalAgentBaseConfig<TTools> {
+  /** Hook called before each generation step */
+  readonly prepareStep?: (
+    input: PrepareStepInput,
+  ) => Promise<PrepareStepOutput> | PrepareStepOutput;
+  /** Callback after each step completes */
+  readonly onStepComplete?: (result: AgentStepResult) => Promise<void> | void;
+  /** Callback when tool needs approval */
+  readonly onToolApproval?: (
+    toolName: string,
+    input: unknown,
+  ) => Promise<{ approved: boolean; reason?: string }>;
+}
+
+/**
+ * Agent execution result.
+ * Uses SDK-aligned AgentFinishReason type.
+ */
+export interface AgentResult {
+  readonly text: string;
+  readonly steps: AgentStepResult[];
+  readonly usage: TokenUsage;
+  readonly finishReason: AgentFinishReason;
+}
+
+// -----------------------------------------------------------------------------
+// Re-exports
+// -----------------------------------------------------------------------------
+
+export type { MessageRole, CoreMessageRole, StepFinishReason, AgentFinishReason };

package/src/agents/fallback/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Fallback and recovery module
+ *
+ * Provides model fallback strategies, circuit breakers,
+ * and resilience patterns for AI applications.
+ *
+ * @module @od-oneapp/ai-platform/fallback
+ */
+
+// Types
+export type { FallbackConfig, FallbackResult, CircuitState, CircuitBreakerConfig } from './types';
+export { AllModelsFailedError, CircuitOpenError } from './types';
+
+// Strategies
+export { executeWithFallback, createFallbackMiddleware } from './strategies/model-fallback';
+
+// Recovery
+export { CircuitBreaker } from './recovery/circuit-breaker';

package/src/agents/fallback/recovery/circuit-breaker.ts

@@ -0,0 +1,166 @@
+/**
+ * Circuit breaker for model reliability
+ */
+
+import { CircuitOpenError } from '../types';
+
+import type { Model } from '../../../models/registry';
+import type { CircuitBreakerConfig, CircuitState } from '../types';
+
+/**
+ * Circuit state for a single model
+ */
+interface CircuitModelState {
+  state: CircuitState;
+  failures: number;
+  successes: number;
+  lastFailure: Date | null;
+  nextRetry: Date | null;
+}
+
+/**
+ * Circuit breaker for model reliability
+ *
+ * Prevents cascading failures by temporarily blocking
+ * calls to failing models.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000, // 30 seconds
+ * });
+ *
+ * try {
+ *   breaker.checkCircuit(Model.SONNET);
+ *   const result = await generateText({ model, prompt });
+ *   breaker.recordSuccess(Model.SONNET);
+ * } catch (error) {
+ *   breaker.recordFailure(Model.SONNET);
+ *   throw error;
+ * }
+ * ```
+ */
+export class CircuitBreaker {
+  private circuits = new Map<Model, CircuitModelState>();
+  private config: Required<CircuitBreakerConfig>;
+
+  constructor(config: CircuitBreakerConfig) {
+    this.config = {
+      failureThreshold: config.failureThreshold,
+      resetTimeout: config.resetTimeout,
+      successThreshold: config.successThreshold ?? 2,
+    };
+  }
+
+  /**
+   * Get or create circuit state for a model
+   */
+  private getCircuit(model: Model): CircuitModelState {
+    const existing = this.circuits.get(model);
+    if (existing) {
+      return existing;
+    }
+
+    const created: CircuitModelState = {
+      state: 'closed',
+      failures: 0,
+      successes: 0,
+      lastFailure: null,
+      nextRetry: null,
+    };
+
+    this.circuits.set(model, created);
+    return created;
+  }
+
+  /**
+   * Check if circuit allows request
+   * @throws CircuitOpenError if circuit is open
+   */
+  checkCircuit(model: Model): void {
+    const circuit = this.getCircuit(model);
+
+    if (circuit.state === 'closed') {
+      return; // Allow request
+    }
+
+    if (circuit.state === 'open') {
+      // Check if we should transition to half-open
+      if (circuit.nextRetry && new Date() >= circuit.nextRetry) {
+        circuit.state = 'half-open';
+        circuit.successes = 0;
+        return; // Allow test request
+      }
+
+      throw new CircuitOpenError(
+        model,
+        circuit.nextRetry ?? new Date(Date.now() + this.config.resetTimeout),
+      );
+    }
+
+    // half-open: allow request
+  }
+
+  /**
+   * Record a successful request
+   */
+  recordSuccess(model: Model): void {
+    const circuit = this.getCircuit(model);
+
+    if (circuit.state === 'half-open') {
+      circuit.successes++;
+
+      if (circuit.successes >= this.config.successThreshold) {
+        // Close the circuit
+        circuit.state = 'closed';
+        circuit.failures = 0;
+        circuit.successes = 0;
+        circuit.nextRetry = null;
+      }
+    } else if (circuit.state === 'closed') {
+      // Reset failure count on success
+      circuit.failures = 0;
+    }
+  }
+
+  /**
+   * Record a failed request
+   */
+  recordFailure(model: Model): void {
+    const circuit = this.getCircuit(model);
+    circuit.failures++;
+    circuit.lastFailure = new Date();
+
+    if (circuit.state === 'half-open') {
+      // Failed during half-open, re-open circuit
+      circuit.state = 'open';
+      circuit.nextRetry = new Date(Date.now() + this.config.resetTimeout);
+    } else if (circuit.state === 'closed' && circuit.failures >= this.config.failureThreshold) {
+      // Threshold reached, open circuit
+      circuit.state = 'open';
+      circuit.nextRetry = new Date(Date.now() + this.config.resetTimeout);
+    }
+  }
+
+  /**
+   * Get current circuit state
+   */
+  getState(model: Model): CircuitState {
+    return this.getCircuit(model).state;
+  }
+
+  /**
+   * Manually reset a circuit
+   */
+  reset(model: Model): void {
+    this.circuits.delete(model);
+  }
+
+  /**
+   * Reset all circuits
+   */
+  resetAll(): void {
+    this.circuits.clear();
+  }
+}

package/src/agents/fallback/strategies/model-fallback.ts

@@ -0,0 +1,192 @@
+/**
+ * Model fallback strategy
+ * Automatically falls back to alternative models on failure
+ */
+
+import { createLanguageModel } from '../../../models';
+import { AllModelsFailedError } from '../types';
+
+import type { WrapGenerateArgs, WrapStreamArgs } from '../../../sdk/middleware/model-middleware';
+import type { SDKLanguageModel , SDKLanguageModelV3, SDKLanguageModelV3Middleware } from '../../../shared';
+import type { FallbackConfig, FallbackResult } from '../types';
+
+
+/**
+ * Sleep utility
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute with model fallback
+ *
+ * @example
+ * ```ts
+ * const result = await executeWithFallback(
+ *   {
+ *     primary: Model.SONNET,
+ *     fallbacks: [Model.HAIKU, Model.GPT_4O_MINI],
+ *     maxRetries: 2,
+ *   },
+ *   async (model) => {
+ *     return generateText({ model, prompt: "Hello" });
+ *   }
+ * );
+ *
+ * console.log(`Succeeded with ${result.model} after ${result.attempts} attempts`);
+ * ```
+ */
+export async function executeWithFallback<T>(
+  config: FallbackConfig,
+  execute: (model: SDKLanguageModel) => Promise<T>,
+): Promise<FallbackResult<T>> {
+  const {
+    primary,
+    fallbacks,
+    maxRetries = 3,
+    retryDelay = 1000,
+    exponentialBackoff = true,
+  } = config;
+
+  const resolveModel = config.resolveModel ?? createLanguageModel;
+  const allModels = [primary, ...fallbacks];
+  const failedModels: FallbackResult<T>['failedModels'] = [];
+  let totalAttempts = 0;
+
+  for (const model of allModels) {
+    let attempts = 0;
+    let lastError: Error | null = null;
+
+    while (attempts < maxRetries) {
+      attempts++;
+      totalAttempts++;
+
+      try {
+        const provider = resolveModel(model);
+        const result = await execute(provider);
+
+        return {
+          result,
+          model,
+          attempts: totalAttempts,
+          failedModels,
+        };
+      } catch (error) {
+        lastError = error as Error;
+
+        // Check if error is retryable
+        if (!isRetryableError(error)) {
+          break; // Move to next model
+        }
+
+        // Wait before retry
+        if (attempts < maxRetries) {
+          const delay = exponentialBackoff ? retryDelay * Math.pow(2, attempts - 1) : retryDelay;
+          await sleep(delay);
+        }
+      }
+    }
+
+    // Record failure for this model
+    if (lastError) {
+      failedModels.push({
+        model,
+        error: lastError,
+        attempts,
+      });
+    }
+  }
+
+  throw new AllModelsFailedError(
+    `All models failed after ${totalAttempts} total attempts`,
+    failedModels.map(f => ({ model: f.model, error: f.error })),
+  );
+}
+
+/**
+ * Check if an error is retryable
+ */
+function isRetryableError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+
+  const message = error.message.toLowerCase();
+
+  // Rate limit errors are retryable
+  if (message.includes('rate limit') || message.includes('429')) return true;
+
+  // Timeout errors are retryable
+  if (message.includes('timeout') || message.includes('timed out')) return true;
+
+  // Server errors are retryable
+  if (message.includes('500') || message.includes('502') || message.includes('503')) {
+    return true;
+  }
+
+  // Network errors are retryable
+  if (message.includes('network') || message.includes('connection')) return true;
+
+  return false;
+}
+
+/**
+ * Create fallback middleware for AI SDK
+ */
+export function createFallbackMiddleware(config: FallbackConfig): SDKLanguageModelV3Middleware {
+  const asLanguageModelV3 = (model: SDKLanguageModel, modelName: string): SDKLanguageModelV3 => {
+    if (typeof model === 'string') {
+      throw new Error(
+        `Fallback middleware requires LanguageModelV3 instances, got '${modelName}'.`,
+      );
+    }
+
+    if (model.specificationVersion !== 'v3') {
+      throw new Error(
+        `Fallback middleware requires LanguageModelV3 instances, got '${model.specificationVersion}'.`,
+      );
+    }
+
+    return model;
+  };
+
+  const isSameModel = (candidate: SDKLanguageModelV3, current: SDKLanguageModelV3): boolean =>
+    candidate.provider === current.provider && candidate.modelId === current.modelId;
+
+  const describeModel = (model: SDKLanguageModel): string => {
+    if (typeof model === 'string') {
+      return model;
+    }
+
+    return `${model.provider}:${model.modelId}`;
+  };
+
+  return {
+    specificationVersion: 'v3',
+    wrapGenerate: async ({ doGenerate, params, model }: WrapGenerateArgs) => {
+      const result = await executeWithFallback(config, async providerModel => {
+        const provider = asLanguageModelV3(providerModel, describeModel(providerModel));
+
+        if (isSameModel(provider, model)) {
+          return await doGenerate();
+        }
+
+        return await provider.doGenerate(params);
+      });
+
+      return result.result;
+    },
+    wrapStream: async ({ doStream, params, model }: WrapStreamArgs) => {
+      const result = await executeWithFallback(config, async providerModel => {
+        const provider = asLanguageModelV3(providerModel, describeModel(providerModel));
+
+        if (isSameModel(provider, model)) {
+          return await doStream();
+        }
+
+        return await provider.doStream(params);
+      });
+
+      return result.result;
+    },
+  };
+}

package/src/agents/fallback/types.ts

@@ -0,0 +1,87 @@
+/**
+ * Fallback and recovery types
+ */
+
+import type { Model } from '../../models/registry';
+import type { SDKLanguageModel } from '../../shared';
+
+/**
+ * Fallback strategy configuration
+ */
+export interface FallbackConfig {
+  /** Primary model to use */
+  primary: Model;
+  /** Fallback models in order of preference */
+  fallbacks: Model[];
+  /** Optional model resolver override for testing or advanced routing */
+  resolveModel?: (model: Model) => SDKLanguageModel;
+  /** Maximum retries per model */
+  maxRetries?: number;
+  /** Delay between retries in ms */
+  retryDelay?: number;
+  /** Whether to use exponential backoff */
+  exponentialBackoff?: boolean;
+}
+
+/**
+ * Fallback result with metadata
+ */
+export interface FallbackResult<T> {
+  /** The result from successful model */
+  result: T;
+  /** Which model succeeded */
+  model: Model;
+  /** Number of attempts before success */
+  attempts: number;
+  /** Models that failed */
+  failedModels: Array<{
+    model: Model;
+    error: Error;
+    attempts: number;
+  }>;
+}
+
+/**
+ * Circuit breaker state
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit */
+  failureThreshold: number;
+  /** Time in ms before trying again (half-open) */
+  resetTimeout: number;
+  /** Number of successes in half-open to close */
+  successThreshold?: number;
+}
+
+/**
+ * All models failed error
+ */
+export class AllModelsFailedError extends Error {
+  constructor(
+    message: string,
+    public readonly failures: Array<{ model: Model; error: Error }>,
+  ) {
+    super(message);
+    this.name = 'AllModelsFailedError';
+    Object.setPrototypeOf(this, AllModelsFailedError.prototype);
+  }
+}
+
+/**
+ * Circuit open error
+ */
+export class CircuitOpenError extends Error {
+  constructor(
+    public readonly model: Model,
+    public readonly resetTime: Date,
+  ) {
+    super(`Circuit open for model ${model}, resets at ${resetTime.toISOString()}`);
+    this.name = 'CircuitOpenError';
+    Object.setPrototypeOf(this, CircuitOpenError.prototype);
+  }
+}