cognitive-core 0.2.0 → 0.2.2

package/tests/learning/unified-pipeline-efficacy.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { UnifiedLearningPipeline, createUnifiedPipeline } from '../../src/learning/unified-pipeline.js';
+import { MemorySystem } from '../../src/memory/system.js';
+import { createTrajectory, type Trajectory } from '../../src/types/trajectory.js';
+import { createTask } from '../../src/types/task.js';
+import { createStep } from '../../src/types/step.js';
+import { successOutcome, failureOutcome } from '../../src/types/outcome.js';
+import { createPlaybook } from '../../src/types/playbook.js';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createSqlitePersistence } from '../../src/persistence/index.js';
+import type { SqlitePersistence } from '../../src/persistence/index.js';
+import type { Playbook } from '../../src/types/playbook.js';
+
+function makeTrajectory(overrides?: {
+  success?: boolean;
+  domain?: string;
+  description?: string;
+}): Trajectory {
+  const success = overrides?.success ?? true;
+  return createTrajectory({
+    task: createTask({
+      description: overrides?.description ?? 'Fix the typescript import error',
+      domain: overrides?.domain ?? 'typescript',
+    }),
+    steps: [
+      createStep({
+        thought: 'Let me check the imports',
+        action: 'ReadFile src/index.ts',
+        observation: 'File content: import { foo } from "./bar"',
+      }),
+      createStep({
+        thought: 'The import path is wrong',
+        action: 'EditFile src/index.ts',
+        observation: 'File updated successfully',
+      }),
+    ],
+    outcome: success
+      ? successOutcome('Fixed import path')
+      : failureOutcome('Could not resolve import'),
+    agentId: 'test-agent',
+  });
+}
+
+function makePlaybook(overrides?: Partial<{
+  name: string;
+  domain: string;
+  successCount: number;
+  failureCount: number;
+  confidence: number;
+}>): Playbook {
+  return createPlaybook({
+    name: overrides?.name ?? 'test-playbook',
+    applicability: {
+      situations: ['fix import'],
+      domains: [overrides?.domain ?? 'typescript'],
+      triggers: ['import error'],
+      antiPatterns: [],
+    },
+    guidance: {
+      strategy: 'Check and fix import paths',
+      tactics: ['Read the file', 'Fix the path'],
+      verification: [],
+      commonPitfalls: [],
+    },
+    successCount: overrides?.successCount ?? 5,
+    failureCount: overrides?.failureCount ?? 1,
+    confidence: overrides?.confidence ?? 0.8,
+  });
+}
+
+describe('UnifiedLearningPipeline — efficacy maintenance', () => {
+  let tempDir: string;
+  let memory: MemorySystem;
+  let pipeline: UnifiedLearningPipeline;
+  let persistence: SqlitePersistence;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'atlas-efficacy-test-'));
+    persistence = createSqlitePersistence({ baseDir: tempDir });
+    await persistence.init();
+    memory = new MemorySystem(persistence, tempDir);
+    await memory.init();
+  });
+
+  afterEach(async () => {
+    await memory.close();
+    persistence.close();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('should register efficacy tasks by default', async () => {
+    pipeline = createUnifiedPipeline(memory, {
+      batch: { learning: { minTrajectories: 100 }, energy: { countThreshold: 100 } },
+      features: { healing: false },
+    }, persistence);
+    await pipeline.init();
+
+    const stats = pipeline.getStats();
+    expect(stats.maintenanceTasks).toContain('playbook-decay-detection');
+    expect(stats.maintenanceTasks).toContain('playbook-efficacy-audit');
+    expect(stats.maintenanceTasks).toContain('playbook-lifecycle-review');
+  });
+
+  it('should NOT register efficacy tasks when feature is disabled', async () => {
+    pipeline = createUnifiedPipeline(memory, {
+      batch: { learning: { minTrajectories: 100 }, energy: { countThreshold: 100 } },
+      features: { healing: false, efficacy: false },
+    }, persistence);
+    await pipeline.init();
+
+    const stats = pipeline.getStats();
+    expect(stats.maintenanceTasks).not.toContain('playbook-decay-detection');
+    expect(stats.maintenanceTasks).not.toContain('playbook-efficacy-audit');
+    expect(stats.maintenanceTasks).not.toContain('playbook-lifecycle-review');
+  });
+
+  it('decay detection should skip when no playbooks exist', async () => {
+    pipeline = createUnifiedPipeline(memory, {
+      batch: { learning: { minTrajectories: 100 }, energy: { countThreshold: 100 } },
+      features: { healing: false },
+    }, persistence);
+    await pipeline.init();
+
+    const result = await pipeline.runMaintenance({ force: true });
+
+    expect(result.ran).toBe(true);
+    const decayTask = result.taskResults.find(t => t.taskName === 'playbook-decay-detection');
+    expect(decayTask).toBeDefined();
+    expect(decayTask!.success).toBe(true);
+    expect((decayTask!.details as Record<string, unknown>).skipped).toBe(true);
+  });
+
+  it('decay detection should run with playbooks and annotations', async () => {
+    // Add playbooks
+    const pb = makePlaybook({ name: 'import-fixer', successCount: 10, failureCount: 5 });
+    await memory.playbooks.add(pb);
+
+    pipeline = createUnifiedPipeline(memory, {
+      batch: { learning: { minTrajectories: 100 }, energy: { countThreshold: 100 } },
+      features: { healing: false },
+      efficacy: { minPlaybooks: 1, minAnnotations: 0, lifecycleReviewFrequency: 3 },
+    }, persistence);
+    await pipeline.init();
+
+    const result = await pipeline.runMaintenance({ force: true });
+
+    const decayTask = result.taskResults.find(t => t.taskName === 'playbook-decay-detection');
+    expect(decayTask).toBeDefined();
+    expect(decayTask!.success).toBe(true);
+    const details = decayTask!.details as Record<string, unknown>;
+    expect(details.skipped).toBeUndefined();
+    expect(typeof details.healthyCount).toBe('number');
+  });
+
+  it('efficacy audit should skip when no decay results found flagged playbooks', async () => {
+    const pb = makePlaybook({ name: 'stable-playbook', confidence: 0.9 });
+    await memory.playbooks.add(pb);
+
+    pipeline = createUnifiedPipeline(memory, {
+      batch: { learning: { minTrajectories: 100 }, energy: { countThreshold: 100 } },
+      features: { healing: false },
+      efficacy: { minPlaybooks: 1, minAnnotations: 0, lifecycleReviewFrequency: 3 },
+    }, persistence);
+    await pipeline.init();
+
+    const result = await pipeline.runMaintenance({ force: true });
+
+    const auditTask = result.taskResults.find(t => t.taskName === 'playbook-efficacy-audit');
+    expect(auditTask).toBeDefined();
+    expect(auditTask!.success).toBe(true);
+    const details = auditTask!.details as Record<string, unknown>;
+    // Should be skipped because decay detection found no flagged playbooks
+    expect(details.skipped).toBe(true);
+  });
+
+  it('lifecycle review should respect frequency setting', async () => {
+    const pb = makePlaybook({ name: 'lifecycle-test' });
+    await memory.playbooks.add(pb);
+
+    pipeline = createUnifiedPipeline(memory, {
+      batch: { learning: { minTrajectories: 100 }, energy: { countThreshold: 100 } },
+      features: { healing: false },
+      efficacy: { minPlaybooks: 1, minAnnotations: 0, lifecycleReviewFrequency: 2 },
+    }, persistence);
+    await pipeline.init();
+
+    // First maintenance (cycle 0) — should run (0 % 2 === 0)
+    const result1 = await pipeline.runMaintenance({ force: true });
+    const lifecycleTask1 = result1.taskResults.find(t => t.taskName === 'playbook-lifecycle-review');
+    expect(lifecycleTask1).toBeDefined();
+    const details1 = lifecycleTask1!.details as Record<string, unknown>;
+    expect(details1.totalPlaybooks).toBeDefined();
+
+    // Second maintenance (cycle 1) — should skip (1 % 2 !== 0)
+    const result2 = await pipeline.runMaintenance({ force: true });
+    const lifecycleTask2 = result2.taskResults.find(t => t.taskName === 'playbook-lifecycle-review');
+    expect(lifecycleTask2).toBeDefined();
+    const details2 = lifecycleTask2!.details as Record<string, unknown>;
+    expect(details2.skipped).toBe(true);
+
+    // Third maintenance (cycle 2) — should run again (2 % 2 === 0)
+    const result3 = await pipeline.runMaintenance({ force: true });
+    const lifecycleTask3 = result3.taskResults.find(t => t.taskName === 'playbook-lifecycle-review');
+    expect(lifecycleTask3).toBeDefined();
+    const details3 = lifecycleTask3!.details as Record<string, unknown>;
+    expect(details3.totalPlaybooks).toBeDefined();
+  });
+
+  it('lifecycle review returns portfolio snapshot data', async () => {
+    await memory.playbooks.add(makePlaybook({ name: 'pb-1', confidence: 0.9 }));
+    await memory.playbooks.add(makePlaybook({ name: 'pb-2', confidence: 0.4, domain: 'python' }));
+
+    pipeline = createUnifiedPipeline(memory, {
+      batch: { learning: { minTrajectories: 100 }, energy: { countThreshold: 100 } },
+      features: { healing: false },
+      efficacy: { minPlaybooks: 1, minAnnotations: 0, lifecycleReviewFrequency: 1 },
+    }, persistence);
+    await pipeline.init();
+
+    const result = await pipeline.runMaintenance({ force: true });
+
+    const lifecycleTask = result.taskResults.find(t => t.taskName === 'playbook-lifecycle-review');
+    expect(lifecycleTask).toBeDefined();
+    const details = lifecycleTask!.details as Record<string, unknown>;
+    expect(details.totalPlaybooks).toBe(2);
+    expect(details.snapshot).toBeDefined();
+    const snapshot = details.snapshot as Record<string, unknown>;
+    expect(snapshot.confidenceBands).toBeDefined();
+  });
+});

package/tests/memory/candidate-retrieval.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getCandidates,
+  type ItemResolver,
+  type CandidateRetrievalOptions,
+} from '../../src/memory/candidate-retrieval.js';
+import type { InvertedIndex } from '../../src/embeddings/inverted-index.js';
+
+/** Create a mock inverted index */
+function createMockIndex(candidateIds: string[]): InvertedIndex {
+  return {
+    getCandidates: (_query: string, _maxCandidates: number) => candidateIds,
+    add: () => {},
+    remove: () => {},
+    clear: () => {},
+    size: candidateIds.length,
+  } as unknown as InvertedIndex;
+}
+
+/** Create a mock item resolver */
+function createMockResolver<T>(items: Map<string, T>): ItemResolver<T> {
+  return {
+    get: (id: string) => items.get(id),
+    values: () => Array.from(items.values()),
+  };
+}
+
+describe('getCandidates', () => {
+  it('should use index results when enough candidates found', () => {
+    const items = new Map([
+      ['a', { id: 'a', data: 1 }],
+      ['b', { id: 'b', data: 2 }],
+      ['c', { id: 'c', data: 3 }],
+      ['d', { id: 'd', data: 4 }],
+    ]);
+
+    const index = createMockIndex(['a', 'b', 'c']);
+    const resolver = createMockResolver(items);
+    const options: CandidateRetrievalOptions = { k: 2 };
+
+    const result = getCandidates('query', index, resolver, options);
+
+    // Index returned 3 candidates >= k=2, so resolve by ID
+    expect(result).toHaveLength(3);
+    expect(result.map((r: any) => r.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should fall back to all values when index returns too few', () => {
+    const items = new Map([
+      ['a', { id: 'a', data: 1 }],
+      ['b', { id: 'b', data: 2 }],
+      ['c', { id: 'c', data: 3 }],
+    ]);
+
+    // Index returns only 1 candidate, but k=5
+    const index = createMockIndex(['a']);
+    const resolver = createMockResolver(items);
+    const options: CandidateRetrievalOptions = { k: 5 };
+
+    const result = getCandidates('query', index, resolver, options);
+
+    // Falls back to all values
+    expect(result).toHaveLength(3);
+  });
+
+  it('should use provided fallbackItems instead of resolver.values()', () => {
+    const items = new Map([
+      ['a', { id: 'a', data: 1 }],
+      ['b', { id: 'b', data: 2 }],
+    ]);
+
+    const index = createMockIndex([]); // Empty — triggers fallback
+    const resolver = createMockResolver(items);
+    const fallback = [{ id: 'x', data: 99 }];
+    const options: CandidateRetrievalOptions = { k: 5 };
+
+    const result = getCandidates('query', index, resolver, options, fallback);
+
+    expect(result).toEqual(fallback);
+  });
+
+  it('should skip unresolvable IDs from index', () => {
+    const items = new Map([
+      ['a', { id: 'a', data: 1 }],
+      // 'b' is missing from resolver
+    ]);
+
+    const index = createMockIndex(['a', 'b', 'missing']);
+    const resolver = createMockResolver(items);
+    const options: CandidateRetrievalOptions = { k: 2 };
+
+    const result = getCandidates('query', index, resolver, options);
+
+    // 3 candidates from index >= k=2, but only 'a' resolves
+    expect(result).toHaveLength(1);
+    expect((result[0] as any).id).toBe('a');
+  });
+
+  it('should respect candidateMultiplier option', () => {
+    let capturedMax = 0;
+    const mockIndex = {
+      getCandidates: (_q: string, max: number) => {
+        capturedMax = max;
+        return ['a', 'b'];
+      },
+    } as unknown as InvertedIndex;
+
+    const items = new Map([['a', 'A'], ['b', 'B']]);
+    const resolver = createMockResolver(items);
+
+    getCandidates('q', mockIndex, resolver, { k: 5, candidateMultiplier: 3 });
+
+    // maxCandidates = max(k * multiplier, minCandidates) = max(15, 50) = 50
+    expect(capturedMax).toBe(50);
+  });
+
+  it('should respect minCandidates option', () => {
+    let capturedMax = 0;
+    const mockIndex = {
+      getCandidates: (_q: string, max: number) => {
+        capturedMax = max;
+        return [];
+      },
+    } as unknown as InvertedIndex;
+
+    const resolver = createMockResolver(new Map());
+
+    getCandidates('q', mockIndex, resolver, { k: 2, candidateMultiplier: 10, minCandidates: 100 });
+
+    // maxCandidates = max(2 * 10, 100) = 100
+    expect(capturedMax).toBe(100);
+  });
+
+  it('should use default multiplier=10 and minCandidates=50', () => {
+    let capturedMax = 0;
+    const mockIndex = {
+      getCandidates: (_q: string, max: number) => {
+        capturedMax = max;
+        return [];
+      },
+    } as unknown as InvertedIndex;
+
+    const resolver = createMockResolver(new Map());
+
+    getCandidates('q', mockIndex, resolver, { k: 3 });
+
+    // maxCandidates = max(3 * 10, 50) = 50
+    expect(capturedMax).toBe(50);
+  });
+
+  it('should fall back to full scan when index returns enough IDs but none resolve', () => {
+    const items = new Map([
+      ['real', { id: 'real', data: 1 }],
+    ]);
+
+    // Index returns 5 stale/invalid IDs
+    const index = createMockIndex(['gone1', 'gone2', 'gone3', 'gone4', 'gone5']);
+    const resolver = createMockResolver(items);
+    const options: CandidateRetrievalOptions = { k: 3 };
+
+    const result = getCandidates('query', index, resolver, options);
+
+    // 5 >= k=3, but none resolve → falls back to full scan
+    expect(result).toHaveLength(1);
+    expect((result[0] as any).id).toBe('real');
+  });
+});