cognitive-core 0.2.5 → 0.3.1

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

@@ -1,223 +0,0 @@
-/**
- * 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

@@ -1,337 +0,0 @@
-/**
- * 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,
-};