@od-oneapp/ai-platform 0.1.0

package/src/sdk/errors/utils.ts

@@ -0,0 +1,148 @@
+/**
+ * Error handling utilities
+ */
+
+import {
+  PlatformAIError,
+  RateLimitError,
+  type ModelUnavailableError,
+  CircuitOpenError,
+} from './base';
+
+/**
+ * Check if an error is a PlatformAIError
+ */
+export function isPlatformError(error: unknown): error is PlatformAIError {
+  return error instanceof PlatformAIError;
+}
+
+/**
+ * Check if an error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof PlatformAIError) {
+    return error.isRetryable;
+  }
+
+  // Check for common retryable HTTP errors
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes('timeout') ||
+      message.includes('econnreset') ||
+      message.includes('econnrefused') ||
+      message.includes('temporarily unavailable') ||
+      message.includes('503') ||
+      message.includes('429')
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Get retry delay for an error (if applicable)
+ */
+export function getRetryDelay(error: unknown): number | undefined {
+  if (error instanceof RateLimitError) {
+    return error.retryAfterMs;
+  }
+
+  if (error instanceof CircuitOpenError && error.nextRetryAt) {
+    const delay = error.nextRetryAt.getTime() - Date.now();
+    return delay > 0 ? delay : undefined;
+  }
+
+  return undefined;
+}
+
+/**
+ * Wrap an error as a PlatformAIError
+ */
+export function wrapError(error: unknown, code: string, message?: string): PlatformAIError {
+  if (error instanceof PlatformAIError) {
+    return error;
+  }
+
+  const cause = error instanceof Error ? error : new Error(String(error));
+
+  return new PlatformAIError({
+    message: message || cause.message,
+    code,
+    isRetryable: isRetryableError(error),
+    cause,
+  });
+}
+
+/**
+ * Create error handler with fallback behavior
+ */
+export function createErrorHandler<T>(options: {
+  onRateLimit?: () => T | Promise<T>;
+  onModelUnavailable?: (error: ModelUnavailableError) => T | Promise<T>;
+  onCircuitOpen?: (error: CircuitOpenError) => T | Promise<T>;
+  onGuardrail?: () => T | Promise<T>;
+  onDefault?: (error: PlatformAIError) => T | Promise<T>;
+}) {
+  return async (error: unknown): Promise<T> => {
+    const platformError = isPlatformError(error) ? error : wrapError(error, 'UNKNOWN_ERROR');
+
+    switch (platformError.code) {
+      case 'RATE_LIMIT_EXCEEDED':
+        if (options.onRateLimit) {
+          return options.onRateLimit();
+        }
+        break;
+
+      case 'MODEL_UNAVAILABLE':
+        if (options.onModelUnavailable) {
+          return options.onModelUnavailable(error as ModelUnavailableError);
+        }
+        break;
+
+      case 'CIRCUIT_OPEN':
+        if (options.onCircuitOpen) {
+          return options.onCircuitOpen(error as CircuitOpenError);
+        }
+        break;
+
+      case 'GUARDRAIL_VIOLATION':
+        if (options.onGuardrail) {
+          return options.onGuardrail();
+        }
+        break;
+    }
+
+    if (options.onDefault) {
+      return options.onDefault(platformError);
+    }
+
+    throw platformError;
+  };
+}
+
+/**
+ * Aggregate multiple errors into a single error
+ */
+export class AggregateAIError extends PlatformAIError {
+  readonly errors: PlatformAIError[];
+
+  constructor(errors: Array<Error | PlatformAIError>) {
+    const platformErrors = errors.map(e =>
+      isPlatformError(e) ? e : wrapError(e, 'UNKNOWN_ERROR'),
+    );
+
+    super({
+      message: `Multiple errors occurred: ${platformErrors.map(e => e.message).join('; ')}`,
+      code: 'AGGREGATE_ERROR',
+      isRetryable: platformErrors.some(e => e.isRetryable),
+      metadata: {
+        errorCount: platformErrors.length,
+        errorCodes: platformErrors.map(e => e.code),
+      },
+    });
+
+    this.name = 'AggregateAIError';
+    this.errors = platformErrors;
+  }
+}

package/src/sdk/experimental/index.ts

@@ -0,0 +1,286 @@
+/**
+ * Experimental features module
+ *
+ * Features in this module use the experimental_ prefix convention
+ * from Vercel AI SDK to indicate they may change in future versions.
+ *
+ * @module @od-oneapp/ai-platform/sdk/experimental
+ */
+
+import type { SDKLanguageModelV3Middleware } from '../../shared';
+import type { WrapGenerateArgs, WrapStreamArgs } from '../middleware/model-middleware';
+
+/**
+ * Experimental: Output structure helpers
+ *
+ * Provides utilities for working with structured outputs
+ */
+export const experimental_Output = {
+  /**
+   * Create an object output schema
+   */
+  object<T>(options: { schema: T; description?: string }): {
+    type: 'object';
+    schema: T;
+    description?: string;
+  } {
+    return {
+      type: 'object',
+      schema: options.schema,
+      description: options.description,
+    };
+  },
+
+  /**
+   * Create an array output schema
+   */
+  array<T>(options: { items: T; description?: string }): {
+    type: 'array';
+    items: T;
+    description?: string;
+  } {
+    return {
+      type: 'array',
+      items: options.items,
+      description: options.description,
+    };
+  },
+
+  /**
+   * Create an enum output schema
+   */
+  enum<T extends readonly string[]>(
+    values: T,
+    description?: string,
+  ): { type: 'enum'; values: T; description?: string } {
+    return {
+      type: 'enum',
+      values,
+      description,
+    };
+  },
+};
+
+/**
+ * Experimental: Compose multiple middlewares
+ *
+ * @example
+ * ```ts
+ * import { experimental_composeMiddleware } from "@od-oneapp/ai-platform";
+ *
+ * const combined = experimental_composeMiddleware([
+ *   cachingMiddleware,
+ *   loggingMiddleware,
+ *   rateLimitMiddleware,
+ * ]);
+ * ```
+ */
+export function experimental_composeMiddleware(
+  middlewares: SDKLanguageModelV3Middleware[],
+): SDKLanguageModelV3Middleware {
+  return {
+    specificationVersion: 'v3',
+    wrapGenerate: async (options: WrapGenerateArgs) => {
+      let wrappedGenerate = options.doGenerate;
+
+      // Apply middlewares in reverse order so first middleware runs first
+      for (const middleware of [...middlewares].reverse()) {
+        if (middleware.wrapGenerate) {
+          const currentWrapped = wrappedGenerate;
+          const currentMiddleware = middleware.wrapGenerate;
+          wrappedGenerate = () =>
+            currentMiddleware({
+              ...options,
+              doGenerate: currentWrapped,
+            });
+        }
+      }
+
+      return wrappedGenerate();
+    },
+
+    wrapStream: async (options: WrapStreamArgs) => {
+      let wrappedStream = options.doStream;
+
+      for (const middleware of [...middlewares].reverse()) {
+        if (middleware.wrapStream) {
+          const currentWrapped = wrappedStream;
+          const currentMiddleware = middleware.wrapStream;
+          wrappedStream = () =>
+            currentMiddleware({
+              ...options,
+              doStream: currentWrapped,
+            });
+        }
+      }
+
+      return wrappedStream();
+    },
+  };
+}
+
+/**
+ * Experimental: Create a telemetry span wrapper
+ *
+ * @example
+ * ```ts
+ * import { experimental_withSpan } from "@od-oneapp/ai-platform";
+ *
+ * const result = await experimental_withSpan("my-operation", async (span) => {
+ *   span.setAttribute("model", "gpt-4");
+ *   return await generateText({ ... });
+ * });
+ * ```
+ */
+export async function experimental_withSpan<T>(
+  name: string,
+  fn: (span: ExperimentalSpan) => Promise<T>,
+  options: { attributes?: Record<string, string | number | boolean> } = {},
+): Promise<T> {
+  const span = new ExperimentalSpan(name, options.attributes);
+
+  try {
+    const result = await fn(span);
+    span.end('ok');
+    return result;
+  } catch (error) {
+    span.end('error');
+    throw error;
+  }
+}
+
+/**
+ * Experimental span for telemetry
+ */
+class ExperimentalSpan {
+  private attributes: Record<string, string | number | boolean> = {};
+  private startTime = Date.now();
+  private endTime?: number;
+  private status?: 'ok' | 'error';
+
+  constructor(
+    readonly name: string,
+    initialAttributes?: Record<string, string | number | boolean>,
+  ) {
+    if (initialAttributes) {
+      this.attributes = { ...initialAttributes };
+    }
+  }
+
+  setAttribute(key: string, value: string | number | boolean): void {
+    this.attributes[key] = value;
+  }
+
+  end(status: 'ok' | 'error'): void {
+    this.endTime = Date.now();
+    this.status = status;
+  }
+
+  getDuration(): number {
+    return (this.endTime || Date.now()) - this.startTime;
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      attributes: this.attributes,
+      startTime: this.startTime,
+      endTime: this.endTime,
+      duration: this.getDuration(),
+      status: this.status,
+    };
+  }
+}
+
+/**
+ * Experimental: Create a retry wrapper with exponential backoff
+ *
+ * @example
+ * ```ts
+ * import { experimental_retry } from "@od-oneapp/ai-platform";
+ *
+ * const result = await experimental_retry(
+ *   () => generateText({ ... }),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+export async function experimental_retry<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+  } = {},
+): Promise<T> {
+  const { maxRetries = 3, baseDelay = 1000, maxDelay = 30000, shouldRetry = () => true } = options;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === maxRetries || !shouldRetry(error, attempt)) {
+        throw error;
+      }
+
+      const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Experimental: Transform assistant messages with custom logic
+ */
+export function experimental_transformAssistantMessage(
+  transform: (message: { role: 'assistant'; content: string }) => {
+    role: 'assistant';
+    content: string;
+  },
+): SDKLanguageModelV3Middleware {
+  const isTextPart = (value: unknown): value is { type: 'text'; text: string } => {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      'type' in value &&
+      (value as { type?: unknown }).type === 'text' &&
+      'text' in value &&
+      typeof (value as { text?: unknown }).text === 'string'
+    );
+  };
+
+  return {
+    specificationVersion: 'v3',
+    wrapGenerate: async ({ doGenerate }: WrapGenerateArgs) => {
+      const result = await doGenerate();
+
+      if (Array.isArray(result.content)) {
+        const content = result.content.map(part => {
+          if (!isTextPart(part)) {
+            return part;
+          }
+          const transformed = transform({
+            role: 'assistant',
+            content: part.text,
+          });
+          return { ...part, text: transformed.content };
+        });
+
+        return { ...result, content };
+      }
+
+      return result;
+    },
+  };
+}

package/src/sdk/index.ts

@@ -0,0 +1,25 @@
+/**
+ * SDK Extensions Module
+ *
+ * Extensions for Vercel AI SDK v6:
+ * - Error hierarchy (PlatformAIError)
+ * - Stop conditions (stopWhen utilities)
+ * - Experimental middleware patterns
+ *
+ * @module sdk
+ */
+
+export * from "./errors";
+export * from "./stop-conditions";
+export * from "./experimental";
+
+// Middleware re-exports (selective to avoid CircuitOpenError conflict with errors/)
+export {
+  CircuitBreaker,
+  CircuitBreakerRegistry,
+  circuitBreakerRegistry,
+  withCircuitBreaker,
+  createCircuitBreaker,
+  type CircuitBreakerConfig,
+  type CircuitState,
+} from "./middleware";

package/src/sdk/middleware/ai-middleware.ts

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Official AI SDK v6 Middleware Patterns
+ * Official AI SDK v6 Middleware Patterns
+ * Pure AI SDK v6 alignment - no custom middleware implementations
+ * All functionality handled by official wrapLanguageModel + defaultSettingsMiddleware
+ */
+
+import { logDebug, logError, logInfo } from '@repo/shared/logs/server';
+
+import { defaultSettingsMiddleware, wrapLanguageModel } from '../../shared';
+
+import type { SDKLanguageModelV3 } from '../../shared';
+
+/**
+ * Official AI SDK v6 middleware helpers
+ * These are convenience functions that use ONLY official SDK patterns
+ */
+
+/**
+ * Create a wrapped model with official middleware patterns
+ * Replaces all custom withRetry, withErrorHandling, withMetrics
+ */
+export function createWrappedModel(
+  baseModel: SDKLanguageModelV3,
+  settings?: Record<string, unknown>,
+) {
+  return wrapLanguageModel({
+    model: baseModel,
+    middleware: settings ? [defaultSettingsMiddleware({ settings })] : [],
+  });
+}
+
+/**
+ * Observability hooks that work with official AI SDK v6 patterns
+ * Use these in onStepFinish, onFinish callbacks of official SDK functions
+ */
+export const observabilityHooks = {
+  /**
+   * Log operation start - use in function start
+   */
+  logStart: (operation: string, config: { model?: string }) => {
+    logInfo('AI operation started', { operation, model: config.model });
+  },
+
+  /**
+   * Log operation completion - use in onFinish callback
+   */
+  logComplete: (operation: string, config: { model?: string }, duration: number) => {
+    logInfo('AI operation completed', { operation, duration, model: config.model });
+  },
+
+  /**
+   * Log operation error - use in try/catch blocks
+   */
+  logError: (
+    operation: string,
+    config: { model?: string },
+    error: Error | unknown,
+    duration?: number,
+  ) => {
+    logError('AI operation failed', {
+      operation,
+      duration,
+      model: config.model,
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+    });
+  },
+
+  /**
+   * Log step completion - use in onStepFinish callbacks
+   */
+  logStep: (stepNumber: number, finishReason: string, toolCallsCount: number) => {
+    logDebug('AI step completed', { stepNumber, finishReason, toolCallsCount });
+  },
+};
+
+/**
+ * DEPRECATED - Use official AI SDK v6 patterns instead
+ *
+ * Instead of custom middleware, use:
+ * - wrapLanguageModel() with defaultSettingsMiddleware()
+ * - onStepFinish callbacks for metrics
+ * - try/catch blocks for error handling
+ * - Native SDK retry mechanisms
+ */
+export const deprecatedNotice = {
+  message: 'Custom middleware deprecated. Use official AI SDK v6 wrapLanguageModel patterns.',
+  migration: {
+    withRetry: 'Use native SDK retry mechanisms and error handling',
+    withErrorHandling: 'Use try/catch with observabilityHooks.logError',
+    withMetrics: 'Use onStepFinish/onFinish callbacks with observabilityHooks',
+    composeMiddleware: 'Use wrapLanguageModel with middleware array',
+  },
+};

package/src/sdk/middleware/cache.ts

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Caching middleware for AI requests
+ * Caching middleware for AI requests
+ *
+ * Simple in-memory LRU cache implementation
+ * For production, integrate with @upstash/redis or Redis client
+ */
+
+// Simple in-memory LRU cache
+class LRUCache<TValue = unknown> {
+  private cache = new Map<string, { value: TValue; expiry: number }>();
+  private maxSize: number;
+
+  constructor(maxSize = 1000) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: string): TValue | null {
+    const item = this.cache.get(key);
+    if (!item) return null;
+
+    if (Date.now() > item.expiry) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, item);
+    return item.value;
+  }
+
+  getTtl(key: string): number {
+    const item = this.cache.get(key);
+    if (!item) return 0;
+
+    if (Date.now() > item.expiry) {
+      this.cache.delete(key);
+      return 0;
+    }
+
+    return Math.max(0, item.expiry - Date.now());
+  }
+
+  set(key: string, value: TValue, ttlSeconds = 3600): void {
+    // Remove oldest item if at capacity
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    this.cache.set(key, {
+      value,
+      expiry: Date.now() + ttlSeconds * 1000,
+    });
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+}
+
+interface CacheConfig<TRequest = unknown, TResponse = unknown> {
+  ttl?: number; // Time to live in seconds
+  keyGenerator?: (request: TRequest) => string;
+  shouldServeFromCache?: (request: TRequest, cachedValue: TResponse) => boolean;
+  shouldCacheResult?: (request: TRequest, response: TResponse) => boolean;
+  invalidateOnError?: boolean;
+  maxSize?: number;
+  provider?: 'redis' | 'upstash' | 'memory';
+  cacheInstance?: LRUCache<TResponse>;
+}
+
+const globalCache = new LRUCache<unknown>();
+
+const defaultKeyGenerator = (request: unknown): string => {
+  if (typeof request === 'object' && request !== null) {
+    const data = request as {
+      model?: unknown;
+      messages?: unknown;
+      temperature?: unknown;
+    };
+    return JSON.stringify({
+      model: data.model,
+      messages: data.messages,
+      temperature: data.temperature,
+    });
+  }
+
+  return JSON.stringify({ request });
+};
+
+const cacheMiddleware = <TRequest = unknown, TResponse = unknown>(
+  config: CacheConfig<TRequest, TResponse> = {},
+) => {
+  const {
+    ttl = 3600, // 1 hour default
+    keyGenerator = defaultKeyGenerator as (request: TRequest) => string,
+    shouldServeFromCache = (request: TRequest, cachedValue: TResponse) => Boolean(cachedValue),
+    shouldCacheResult = (request: TRequest, response: TResponse) =>
+      Boolean(response) &&
+      typeof response === 'object' &&
+      response !== null &&
+      !('error' in response),
+    invalidateOnError = true,
+  } = config;
+
+  // Use global cache by default, allow override
+  const cache = (config.cacheInstance ?? globalCache) as LRUCache<TResponse>;
+
+  return async (request: TRequest, next: (req: TRequest) => Promise<TResponse>) => {
+    const cacheKey = keyGenerator(request);
+    if (typeof cacheKey !== 'string' || cacheKey.length === 0) {
+      throw new Error('Cache key must be a non-empty string');
+    }
+
+    // Check cache first - split read decision
+    const cached = cache.get(cacheKey);
+    if (cached && shouldServeFromCache(request, cached)) {
+      return {
+        ...cached,
+        fromCache: true,
+        cacheKey,
+        cacheTtlRemaining: cache.getTtl(cacheKey),
+      };
+    }
+
+    try {
+      const response = await next(request);
+
+      // Store in cache if should cache - split write decision
+      if (shouldCacheResult(request, response)) {
+        cache.set(cacheKey, response, ttl);
+      }
+
+      return response;
+    } catch (error) {
+      // Optionally invalidate cache on error
+      if (invalidateOnError) {
+        cache.delete(cacheKey);
+      }
+      throw error;
+    }
+  };
+};
+
+// Export alias for index.ts
+export const cache = cacheMiddleware;