@od-oneapp/ai-platform 0.1.0

package/src/agents/triage/triage-agent.ts

@@ -0,0 +1,280 @@
+/**
+ * @fileoverview Triage agent for routing requests to specialized agents.
+ * @module @od-oneapp/ai-platform/agents/triage
+ */
+
+import { z } from 'zod';
+
+import { generateObject } from '../../shared';
+import { createInitialState } from '../base/factory';
+
+import type { SDKLanguageModel } from '../../shared';
+import type { Agent, AgentConfig, BaseAgentState, AgentExecutionOptions } from '../base/types';
+
+
+/**
+ * Agent capability description.
+ */
+export interface AgentCapability {
+  /** Agent ID */
+  agentId: string;
+  /** Agent name */
+  name: string;
+  /** What the agent can do */
+  description: string;
+  /** Example queries this agent handles */
+  examples?: string[];
+  /** Keywords that indicate this agent */
+  keywords?: string[];
+}
+
+/**
+ * Triage result schema.
+ */
+export const TriageResultSchema = z.object({
+  /** Selected agent ID */
+  selectedAgentId: z.string(),
+  /** Confidence score 0-1 */
+  confidence: z.number().min(0).max(1),
+  /** Reasoning for selection */
+  reasoning: z.string(),
+  /** Reformulated query for the selected agent */
+  reformulatedQuery: z.string().optional(),
+  /** Whether multiple agents might be needed */
+  requiresMultiAgent: z.boolean().default(false),
+  /** Other potentially relevant agents */
+  alternativeAgents: z
+    .array(
+      z.object({
+        agentId: z.string(),
+        confidence: z.number().min(0).max(1),
+      }),
+    )
+    .optional(),
+});
+
+export type TriageResult = z.infer<typeof TriageResultSchema>;
+
+/**
+ * Triage agent configuration.
+ */
+export interface TriageAgentConfig extends Omit<AgentConfig, 'systemPrompt'> {
+  /** Available agents to route to */
+  agents: AgentCapability[];
+  /** Minimum confidence threshold for routing */
+  confidenceThreshold?: number;
+  /** Fallback agent ID if no match */
+  fallbackAgentId?: string;
+  /** Custom triage prompt */
+  customPrompt?: string;
+  /**
+   * Max turns for triage (defaults to 1).
+   * Triage is inherently a single-turn operation - we want ONE routing decision.
+   * This aligns with SDK v6 pattern: maxTurns: 1 for pure routing.
+   */
+  maxTurns?: 1;
+}
+
+/**
+ * Creates a triage agent that routes requests to specialized agents.
+ *
+ * @param config - Triage agent configuration
+ * @returns Triage agent
+ *
+ * @example
+ * ```ts
+ * const triageAgent = createTriageAgent({
+ *   id: 'triage',
+ *   name: 'Request Router',
+ *   description: 'Routes requests to appropriate agents',
+ *   agents: [
+ *     { agentId: 'code', name: 'Code Agent', description: 'Writes and reviews code' },
+ *     { agentId: 'research', name: 'Research Agent', description: 'Researches topics' },
+ *   ],
+ *   fallbackAgentId: 'general',
+ * });
+ *
+ * const result = await triageAgent.triage('Help me write a React component', {
+ *   model: openai('gpt-4o-mini'),
+ * });
+ * ```
+ */
+export function createTriageAgent(config: TriageAgentConfig) {
+  const { agents, confidenceThreshold = 0.5, fallbackAgentId, customPrompt } = config;
+
+  const systemPrompt = customPrompt ?? buildTriagePrompt(agents);
+
+  const triageConfig: AgentConfig = {
+    ...config,
+    systemPrompt,
+  };
+
+  return {
+    config: triageConfig,
+    agents,
+
+    /**
+     * Routes a query to the most appropriate agent.
+     */
+    async triage(
+      query: string,
+      options: { model: SDKLanguageModel; context?: AgentExecutionOptions['context'] },
+    ): Promise<TriageResult> {
+      const { object } = await generateObject({
+        model: options.model,
+        system: systemPrompt,
+        prompt: `Route this query to the most appropriate agent:\n\n"${query}"`,
+        schema: TriageResultSchema,
+        abortSignal: options.context?.abortSignal,
+      });
+
+      // Apply confidence threshold
+      if (object.confidence < confidenceThreshold && fallbackAgentId) {
+        return {
+          ...object,
+          selectedAgentId: fallbackAgentId,
+          reasoning: `Confidence (${object.confidence}) below threshold. Using fallback agent. Original reasoning: ${object.reasoning}`,
+        };
+      }
+
+      return object;
+    },
+
+    /**
+     * Full agent execution (includes triage + delegation).
+     */
+    async execute(
+      prompt: string,
+      options: AgentExecutionOptions & {
+        agentRegistry: Map<string, Agent>;
+      },
+    ): Promise<BaseAgentState & { triageResult: TriageResult }> {
+      const state = createInitialState(options.messages);
+
+      // Triage the request
+      const triageResult = await this.triage(prompt, {
+        model: options.model,
+        context: options.context,
+      });
+
+      state.metadata.triageResult = triageResult;
+
+      // Get the selected agent
+      const selectedAgent = options.agentRegistry.get(triageResult.selectedAgentId);
+
+      if (!selectedAgent) {
+        state.error = new Error(`Agent not found: ${triageResult.selectedAgentId}`);
+        state.isComplete = true;
+        return { ...state, triageResult };
+      }
+
+      // Execute the selected agent (exclude agentRegistry from options to avoid passing it to child agents)
+      const agentQuery = triageResult.reformulatedQuery ?? prompt;
+      const { agentRegistry: _, ...agentOptions } = options;
+      const agentResult = await selectedAgent.execute(agentQuery, agentOptions);
+
+      return {
+        ...agentResult,
+        metadata: {
+          ...agentResult.metadata,
+          triageResult,
+          delegatedTo: triageResult.selectedAgentId,
+        },
+        triageResult,
+      };
+    },
+  };
+}
+
+/**
+ * Builds the triage system prompt from agent capabilities.
+ */
+function buildTriagePrompt(agents: AgentCapability[]): string {
+  const agentDescriptions = agents
+    .map(agent => {
+      let desc = `- ${agent.name} (ID: ${agent.agentId}): ${agent.description}`;
+      if (agent.examples?.length) {
+        desc += `\n  Examples: ${agent.examples.join(', ')}`;
+      }
+      if (agent.keywords?.length) {
+        desc += `\n  Keywords: ${agent.keywords.join(', ')}`;
+      }
+      return desc;
+    })
+    .join('\n\n');
+
+  return `You are a request routing agent. Your job is to analyze incoming queries and route them to the most appropriate specialized agent.
+
+Available Agents:
+${agentDescriptions}
+
+Instructions:
+1. Analyze the query to understand the user's intent
+2. Match the intent to the most suitable agent based on capabilities
+3. Provide a confidence score (0-1) for your selection
+4. Optionally reformulate the query to be more specific for the selected agent
+5. Consider if multiple agents might be needed for complex queries
+
+Always respond with your routing decision in the specified JSON format.`;
+}
+
+/**
+ * Options for keyword-based triage.
+ */
+export interface KeywordTriageOptions {
+  /** Minimum keyword matches required for full confidence (default: 3) */
+  minMatchesForFullConfidence?: number;
+}
+
+/**
+ * Creates a simple keyword-based triage function.
+ *
+ * @param rules - Keyword to agent ID mapping
+ * @param fallback - Fallback agent ID
+ * @param options - Optional configuration for the triage function
+ * @returns Triage function
+ */
+export function createKeywordTriage(
+  rules: Array<{ keywords: string[]; agentId: string; priority?: number }>,
+  fallback: string,
+  options?: KeywordTriageOptions,
+): (query: string) => TriageResult {
+  const minMatches = options?.minMatchesForFullConfidence ?? 3;
+
+  return (query: string) => {
+    const lowerQuery = query.toLowerCase();
+    const matches: Array<{ agentId: string; count: number; priority: number }> = [];
+
+    for (const rule of rules) {
+      const count = rule.keywords.filter(kw => lowerQuery.includes(kw.toLowerCase())).length;
+      if (count > 0) {
+        matches.push({
+          agentId: rule.agentId,
+          count,
+          priority: rule.priority ?? 0,
+        });
+      }
+    }
+
+    // Sort by count then priority
+    matches.sort((a, b) => {
+      if (b.count !== a.count) return b.count - a.count;
+      return b.priority - a.priority;
+    });
+
+    const best = matches[0];
+
+    return {
+      selectedAgentId: best?.agentId ?? fallback,
+      confidence: best ? Math.min(best.count / minMatches, 1) : 0,
+      reasoning: best
+        ? `Matched ${best.count} keywords for agent ${best.agentId}`
+        : `No keyword matches, using fallback`,
+      requiresMultiAgent: false,
+      alternativeAgents: matches.slice(1).map(m => ({
+        agentId: m.agentId,
+        confidence: Math.min(m.count / minMatches, 1),
+      })),
+    };
+  };
+}

package/src/agents/workflows/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Workflow Module Index
+ */
+
+export * from './interfaces';
+export * from './schema';

package/src/agents/workflows/interfaces.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Workflow Interfaces
+ *
+ * Defines standard interfaces for Agentic Workflows compatible with Vercel's patterns.
+ *
+ * @module @od-oneapp/ai-platform/workflows/interfaces
+ */
+
+/**
+ * Represents a discrete step in a workflow.
+ */
+export interface WorkflowStep<TInput = unknown, TOutput = unknown> {
+  id: string;
+  name: string;
+  execute(input: TInput): Promise<TOutput>;
+}
+
+/**
+ * Represents a long-running workflow with state.
+ */
+export interface Workflow<TState> {
+  id: string;
+  state: TState;
+  steps: WorkflowStep<unknown, unknown>[];
+
+  /** Start or resume the workflow. */
+  run(): Promise<TState>;
+}
+
+/**
+ * State serialization helper.
+ */
+export interface StateSerializer<T> {
+  serialize(state: T): string;
+  deserialize(json: string): T;
+}

package/src/agents/workflows/schema.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Workflow Schemas
+ *
+ * Zod schemas for workflow state management.
+ *
+ * @module @od-oneapp/ai-platform/workflows/schema
+ */
+
+import { z } from 'zod';
+
+export const workflowStateSchema = z.object({
+  id: z.string(),
+  status: z.enum(['pending', 'running', 'completed', 'failed']),
+  currentStepId: z.string().optional(),
+  data: z.record(z.string(), z.unknown()),
+  error: z.string().optional(),
+  updatedAt: z.string().datetime(),
+});
+
+export type WorkflowState = z.infer<typeof workflowStateSchema>;

package/src/caching/adapters/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Cache adapters for different storage backends
+ */
+
+export { MemoryCacheAdapter } from './memory';
+export { RedisCacheAdapter } from './redis';
+export type { RedisClient } from '../../integrations/redis';

package/src/caching/adapters/memory.ts

@@ -0,0 +1,77 @@
+/**
+ * In-memory cache adapter for development and testing
+ */
+
+import type { CacheAdapter, CachedResponse } from '../types';
+
+interface CacheEntry {
+  value: CachedResponse;
+  expiresAt: number;
+}
+
+/**
+ * In-memory cache adapter
+ * Suitable for development, testing, and single-instance deployments
+ *
+ * @example
+ * ```ts
+ * const adapter = new MemoryCacheAdapter({ maxSize: 1000 });
+ * const caching = createCachingMiddleware({ adapter });
+ * ```
+ */
+export class MemoryCacheAdapter implements CacheAdapter {
+  private cache = new Map<string, CacheEntry>();
+  private maxSize: number;
+
+  constructor(options: { maxSize?: number } = {}) {
+    this.maxSize = options.maxSize ?? 10000;
+  }
+
+  async get(key: string): Promise<CachedResponse | null> {
+    const entry = this.cache.get(key);
+
+    if (!entry) return null;
+
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Refresh recency for LRU by re-inserting
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    // Return a clone to prevent external mutation of cached data
+    return structuredClone(entry.value);
+  }
+
+  async set(key: string, value: CachedResponse, ttl: number): Promise<void> {
+    // LRU eviction if at capacity
+    if (this.cache.has(key)) {
+      // Delete first to refresh position (move to end)
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      // Use !== undefined to handle empty-string keys correctly
+      if (oldestKey !== undefined) this.cache.delete(oldestKey);
+    }
+
+    // Clone value to prevent external mutation affecting cached data
+    this.cache.set(key, {
+      value: structuredClone(value),
+      expiresAt: Date.now() + ttl * 1000,
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.cache.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+  }
+
+  /** Get current cache size */
+  get size(): number {
+    return this.cache.size;
+  }
+}

package/src/caching/adapters/redis.ts

@@ -0,0 +1,60 @@
+/**
+ * Redis cache adapter for distributed deployments
+ */
+
+import { logWarn } from '@repo/shared/logs';
+
+import type { RedisClient } from '../../integrations/redis';
+import type { CacheAdapter, CachedResponse } from '../types';
+
+/**
+ * Redis cache adapter for distributed deployments
+ *
+ * @example
+ * ```ts
+ * import { createUpstashRedis } from '../../integrations/redis';
+ * const redis = createUpstashRedis({ url: '...', token: '...' });
+ * const adapter = new RedisCacheAdapter(redis, { prefix: "ai-cache:" });
+ * ```
+ */
+export class RedisCacheAdapter implements CacheAdapter {
+  private redis: RedisClient;
+  private prefix: string;
+
+  constructor(redis: RedisClient, options: { prefix?: string } = {}) {
+    this.redis = redis;
+    this.prefix = options.prefix ?? 'ai-cache:';
+  }
+
+  private getKey(key: string): string {
+    return `${this.prefix}${key}`;
+  }
+
+  async get(key: string): Promise<CachedResponse | null> {
+    const data = await this.redis.get(this.getKey(key));
+    if (!data) return null;
+
+    try {
+      return JSON.parse(data) as CachedResponse;
+    } catch (error) {
+      logWarn(`[RedisCacheAdapter] Failed to parse cached data for key "${key}"`, {
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+      return null;
+    }
+  }
+
+  async set(key: string, value: CachedResponse, ttl: number): Promise<void> {
+    await this.redis.set(this.getKey(key), JSON.stringify(value), 'EX', ttl);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.redis.del(this.getKey(key));
+  }
+
+  async clear(): Promise<void> {
+    if (this.redis.flushdb) {
+      await this.redis.flushdb();
+    }
+  }
+}

package/src/caching/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Response caching module for AI SDK
+ *
+ * Provides middleware for caching AI responses with multiple
+ * storage backends and caching strategies.
+ *
+ * @module @od-oneapp/ai-platform/caching
+ */
+
+export { createCachingMiddleware, computeCacheKey } from './middleware';
+export type {
+  CacheAdapter,
+  CachedResponse,
+  CacheStrategy,
+  CachingMiddlewareOptions,
+} from './types';
+export * from "./adapters";