cognitive-core 0.1.0 → 0.2.0

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

@@ -0,0 +1,223 @@
+/**
+ * Knowledge Defragmentation Template
+ *
+ * Agentic task template for knowledge base defragmentation.
+ * Routes simple cases to heuristic (KnowledgeDefragmenter) and
+ * complex cases to an agent workspace.
+ *
+ * - Small inbox + ≤50 notes → heuristic fallback
+ * - ≤200 notes → lightweight agent
+ * - Larger → standard agent
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type { KnowledgeNote, DefragResult, InboxResult } from '../../types/knowledge.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 KnowledgeDefragInput {
+  /** All notes currently in the knowledge bank */
+  notes: KnowledgeNote[];
+  /** Number of inbox items */
+  inboxCount: number;
+  /** Domain names present in the knowledge bank */
+  domains: string[];
+  /** Entity names present in the knowledge bank */
+  entities: string[];
+}
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const knowledgeDefragTemplate: AgenticTaskTemplate<
+  KnowledgeDefragInput,
+  DefragResult
+> = {
+  taskType: 'knowledge-defrag',
+  domain: 'knowledge-defrag',
+  description:
+    'Defragment a knowledge bank: consolidate observations, detect contradictions, rebuild graph, regenerate domain summaries, sweep stale notes.',
+
+  agentType: 'claude-code',
+  captureToolCalls: true,
+
+  // === COMPLEXITY ASSESSMENT ===
+
+  assessComplexity(input: KnowledgeDefragInput): AnalysisComplexity {
+    const noteCount = input.notes.length;
+
+    // Small inbox + few notes → heuristic
+    if (input.inboxCount <= 10 && noteCount <= 50) {
+      return 'heuristic';
+    }
+
+    // Medium → lightweight
+    if (noteCount <= 200) {
+      return 'lightweight';
+    }
+
+    // Large → standard
+    return 'standard';
+  },
+
+  // === HEURISTIC FALLBACK ===
+
+  async heuristicFallback(
+    _input: KnowledgeDefragInput
+  ): Promise<DefragResult> {
+    // Caller (KnowledgeBank.defragment) delegates to KnowledgeDefragmenter directly.
+    // This stub returns an empty result for the template interface.
+    const emptyInbox: InboxResult = {
+      processed: 0,
+      failed: 0,
+      movedToObservations: 0,
+      movedToEntities: 0,
+      movedToDomains: 0,
+    };
+    return {
+      inbox: emptyInbox,
+      consolidated: 0,
+      contradictions: 0,
+      graphRebuilt: false,
+      domainSummariesRegenerated: 0,
+      decay: { decayed: 0, newlyStale: 0, alreadyStale: 0 },
+    };
+  },
+
+  // === WORKSPACE SETUP ===
+
+  async prepareWorkspace(
+    input: KnowledgeDefragInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    // Write state summary
+    await handle.writeJson('input', 'state.json', {
+      noteCount: input.notes.length,
+      inboxCount: input.inboxCount,
+      domains: input.domains,
+      entities: input.entities,
+    });
+
+    // Write individual notes
+    for (const note of input.notes) {
+      const content = serializeKnowledgeNote(note);
+      await handle.writeRaw(
+        'input',
+        `notes/${note.frontmatter.id}.md`,
+        content
+      );
+    }
+  },
+
+  buildTaskPrompt(input: KnowledgeDefragInput): string {
+    const noteCount = input.notes.length;
+    const domainList = input.domains.join(', ') || 'none';
+
+    return `# Knowledge Bank Defragmentation
+
+## Knowledge Bank State
+- **${noteCount} notes** across domains: ${domainList}
+- **${input.inboxCount} inbox items** pending
+- **${input.entities.length} entities** tracked
+
+## Input Files
+- \`state.json\` — bank statistics and metadata
+- \`notes/*.md\` — all knowledge notes with frontmatter
+
+## Tasks
+
+1. **Consolidation**: Group observations by entity. If ≥3 observations reference the same entity, create a consolidated entity note.
+2. **Contradiction Detection**: Find note pairs with conflicting information. Flag for review.
+3. **Domain Summary Regeneration**: For each domain, generate a summary listing key entities and top observations.
+
+## Output
+
+Write \`defrag-result.json\` containing:
+\`\`\`json
+{
+  "consolidated": <number>,
+  "contradictions": <number>,
+  "domainSummariesRegenerated": <number>,
+  "actions": [
+    { "type": "consolidate", "entityName": "...", "observationIds": [...] },
+    { "type": "contradiction", "noteA": "...", "noteB": "...", "description": "..." },
+    { "type": "domain-summary", "domain": "...", "content": "..." }
+  ]
+}
+\`\`\`
+`;
+  },
+
+  // === SKILLS & RESOURCES ===
+
+  getSkills(): [] {
+    return [];
+  },
+
+  getResources(): [] {
+    return [];
+  },
+
+  // === OUTPUT ===
+
+  outputConfig: {
+    files: [
+      {
+        path: 'defrag-result.json',
+        format: 'json' as const,
+        required: true,
+      },
+    ],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<DefragResult> {
+    const parsed = (await handle.readJson('output', 'defrag-result.json')) as Record<string, unknown>;
+
+    const emptyInbox: InboxResult = {
+      processed: 0,
+      failed: 0,
+      movedToObservations: 0,
+      movedToEntities: 0,
+      movedToDomains: 0,
+    };
+
+    return {
+      inbox: emptyInbox,
+      consolidated: (parsed.consolidated as number) ?? 0,
+      contradictions: (parsed.contradictions as number) ?? 0,
+      graphRebuilt: false,
+      domainSummariesRegenerated: (parsed.domainSummariesRegenerated as number) ?? 0,
+      decay: { decayed: 0, newlyStale: 0, alreadyStale: 0 },
+    };
+  },
+
+  async processOutput(
+    _output: DefragResult,
+    _input: KnowledgeDefragInput,
+    _context: ProcessingContext
+  ): Promise<void> {
+    // No-op — caller applies results directly
+  },
+
+  // === COMPUTE ===
+
+  getComputeRequirements(
+    _input: KnowledgeDefragInput,
+    complexity: AnalysisComplexity
+  ): ComputeRequirements {
+    return {
+      mode: 'local' as const,
+      timeout: complexity === 'standard' ? 300_000 : 120_000,
+    };
+  },
+};

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,
+};