@od-oneapp/ai-platform 0.1.0

package/src/grounding/context/safe-context.ts

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Safe context extraction and validation utilities.
+ * @module @od-oneapp/ai-platform/context
+ */
+
+import { IdentityContextSchema, RequestContextSchema } from './types';
+
+import type { IdentityContext, RequestContext } from './types';
+
+/**
+ * Safely extracts identity context, returning a minimal safe context if validation fails.
+ * Never throws - returns a safe default for anonymous/system operations.
+ *
+ * @param input - Raw context input (potentially untrusted)
+ * @returns Validated IdentityContext or safe default
+ *
+ * @example
+ * ```ts
+ * const ctx = getSafeIdentityContext(request.headers);
+ * // Always returns valid IdentityContext, never throws
+ * ```
+ */
+export function getSafeIdentityContext(input: unknown): IdentityContext {
+  const result = IdentityContextSchema.safeParse(input);
+
+  if (result.success) {
+    return result.data;
+  }
+
+  // Return anonymous context for failed validation
+  return {
+    userId: 'anonymous',
+    role: 'user',
+    permissions: [],
+  };
+}
+
+/**
+ * Safely extracts request context with timestamp and locale defaults.
+ *
+ * @param input - Raw context input
+ * @returns Validated RequestContext or safe default
+ */
+export function getSafeRequestContext(input: unknown): RequestContext {
+  const result = RequestContextSchema.safeParse(input);
+
+  if (result.success) {
+    return result.data;
+  }
+
+  // Return minimal request context
+  return {
+    userId: 'anonymous',
+    role: 'user',
+    permissions: [],
+    timestamp: new Date(),
+    locale: 'en-US',
+    timezone: 'UTC',
+  };
+}
+
+/**
+ * Creates a fresh request context from identity context.
+ * Adds request-scoped fields like timestamp.
+ *
+ * @param identity - Base identity context
+ * @param overrides - Optional field overrides
+ * @returns Fresh RequestContext
+ */
+export function createRequestContext(
+  identity: IdentityContext,
+  overrides?: Partial<RequestContext>,
+): RequestContext {
+  return {
+    ...identity,
+    timestamp: new Date(),
+    locale: 'en-US',
+    timezone: 'UTC',
+    ...overrides,
+  };
+}
+
+/**
+ * Checks if context has a specific permission.
+ *
+ * @param context - Identity context to check
+ * @param permission - Permission string to look for
+ * @returns True if permission exists
+ */
+export function hasPermission(context: IdentityContext, permission: string): boolean {
+  return context.permissions.includes(permission) || context.role === 'admin';
+}
+
+/**
+ * Checks if context has any of the specified permissions.
+ *
+ * @param context - Identity context to check
+ * @param permissions - Permission strings to check
+ * @returns True if any permission exists
+ */
+export function hasAnyPermission(context: IdentityContext, permissions: string[]): boolean {
+  if (context.role === 'admin') return true;
+  return permissions.some(p => context.permissions.includes(p));
+}
+
+/**
+ * Checks if context has all specified permissions.
+ *
+ * @param context - Identity context to check
+ * @param permissions - Permission strings to check
+ * @returns True if all permissions exist
+ */
+export function hasAllPermissions(context: IdentityContext, permissions: string[]): boolean {
+  if (context.role === 'admin') return true;
+  return permissions.every(p => context.permissions.includes(p));
+}

package/src/grounding/context/types.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Context types for AI operations.
+ * @module @od-oneapp/ai-platform/context
+ */
+
+import { z } from 'zod';
+
+/**
+ * User identity context for AI operations.
+ * Provides user information for tool authorization and personalization.
+ */
+export const IdentityContextSchema = z.object({
+  /** Unique user identifier */
+  userId: z.string(),
+  /** User's display name */
+  name: z.string().optional(),
+  /** User's email address */
+  email: z.string().email().optional(),
+  /** User's role in the system */
+  role: z.enum(['user', 'admin', 'system']).default('user'),
+  /** Permissions granted to the user */
+  permissions: z.array(z.string()).default([]),
+  /** Organization or tenant ID */
+  organizationId: z.string().optional(),
+  /** Session ID for tracking */
+  sessionId: z.string().optional(),
+  /** Additional metadata */
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type IdentityContext = z.infer<typeof IdentityContextSchema>;
+
+/**
+ * Request context for AI operations.
+ * Extends identity with request-specific information.
+ */
+export const RequestContextSchema = IdentityContextSchema.extend({
+  /** Request timestamp */
+  timestamp: z.date().default(() => new Date()),
+  /** Request locale */
+  locale: z.string().default('en-US'),
+  /** Request timezone */
+  timezone: z.string().default('UTC'),
+  /** Client IP address (anonymized) */
+  ipCountry: z.string().optional(),
+  /** User agent string */
+  userAgent: z.string().optional(),
+});
+
+export type RequestContext = z.infer<typeof RequestContextSchema>;
+
+/**
+ * Minimal context for anonymous or system operations.
+ */
+export const MinimalContextSchema = z.object({
+  /** Operation type */
+  operation: z.string(),
+  /** Timestamp */
+  timestamp: z.date().default(() => new Date()),
+});
+
+export type MinimalContext = z.infer<typeof MinimalContextSchema>;

package/src/grounding/context-engineering/error-handling.ts

@@ -0,0 +1,359 @@
+/**
+ * @fileoverview Error handling and recovery utilities for AI agents.
+ * @module @od-oneapp/ai-platform/context-engineering
+ */
+
+/**
+ * AI-specific error types.
+ */
+export type AIErrorType =
+  | 'rate-limit'
+  | 'context-length'
+  | 'content-filter'
+  | 'timeout'
+  | 'api-error'
+  | 'tool-error'
+  | 'validation'
+  | 'unknown';
+
+/**
+ * AI error with typed classification.
+ */
+export class AIError extends Error {
+  readonly type: AIErrorType;
+  readonly retryable: boolean;
+  readonly retryAfter?: number;
+  readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    type: AIErrorType,
+    options?: {
+      retryable?: boolean;
+      retryAfter?: number;
+      details?: Record<string, unknown>;
+      cause?: Error;
+    },
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = 'AIError';
+    this.type = type;
+    this.retryable = options?.retryable ?? isRetryableByDefault(type);
+    this.retryAfter = options?.retryAfter;
+    this.details = options?.details;
+  }
+}
+
+/**
+ * Determines if an error type is retryable by default.
+ */
+function isRetryableByDefault(type: AIErrorType): boolean {
+  switch (type) {
+    case 'rate-limit':
+    case 'timeout':
+    case 'api-error':
+      return true;
+    case 'context-length':
+    case 'content-filter':
+    case 'tool-error':
+    case 'validation':
+    case 'unknown':
+      return false;
+  }
+}
+
+/**
+ * Classifies an error into an AIError type.
+ */
+export function classifyError(error: unknown): AIError {
+  if (error instanceof AIError) {
+    return error;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  const cause = error instanceof Error ? error : undefined;
+
+  // Rate limit detection
+  if (
+    message.includes('rate limit') ||
+    message.includes('429') ||
+    message.includes('too many requests')
+  ) {
+    const retryAfter = extractRetryAfter(message);
+    return new AIError(message, 'rate-limit', { retryable: true, retryAfter, cause });
+  }
+
+  // Context length detection
+  if (
+    message.includes('context length') ||
+    message.includes('maximum context') ||
+    message.includes('token limit') ||
+    message.includes('too long')
+  ) {
+    return new AIError(message, 'context-length', { retryable: false, cause });
+  }
+
+  // Content filter detection
+  if (
+    message.includes('content filter') ||
+    message.includes('content policy') ||
+    message.includes('safety')
+  ) {
+    return new AIError(message, 'content-filter', { retryable: false, cause });
+  }
+
+  // Timeout detection
+  if (
+    message.includes('timeout') ||
+    message.includes('timed out') ||
+    message.includes('ETIMEDOUT')
+  ) {
+    return new AIError(message, 'timeout', { retryable: true, cause });
+  }
+
+  // API error detection
+  if (
+    message.includes('500') ||
+    message.includes('502') ||
+    message.includes('503') ||
+    message.includes('API error')
+  ) {
+    return new AIError(message, 'api-error', { retryable: true, cause });
+  }
+
+  return new AIError(message, 'unknown', { cause });
+}
+
+/**
+ * Extracts retry-after value from error message.
+ */
+function extractRetryAfter(message: string): number | undefined {
+  const match = message.match(/retry.+?(\d+)\s*(s|seconds?|ms|milliseconds?)/i);
+  if (match?.[1] && match[2]) {
+    const value = parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    return unit.startsWith('ms') ? value : value * 1000;
+  }
+  return undefined;
+}
+
+/**
+ * Recovery strategy configuration.
+ */
+export interface RecoveryStrategy {
+  /** Error types this strategy handles */
+  errorTypes: AIErrorType[];
+  /** Recovery action */
+  action: RecoveryAction;
+  /** Maximum retries for this strategy */
+  maxRetries?: number;
+}
+
+/**
+ * Recovery action types.
+ */
+export type RecoveryAction =
+  | { type: 'retry'; backoff?: 'exponential' | 'linear' | 'fixed'; baseDelay?: number }
+  | { type: 'reduce-context'; factor?: number }
+  | { type: 'switch-model'; fallbackModel: string }
+  | { type: 'fail'; message?: string }
+  | { type: 'custom'; handler: (error: AIError) => Promise<RecoveryResult> };
+
+/**
+ * Result of recovery attempt.
+ */
+export interface RecoveryResult {
+  /** Whether recovery was successful */
+  success: boolean;
+  /** Action taken */
+  action: string;
+  /** Should continue execution */
+  continueExecution: boolean;
+  /** Modified parameters (e.g., reduced context) */
+  modifiedParams?: Record<string, unknown>;
+  /** Error if recovery failed */
+  error?: Error;
+}
+
+/**
+ * Creates an error recovery handler.
+ *
+ * @param strategies - Recovery strategies in priority order
+ * @returns Recovery handler
+ *
+ * @example
+ * ```ts
+ * const recover = createErrorRecovery([
+ *   {
+ *     errorTypes: ['rate-limit'],
+ *     action: { type: 'retry', backoff: 'exponential', baseDelay: 1000 },
+ *     maxRetries: 3,
+ *   },
+ *   {
+ *     errorTypes: ['context-length'],
+ *     action: { type: 'reduce-context', factor: 0.5 },
+ *   },
+ *   {
+ *     errorTypes: ['content-filter'],
+ *     action: { type: 'fail', message: 'Content blocked by safety filters' },
+ *   },
+ * ]);
+ *
+ * try {
+ *   await generateText(...);
+ * } catch (e) {
+ *   const result = await recover(e, { attempt: 1 });
+ *   if (result.continueExecution) {
+ *     // Retry with modified params
+ *   }
+ * }
+ * ```
+ */
+export function createErrorRecovery(strategies: RecoveryStrategy[]) {
+  const retryCounters = new Map<AIErrorType, number>();
+
+  return async function recover(
+    error: unknown,
+    context: { attempt: number; maxMessages?: number },
+  ): Promise<RecoveryResult> {
+    const aiError = classifyError(error);
+
+    // Find matching strategy
+    const strategy = strategies.find(s => s.errorTypes.includes(aiError.type));
+
+    if (!strategy) {
+      return {
+        success: false,
+        action: 'none',
+        continueExecution: false,
+        error: aiError,
+      };
+    }
+
+    // Check retry count
+    const currentRetries = retryCounters.get(aiError.type) ?? 0;
+    if (strategy.maxRetries !== undefined && currentRetries >= strategy.maxRetries) {
+      return {
+        success: false,
+        action: 'max-retries-exceeded',
+        continueExecution: false,
+        error: aiError,
+      };
+    }
+
+    // Execute recovery action
+    switch (strategy.action.type) {
+      case 'retry': {
+        retryCounters.set(aiError.type, currentRetries + 1);
+        const delay = calculateDelay(strategy.action, context.attempt);
+
+        if (aiError.retryAfter) {
+          await sleep(aiError.retryAfter);
+        } else {
+          await sleep(delay);
+        }
+
+        return {
+          success: true,
+          action: 'retry',
+          continueExecution: true,
+        };
+      }
+
+      case 'reduce-context': {
+        const factor = strategy.action.factor ?? 0.5;
+        const newMaxMessages = Math.floor((context.maxMessages ?? 20) * factor);
+
+        return {
+          success: true,
+          action: 'reduce-context',
+          continueExecution: true,
+          modifiedParams: { maxMessages: newMaxMessages },
+        };
+      }
+
+      case 'switch-model': {
+        return {
+          success: true,
+          action: 'switch-model',
+          continueExecution: true,
+          modifiedParams: { model: strategy.action.fallbackModel },
+        };
+      }
+
+      case 'fail': {
+        return {
+          success: false,
+          action: 'fail',
+          continueExecution: false,
+          error: new AIError(strategy.action.message ?? aiError.message, aiError.type),
+        };
+      }
+
+      case 'custom': {
+        return strategy.action.handler(aiError);
+      }
+    }
+  };
+}
+
+/**
+ * Calculates delay based on backoff strategy.
+ */
+function calculateDelay(
+  action: Extract<RecoveryAction, { type: 'retry' }>,
+  attempt: number,
+): number {
+  const baseDelay = action.baseDelay ?? 1000;
+  const backoff = action.backoff ?? 'fixed';
+
+  switch (backoff) {
+    case 'exponential':
+      return baseDelay * Math.pow(2, attempt - 1);
+    case 'linear':
+      return baseDelay * attempt;
+    case 'fixed':
+      return baseDelay;
+    default: {
+      const exhaustiveCheck: never = backoff;
+      throw new Error(`Unknown backoff strategy: ${exhaustiveCheck}`);
+    }
+  }
+}
+
+/**
+ * Sleep helper.
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Default recovery strategies.
+ */
+export const DefaultRecoveryStrategies: RecoveryStrategy[] = [
+  {
+    errorTypes: ['rate-limit'],
+    action: { type: 'retry', backoff: 'exponential', baseDelay: 1000 },
+    maxRetries: 5,
+  },
+  {
+    errorTypes: ['timeout'],
+    action: { type: 'retry', backoff: 'exponential', baseDelay: 2000 },
+    maxRetries: 3,
+  },
+  {
+    errorTypes: ['api-error'],
+    action: { type: 'retry', backoff: 'exponential', baseDelay: 1000 },
+    maxRetries: 3,
+  },
+  {
+    errorTypes: ['context-length'],
+    action: { type: 'reduce-context', factor: 0.5 },
+    maxRetries: 2,
+  },
+  {
+    errorTypes: ['content-filter'],
+    action: { type: 'fail', message: 'Content was blocked by safety filters' },
+  },
+];

package/src/grounding/context-engineering/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Context engineering utilities for AI SDK v6.
+ * @module @od-oneapp/ai-platform/context-engineering
+ *
+ * @example
+ * ```ts
+ * import {
+ *   // Tool Masking
+ *   createToolMasker,
+ *   MaskingRules,
+ *   // Memory
+ *   createMemoryManager,
+ *   InMemoryStore,
+ *   // Error Handling
+ *   createErrorRecovery,
+ *   AIError,
+ * } from '@od-oneapp/ai-platform/context-engineering';
+ * ```
+ */
+
+export * from './tool-masking';
+export * from './memory';
+export * from './error-handling';