cognitive-core 0.0.1 → 0.1.0

package/tests/types/task.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect } from 'vitest';
+import {
+  TaskSchema,
+  VerificationSpecSchema,
+  createTask,
+  type Task,
+  type VerificationSpec,
+} from '../../src/types/task.js';
+
+describe('VerificationSpec', () => {
+  it('should validate exact_match verification', () => {
+    const spec: VerificationSpec = {
+      type: 'exact_match',
+      expected: 'hello',
+    };
+    const result = VerificationSpecSchema.parse(spec);
+    expect(result.type).toBe('exact_match');
+    expect(result.expected).toBe('hello');
+  });
+
+  it('should validate fuzzy_match with tolerance', () => {
+    const spec: VerificationSpec = {
+      type: 'fuzzy_match',
+      expected: 42,
+      tolerance: 0.1,
+    };
+    const result = VerificationSpecSchema.parse(spec);
+    expect(result.type).toBe('fuzzy_match');
+    expect(result.tolerance).toBe(0.1);
+  });
+
+  it('should validate function verification', () => {
+    const spec: VerificationSpec = {
+      type: 'function',
+      verifier_id: 'custom-verifier',
+    };
+    const result = VerificationSpecSchema.parse(spec);
+    expect(result.type).toBe('function');
+    expect(result.verifier_id).toBe('custom-verifier');
+  });
+
+  it('should validate llm verification', () => {
+    const spec: VerificationSpec = {
+      type: 'llm',
+      expected: 'The output should be correct',
+    };
+    const result = VerificationSpecSchema.parse(spec);
+    expect(result.type).toBe('llm');
+  });
+
+  it('should reject invalid verification types', () => {
+    expect(() =>
+      VerificationSpecSchema.parse({ type: 'invalid' })
+    ).toThrow();
+  });
+});
+
+describe('Task', () => {
+  it('should validate a complete task', () => {
+    const task: Task = {
+      id: 'task-1',
+      domain: 'code',
+      description: 'Write a function to add two numbers',
+      context: { language: 'typescript' },
+      verification: { type: 'exact_match', expected: 5 },
+      embedding: [0.1, 0.2, 0.3],
+      metadata: { priority: 'high' },
+      createdAt: new Date(),
+    };
+    const result = TaskSchema.parse(task);
+    expect(result.id).toBe('task-1');
+    expect(result.domain).toBe('code');
+    expect(result.context.language).toBe('typescript');
+  });
+
+  it('should apply defaults for optional fields', () => {
+    const task = TaskSchema.parse({
+      id: 'task-2',
+      domain: 'reasoning',
+      description: 'Solve a puzzle',
+    });
+    expect(task.context).toEqual({});
+    expect(task.metadata).toEqual({});
+    expect(task.createdAt).toBeInstanceOf(Date);
+  });
+
+  it('should allow missing verification', () => {
+    const task = TaskSchema.parse({
+      id: 'task-3',
+      domain: 'arc',
+      description: 'Pattern matching task',
+    });
+    expect(task.verification).toBeUndefined();
+  });
+});
+
+describe('createTask', () => {
+  it('should create a task with required fields', () => {
+    const task = createTask({
+      domain: 'code',
+      description: 'Implement a sorting algorithm',
+    });
+    expect(task.id).toBeDefined();
+    expect(task.id.length).toBeGreaterThan(0);
+    expect(task.domain).toBe('code');
+    expect(task.description).toBe('Implement a sorting algorithm');
+  });
+
+  it('should create a task with custom id', () => {
+    const task = createTask({
+      id: 'my-custom-id',
+      domain: 'swe',
+      description: 'Fix a bug',
+    });
+    expect(task.id).toBe('my-custom-id');
+  });
+
+  it('should create a task with context', () => {
+    const task = createTask({
+      domain: 'code',
+      description: 'Write tests',
+      context: { framework: 'vitest', coverage: true },
+    });
+    expect(task.context.framework).toBe('vitest');
+    expect(task.context.coverage).toBe(true);
+  });
+
+  it('should create a task with verification', () => {
+    const task = createTask({
+      domain: 'reasoning',
+      description: 'Calculate 2+2',
+      verification: { type: 'exact_match', expected: 4 },
+    });
+    expect(task.verification?.type).toBe('exact_match');
+    expect(task.verification?.expected).toBe(4);
+  });
+
+  it('should create a task with metadata', () => {
+    const task = createTask({
+      domain: 'code',
+      description: 'Refactor code',
+      metadata: { author: 'test', source: 'manual' },
+    });
+    expect(task.metadata.author).toBe('test');
+    expect(task.metadata.source).toBe('manual');
+  });
+
+  it('should set createdAt to current time', () => {
+    const before = new Date();
+    const task = createTask({
+      domain: 'test',
+      description: 'Test task',
+    });
+    const after = new Date();
+    expect(task.createdAt.getTime()).toBeGreaterThanOrEqual(before.getTime());
+    expect(task.createdAt.getTime()).toBeLessThanOrEqual(after.getTime());
+  });
+});

package/tests/types/trajectory.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect } from 'vitest';
+import {
+  TrajectorySchema,
+  createTrajectory,
+  isSuccessful,
+  getKeySteps,
+  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';
+
+describe('Trajectory', () => {
+  const sampleTask = createTask({
+    id: 'task-1',
+    domain: 'code',
+    description: 'Write a hello world function',
+  });
+
+  const sampleSteps = [
+    createStep({
+      thought: 'I need to create a function',
+      action: 'write_code()',
+      observation: 'Function written',
+    }),
+    createStep({
+      action: 'run_tests()',
+      observation: 'Tests passed',
+    }),
+  ];
+
+  it('should validate a complete trajectory', () => {
+    const trajectory: Trajectory = {
+      id: 'traj-1',
+      task: sampleTask,
+      steps: sampleSteps,
+      outcome: successOutcome('function helloWorld() { return "hello"; }'),
+      agentId: 'claude-code',
+      timestamp: new Date(),
+      llmCalls: 5,
+      totalTokens: 1500,
+      wallTimeSeconds: 30,
+      metadata: { version: '1.0' },
+    };
+    const result = TrajectorySchema.parse(trajectory);
+    expect(result.id).toBe('traj-1');
+    expect(result.agentId).toBe('claude-code');
+    expect(result.llmCalls).toBe(5);
+    expect(result.totalTokens).toBe(1500);
+  });
+
+  it('should apply defaults for optional fields', () => {
+    const trajectory = TrajectorySchema.parse({
+      id: 'traj-2',
+      task: sampleTask,
+      steps: [],
+      outcome: { success: true },
+      agentId: 'test-agent',
+    });
+    expect(trajectory.llmCalls).toBe(0);
+    expect(trajectory.totalTokens).toBe(0);
+    expect(trajectory.wallTimeSeconds).toBe(0);
+    expect(trajectory.metadata).toEqual({});
+    expect(trajectory.timestamp).toBeInstanceOf(Date);
+  });
+
+  it('should allow empty steps array', () => {
+    const trajectory = TrajectorySchema.parse({
+      id: 'traj-3',
+      task: sampleTask,
+      steps: [],
+      outcome: failureOutcome('No steps taken'),
+      agentId: 'agent',
+    });
+    expect(trajectory.steps).toEqual([]);
+  });
+});
+
+describe('createTrajectory', () => {
+  const task = createTask({
+    domain: 'reasoning',
+    description: 'Solve a logic puzzle',
+  });
+
+  const steps = [
+    createStep({ action: 'analyze', observation: 'Found pattern' }),
+    createStep({ action: 'apply', observation: 'Applied rule' }),
+    createStep({ action: 'verify', observation: 'Correct' }),
+  ];
+
+  it('should create a trajectory with required fields', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('solved'),
+      agentId: 'reasoning-agent',
+    });
+    expect(trajectory.id).toBeDefined();
+    expect(trajectory.id.length).toBeGreaterThan(0);
+    expect(trajectory.task).toEqual(task);
+    expect(trajectory.steps).toHaveLength(3);
+    expect(trajectory.agentId).toBe('reasoning-agent');
+  });
+
+  it('should create a trajectory with custom id', () => {
+    const trajectory = createTrajectory({
+      id: 'custom-traj-id',
+      task,
+      steps: [],
+      outcome: failureOutcome('failed'),
+      agentId: 'agent',
+    });
+    expect(trajectory.id).toBe('custom-traj-id');
+  });
+
+  it('should create a trajectory with metrics', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome(42),
+      agentId: 'agent',
+      llmCalls: 10,
+      totalTokens: 5000,
+      wallTimeSeconds: 120,
+    });
+    expect(trajectory.llmCalls).toBe(10);
+    expect(trajectory.totalTokens).toBe(5000);
+    expect(trajectory.wallTimeSeconds).toBe(120);
+  });
+
+  it('should create a trajectory with metadata', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('done'),
+      agentId: 'agent',
+      metadata: { attempt: 2, model: 'gpt-4' },
+    });
+    expect(trajectory.metadata.attempt).toBe(2);
+    expect(trajectory.metadata.model).toBe('gpt-4');
+  });
+
+  it('should set timestamp to current time', () => {
+    const before = new Date();
+    const trajectory = createTrajectory({
+      task,
+      steps: [],
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+    const after = new Date();
+    expect(trajectory.timestamp.getTime()).toBeGreaterThanOrEqual(before.getTime());
+    expect(trajectory.timestamp.getTime()).toBeLessThanOrEqual(after.getTime());
+  });
+});
+
+describe('isSuccessful', () => {
+  const task = createTask({ domain: 'test', description: 'test' });
+
+  it('should return true for successful trajectory', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps: [],
+      outcome: successOutcome('done'),
+      agentId: 'agent',
+    });
+    expect(isSuccessful(trajectory)).toBe(true);
+  });
+
+  it('should return false for failed trajectory', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps: [],
+      outcome: failureOutcome('error'),
+      agentId: 'agent',
+    });
+    expect(isSuccessful(trajectory)).toBe(false);
+  });
+});
+
+describe('getKeySteps', () => {
+  const task = createTask({ domain: 'test', description: 'test' });
+
+  it('should return steps above threshold', () => {
+    const steps = [
+      { ...createStep({ action: 'a', observation: 'o' }), attributionScore: 0.1 },
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.3 },
+      { ...createStep({ action: 'c', observation: 'o' }), attributionScore: 0.8 },
+      { ...createStep({ action: 'd', observation: 'o' }), attributionScore: 0.15 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    const keySteps = getKeySteps(trajectory);
+    expect(keySteps).toHaveLength(3);
+    expect(keySteps[0].action).toBe('b');
+    expect(keySteps[1].action).toBe('c');
+    expect(keySteps[2].action).toBe('d');
+  });
+
+  it('should use custom threshold', () => {
+    const steps = [
+      { ...createStep({ action: 'a', observation: 'o' }), attributionScore: 0.4 },
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.6 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    expect(getKeySteps(trajectory, 0.5)).toHaveLength(1);
+    expect(getKeySteps(trajectory, 0.3)).toHaveLength(2);
+    expect(getKeySteps(trajectory, 0.7)).toHaveLength(0);
+  });
+
+  it('should handle steps without attribution scores', () => {
+    const steps = [
+      createStep({ action: 'a', observation: 'o' }),
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.5 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    const keySteps = getKeySteps(trajectory);
+    expect(keySteps).toHaveLength(1);
+    expect(keySteps[0].action).toBe('b');
+  });
+
+  it('should return empty array for trajectory with no key steps', () => {
+    const steps = [
+      { ...createStep({ action: 'a', observation: 'o' }), attributionScore: 0.05 },
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.1 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    expect(getKeySteps(trajectory)).toHaveLength(0);
+  });
+});

package/tests/utils/similarity.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from 'vitest';
+import {
+  cosineSimilarity,
+  jaccardSimilarity,
+  ngramSimilarity,
+  textSimilarity,
+  tokenize,
+  findTopK,
+} from '../../src/utils/similarity.js';
+
+describe('cosineSimilarity', () => {
+  it('should return 1 for identical vectors', () => {
+    expect(cosineSimilarity([1, 0, 0], [1, 0, 0])).toBeCloseTo(1);
+    expect(cosineSimilarity([0.5, 0.5], [0.5, 0.5])).toBeCloseTo(1);
+  });
+
+  it('should return 0 for orthogonal vectors', () => {
+    expect(cosineSimilarity([1, 0], [0, 1])).toBeCloseTo(0);
+    expect(cosineSimilarity([1, 0, 0], [0, 1, 0])).toBeCloseTo(0);
+  });
+
+  it('should return -1 for opposite vectors', () => {
+    expect(cosineSimilarity([1, 0], [-1, 0])).toBeCloseTo(-1);
+  });
+
+  it('should handle arbitrary vectors', () => {
+    const a = [1, 2, 3];
+    const b = [4, 5, 6];
+    // dot = 1*4 + 2*5 + 3*6 = 32
+    // normA = sqrt(14), normB = sqrt(77)
+    const expected = 32 / (Math.sqrt(14) * Math.sqrt(77));
+    expect(cosineSimilarity(a, b)).toBeCloseTo(expected);
+  });
+
+  it('should return 0 for zero vectors', () => {
+    expect(cosineSimilarity([0, 0, 0], [1, 2, 3])).toBe(0);
+    expect(cosineSimilarity([1, 2, 3], [0, 0, 0])).toBe(0);
+  });
+
+  it('should throw for vectors of different lengths', () => {
+    expect(() => cosineSimilarity([1, 2], [1, 2, 3])).toThrow();
+  });
+});
+
+describe('tokenize', () => {
+  it('should split text into lowercase tokens', () => {
+    expect(tokenize('Hello World')).toEqual(['hello', 'world']);
+  });
+
+  it('should remove punctuation', () => {
+    expect(tokenize('Hello, world!')).toEqual(['hello', 'world']);
+  });
+
+  it('should handle multiple spaces', () => {
+    expect(tokenize('a   b  c')).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should return empty array for empty string', () => {
+    expect(tokenize('')).toEqual([]);
+  });
+
+  it('should handle special characters', () => {
+    expect(tokenize("it's a test-case")).toEqual(['it', 's', 'a', 'test', 'case']);
+  });
+});
+
+describe('jaccardSimilarity', () => {
+  it('should return 1 for identical strings', () => {
+    expect(jaccardSimilarity('hello world', 'hello world')).toBe(1);
+  });
+
+  it('should return 0 for completely different strings', () => {
+    expect(jaccardSimilarity('abc', 'xyz')).toBe(0);
+  });
+
+  it('should handle partial overlap', () => {
+    // 'hello' appears in both
+    const sim = jaccardSimilarity('hello world', 'hello there');
+    expect(sim).toBeGreaterThan(0);
+    expect(sim).toBeLessThan(1);
+  });
+
+  it('should return 0 for empty strings', () => {
+    expect(jaccardSimilarity('', '')).toBe(0);
+    expect(jaccardSimilarity('hello', '')).toBe(0);
+  });
+
+  it('should be case insensitive', () => {
+    expect(jaccardSimilarity('HELLO', 'hello')).toBe(1);
+  });
+});
+
+describe('ngramSimilarity', () => {
+  it('should return 1 for identical strings', () => {
+    expect(ngramSimilarity('hello', 'hello')).toBe(1);
+  });
+
+  it('should return 0 for completely different strings', () => {
+    expect(ngramSimilarity('abc', 'xyz')).toBe(0);
+  });
+
+  it('should handle partial overlap', () => {
+    const sim = ngramSimilarity('hello', 'hella');
+    expect(sim).toBeGreaterThan(0);
+    expect(sim).toBeLessThan(1);
+  });
+
+  it('should use custom n-gram size', () => {
+    const sim2 = ngramSimilarity('hello', 'help', 2);
+    const sim3 = ngramSimilarity('hello', 'help', 3);
+    // Different n values give different results
+    expect(sim2).not.toBe(sim3);
+  });
+});
+
+describe('textSimilarity', () => {
+  it('should return 1 for identical text', () => {
+    expect(textSimilarity('hello world', 'hello world')).toBe(1);
+  });
+
+  it('should return 0 for completely different text', () => {
+    expect(textSimilarity('abc', 'xyz')).toBe(0);
+  });
+
+  it('should return intermediate values for partial matches', () => {
+    const sim = textSimilarity('fix the bug', 'debug the issue');
+    expect(sim).toBeGreaterThan(0);
+    expect(sim).toBeLessThan(1);
+  });
+});
+
+describe('findTopK', () => {
+  it('should find top-k items by string similarity', () => {
+    const items = [
+      { id: 1, text: 'hello world' },
+      { id: 2, text: 'hello there' },
+      { id: 3, text: 'goodbye world' },
+      { id: 4, text: 'completely different' },
+    ];
+
+    const results = findTopK('hello world', items, (item) => item.text, 2);
+    expect(results).toHaveLength(2);
+    expect(results[0].item.id).toBe(1); // Exact match
+    expect(results[0].score).toBe(1);
+  });
+
+  it('should find top-k items by vector similarity', () => {
+    const items = [
+      { id: 1, vec: [1, 0, 0] },
+      { id: 2, vec: [0.9, 0.1, 0] },
+      { id: 3, vec: [0, 1, 0] },
+      { id: 4, vec: [-1, 0, 0] },
+    ];
+
+    const results = findTopK([1, 0, 0], items, (item) => item.vec, 2);
+    expect(results).toHaveLength(2);
+    expect(results[0].item.id).toBe(1);
+    expect(results[1].item.id).toBe(2);
+  });
+
+  it('should handle items without vectors', () => {
+    const items = [
+      { id: 1, text: 'hello' },
+      { id: 2, text: undefined },
+      { id: 3, text: 'world' },
+    ];
+
+    const results = findTopK(
+      'hello',
+      items,
+      (item) => item.text,
+      3
+    );
+    expect(results).toHaveLength(3);
+    expect(results[2].score).toBe(0); // Item with undefined text
+  });
+
+  it('should return fewer items if k is larger than array', () => {
+    const items = [{ id: 1, text: 'hello' }];
+    const results = findTopK('hello', items, (item) => item.text, 10);
+    expect(results).toHaveLength(1);
+  });
+
+  it('should handle empty items array', () => {
+    const results = findTopK('hello', [], (item: { text: string }) => item.text, 5);
+    expect(results).toHaveLength(0);
+  });
+});