cognitive-core 0.0.2 → 0.1.2

package/src/workspace/templates/knowledge-extraction.ts

@@ -0,0 +1,337 @@
+/**
+ * Knowledge Extraction Template
+ *
+ * Extracts factual knowledge from agent trajectories using the
+ * AgenticTaskTemplate pattern. Routes simple trajectories to the
+ * heuristic KnowledgeExtractor, and complex ones to an agent.
+ *
+ * - Short successful trajectories (≤5 steps) → heuristic fallback
+ * - Medium trajectories (5-15 steps) → lightweight agent
+ * - Long or failed trajectories → standard agent
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type { Trajectory } from '../../types/index.js';
+import type { AnalysisResult } from '../../learning/analyzer.js';
+import type { KnowledgeNote, ExtractedKnowledge } from '../../types/knowledge.js';
+import { KnowledgeExtractor } from '../../learning/knowledge-extractor.js';
+import { serializeKnowledgeNote } from '../../utils/frontmatter.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+  ProcessingContext,
+} from '../types.js';
+import type { ComputeRequirements } from '../../runtime/compute-provider.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+export interface KnowledgeExtractionInput {
+  trajectory: Trajectory;
+  analysis: AnalysisResult;
+  /** Known entity names from the knowledge bank */
+  existingEntities: string[];
+  /** Related notes for agent context */
+  relatedNotes: KnowledgeNote[];
+}
+
+// Output is ExtractedKnowledge (from types/knowledge.ts)
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const knowledgeExtractionTemplate: AgenticTaskTemplate<
+  KnowledgeExtractionInput,
+  ExtractedKnowledge
+> = {
+  taskType: 'knowledge-extraction',
+  domain: 'knowledge-extraction',
+  description:
+    'Extract factual knowledge from agent trajectories — observations, entity updates, and cross-references',
+
+  // === COMPLEXITY ASSESSMENT ===
+
+  assessComplexity(input: KnowledgeExtractionInput): AnalysisComplexity {
+    const { trajectory } = input;
+
+    // Short successful trajectories → heuristic (KnowledgeExtractor is fine)
+    if (trajectory.steps.length <= 5 && trajectory.outcome.success) {
+      return 'heuristic';
+    }
+
+    // Very short trajectories even if failed → lightweight
+    if (trajectory.steps.length <= 3) {
+      return 'lightweight';
+    }
+
+    // Failed trajectories benefit from semantic analysis
+    if (!trajectory.outcome.success) {
+      return 'standard';
+    }
+
+    // Long trajectories need agent to identify what's worth extracting
+    if (trajectory.steps.length > 15) {
+      return 'standard';
+    }
+
+    return 'lightweight';
+  },
+
+  // === HEURISTIC FALLBACK ===
+
+  async heuristicFallback(
+    input: KnowledgeExtractionInput
+  ): Promise<ExtractedKnowledge> {
+    const extractor = new KnowledgeExtractor();
+    return extractor.extract(input.trajectory, input.analysis, {
+      existingEntities: input.existingEntities,
+    });
+  },
+
+  // === WORKSPACE SETUP ===
+
+  async prepareWorkspace(
+    input: KnowledgeExtractionInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    const { trajectory, analysis, existingEntities, relatedNotes } = input;
+
+    // Write trajectory context
+    await handle.writeJson('input', 'context.json', {
+      taskId: trajectory.task.id,
+      taskDomain: trajectory.task.domain,
+      taskDescription: trajectory.task.description,
+      outcome: {
+        success: trajectory.outcome.success,
+        partialScore: trajectory.outcome.partialScore,
+        errorInfo: trajectory.outcome.errorInfo,
+      },
+      stepCount: trajectory.steps.length,
+      wallTimeSeconds: trajectory.wallTimeSeconds,
+      llmCalls: trajectory.llmCalls,
+    });
+
+    // Write steps as JSONL
+    await handle.writeJsonl(
+      'input',
+      'steps.jsonl',
+      trajectory.steps.map((step, i) => ({
+        index: i,
+        thought: step.thought,
+        action: step.action,
+        observation: step.observation,
+        metadata: step.metadata,
+        attributionScore: step.attributionScore,
+      }))
+    );
+
+    // Write pre-computed analysis
+    await handle.writeJson('input', 'analysis.json', {
+      success: analysis.success,
+      keySteps: analysis.keySteps,
+      errorPatterns: analysis.errorPatterns,
+      abstractable: analysis.abstractable,
+    });
+
+    // Write existing entities for reference
+    await handle.writeJson('resources', 'existing-entities.json', {
+      entities: existingEntities,
+    });
+
+    // Write related knowledge notes as markdown files
+    for (const note of relatedNotes.slice(0, 20)) {
+      const filename = `${note.frontmatter.id}.md`;
+      const content = serializeKnowledgeNote(note);
+      await handle.writeRaw('resources', `related-notes/${filename}`, content);
+    }
+  },
+
+  // === PROMPT ===
+
+  buildTaskPrompt(input: KnowledgeExtractionInput): string {
+    const { trajectory } = input;
+    const outcomeStr = trajectory.outcome.success ? 'SUCCESSFUL' : 'FAILED';
+
+    return [
+      `Extract factual knowledge from this ${outcomeStr} agent trajectory (${trajectory.steps.length} steps, domain: ${trajectory.task.domain}).`,
+      '',
+      'Read the trajectory from input/context.json, input/steps.jsonl, and input/analysis.json.',
+      'Reference existing entities in resources/existing-entities.json.',
+      'Review related knowledge notes in resources/related-notes/ to avoid duplicates.',
+      '',
+      'Extract the following types of knowledge:',
+      '',
+      '1. **Observations**: Atomic facts learned from this trajectory.',
+      '   - Error patterns and their fixes',
+      '   - Configuration requirements and constraints',
+      '   - Tool/library behaviors discovered',
+      '   - Causal relationships (what caused what)',
+      '',
+      '2. **Entity Updates**: New information about known entities.',
+      '   - If an entity already exists (see existing-entities.json), produce an update',
+      '   - Include the evidence source (trajectory ID)',
+      '',
+      '3. **Links**: Relationships between knowledge notes.',
+      '   - Use relations: related-to, depends-on, caused-by, led-to, uses, supports',
+      '',
+      'Write your extraction to output/extraction.json with this schema:',
+      '```json',
+      '{',
+      '  "observations": [',
+      '    {',
+      '      "title": "string",',
+      '      "body": "string (markdown)",',
+      '      "domain": ["string"],',
+      '      "entities": ["string"],',
+      '      "tags": ["string"],',
+      '      "confidence": 0.3',
+      '    }',
+      '  ],',
+      '  "entityUpdates": [',
+      '    {',
+      '      "entityId": "string (kebab-case slug)",',
+      '      "section": "string (markdown section to append)",',
+      '      "trajectoryId": "string"',
+      '    }',
+      '  ],',
+      '  "links": [',
+      '    {',
+      '      "from": "string (note ID)",',
+      '      "to": "string (note ID)",',
+      '      "relation": "string"',
+      '    }',
+      '  ]',
+      '}',
+      '```',
+      '',
+      'Guidelines:',
+      '- Each observation should be a single atomic fact',
+      '- Confidence should be 0.3 for single-observation facts',
+      '- Use kebab-case for entity IDs (e.g., "prisma", "next-js")',
+      '- Only extract knowledge that is genuinely useful for future tasks',
+    ].join('\n');
+  },
+
+  // === SKILLS & RESOURCES ===
+
+  getSkills() {
+    return [];
+  },
+
+  getResources() {
+    return [];
+  },
+
+  // === OUTPUT ===
+
+  outputConfig: {
+    files: [
+      {
+        path: 'extraction.json',
+        format: 'json' as const,
+        required: true,
+        description:
+          'Extracted knowledge: observations, entity updates, and links',
+      },
+    ],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<ExtractedKnowledge> {
+    const raw = await handle.readJson('output', 'extraction.json');
+    const data = raw as Record<string, unknown>;
+
+    // Parse observations into KnowledgeNote format
+    const rawObs = Array.isArray(data.observations) ? data.observations : [];
+    const observations: KnowledgeNote[] = [];
+
+    for (const obs of rawObs) {
+      if (typeof obs !== 'object' || obs === null) continue;
+      const o = obs as Record<string, unknown>;
+
+      const { createObservation } = await import('../../types/knowledge.js');
+      observations.push(
+        createObservation({
+          title: String(o.title ?? 'Untitled'),
+          body: String(o.body ?? ''),
+          domain: Array.isArray(o.domain)
+            ? o.domain.map(String)
+            : ['unknown'],
+          entities: Array.isArray(o.entities) ? o.entities.map(String) : [],
+          tags: Array.isArray(o.tags) ? o.tags.map(String) : [],
+          confidence: typeof o.confidence === 'number' ? o.confidence : 0.3,
+          source: { origin: 'extracted' },
+        })
+      );
+    }
+
+    // Parse entity updates
+    const rawUpdates = Array.isArray(data.entityUpdates)
+      ? data.entityUpdates
+      : [];
+    const entityUpdates = rawUpdates
+      .filter(
+        (u): u is Record<string, unknown> =>
+          typeof u === 'object' && u !== null
+      )
+      .map((u) => ({
+        entityId: String(u.entityId ?? ''),
+        section: String(u.section ?? ''),
+        trajectoryId: String(u.trajectoryId ?? ''),
+      }));
+
+    // Parse links
+    const rawLinks = Array.isArray(data.links) ? data.links : [];
+    const links = rawLinks
+      .filter(
+        (l): l is Record<string, unknown> =>
+          typeof l === 'object' && l !== null
+      )
+      .map((l) => ({
+        from: String(l.from ?? ''),
+        to: String(l.to ?? ''),
+        relation: String(l.relation ?? 'related-to') as any,
+      }));
+
+    return {
+      observations,
+      entityUpdates,
+      contradictions: [],
+      links,
+      playbookLinks: [],
+    };
+  },
+
+  async processOutput(
+    _output: ExtractedKnowledge,
+    _input: KnowledgeExtractionInput,
+    _context: ProcessingContext
+  ): Promise<void> {
+    // No-op: caller handles applying the extraction via applyExtraction()
+  },
+
+  // === COMPUTE ===
+
+  computeRequirements: {
+    mode: 'local',
+    complexity: 'lightweight',
+  },
+
+  getComputeRequirements(
+    _input: KnowledgeExtractionInput,
+    complexity: AnalysisComplexity
+  ): ComputeRequirements {
+    return {
+      mode: 'local',
+      complexity,
+      timeout: complexity === 'standard' ? 180_000 : 60_000,
+    };
+  },
+
+  // === CONFIG ===
+
+  agentType: 'claude-code',
+  timeout: 120_000,
+  captureToolCalls: true,
+};

package/src/workspace/templates/meta-reflection.ts

@@ -0,0 +1,208 @@
+/**
+ * Meta-Reflection Template
+ *
+ * Replaces MetaLearner.generateReflection() with workspace-based
+ * semantic reflection that analyzes what worked and why.
+ *
+ * - Clear success with high confidence routing → heuristic fallback
+ * - Failures or uncertain outcomes → agent reflects on execution
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type { Trajectory } from '../../types/index.js';
+import type { PlaybookMatch } from '../../memory/playbook.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+} from '../types.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+export interface MetaReflectionInput {
+  trajectory: Trajectory;
+  routingDecision: {
+    strategy: string;
+    confidence: number;
+    estimatedBudget: number;
+    reasoning: string;
+  };
+  playbooksUsed: PlaybookMatch[];
+}
+
+/**
+ * Simplified meta-reflection output.
+ * The full MetaObservation is constructed by the MetaLearner after
+ * receiving this output, so we only need the core reflection data.
+ */
+export interface MetaReflectionOutput {
+  /** Was the retrieval helpful, neutral, or misleading? */
+  retrievalQuality: 'helpful' | 'neutral' | 'misleading';
+  /** Overall outcome quality */
+  outcomeQuality: 'excellent' | 'good' | 'acceptable' | 'poor';
+  /** What worked well */
+  whatWorked: string[];
+  /** What failed or was suboptimal */
+  whatFailed: string[];
+  /** Suggestions for improvement */
+  suggestions: string[];
+  /** Whether decomposition was used */
+  decompositionUsed: boolean;
+  /** Whether backtracking occurred */
+  backtrackingOccurred: boolean;
+  /** Estimated refinement iterations */
+  refinementIterations: number;
+}
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const metaReflectionTemplate: AgenticTaskTemplate<
+  MetaReflectionInput,
+  MetaReflectionOutput
+> = {
+  taskType: 'meta-reflection',
+  domain: 'meta-reflection',
+  description: 'Reflect on task execution to generate meta-learning observations',
+
+  assessComplexity(input: MetaReflectionInput): AnalysisComplexity {
+    // Clear success with high confidence → heuristic
+    if (
+      input.trajectory.outcome.success &&
+      input.routingDecision.confidence > 0.8
+    ) {
+      return 'heuristic';
+    }
+    return 'lightweight';
+  },
+
+  async heuristicFallback(input: MetaReflectionInput): Promise<MetaReflectionOutput> {
+    const { trajectory, routingDecision, playbooksUsed } = input;
+    const wasSuccessful = trajectory.outcome.success;
+    const actualEffort = trajectory.llmCalls ?? trajectory.steps.length;
+    const effortRatio = actualEffort / routingDecision.estimatedBudget;
+
+    return {
+      retrievalQuality: playbooksUsed.length === 0 ? 'neutral'
+        : wasSuccessful ? 'helpful' : 'neutral',
+      outcomeQuality: !wasSuccessful ? 'poor'
+        : effortRatio <= 0.5 ? 'excellent'
+        : effortRatio <= 1.0 ? 'good'
+        : effortRatio <= 2.0 ? 'acceptable' : 'poor',
+      whatWorked: wasSuccessful
+        ? [`${routingDecision.strategy} routing led to success`]
+        : [],
+      whatFailed: wasSuccessful
+        ? []
+        : [`${routingDecision.strategy} routing did not lead to success`],
+      suggestions: wasSuccessful ? [] : ['Consider alternative approaches'],
+      decompositionUsed: trajectory.steps.some(
+        s => s.thought?.includes('break') || s.thought?.includes('step by step')
+      ),
+      backtrackingOccurred: false,
+      refinementIterations: 0,
+    };
+  },
+
+  async prepareWorkspace(
+    input: MetaReflectionInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    const { trajectory, routingDecision, playbooksUsed } = input;
+
+    await handle.writeJson('input', 'context.json', {
+      routing: routingDecision,
+      outcome: trajectory.outcome,
+      stepCount: trajectory.steps.length,
+      wallTimeSeconds: trajectory.wallTimeSeconds,
+      playbooksInjected: playbooksUsed.map(pm => ({
+        name: pm.playbook.name,
+        strategy: pm.playbook.guidance.strategy,
+        score: pm.score,
+        matchType: pm.matchType,
+      })),
+    });
+
+    await handle.writeJsonl('input', 'steps.jsonl',
+      trajectory.steps.map((step, i) => ({
+        index: i,
+        thought: step.thought?.slice(0, 200),
+        action: step.action.slice(0, 200),
+        observation: step.observation?.slice(0, 200),
+      }))
+    );
+  },
+
+  buildTaskPrompt(input: MetaReflectionInput): string {
+    const outcome = input.trajectory.outcome.success ? 'SUCCESSFUL' : 'FAILED';
+    return [
+      `Reflect on this ${outcome} task execution.`,
+      '',
+      'Read input/context.json for routing decision and outcome.',
+      'Read input/steps.jsonl for the execution trace.',
+      '',
+      'Analyze:',
+      '1. Was the retrieved knowledge helpful, neutral, or misleading?',
+      '2. What outcome quality level (excellent/good/acceptable/poor)?',
+      '3. What worked well? What failed?',
+      '4. What suggestions for future similar tasks?',
+      '5. Was decomposition used? Did backtracking occur?',
+      '',
+      'Write to output/reflection.json with this schema:',
+      '```json',
+      '{',
+      '  "retrievalQuality": "helpful" | "neutral" | "misleading",',
+      '  "outcomeQuality": "excellent" | "good" | "acceptable" | "poor",',
+      '  "whatWorked": ["..."],',
+      '  "whatFailed": ["..."],',
+      '  "suggestions": ["..."],',
+      '  "decompositionUsed": boolean,',
+      '  "backtrackingOccurred": boolean,',
+      '  "refinementIterations": number',
+      '}',
+      '```',
+    ].join('\n');
+  },
+
+  getSkills() { return []; },
+  getResources() { return []; },
+
+  outputConfig: {
+    files: [{
+      path: 'reflection.json',
+      format: 'json' as const,
+      required: true,
+      description: 'Meta-reflection on task execution',
+    }],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<MetaReflectionOutput> {
+    const raw = await handle.readJson('output', 'reflection.json') as Record<string, unknown>;
+    return {
+      retrievalQuality: (['helpful', 'neutral', 'misleading'].includes(String(raw.retrievalQuality))
+        ? raw.retrievalQuality : 'neutral') as MetaReflectionOutput['retrievalQuality'],
+      outcomeQuality: (['excellent', 'good', 'acceptable', 'poor'].includes(String(raw.outcomeQuality))
+        ? raw.outcomeQuality : 'poor') as MetaReflectionOutput['outcomeQuality'],
+      whatWorked: Array.isArray(raw.whatWorked) ? raw.whatWorked.map(String) : [],
+      whatFailed: Array.isArray(raw.whatFailed) ? raw.whatFailed.map(String) : [],
+      suggestions: Array.isArray(raw.suggestions) ? raw.suggestions.map(String) : [],
+      decompositionUsed: Boolean(raw.decompositionUsed),
+      backtrackingOccurred: Boolean(raw.backtrackingOccurred),
+      refinementIterations: typeof raw.refinementIterations === 'number'
+        ? raw.refinementIterations : 0,
+    };
+  },
+
+  async processOutput(): Promise<void> {},
+
+  agentType: 'claude-code',
+  timeout: 120_000,
+  captureToolCalls: true,
+
+  computeRequirements: {
+    mode: 'local',
+    complexity: 'lightweight',
+  },
+};