@od-oneapp/ai-platform 0.1.0

package/src/agents/evaluator-optimizer/optimizer.ts

@@ -0,0 +1,322 @@
+/**
+ * Optimizer Module
+ * Implements content optimization strategies based on evaluation feedback
+ * Based on VERCEL_AI_SDK_V6_PATTERNS.md section 4.2
+ */
+
+import { generateText } from '../../shared';
+
+import { type OptimizerInput, type Optimizer, type EvaluationResult } from './schema';
+
+/**
+ * Prompt Optimizer
+ * Refines input prompts and generation instructions based on evaluation feedback
+ * Used to iteratively improve generation quality
+ */
+export class PromptOptimizer implements Optimizer {
+  /**
+   * Model identifier for optimization (typically a high-quality model)
+   * @default 'anthropic/claude-3-5-sonnet-20241022'
+   */
+  private modelId: string;
+
+  constructor(modelId: string = 'anthropic/claude-3-5-sonnet-20241022') {
+    this.modelId = modelId;
+  }
+
+  /**
+   * Optimize content by generating improved version based on feedback
+   * Focuses on addressing specific issues while preserving strengths
+   *
+   * @param input - Optimizer input containing content and evaluation feedback
+   * @returns Promise resolving to improved content
+   *
+   * @example
+   * ```typescript
+   * const optimizer = new PromptOptimizer();
+   * const improved = await optimizer.optimize({
+   *   content: "Original content",
+   *   evaluationFeedback: evaluationResult,
+   *   originalRequest: "User request",
+   *   iterationNumber: 1
+   * });
+   * ```
+   */
+  async optimize(input: OptimizerInput): Promise<string> {
+    const { content, evaluationFeedback, originalRequest, iterationNumber = 1 } = input;
+
+    const systemPrompt = `You are an expert content optimizer. Your role is to improve content based on evaluation feedback.
+
+CRITICAL GUIDELINES:
+1. Address ALL specific issues mentioned in the feedback
+2. Implement the top improvement suggestions
+3. PRESERVE all identified strengths - do not change what works
+4. Maintain the original intent and core message
+5. Keep the same format and style unless feedback suggests otherwise
+6. Make the content more concise and clear without losing nuance
+
+Remember: You are enhancing, not rewriting. The goal is to reach the quality threshold (${evaluationFeedback.qualityScore + (9 - evaluationFeedback.qualityScore) / 2}/10 minimum).`;
+
+    const userPrompt = `${iterationNumber > 1 ? `[Optimization Iteration ${iterationNumber}]\n` : ''}ORIGINAL USER REQUEST:
+${originalRequest}
+
+CURRENT CONTENT:
+${content}
+
+EVALUATION FEEDBACK (Score: ${evaluationFeedback.qualityScore}/10):
+
+ISSUES TO FIX:
+${evaluationFeedback.specificIssues.map(issue => `• ${issue}`).join('\n')}
+
+IMPROVEMENT SUGGESTIONS:
+${evaluationFeedback.improvementSuggestions.map(suggestion => `• ${suggestion}`).join('\n')}
+
+STRENGTHS TO PRESERVE:
+${evaluationFeedback.strengths.map(strength => `• ${strength}`).join('\n')}
+
+OVERALL ASSESSMENT:
+${evaluationFeedback.overallAssessment}
+
+Please improve this content. Address each issue specifically, implement the suggestions, and ensure all strengths are preserved.
+Provide the optimized content directly without explanation.`;
+
+    try {
+      const { text: improvedContent } = await generateText({
+        model: this.modelId,
+        system: systemPrompt,
+        prompt: userPrompt,
+      });
+
+      return improvedContent;
+    } catch (error) {
+      throw new Error(
+        `Optimization failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Output Optimizer
+ * Improves existing content output iteratively based on feedback
+ * Focuses on enhancing clarity, structure, and completeness
+ */
+export class OutputOptimizer implements Optimizer {
+  /**
+   * Model identifier for optimization
+   */
+  private modelId: string;
+
+  /**
+   * Strategy for optimization: 'expand', 'refine', 'restructure'
+   * If undefined, strategy is auto-selected based on feedback
+   */
+  private configuredStrategy?: 'expand' | 'refine' | 'restructure';
+
+  constructor(
+    modelId: string = 'anthropic/claude-3-5-sonnet-20241022',
+    strategy?: 'expand' | 'refine' | 'restructure',
+  ) {
+    this.modelId = modelId;
+    this.configuredStrategy = strategy;
+  }
+
+  /**
+   * Determine optimization strategy based on feedback
+   * Only used when no strategy was configured in constructor
+   */
+  private selectStrategy(feedback: EvaluationResult): 'expand' | 'refine' | 'restructure' {
+    // If many issues with clarity/structure, restructure
+    if (feedback.specificIssues.some(i => /structure|organization|clarity|flow/i.test(i))) {
+      return 'restructure';
+    }
+
+    // If issues about completeness/detail, expand
+    if (
+      feedback.specificIssues.some(i =>
+        /incomplete|missing|lack|insufficient|detail|example/i.test(i),
+      )
+    ) {
+      return 'expand';
+    }
+
+    // Default to refine
+    return 'refine';
+  }
+
+  /**
+   * Optimize content using strategy-based approach
+   */
+  async optimize(input: OptimizerInput): Promise<string> {
+    const { content, evaluationFeedback, originalRequest, iterationNumber = 1 } = input;
+
+    // Use configured strategy if provided, otherwise auto-select based on feedback
+    const strategy = this.configuredStrategy ?? this.selectStrategy(evaluationFeedback);
+
+    let systemPrompt: string;
+    let userPrompt: string;
+
+    switch (strategy) {
+      case 'expand':
+        systemPrompt = `You are a content expansion specialist. Your role is to add depth, detail, and examples to make content more comprehensive while preserving the core message.
+
+Guidelines:
+1. Add specific examples for abstract points
+2. Include more context and background
+3. Expand on underexplained concepts
+4. Add supporting evidence or details
+5. Maintain clarity and conciseness`;
+
+        userPrompt = `Expand this content with more detail and examples:
+
+ORIGINAL REQUEST: ${originalRequest}
+
+ITERATION: ${iterationNumber}
+
+CURRENT CONTENT:
+${content}
+
+ISSUES TO ADDRESS (expand on these):
+${evaluationFeedback.specificIssues.map(i => `• ${i}`).join('\n')}
+
+Provide the expanded content directly.`;
+        break;
+
+      case 'restructure':
+        systemPrompt = `You are a content restructuring specialist. Your role is to reorganize content for better clarity, flow, and logical structure.
+
+Guidelines:
+1. Use clearer topic organization
+2. Improve logical flow and transitions
+3. Strengthen paragraph structure
+4. Use headers or sections if appropriate
+5. Ensure each section flows naturally to the next`;
+
+        userPrompt = `Restructure this content for better clarity and flow:
+
+ORIGINAL REQUEST: ${originalRequest}
+
+ITERATION: ${iterationNumber}
+
+CURRENT CONTENT:
+${content}
+
+STRUCTURAL ISSUES TO FIX:
+${evaluationFeedback.specificIssues.map(i => `• ${i}`).join('\n')}
+
+Provide the restructured content directly.`;
+        break;
+      case 'refine':
+        systemPrompt = `You are a content refinement specialist. Your role is to polish and improve content quality through careful editing.
+
+Guidelines:
+1. Improve clarity and precision of language
+2. Eliminate redundancy and wordiness
+3. Enhance readability
+4. Fix any grammatical or stylistic issues
+5. Ensure tone is appropriate`;
+
+        userPrompt = `Refine this content for better quality:
+
+ORIGINAL REQUEST: ${originalRequest}
+
+ITERATION: ${iterationNumber}
+
+CURRENT CONTENT:
+${content}
+
+ISSUES TO ADDRESS:
+${evaluationFeedback.specificIssues.map(i => `• ${i}`).join('\n')}
+
+SUGGESTIONS TO IMPLEMENT:
+${evaluationFeedback.improvementSuggestions.map(s => `• ${s}`).join('\n')}
+
+Provide the refined content directly.`;
+        break;
+      default: {
+        const exhaustiveCheck: never = strategy;
+        throw new Error(`Unsupported optimization strategy: ${exhaustiveCheck}`);
+      }
+    }
+
+    try {
+      const { text: optimizedContent } = await generateText({
+        model: this.modelId,
+        system: systemPrompt,
+        prompt: userPrompt,
+      });
+
+      return optimizedContent;
+    } catch (error) {
+      throw new Error(
+        `Output optimization failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Hybrid Optimizer
+ * Combines prompt and output optimization strategies
+ * Adapts strategy based on feedback type and iteration number
+ */
+export class HybridOptimizer implements Optimizer {
+  private promptOptimizer: Optimizer;
+  private outputOptimizer: Optimizer;
+
+  constructor(promptOptimizerModel?: string, outputOptimizerModel?: string) {
+    this.promptOptimizer = new PromptOptimizer(
+      promptOptimizerModel || 'anthropic/claude-3-5-sonnet-20241022',
+    );
+    this.outputOptimizer = new OutputOptimizer(
+      outputOptimizerModel || 'anthropic/claude-3-5-sonnet-20241022',
+    );
+  }
+
+  /**
+   * Choose optimization approach based on iteration and feedback
+   */
+  async optimize(input: OptimizerInput): Promise<string> {
+    const { iterationNumber = 1 } = input;
+
+    // Early iterations: use output optimizer (faster, targeted)
+    if (iterationNumber <= 2) {
+      return this.outputOptimizer.optimize(input);
+    }
+
+    // Later iterations: use prompt optimizer (more comprehensive)
+    if (iterationNumber <= 4) {
+      return this.promptOptimizer.optimize(input);
+    }
+
+    // Final iteration: use output optimizer for final polish
+    return this.outputOptimizer.optimize(input);
+  }
+}
+
+/**
+ * Factory function to create prompt optimizer
+ */
+export function createPromptOptimizer(modelId?: string): Optimizer {
+  return new PromptOptimizer(modelId);
+}
+
+/**
+ * Factory function to create output optimizer
+ */
+export function createOutputOptimizer(
+  modelId?: string,
+  strategy?: 'expand' | 'refine' | 'restructure',
+): Optimizer {
+  return new OutputOptimizer(modelId, strategy);
+}
+
+/**
+ * Factory function to create hybrid optimizer
+ */
+export function createHybridOptimizer(
+  promptOptimizerModel?: string,
+  outputOptimizerModel?: string,
+): Optimizer {
+  return new HybridOptimizer(promptOptimizerModel, outputOptimizerModel);
+}

package/src/agents/evaluator-optimizer/schema.ts

@@ -0,0 +1,302 @@
+/**
+ * Evaluator-Optimizer Schema Definitions
+ * Based on VERCEL_AI_SDK_V6_PATTERNS.md section 4.2
+ * Comprehensive type definitions for iterative quality refinement
+ */
+
+import { z } from 'zod';
+
+/** Minimum iteration number. */
+const MIN_ITERATION_NUMBER = 1;
+
+/** Maximum iteration number for safety. */
+const MAX_ITERATION_NUMBER = 100;
+
+/** Minimum quality threshold. */
+const MIN_QUALITY_THRESHOLD = 1;
+
+/** Maximum quality threshold. */
+const MAX_QUALITY_THRESHOLD = 10;
+
+/** Maximum allowed issues before failing threshold. */
+const MAX_ALLOWED_ISSUES = 100;
+
+/**
+ * Evaluation result schema with 9-dimensional assessment
+ * Used by evaluator tool to assess content quality across multiple criteria
+ */
+export const EvaluationResultSchema = z.object({
+  /**
+   * Overall quality score (1-10)
+   * 1-3: Poor, significant issues
+   * 4-6: Fair, notable problems
+   * 7-8: Good, minor improvements needed
+   * 9-10: Excellent, meets or exceeds threshold
+   */
+  qualityScore: z.number().min(1).max(10),
+
+  /**
+   * Checks if original tone is preserved in the content
+   * True: Tone maintained appropriately
+   * False: Tone has been altered inappropriately
+   */
+  preservesTone: z.boolean(),
+
+  /**
+   * Checks if nuance and subtlety are preserved
+   * True: Nuanced meaning preserved
+   * False: Oversimplified or missing context
+   */
+  preservesNuance: z.boolean(),
+
+  /**
+   * Cultural sensitivity and accuracy assessment
+   * True: Culturally appropriate and accurate
+   * False: Contains cultural inaccuracies or insensitivity
+   */
+  culturallyAccurate: z.boolean(),
+
+  /**
+   * Technical accuracy and correctness
+   * True: All technical content is accurate
+   * False: Contains technical errors or inaccuracies
+   */
+  technicallyCorrect: z.boolean(),
+
+  /**
+   * Array of specific issues found during evaluation
+   * Each string describes a concrete problem
+   * Examples: "Missing context", "Grammatical error", "Unclear reference"
+   */
+  specificIssues: z.array(z.string()),
+
+  /**
+   * Actionable suggestions for improvement
+   * Each string provides specific guidance on how to improve
+   * Examples: "Expand paragraph 2", "Add examples", "Clarify terminology"
+   */
+  improvementSuggestions: z.array(z.string()),
+
+  /**
+   * Identified strengths to preserve during optimization
+   * These aspects should be maintained and not changed during optimization
+   * Examples: "Strong opening", "Clear methodology", "Engaging examples"
+   */
+  strengths: z.array(z.string()),
+
+  /**
+   * Summary assessment of the overall content quality
+   * Brief narrative summary combining all evaluation dimensions
+   */
+  overallAssessment: z.string(),
+
+  /**
+   * Boolean indicating if content meets quality threshold
+   * Automatically determined: meetsThreshold = qualityScore >= targetThreshold
+   * True: Content meets or exceeds threshold, ready to deliver
+   * False: Content needs optimization cycle
+   */
+  meetsThreshold: z.boolean(),
+});
+
+/**
+ * Type extracted from EvaluationResultSchema
+ */
+export type EvaluationResult = z.infer<typeof EvaluationResultSchema>;
+
+/**
+ * Optimizer tool input schema
+ * Defines what information optimizer receives to improve content
+ */
+export const OptimizerInputSchema = z.object({
+  /**
+   * The current content that needs optimization
+   */
+  content: z.string(),
+
+  /**
+   * Evaluation feedback from the evaluator tool
+   * Contains scores, issues, and suggestions
+   */
+  evaluationFeedback: EvaluationResultSchema,
+
+  /**
+   * The original user request that spawned this content generation
+   * Used to ensure optimizations stay aligned with original intent
+   */
+  originalRequest: z.string(),
+
+  /**
+   * Optional iteration context (1-100).
+   */
+  iterationNumber: z.number().min(MIN_ITERATION_NUMBER).max(MAX_ITERATION_NUMBER).optional(),
+
+  /**
+   * Optional previous versions for comparison.
+   */
+  previousVersions: z.array(z.string()).optional(),
+});
+
+export type OptimizerInput = z.infer<typeof OptimizerInputSchema>;
+
+/**
+ * Evaluator tool input schema
+ * Defines what information evaluator receives
+ */
+export const EvaluatorInputSchema = z.object({
+  /**
+   * Content to evaluate
+   */
+  content: z.string(),
+
+  /**
+   * Original request that generated this content
+   * Provides context for evaluation
+   */
+  originalRequest: z.string(),
+
+  /**
+   * Optional evaluation criteria and thresholds.
+   */
+  criteria: z
+    .object({
+      /**
+       * Target quality threshold (default: 8).
+       * Content must reach this score to pass.
+       */
+      threshold: z.number().min(MIN_QUALITY_THRESHOLD).max(MAX_QUALITY_THRESHOLD).default(8),
+
+      /**
+       * Specific evaluation focus areas.
+       * If provided, evaluator emphasizes these dimensions.
+       */
+      focusAreas: z.array(z.string()).optional(),
+
+      /**
+       * Maximum allowed issues before failing threshold.
+       * If provided, helps determine meetsThreshold.
+       */
+      maxAllowedIssues: z.number().min(0).max(MAX_ALLOWED_ISSUES).optional(),
+    })
+    .optional(),
+
+  /**
+   * Optional iteration context (1-100).
+   */
+  iterationNumber: z.number().min(MIN_ITERATION_NUMBER).max(MAX_ITERATION_NUMBER).optional(),
+});
+
+export type EvaluatorInput = z.infer<typeof EvaluatorInputSchema>;
+
+/**
+ * Feedback loop configuration
+ */
+export const FeedbackLoopConfigSchema = z.object({
+  /**
+   * Maximum number of evaluation-optimization cycles (default: 5)
+   */
+  maxIterations: z.number().min(1).max(10).default(5),
+
+  /**
+   * Target quality score threshold (default: 8, range 1-10)
+   * Content must reach this score to exit the loop
+   */
+  targetScore: z.number().min(1).max(10).default(8),
+
+  /**
+   * Enable detailed logging of each cycle (default: false)
+   */
+  enableLogging: z.boolean().default(false),
+
+  /**
+   * Stop on first threshold achievement (default: true)
+   * If false, continues to attempt reaching even higher scores
+   */
+  stopOnThreshold: z.boolean().default(true),
+
+  /**
+   * Detect diminishing returns after N cycles without improvement
+   */
+  diminishingReturnThreshold: z.number().min(1).default(2),
+});
+
+export type FeedbackLoopConfig = z.infer<typeof FeedbackLoopConfigSchema>;
+
+/**
+ * Complete optimization result returned by feedback loop
+ */
+export const OptimizedResultSchema = z.object({
+  /**
+   * Final optimized content
+   */
+  finalContent: z.string(),
+
+  /**
+   * Final evaluation result
+   */
+  finalEvaluation: EvaluationResultSchema,
+
+  /**
+   * Total number of cycles completed
+   */
+  cyclesCompleted: z.number(),
+
+  /**
+   * Whether content met threshold
+   */
+  meetsThreshold: z.boolean(),
+
+  /**
+   * History of evaluation scores across cycles
+   * Index 0 = initial evaluation, last index = final evaluation
+   */
+  scoreHistory: z.array(z.number()),
+
+  /**
+   * History of content versions
+   * Index 0 = initial content, last index = final content
+   */
+  contentHistory: z.array(z.string()),
+
+  /**
+   * Reason for loop termination
+   * - "threshold_met": reached target score
+   * - "max_iterations": reached max cycles without meeting threshold
+   * - "diminishing_returns": detected diminishing returns
+   * - "error": error occurred during processing
+   */
+  terminationReason: z.enum(['threshold_met', 'max_iterations', 'diminishing_returns', 'error']),
+
+  /**
+   * Optional error message if termination reason is "error"
+   */
+  error: z.string().optional(),
+
+  /**
+   * Metadata about the optimization process
+   */
+  metadata: z
+    .object({
+      startTime: z.string(),
+      endTime: z.string(),
+      processingTimeMs: z.number(),
+      averageScoreImprovement: z.number(),
+    })
+    .optional(),
+});
+
+export type OptimizedResult = z.infer<typeof OptimizedResultSchema>;
+
+/**
+ * Evaluator interface for dependency injection
+ */
+export interface Evaluator {
+  evaluate(input: EvaluatorInput): Promise<EvaluationResult>;
+}
+
+/**
+ * Optimizer interface for dependency injection
+ */
+export interface Optimizer {
+  optimize(input: OptimizerInput): Promise<string>;
+}

package/src/agents/evaluator-optimizer/utils.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Shared utilities for evaluator-optimizer module
+ * @module @od-oneapp/ai-platform/agents/evaluator-optimizer/utils
+ */
+
+import { anthropic, openai, type SDKLanguageModel } from '../../shared';
+
+/**
+ * Creates an AI SDK LanguageModel instance from a provider-prefixed model ID string.
+ *
+ * Parses the provider prefix (e.g., `openai/`, `anthropic/`) and instantiates
+ * the corresponding SDK provider with the model name.
+ *
+ * @param modelId - Model ID in `provider/model-name` format (e.g., `'openai/gpt-4o-mini'`)
+ * @returns AI SDK LanguageModel instance
+ * @throws Error if the provider prefix is missing or unsupported
+ *
+ * @example
+ * ```ts
+ * const model = createLanguageModelFromId('openai/gpt-4o-mini');
+ * const model2 = createLanguageModelFromId('anthropic/claude-sonnet-4-20250514');
+ * ```
+ */
+export function createLanguageModelFromId(modelId: string): SDKLanguageModel {
+  const [provider, ...modelIdParts] = modelId.split('/');
+  const actualModelId = modelIdParts.join('/');
+
+  if (!provider) {
+    throw new Error(
+      'Model ID must include a provider prefix like "openai/..." or "anthropic/...".',
+    );
+  }
+
+  switch (provider) {
+    case 'openai':
+      return openai(actualModelId);
+    case 'anthropic':
+      return anthropic(actualModelId);
+    default:
+      throw new Error(`Unsupported provider: ${provider}. Supported providers: openai, anthropic`);
+  }
+}