@cogitator-ai/self-modifying 17.0.18 → 19.0.0

package/src/architecture-evolution/capability-analyzer.ts

@@ -1,5 +1,21 @@
+import { createHash } from 'node:crypto';
 import type { Tool, LLMBackend, TaskProfile } from '@cogitator-ai/types';
 import { buildTaskProfilePrompt, parseTaskProfileResponse } from './prompts';
+import { llmChat } from '../utils/llm-helper';
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function containsPhrase(text: string, phrase: string): boolean {
+  return new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(phrase)}(?:s|es|ed|ing)?(?:$|[^a-z0-9])`).test(
+    text
+  );
+}
+
+function tokenize(text: string): string[] {
+  return text.split(/[^a-z0-9-]+/).filter(Boolean);
+}
 
 export interface CapabilityAnalyzerOptions {
   llm?: LLMBackend;
@@ -146,7 +162,7 @@ export class CapabilityAnalyzer {
       constraints?: { maxCost?: number; maxLatency?: number };
     }
   ): Promise<TaskProfile> {
-    const cacheKey = this.buildCacheKey(taskDescription);
+    const cacheKey = this.buildCacheKey(taskDescription, context);
     const cached = this.profileCache.get(cacheKey);
     if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
       return cached.profile;
@@ -190,32 +206,20 @@ export class CapabilityAnalyzer {
         constraints: context?.constraints,
       });
 
-      const response = llm.complete
-        ? await llm.complete({
-            messages: [
-              {
-                role: 'system',
-                content:
-                  'You are a task analysis expert. Analyze tasks and determine their characteristics.',
-              },
-              { role: 'user', content: prompt },
-            ],
-            temperature: 0.2,
-          })
-        : await llm.chat({
-            model: this.model,
-            messages: [
-              {
-                role: 'system',
-                content:
-                  'You are a task analysis expert. Analyze tasks and determine their characteristics.',
-              },
-              { role: 'user', content: prompt },
-            ],
-            temperature: 0.2,
-          });
-
-      const parsed = parseTaskProfileResponse(response.content);
+      const content = await llmChat(
+        llm,
+        [
+          {
+            role: 'system',
+            content:
+              'You are a task analysis expert. Analyze tasks and determine their characteristics.',
+          },
+          { role: 'user', content: prompt },
+        ],
+        { model: this.model, temperature: 0.2 }
+      );
+
+      const parsed = parseTaskProfileResponse(content);
       if (parsed) {
         return parsed;
       }
@@ -226,8 +230,7 @@ export class CapabilityAnalyzer {
 
   private analyzeHeuristically(taskDescription: string, availableTools?: Tool[]): TaskProfile {
     const lowerTask = taskDescription.toLowerCase();
-    const words = lowerTask.split(/\s+/);
-    const wordCount = words.length;
+    const wordCount = tokenize(lowerTask).length;
 
     const domain = this.detectDomain(lowerTask);
     const complexity = this.detectComplexity(lowerTask, wordCount);
@@ -260,7 +263,7 @@ export class CapabilityAnalyzer {
 
     for (const [domain, keywords] of Object.entries(DOMAIN_KEYWORDS)) {
       for (const keyword of keywords) {
-        if (task.includes(keyword)) {
+        if (containsPhrase(task, keyword)) {
           scores[domain] += keyword.length > 5 ? 2 : 1;
         }
       }
@@ -272,7 +275,7 @@ export class CapabilityAnalyzer {
   }
 
   private detectComplexity(task: string, wordCount: number): TaskProfile['complexity'] {
-    const taskWords = new Set(task.split(/\s+/));
+    const taskWords = new Set(tokenize(task));
 
     for (const [level, indicators] of Object.entries(COMPLEXITY_INDICATORS).reverse()) {
       for (const indicator of indicators) {
@@ -309,14 +312,14 @@ export class CapabilityAnalyzer {
 
     let toolMentions = 0;
     for (const indicator of toolIndicators) {
-      if (task.includes(indicator)) {
+      if (containsPhrase(task, indicator)) {
         toolMentions++;
       }
     }
 
     if (availableTools?.length) {
       for (const tool of availableTools) {
-        if (task.includes(tool.name.toLowerCase())) {
+        if (containsPhrase(task, tool.name.toLowerCase())) {
           toolMentions += 2;
         }
       }
@@ -380,7 +383,7 @@ export class CapabilityAnalyzer {
   ): TaskProfile['accuracyRequirement'] {
     const criticalIndicators = ['critical', 'exact', 'precise', 'must be correct', 'no errors'];
     for (const indicator of criticalIndicators) {
-      if (task.includes(indicator)) {
+      if (containsPhrase(task, indicator)) {
         return 'critical';
       }
     }
@@ -391,7 +394,7 @@ export class CapabilityAnalyzer {
 
     const approximateIndicators = ['rough', 'approximate', 'estimate', 'about', 'roughly'];
     for (const indicator of approximateIndicators) {
-      if (task.includes(indicator)) {
+      if (containsPhrase(task, indicator)) {
         return 'approximate';
       }
     }
@@ -405,20 +408,33 @@ export class CapabilityAnalyzer {
     const relaxedIndicators = ['when possible', 'eventually', 'no rush'];
 
     for (const indicator of strictIndicators) {
-      if (task.includes(indicator)) return 'strict';
+      if (containsPhrase(task, indicator)) return 'strict';
     }
     for (const indicator of moderateIndicators) {
-      if (task.includes(indicator)) return 'moderate';
+      if (containsPhrase(task, indicator)) return 'moderate';
     }
     for (const indicator of relaxedIndicators) {
-      if (task.includes(indicator)) return 'relaxed';
+      if (containsPhrase(task, indicator)) return 'relaxed';
     }
 
     return 'none';
   }
 
-  private buildCacheKey(task: string): string {
-    return task.slice(0, 200).toLowerCase().replace(/\s+/g, ' ').trim();
+  private buildCacheKey(
+    task: string,
+    context?: {
+      availableTools?: Tool[];
+      previousTasks?: string[];
+      constraints?: { maxCost?: number; maxLatency?: number };
+    }
+  ): string {
+    const raw = JSON.stringify([
+      task.toLowerCase().replace(/\s+/g, ' ').trim(),
+      (context?.availableTools ?? []).map((t) => t.name).sort(),
+      context?.previousTasks ?? [],
+      context?.constraints ?? {},
+    ]);
+    return createHash('sha256').update(raw).digest('hex');
   }
 
   clearCache(): void {

package/src/architecture-evolution/index.ts

@@ -10,6 +10,7 @@ export {
   ParameterOptimizer,
   type ParameterOptimizerOptions,
   type OptimizationResult,
+  type HistoricalRecord,
 } from './parameter-optimizer';
 
 export {
@@ -19,5 +20,6 @@ export {
   parseTaskProfileResponse,
   parseCandidateGenerationResponse,
   parsePerformanceAnalysisResponse,
+  sanitizeCandidateConfig,
   ARCHITECTURE_ANALYSIS_SYSTEM_PROMPT,
 } from './prompts';

package/src/architecture-evolution/parameter-optimizer.ts

@@ -13,17 +13,23 @@ import {
   buildPerformanceAnalysisPrompt,
   parseCandidateGenerationResponse,
   parsePerformanceAnalysisResponse,
+  MAX_TOKENS_RANGE,
+  REFLECTION_DEPTH_RANGE,
+  TEMPERATURE_RANGE,
 } from './prompts';
+import { llmChat } from '../utils/llm-helper';
 
 export interface ParameterOptimizerOptions {
   llm: LLMBackend;
   config: ArchitectureEvolutionConfig;
   baseConfig: ArchitectureConfig;
   model?: string;
+  availableModels?: string[];
 }
 
 export interface OptimizationResult {
   recommendedConfig: ArchitectureConfig;
+  taskProfile: TaskProfile;
   candidate: EvolutionCandidate | null;
   metrics: EvolutionMetrics;
   shouldAdopt: boolean;
@@ -31,7 +37,7 @@ export interface OptimizationResult {
   reasoning: string;
 }
 
-interface HistoricalRecord {
+export interface HistoricalRecord {
   taskProfile: TaskProfile;
   config: Partial<ArchitectureConfig>;
   score: number;
@@ -44,6 +50,7 @@ export class ParameterOptimizer {
   private readonly config: ArchitectureEvolutionConfig;
   private readonly model: string;
   private readonly baseConfig: ArchitectureConfig;
+  private readonly availableModels: string[];
   private readonly capabilityAnalyzer: CapabilityAnalyzer;
   private readonly evolutionStrategy: EvolutionStrategy;
 
@@ -58,6 +65,7 @@ export class ParameterOptimizer {
     this.config = options.config;
     this.model = options.model ?? 'default';
     this.baseConfig = options.baseConfig;
+    this.availableModels = options.availableModels ?? [];
 
     this.capabilityAnalyzer = new CapabilityAnalyzer({
       llm: options.llm,
@@ -79,24 +87,28 @@ export class ParameterOptimizer {
     }
 
     const selection = this.evolutionStrategy.select(this.candidates);
+    const candidate = selection.candidate;
 
-    const mergedConfig = this.mergeConfigs(this.baseConfig, selection.candidate.config);
+    const mergedConfig = this.mergeConfigs(this.baseConfig, candidate.config);
 
     const bestEvaluated = this.candidates
       .filter((c) => c.evaluationCount > 0)
       .sort((a, b) => b.score - a.score)[0];
 
+    const threshold = this.config.adaptationThreshold ?? 0.1;
     const shouldAdopt =
+      candidate.evaluationCount === 0 ||
       !bestEvaluated ||
-      selection.candidate.id === bestEvaluated.id ||
-      selection.score >= bestEvaluated.score * 0.9;
+      candidate.id === bestEvaluated.id ||
+      candidate.score >= bestEvaluated.score - threshold;
 
     return {
       recommendedConfig: mergedConfig,
-      candidate: selection.candidate,
+      taskProfile: profile,
+      candidate,
       metrics: this.calculateMetrics(),
       shouldAdopt,
-      confidence: selection.score,
+      confidence: candidate.evaluationCount > 0 ? candidate.score : 0.5,
       reasoning: selection.reasoning,
     };
   }
@@ -143,11 +155,13 @@ export class ParameterOptimizer {
     const prompt = buildCandidateGenerationPrompt(
       profile,
       this.baseConfig,
-      this.getRelevantHistory(profile)
+      this.getRelevantHistory(profile),
+      { availableModels: this.availableModels }
     );
 
     try {
-      const response = await this.callLLM(
+      const content = await llmChat(
+        this.llm,
         [
           {
             role: 'system',
@@ -155,14 +169,17 @@ export class ParameterOptimizer {
           },
           { role: 'user', content: prompt },
         ],
-        0.5
+        { model: this.model, temperature: 0.5 }
       );
 
-      const generated = parseCandidateGenerationResponse(response.content);
+      const generated = parseCandidateGenerationResponse(content, {
+        availableModels: this.availableModels,
+      }).filter((c) => c.risk !== 'high');
 
+      const maxCandidates = this.config.maxCandidates ?? 10;
       this.candidates = [
         this.createBaselineCandidate(),
-        ...generated.map((c) => ({
+        ...generated.slice(0, Math.max(0, maxCandidates - 1)).map((c) => ({
           ...c,
           generation: this.currentGeneration,
         })),
@@ -258,18 +275,27 @@ export class ParameterOptimizer {
 
     if (Math.random() < mutationRate) {
       const base = mutated.temperature ?? this.baseConfig.temperature;
-      mutated.temperature = Math.max(0, Math.min(2, base + (Math.random() - 0.5) * 0.3));
+      mutated.temperature = Math.max(
+        TEMPERATURE_RANGE.min,
+        Math.min(TEMPERATURE_RANGE.max, base + (Math.random() - 0.5) * 0.3)
+      );
     }
 
     if (Math.random() < mutationRate) {
       const base = mutated.maxTokens ?? this.baseConfig.maxTokens;
       const delta = Math.floor((Math.random() - 0.5) * 1000);
-      mutated.maxTokens = Math.max(100, Math.min(32000, base + delta));
+      mutated.maxTokens = Math.max(
+        MAX_TOKENS_RANGE.min,
+        Math.min(MAX_TOKENS_RANGE.max, base + delta)
+      );
     }
 
     if (Math.random() < mutationRate) {
       const base = mutated.reflectionDepth ?? this.baseConfig.reflectionDepth;
-      mutated.reflectionDepth = Math.max(0, Math.min(5, base + Math.round(Math.random() * 2 - 1)));
+      mutated.reflectionDepth = Math.max(
+        REFLECTION_DEPTH_RANGE.min,
+        Math.min(REFLECTION_DEPTH_RANGE.max, base + Math.round(Math.random() * 2 - 1))
+      );
     }
 
     return mutated;
@@ -334,14 +360,14 @@ export class ParameterOptimizer {
     if (minEvaluations < minRequired) return false;
 
     const evaluationsSinceEvolution = this.history.filter(
-      (h) => h.timestamp > this.getLastEvolutionTime()
+      (h) => h.timestamp > this.lastEvolutionTimestamp
     ).length;
 
-    return evaluationsSinceEvolution >= 5;
+    return evaluationsSinceEvolution >= this.getEvaluationWindow();
   }
 
-  private getLastEvolutionTime(): number {
-    return this.lastEvolutionTimestamp;
+  private getEvaluationWindow(): number {
+    return Math.max(1, this.config.evaluationWindow ?? 10);
   }
 
   private getRelevantHistory(profile: TaskProfile): HistoricalRecord[] {
@@ -350,7 +376,7 @@ export class ParameterOptimizer {
         (h) =>
           h.taskProfile.domain === profile.domain || h.taskProfile.complexity === profile.complexity
       )
-      .slice(-10);
+      .slice(-this.getEvaluationWindow());
   }
 
   private mergeConfigs(
@@ -446,9 +472,10 @@ export class ParameterOptimizer {
   }
 
   private calculateConvergenceRate(): number {
-    if (this.history.length < 10) return 0;
+    const window = this.getEvaluationWindow();
+    if (this.history.length < window) return 0;
 
-    const recentScores = this.history.slice(-10).map((h) => h.score);
+    const recentScores = this.history.slice(-window).map((h) => h.score);
     const variance = this.calculateVariance(recentScores);
 
     return Math.max(0, 1 - variance * 4);
@@ -495,30 +522,21 @@ export class ParameterOptimizer {
     const prompt = buildPerformanceAnalysisPrompt(evaluatedCandidates, results);
 
     try {
-      const response = await this.callLLM(
+      const content = await llmChat(
+        this.llm,
         [
           { role: 'system', content: 'You are an AI performance analyst.' },
           { role: 'user', content: prompt },
         ],
-        0.2
+        { model: this.model, temperature: 0.2 }
       );
 
-      return parsePerformanceAnalysisResponse(response.content);
+      return parsePerformanceAnalysisResponse(content);
     } catch {
       return null;
     }
   }
 
-  private async callLLM(
-    messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>,
-    temperature: number
-  ) {
-    if (this.llm.complete) {
-      return this.llm.complete({ messages, temperature });
-    }
-    return this.llm.chat({ model: this.model, messages, temperature });
-  }
-
   getCandidates(): EvolutionCandidate[] {
     return [...this.candidates];
   }

package/src/architecture-evolution/prompts.ts

@@ -60,8 +60,18 @@ export function buildCandidateGenerationPrompt(
     config: Partial<ArchitectureConfig>;
     score: number;
     metrics: Record<string, number>;
-  }>
+  }>,
+  options: { availableModels?: string[] } = {}
 ): string {
+  const availableModels = options.availableModels ?? [];
+  const modelLine =
+    availableModels.length > 0
+      ? `\n      "model": ${availableModels.map((m) => JSON.stringify(m)).join(' | ')} | null,`
+      : '';
+  const modelRule =
+    availableModels.length > 0
+      ? `Only use models from this list: ${availableModels.join(', ')}.`
+      : 'Do not change the model.';
   const historySection = historicalPerformance?.length
     ? `
 HISTORICAL PERFORMANCE:
@@ -85,18 +95,17 @@ ${historySection}
 
 Generate 3-5 candidate configurations that might improve performance.
 Each candidate should modify 1-3 parameters from current config.
+${modelRule}
 
 Respond with a JSON array:
 [
   {
     "id": "candidate_1",
-    "config": {
-      "model": "model name or null to keep current",
-      "temperature": number or null,
+    "config": {${modelLine}
+      "temperature": number between 0 and 2 or null,
       "maxTokens": number or null,
-      "systemPromptAdditions": "additional instructions or null",
       "toolStrategy": "sequential" | "parallel" | "adaptive" | null,
-      "reflectionDepth": number or null
+      "reflectionDepth": integer between 0 and 5 or null
     },
     "reasoning": "Why this configuration might help",
     "expectedImprovement": 0.0-1.0,
@@ -142,58 +151,187 @@ Respond with:
 }`;
 }
 
+const COMPLEXITIES: readonly TaskProfile['complexity'][] = [
+  'trivial',
+  'simple',
+  'moderate',
+  'complex',
+  'expert',
+  'extreme',
+];
+const DOMAINS: readonly TaskProfile['domain'][] = [
+  'general',
+  'coding',
+  'reasoning',
+  'creative',
+  'factual',
+  'conversational',
+];
+const TOOL_INTENSITIES: readonly TaskProfile['toolIntensity'][] = [
+  'none',
+  'light',
+  'moderate',
+  'heavy',
+];
+const REASONING_DEPTHS: readonly TaskProfile['reasoningDepth'][] = [
+  'shallow',
+  'moderate',
+  'deep',
+  'exhaustive',
+];
+const CREATIVITY_LEVELS: readonly TaskProfile['creativityLevel'][] = ['low', 'moderate', 'high'];
+const ACCURACY_LEVELS: readonly TaskProfile['accuracyRequirement'][] = [
+  'approximate',
+  'moderate',
+  'high',
+  'critical',
+];
+const TIME_CONSTRAINTS: readonly TaskProfile['timeConstraint'][] = [
+  'none',
+  'relaxed',
+  'moderate',
+  'strict',
+];
+const TOOL_STRATEGIES: readonly ArchitectureConfig['toolStrategy'][] = [
+  'sequential',
+  'parallel',
+  'adaptive',
+];
+const RISKS: readonly EvolutionCandidate['risk'][] = ['low', 'medium', 'high'];
+
+export const MAX_TOKENS_RANGE = { min: 100, max: 32000 } as const;
+export const REFLECTION_DEPTH_RANGE = { min: 0, max: 5 } as const;
+export const TEMPERATURE_RANGE = { min: 0, max: 2 } as const;
+
+function pickEnum<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === 'string' && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function clamp(value: number, range: { min: number; max: number }): number {
+  return Math.min(range.max, Math.max(range.min, value));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 export function parseTaskProfileResponse(response: string): TaskProfile | null {
   const json = extractJson(response);
   if (!json) return null;
 
+  let parsed: unknown;
   try {
-    const parsed = JSON.parse(json);
-
-    return {
-      complexity: parsed.complexity || 'moderate',
-      domain: parsed.domain || 'general',
-      estimatedTokens: parsed.estimatedTokens || 1000,
-      requiresTools: Boolean(parsed.requiresTools),
-      requiresReasoning: Boolean(parsed.requiresReasoning),
-      requiresCreativity: Boolean(parsed.requiresCreativity),
-      toolIntensity: parsed.toolIntensity || 'none',
-      reasoningDepth: parsed.reasoningDepth || 'moderate',
-      creativityLevel: parsed.creativityLevel || 'moderate',
-      accuracyRequirement: parsed.accuracyRequirement || 'moderate',
-      timeConstraint: parsed.timeConstraint || 'none',
-    };
+    parsed = JSON.parse(json);
   } catch {
     return null;
   }
+  if (!isRecord(parsed)) return null;
+
+  const estimatedTokens = finiteNumber(parsed.estimatedTokens);
+
+  return {
+    complexity: pickEnum(parsed.complexity, COMPLEXITIES, 'moderate'),
+    domain: pickEnum(parsed.domain, DOMAINS, 'general'),
+    estimatedTokens:
+      estimatedTokens !== undefined && estimatedTokens > 0 ? Math.round(estimatedTokens) : 1000,
+    requiresTools: Boolean(parsed.requiresTools),
+    requiresReasoning: Boolean(parsed.requiresReasoning),
+    requiresCreativity: Boolean(parsed.requiresCreativity),
+    toolIntensity: pickEnum(parsed.toolIntensity, TOOL_INTENSITIES, 'none'),
+    reasoningDepth: pickEnum(parsed.reasoningDepth, REASONING_DEPTHS, 'moderate'),
+    creativityLevel: pickEnum(parsed.creativityLevel, CREATIVITY_LEVELS, 'moderate'),
+    accuracyRequirement: pickEnum(parsed.accuracyRequirement, ACCURACY_LEVELS, 'moderate'),
+    timeConstraint: pickEnum(parsed.timeConstraint, TIME_CONSTRAINTS, 'none'),
+  };
 }
 
-export function parseCandidateGenerationResponse(response: string): EvolutionCandidate[] {
+export function sanitizeCandidateConfig(
+  raw: unknown,
+  options: { availableModels?: string[] } = {}
+): Partial<ArchitectureConfig> {
+  if (!isRecord(raw)) return {};
+  const config: Partial<ArchitectureConfig> = {};
+
+  if (typeof raw.model === 'string' && options.availableModels?.includes(raw.model)) {
+    config.model = raw.model;
+  }
+
+  const temperature = finiteNumber(raw.temperature);
+  if (temperature !== undefined) {
+    config.temperature = clamp(temperature, TEMPERATURE_RANGE);
+  }
+
+  const maxTokens = finiteNumber(raw.maxTokens);
+  if (maxTokens !== undefined) {
+    config.maxTokens = clamp(Math.round(maxTokens), MAX_TOKENS_RANGE);
+  }
+
+  if (
+    typeof raw.toolStrategy === 'string' &&
+    (TOOL_STRATEGIES as readonly string[]).includes(raw.toolStrategy)
+  ) {
+    config.toolStrategy = raw.toolStrategy as ArchitectureConfig['toolStrategy'];
+  }
+
+  const reflectionDepth = finiteNumber(raw.reflectionDepth);
+  if (reflectionDepth !== undefined) {
+    config.reflectionDepth = clamp(Math.round(reflectionDepth), REFLECTION_DEPTH_RANGE);
+  }
+
+  return config;
+}
+
+export function parseCandidateGenerationResponse(
+  response: string,
+  options: { availableModels?: string[] } = {}
+): EvolutionCandidate[] {
   const json = extractJsonArray(response);
   if (!json) return [];
 
+  let parsed: unknown;
   try {
-    const parsed = JSON.parse(json);
-    if (!Array.isArray(parsed)) return [];
-
-    return parsed
-      .filter((c: Record<string, unknown>) => c && typeof c === 'object' && c.config)
-      .map((c: Record<string, unknown>, idx: number) => ({
-        id: String(c.id || `candidate_${idx}`),
-        config: c.config as Partial<ArchitectureConfig>,
-        reasoning: String(c.reasoning || ''),
-        expectedImprovement:
-          typeof c.expectedImprovement === 'number' ? c.expectedImprovement : 0.5,
-        risk: (['low', 'medium', 'high'].includes(String(c.risk)) ? c.risk : 'medium') as
-          | 'low'
-          | 'medium'
-          | 'high',
-        generation: 0,
-        score: 0,
-        evaluationCount: 0,
-      }));
+    parsed = JSON.parse(json);
   } catch {
     return [];
   }
+  if (!Array.isArray(parsed)) return [];
+
+  const usedIds = new Set<string>(['baseline']);
+  const candidates: EvolutionCandidate[] = [];
+
+  parsed.forEach((raw: unknown, idx: number) => {
+    if (!isRecord(raw)) return;
+    const config = sanitizeCandidateConfig(raw.config, options);
+    if (Object.keys(config).length === 0) return;
+
+    let id = typeof raw.id === 'string' && raw.id.trim() ? raw.id.trim() : `candidate_${idx}`;
+    while (usedIds.has(id)) {
+      id = `${id}_${idx}`;
+    }
+    usedIds.add(id);
+
+    const expectedImprovement = finiteNumber(raw.expectedImprovement);
+
+    candidates.push({
+      id,
+      config,
+      reasoning: typeof raw.reasoning === 'string' ? raw.reasoning : '',
+      expectedImprovement:
+        expectedImprovement !== undefined ? clamp(expectedImprovement, { min: 0, max: 1 }) : 0.5,
+      risk: pickEnum(raw.risk, RISKS, 'medium'),
+      generation: 0,
+      score: 0,
+      evaluationCount: 0,
+    });
+  });
+
+  return candidates;
 }
 
 export function parsePerformanceAnalysisResponse(response: string): {