cognitive-core 0.0.2 → 0.1.2

package/tests/atlas-knowledge.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createAtlasWithAgents } from '../src/atlas.js';
+import type { Atlas } from '../src/atlas.js';
+import { createTask } from '../src/types/task.js';
+import { createMockBackend, type MockBackend } from '../src/runtime/backends/mock.js';
+import { createObservation, createEntityNote, createDomainSummary } from '../src/types/knowledge.js';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('Atlas: Knowledge Surfacing', () => {
+  let tempDir: string;
+  let atlas: Atlas;
+  let mockBackend: MockBackend;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'atlas-knowledge-test-'));
+    mockBackend = createMockBackend({
+      success: true,
+      result: 'Task completed successfully',
+      durationMs: 50,
+      toolCalls: [],
+    });
+
+    atlas = createAtlasWithAgents([mockBackend], {
+      storage: { baseDir: tempDir },
+      knowledgeBank: {
+        enabled: true,
+        surfacing: {
+          includeDomainSummaries: true,
+          includeEntityNotes: true,
+          maxNotesPerTask: 5,
+          maxTokensForKnowledge: 2000,
+          includeEvidence: false,
+          includeLinks: false,
+        },
+      },
+      execution: {
+        defaultAgentType: 'mock',
+        maxExecutionTime: 60,
+        captureToolCalls: true,
+      },
+    });
+
+    await atlas.init();
+  });
+
+  afterEach(async () => {
+    await atlas.close();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('surfaces knowledge notes in solve result', async () => {
+    const memory = atlas.getMemory();
+    const kb = memory.knowledgeBank!;
+
+    // Seed a domain summary + observation
+    await kb.addObservation(
+      createDomainSummary({
+        domainName: 'database',
+        body: 'Overview of database patterns and ORM usage.',
+        source: { origin: 'extracted' },
+      })
+    );
+    await kb.addObservation(
+      createObservation({
+        id: 'k-prisma-tip',
+        title: 'Prisma migration tip',
+        body: 'Always run db push before migrate dev when schema has drifted',
+        domain: ['database'],
+        entities: ['prisma'],
+        tags: [],
+        source: { origin: 'extracted' },
+      })
+    );
+
+    const task = createTask({
+      domain: 'database',
+      description: 'Fix the database migration drift issue',
+    });
+
+    const result = await atlas.solve(task);
+
+    expect(result.surfacedKnowledge).toBeDefined();
+    expect(result.surfacedKnowledge!.length).toBeGreaterThanOrEqual(1);
+
+    // Domain summary should be surfaced
+    const hasDomain = result.surfacedKnowledge!.some(
+      (k) => k.note.frontmatter.type === 'domain-summary'
+    );
+    expect(hasDomain).toBe(true);
+  });
+
+  it('includes formatted knowledge context in agent prompt', async () => {
+    const memory = atlas.getMemory();
+    const kb = memory.knowledgeBank!;
+
+    await kb.addObservation(
+      createObservation({
+        id: 'k-auth-tip',
+        title: 'Auth pattern',
+        body: 'Always validate JWT tokens on every request to avoid session hijacking',
+        domain: ['auth'],
+        entities: ['jwt'],
+        tags: [],
+        confidence: 0.8,
+        source: { origin: 'extracted' },
+      })
+    );
+
+    const task = createTask({
+      domain: 'auth',
+      description: 'Implement JWT token validation middleware',
+    });
+
+    const result = await atlas.solve(task);
+
+    expect(result.surfacedKnowledge).toBeDefined();
+    expect(result.surfacedKnowledge!.length).toBeGreaterThanOrEqual(1);
+
+    // Verify the formatted knowledge would contain the heading
+    const formatted = kb.formatKnowledgeForPrompt(result.surfacedKnowledge!);
+    expect(formatted).toContain('## Relevant Knowledge');
+  });
+
+  it('returns no surfaced knowledge for empty bank', async () => {
+    const task = createTask({
+      domain: 'code',
+      description: 'Implement a new feature',
+    });
+
+    const result = await atlas.solve(task);
+
+    expect(result.surfacedKnowledge).toBeDefined();
+    expect(result.surfacedKnowledge!.length).toBe(0);
+  });
+
+  it('surfaces entity notes when task mentions entity', async () => {
+    const memory = atlas.getMemory();
+    const kb = memory.knowledgeBank!;
+
+    await kb.addObservation(
+      createEntityNote({
+        entityName: 'Redis',
+        body: 'Redis is an in-memory key-value store used for caching.',
+        domain: ['infrastructure'],
+        source: { origin: 'extracted' },
+      })
+    );
+
+    const task = createTask({
+      domain: 'infrastructure',
+      description: 'Set up redis caching layer for the API',
+    });
+
+    const result = await atlas.solve(task);
+
+    expect(result.surfacedKnowledge).toBeDefined();
+    const entityMatch = result.surfacedKnowledge!.find(
+      (k) => k.matchType === 'entity'
+    );
+    expect(entityMatch).toBeDefined();
+    expect(entityMatch!.note.frontmatter.type).toBe('entity');
+  });
+});

package/tests/embeddings/bm25.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { BM25Index, createBM25Index } from '../../src/embeddings/bm25.js';
+
+describe('BM25Index', () => {
+  let index: BM25Index;
+
+  beforeEach(() => {
+    index = createBM25Index();
+  });
+
+  describe('basic operations', () => {
+    it('should add and retrieve documents', () => {
+      index.add('doc1', 'hello world', 'experience');
+      expect(index.has('doc1')).toBe(true);
+      expect(index.size).toBe(1);
+    });
+
+    it('should remove documents', () => {
+      index.add('doc1', 'hello world', 'experience');
+      expect(index.remove('doc1')).toBe(true);
+      expect(index.has('doc1')).toBe(false);
+      expect(index.size).toBe(0);
+    });
+
+    it('should handle non-existent document removal', () => {
+      expect(index.remove('non-existent')).toBe(false);
+    });
+  });
+
+  describe('search', () => {
+    beforeEach(() => {
+      index.add('doc1', 'machine learning algorithms for classification', 'experience');
+      index.add('doc2', 'deep learning neural networks', 'strategy');
+      index.add('doc3', 'database query optimization techniques', 'concept');
+      index.add('doc4', 'machine learning for natural language processing', 'skill');
+    });
+
+    it('should find relevant documents', () => {
+      const results = index.search('machine learning');
+      expect(results.length).toBeGreaterThan(0);
+
+      // Machine learning docs should be ranked higher
+      const ids = results.map(r => r.id);
+      expect(ids).toContain('doc1');
+      expect(ids).toContain('doc4');
+    });
+
+    it('should filter by type', () => {
+      const results = index.search('learning', { type: 'experience' });
+      expect(results.every(r => r.content.includes('machine'))).toBe(true);
+    });
+
+    it('should respect k limit', () => {
+      const results = index.search('learning', { k: 2 });
+      expect(results.length).toBeLessThanOrEqual(2);
+    });
+
+    it('should return scores in descending order', () => {
+      const results = index.search('machine learning');
+      for (let i = 1; i < results.length; i++) {
+        expect(results[i - 1].score).toBeGreaterThanOrEqual(results[i].score);
+      }
+    });
+
+    it('should return normalized scores between 0 and 1', () => {
+      const results = index.search('machine learning');
+      for (const result of results) {
+        expect(result.score).toBeGreaterThanOrEqual(0);
+        expect(result.score).toBeLessThanOrEqual(1);
+      }
+    });
+  });
+
+  describe('serialization', () => {
+    it('should serialize and deserialize correctly', () => {
+      index.add('doc1', 'hello world', 'experience');
+      index.add('doc2', 'goodbye world', 'strategy');
+
+      const json = index.toJSON();
+      const restored = BM25Index.fromJSON(json);
+
+      expect(restored.size).toBe(2);
+      expect(restored.has('doc1')).toBe(true);
+      expect(restored.has('doc2')).toBe(true);
+
+      // Search should work after restore
+      const results = restored.search('world');
+      expect(results.length).toBe(2);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty index', () => {
+      const results = index.search('anything');
+      expect(results).toEqual([]);
+    });
+
+    it('should handle empty query', () => {
+      index.add('doc1', 'hello world', 'experience');
+      const results = index.search('');
+      expect(results.length).toBe(0);
+    });
+
+    it('should handle special characters', () => {
+      index.add('doc1', 'hello! @world# $test%', 'experience');
+      const results = index.search('hello world test');
+      expect(results.length).toBe(1);
+    });
+
+    it('should filter stop words', () => {
+      index.add('doc1', 'the quick brown fox', 'experience');
+      index.add('doc2', 'a lazy brown dog', 'experience');
+
+      // "the" and "a" are stop words, so searching for them shouldn't find anything
+      // but "brown" should match both
+      const results = index.search('brown');
+      expect(results.length).toBe(2);
+    });
+  });
+
+  describe('BM25 parameters', () => {
+    it('should accept custom k1 and b parameters', () => {
+      const customIndex = createBM25Index({ k1: 2.0, b: 0.5 });
+      customIndex.add('doc1', 'test document', 'experience');
+
+      const results = customIndex.search('test');
+      expect(results.length).toBe(1);
+    });
+  });
+});

package/tests/embeddings/manager.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { EmbeddingManager, createEmbeddingManager } from '../../src/embeddings/manager.js';
+import type { EmbeddingProvider } from '../../src/embeddings/provider.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Mock embedding provider for testing
+class MockEmbeddingProvider implements EmbeddingProvider {
+  readonly name = 'mock';
+  readonly dimension = 3;
+  private callCount = 0;
+
+  async embed(text: string): Promise<number[]> {
+    this.callCount++;
+    // Simple hash-based embedding for deterministic testing
+    const hash = text.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0);
+    return [
+      Math.sin(hash * 0.1),
+      Math.cos(hash * 0.2),
+      Math.sin(hash * 0.3),
+    ];
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    return Promise.all(texts.map(t => this.embed(t)));
+  }
+
+  getCallCount(): number {
+    return this.callCount;
+  }
+}
+
+describe('EmbeddingManager', () => {
+  const testDbPath = '/tmp/test-embeddings.db';
+
+  afterEach(() => {
+    // Clean up test database
+    try {
+      fs.unlinkSync(testDbPath);
+    } catch {
+      // Ignore if file doesn't exist
+    }
+  });
+
+  describe('BM25-only mode (no provider)', () => {
+    let manager: EmbeddingManager;
+
+    beforeEach(() => {
+      manager = createEmbeddingManager({});
+    });
+
+    afterEach(() => {
+      manager.close();
+    });
+
+    it('should work without embedding provider', async () => {
+      await manager.store('id1', 'machine learning algorithms', 'experience');
+      await manager.store('id2', 'database optimization', 'strategy');
+
+      const results = await manager.search('machine learning');
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].id).toBe('id1');
+    });
+
+    it('should report no vector search available', () => {
+      expect(manager.hasVectorSearch).toBe(false);
+      expect(manager.dimension).toBeNull();
+    });
+
+    it('should return undefined embeddings when storing', async () => {
+      const embedding = await manager.store('id1', 'test content', 'experience');
+      expect(embedding).toBeUndefined();
+    });
+
+    it('should return null when trying to embed directly', async () => {
+      const embedding = await manager.embed('test');
+      expect(embedding).toBeNull();
+    });
+  });
+
+  describe('with mock embedding provider (no vector store)', () => {
+    let manager: EmbeddingManager;
+    let provider: MockEmbeddingProvider;
+
+    beforeEach(() => {
+      provider = new MockEmbeddingProvider();
+      // No vectorStorePath, so vector store won't be created
+      manager = createEmbeddingManager({
+        provider,
+      });
+    });
+
+    afterEach(() => {
+      manager.close();
+    });
+
+    it('should fall back to BM25 without vector store path', async () => {
+      await manager.store('id1', 'test content', 'experience');
+
+      // Should use BM25 for search since no vector store
+      const results = await manager.search('test');
+      expect(results.length).toBe(1);
+    });
+  });
+
+  describe('statistics', () => {
+    let manager: EmbeddingManager;
+
+    beforeEach(() => {
+      manager = createEmbeddingManager({});
+    });
+
+    afterEach(() => {
+      manager.close();
+    });
+
+    it('should report correct stats', async () => {
+      await manager.store('id1', 'content 1', 'experience');
+      await manager.store('id2', 'content 2', 'strategy');
+
+      const stats = manager.getStats();
+      expect(stats.bm25Count).toBe(2);
+      expect(stats.hasVectorSearch).toBe(false);
+      expect(stats.providerName).toBeNull();
+    });
+  });
+
+  describe('batch operations', () => {
+    let manager: EmbeddingManager;
+
+    beforeEach(() => {
+      manager = createEmbeddingManager({});
+    });
+
+    afterEach(() => {
+      manager.close();
+    });
+
+    it('should store batch items', async () => {
+      const items = [
+        { id: 'id1', content: 'content 1', type: 'experience' as const },
+        { id: 'id2', content: 'content 2', type: 'strategy' as const },
+        { id: 'id3', content: 'content 3', type: 'concept' as const },
+      ];
+
+      const results = await manager.storeBatch(items);
+
+      expect(results.size).toBe(3);
+      expect(manager.has('id1')).toBe(true);
+      expect(manager.has('id2')).toBe(true);
+      expect(manager.has('id3')).toBe(true);
+    });
+  });
+
+  describe('remove operation', () => {
+    let manager: EmbeddingManager;
+
+    beforeEach(() => {
+      manager = createEmbeddingManager({});
+    });
+
+    afterEach(() => {
+      manager.close();
+    });
+
+    it('should remove items from index', async () => {
+      await manager.store('id1', 'test content', 'experience');
+      expect(manager.has('id1')).toBe(true);
+
+      manager.remove('id1');
+      expect(manager.has('id1')).toBe(false);
+    });
+  });
+
+  describe('search with options', () => {
+    let manager: EmbeddingManager;
+
+    beforeEach(async () => {
+      manager = createEmbeddingManager({});
+      await manager.store('exp1', 'machine learning experience', 'experience');
+      await manager.store('str1', 'machine learning strategy', 'strategy');
+      await manager.store('con1', 'deep learning concept', 'concept');
+      await manager.store('skl1', 'learning skill', 'skill');
+    });
+
+    afterEach(() => {
+      manager.close();
+    });
+
+    it('should filter by type', async () => {
+      const results = await manager.search('learning', { type: 'experience' });
+      expect(results.every(r => r.id.startsWith('exp'))).toBe(true);
+    });
+
+    it('should limit results with k', async () => {
+      const results = await manager.search('learning', { k: 2 });
+      expect(results.length).toBeLessThanOrEqual(2);
+    });
+
+    it('should apply threshold', async () => {
+      const results = await manager.search('learning', { threshold: 0.5 });
+      expect(results.every(r => r.score >= 0.5)).toBe(true);
+    });
+  });
+});