cognitive-core 0.1.0 → 0.2.0

package/src/learning/knowledge-extractor.ts

@@ -0,0 +1,470 @@
+import type { Trajectory } from '../types/trajectory.js';
+import type { AnalysisResult } from './analyzer.js';
+import type {
+  ExtractedKnowledge,
+  EntityUpdate,
+  NewLink,
+  PlaybookLink,
+  KnowledgeNote,
+} from '../types/knowledge.js';
+import { createObservation } from '../types/knowledge.js';
+import { tokenize } from '../utils/similarity.js';
+
+/**
+ * Configuration for the KnowledgeExtractor.
+ */
+export interface KnowledgeExtractorConfig {
+  /** Minimum confidence for new observations (default: 0.3) */
+  initialConfidence: number;
+  /** Similarity threshold for matching entities in text (default: 0.6) */
+  entityMatchThreshold: number;
+  /** Config file patterns to detect (default: common config files) */
+  configFilePatterns: string[];
+}
+
+const DEFAULT_CONFIG: KnowledgeExtractorConfig = {
+  initialConfidence: 0.3,
+  entityMatchThreshold: 0.6,
+  configFilePatterns: [
+    'package.json',
+    'tsconfig.json',
+    'tsconfig',
+    '.eslintrc',
+    'eslint.config',
+    '.prettierrc',
+    'jest.config',
+    'vitest.config',
+    'vite.config',
+    'webpack.config',
+    'next.config',
+    'docker',
+    'Dockerfile',
+    '.env',
+    'Makefile',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+  ],
+};
+
+/**
+ * Context about existing knowledge for smarter extraction.
+ */
+export interface ExtractionContext {
+  /** Known entity names from the knowledge bank */
+  existingEntities?: string[];
+  /** Known note IDs (to avoid creating duplicates) */
+  existingNoteIds?: string[];
+}
+
+/**
+ * KnowledgeExtractor — heuristic engine for extracting factual knowledge
+ * from agent trajectories.
+ *
+ * Runs 4 strategies:
+ * 1. Error patterns → observations (from AnalysisResult.errorPatterns)
+ * 2. Config facts → observations (detect config file reads/writes)
+ * 3. Causal chains → observations + causal links (failure→recovery)
+ * 4. Entity identification → entity updates or new observations
+ *
+ * Plus cross-reference detection for playbook links.
+ */
+export class KnowledgeExtractor {
+  private config: KnowledgeExtractorConfig;
+
+  constructor(config?: Partial<KnowledgeExtractorConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Extract knowledge from a single trajectory and its analysis.
+   */
+  extract(
+    trajectory: Trajectory,
+    analysis: AnalysisResult,
+    context?: ExtractionContext
+  ): ExtractedKnowledge {
+    const observations: KnowledgeNote[] = [];
+    const entityUpdates: EntityUpdate[] = [];
+    const links: NewLink[] = [];
+    const playbookLinks: PlaybookLink[] = [];
+
+    // Strategy 1: Error patterns
+    const errorObs = this.extractErrorPatterns(trajectory, analysis);
+    observations.push(...errorObs);
+
+    // Strategy 2: Config facts
+    const configObs = this.extractConfigFacts(trajectory);
+    observations.push(...configObs);
+
+    // Strategy 3: Causal chains
+    const { observations: causalObs, links: causalLinks } =
+      this.extractCausalChains(trajectory);
+    observations.push(...causalObs);
+    links.push(...causalLinks);
+
+    // Strategy 4: Entity identification
+    const entityResults = this.extractEntityKnowledge(
+      trajectory,
+      analysis,
+      observations,
+      context
+    );
+    entityUpdates.push(...entityResults.updates);
+
+    // Cross-reference: playbook links
+    const pbLinks = this.extractPlaybookLinks(trajectory, observations);
+    playbookLinks.push(...pbLinks);
+
+    return {
+      observations,
+      entityUpdates,
+      contradictions: [], // Deferred to Phase 3
+      links,
+      playbookLinks,
+    };
+  }
+
+  // =========================================================================
+  // Strategy 1: Error Patterns → Observations
+  // =========================================================================
+
+  private extractErrorPatterns(
+    trajectory: Trajectory,
+    analysis: AnalysisResult
+  ): KnowledgeNote[] {
+    const observations: KnowledgeNote[] = [];
+
+    for (const pattern of analysis.errorPatterns) {
+      if (!pattern.suggestedFix) continue;
+
+      // Extract tool/library name from the error signature
+      const entities = this.extractEntitiesFromText(
+        `${pattern.signature} ${pattern.description}`
+      );
+
+      observations.push(
+        createObservation({
+          title: `${pattern.type} error: ${pattern.signature}`,
+          body: [
+            `## Error Pattern`,
+            '',
+            `**Type**: ${pattern.type}`,
+            `**Signature**: ${pattern.signature}`,
+            `**Description**: ${pattern.description}`,
+            `**Fix**: ${pattern.suggestedFix}`,
+            '',
+            `*Observed in trajectory ${trajectory.id}, domain: ${trajectory.task.domain}*`,
+          ].join('\n'),
+          domain: [trajectory.task.domain],
+          entities,
+          tags: ['error-pattern', pattern.type],
+          confidence: this.config.initialConfidence,
+          source: {
+            origin: 'extracted',
+            trajectories: [trajectory.id],
+          },
+        })
+      );
+    }
+
+    return observations;
+  }
+
+  // =========================================================================
+  // Strategy 2: Config Facts
+  // =========================================================================
+
+  private extractConfigFacts(trajectory: Trajectory): KnowledgeNote[] {
+    const observations: KnowledgeNote[] = [];
+    const seenConfigs = new Set<string>();
+
+    for (const step of trajectory.steps) {
+      const actionLower = step.action.toLowerCase();
+      const obsLower = step.observation.toLowerCase();
+
+      for (const pattern of this.config.configFilePatterns) {
+        const patternLower = pattern.toLowerCase();
+        if (
+          !actionLower.includes(patternLower) &&
+          !obsLower.includes(patternLower)
+        ) {
+          continue;
+        }
+
+        // Avoid duplicate observations for the same config file
+        if (seenConfigs.has(pattern)) continue;
+        seenConfigs.add(pattern);
+
+        // Extract version-like strings from the observation
+        const versions = this.extractVersions(step.observation);
+        const entities = this.extractEntitiesFromText(
+          `${step.action} ${step.observation}`
+        );
+
+        const bodyParts = [
+          `## Configuration: ${pattern}`,
+          '',
+          `**Action**: ${step.action.slice(0, 200)}`,
+        ];
+
+        if (versions.length > 0) {
+          bodyParts.push(`**Versions detected**: ${versions.join(', ')}`);
+        }
+
+        bodyParts.push(
+          '',
+          `**Observation**: ${step.observation.slice(0, 300)}`,
+          '',
+          `*Observed in trajectory ${trajectory.id}*`
+        );
+
+        observations.push(
+          createObservation({
+            title: `Config: ${pattern} settings`,
+            body: bodyParts.join('\n'),
+            domain: [trajectory.task.domain],
+            entities,
+            tags: ['config', pattern.replace(/[^a-zA-Z0-9]/g, '-')],
+            confidence: this.config.initialConfidence,
+            source: {
+              origin: 'extracted',
+              trajectories: [trajectory.id],
+            },
+          })
+        );
+      }
+    }
+
+    return observations;
+  }
+
+  // =========================================================================
+  // Strategy 3: Causal Chains (failure → recovery)
+  // =========================================================================
+
+  private extractCausalChains(trajectory: Trajectory): {
+    observations: KnowledgeNote[];
+    links: NewLink[];
+  } {
+    const observations: KnowledgeNote[] = [];
+    const links: NewLink[] = [];
+
+    for (let i = 0; i < trajectory.steps.length - 1; i++) {
+      const step = trajectory.steps[i];
+      const isFailure = this.isFailureStep(step);
+
+      if (!isFailure) continue;
+
+      // Look for recovery in the next 1-3 steps
+      const recoverySteps = [];
+      for (
+        let j = i + 1;
+        j < Math.min(i + 4, trajectory.steps.length);
+        j++
+      ) {
+        const nextStep = trajectory.steps[j];
+        if (!this.isFailureStep(nextStep)) {
+          recoverySteps.push(nextStep);
+          break;
+        }
+      }
+
+      if (recoverySteps.length === 0) continue;
+
+      const recovery = recoverySteps[0];
+      const entities = this.extractEntitiesFromText(
+        `${step.action} ${step.observation} ${recovery.action}`
+      );
+
+      const failureObs = createObservation({
+        title: `Failure-recovery: ${step.action.slice(0, 50)}`,
+        body: [
+          `## Causal Chain`,
+          '',
+          `**Failed action**: ${step.action.slice(0, 200)}`,
+          `**Error**: ${step.observation.slice(0, 200)}`,
+          `**Recovery action**: ${recovery.action.slice(0, 200)}`,
+          `**Result**: ${recovery.observation.slice(0, 200)}`,
+          '',
+          `*Observed in trajectory ${trajectory.id}*`,
+        ].join('\n'),
+        domain: [trajectory.task.domain],
+        entities,
+        tags: ['causal-chain', 'failure-recovery'],
+        confidence: this.config.initialConfidence,
+        source: {
+          origin: 'extracted',
+          trajectories: [trajectory.id],
+        },
+        links: [
+          {
+            target: `recovery-${trajectory.id}-${i}`,
+            relation: 'led-to',
+          },
+        ],
+      });
+
+      observations.push(failureObs);
+
+      links.push({
+        from: failureObs.frontmatter.id,
+        to: `recovery-${trajectory.id}-${i}`,
+        relation: 'led-to',
+        layer: 'causal',
+      });
+    }
+
+    return { observations, links };
+  }
+
+  // =========================================================================
+  // Strategy 4: Entity Identification
+  // =========================================================================
+
+  private extractEntityKnowledge(
+    trajectory: Trajectory,
+    _analysis: AnalysisResult,
+    newObservations: KnowledgeNote[],
+    context?: ExtractionContext
+  ): { updates: EntityUpdate[] } {
+    const updates: EntityUpdate[] = [];
+    const existingEntities = new Set(context?.existingEntities ?? []);
+
+    if (existingEntities.size === 0) return { updates };
+
+    // For each existing entity, check if new observations mention it
+    for (const entityName of existingEntities) {
+      const entityLower = entityName.toLowerCase();
+      const relevantObs = newObservations.filter((obs) => {
+        const text =
+          `${obs.frontmatter.entities.join(' ')} ${obs.body}`.toLowerCase();
+        return text.includes(entityLower);
+      });
+
+      if (relevantObs.length === 0) continue;
+
+      // Produce an entity update with new evidence
+      const summaries = relevantObs
+        .map((obs) => `- ${obs.body.split('\n')[0].replace(/^#+ /, '')}`)
+        .join('\n');
+
+      updates.push({
+        entityId: entityName.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+        section: `## Evidence from trajectory ${trajectory.id}\n\n${summaries}`,
+        trajectoryId: trajectory.id,
+      });
+    }
+
+    return { updates };
+  }
+
+  // =========================================================================
+  // Cross-Reference: Playbook Links
+  // =========================================================================
+
+  private extractPlaybookLinks(
+    trajectory: Trajectory,
+    observations: KnowledgeNote[]
+  ): PlaybookLink[] {
+    const links: PlaybookLink[] = [];
+
+    // Check trajectory metadata for injected playbooks
+    const injectedPlaybooks = trajectory.metadata?.injectedPlaybooks;
+    if (!Array.isArray(injectedPlaybooks) || injectedPlaybooks.length === 0) {
+      return links;
+    }
+
+    // Link each new observation to each injected playbook
+    for (const obs of observations) {
+      for (const playbookId of injectedPlaybooks) {
+        if (typeof playbookId !== 'string') continue;
+
+        links.push({
+          noteId: obs.frontmatter.id,
+          playbookId,
+          relation: 'supports',
+        });
+      }
+    }
+
+    return links;
+  }
+
+  // =========================================================================
+  // Helpers
+  // =========================================================================
+
+  private isFailureStep(step: { action: string; observation: string }): boolean {
+    const obs = step.observation.toLowerCase();
+    return (
+      obs.includes('error') ||
+      obs.includes('failed') ||
+      obs.includes('exception') ||
+      obs.includes('cannot') ||
+      obs.includes('unable to') ||
+      obs.includes('not found')
+    );
+  }
+
+  private extractEntitiesFromText(text: string): string[] {
+    const entities: string[] = [];
+    const tokens = tokenize(text);
+
+    // Known tool/library patterns
+    const knownPatterns = [
+      /\b(node|npm|yarn|pnpm|bun)\b/i,
+      /\b(react|vue|angular|svelte|next|nuxt)\b/i,
+      /\b(express|fastify|koa|hono)\b/i,
+      /\b(prisma|drizzle|typeorm|sequelize|knex)\b/i,
+      /\b(postgres|mysql|sqlite|mongodb|redis)\b/i,
+      /\b(docker|kubernetes|k8s)\b/i,
+      /\b(typescript|javascript|python|rust|go)\b/i,
+      /\b(vitest|jest|mocha|playwright|cypress)\b/i,
+      /\b(eslint|prettier|biome)\b/i,
+      /\b(webpack|vite|esbuild|rollup|turbopack)\b/i,
+      /\b(git|github|gitlab)\b/i,
+    ];
+
+    for (const pattern of knownPatterns) {
+      const match = text.match(pattern);
+      if (match) {
+        const entity = match[1].toLowerCase();
+        if (!entities.includes(entity)) {
+          entities.push(entity);
+        }
+      }
+    }
+
+    // Also extract npm package-like names (scoped or simple)
+    const packagePattern = /@?[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)?/g;
+    const matches = text.match(packagePattern);
+    if (matches) {
+      for (const m of matches) {
+        if (m.length >= 3 && m.length <= 50 && !entities.includes(m)) {
+          // Only include if it looks like a real package name
+          if (tokens.includes(m) || text.includes(`"${m}"`)) {
+            entities.push(m);
+          }
+        }
+      }
+    }
+
+    return entities.slice(0, 10); // Cap at 10 entities
+  }
+
+  private extractVersions(text: string): string[] {
+    const versionPattern = /\b\d+\.\d+(?:\.\d+)?(?:-[a-zA-Z0-9.]+)?\b/g;
+    const matches = text.match(versionPattern);
+    return matches ? [...new Set(matches)] : [];
+  }
+}
+
+/**
+ * Create a KnowledgeExtractor with optional config overrides.
+ */
+export function createKnowledgeExtractor(
+  config?: Partial<KnowledgeExtractorConfig>
+): KnowledgeExtractor {
+  return new KnowledgeExtractor(config);
+}