holosphere 1.1.20 → 2.0.0-alpha1

package/tests/unit/ai/embeddings.test.js

@@ -0,0 +1,384 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { Embeddings } from '../../../src/ai/embeddings.js';
+
+describe('Unit: Embeddings', () => {
+  let embeddings;
+  let mockOpenAI;
+  let mockHolosphere;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mockOpenAI = {
+      embeddings: {
+        create: vi.fn()
+      }
+    };
+
+    mockHolosphere = {
+      put: vi.fn().mockResolvedValue({ success: true }),
+      getAll: vi.fn().mockResolvedValue([])
+    };
+
+    embeddings = new Embeddings(mockOpenAI, mockHolosphere);
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with OpenAI client', () => {
+      const emb = new Embeddings(mockOpenAI);
+      expect(emb.openai).toBe(mockOpenAI);
+      expect(emb.model).toBe('text-embedding-3-small');
+      expect(emb.dimensions).toBe(1536);
+    });
+
+    it('should accept optional HoloSphere instance', () => {
+      const emb = new Embeddings(mockOpenAI, mockHolosphere);
+      expect(emb.holosphere).toBe(mockHolosphere);
+    });
+
+    it('should work without HoloSphere instance', () => {
+      const emb = new Embeddings(mockOpenAI);
+      expect(emb.holosphere).toBeNull();
+    });
+  });
+
+  describe('setHoloSphere', () => {
+    it('should set HoloSphere instance', () => {
+      const emb = new Embeddings(mockOpenAI);
+      emb.setHoloSphere(mockHolosphere);
+      expect(emb.holosphere).toBe(mockHolosphere);
+    });
+  });
+
+  describe('embed', () => {
+    it('should generate embedding for text', async () => {
+      const mockEmbedding = Array(1536).fill(0).map((_, i) => i / 1536);
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: mockEmbedding }]
+      });
+
+      const result = await embeddings.embed('Hello world');
+
+      expect(mockOpenAI.embeddings.create).toHaveBeenCalledWith({
+        model: 'text-embedding-3-small',
+        input: 'Hello world'
+      });
+      expect(result).toEqual(mockEmbedding);
+      expect(result).toHaveLength(1536);
+    });
+
+    it('should throw error on API failure', async () => {
+      mockOpenAI.embeddings.create.mockRejectedValue(new Error('API Error'));
+
+      await expect(embeddings.embed('Test'))
+        .rejects.toThrow('Embedding generation failed: API Error');
+    });
+  });
+
+  describe('embedBatch', () => {
+    it('should generate embeddings for multiple texts', async () => {
+      const mockEmbeddings = [
+        { embedding: Array(1536).fill(0.1) },
+        { embedding: Array(1536).fill(0.2) },
+        { embedding: Array(1536).fill(0.3) }
+      ];
+      mockOpenAI.embeddings.create.mockResolvedValue({ data: mockEmbeddings });
+
+      const result = await embeddings.embedBatch(['text1', 'text2', 'text3']);
+
+      expect(mockOpenAI.embeddings.create).toHaveBeenCalledWith({
+        model: 'text-embedding-3-small',
+        input: ['text1', 'text2', 'text3']
+      });
+      expect(result).toHaveLength(3);
+      expect(result[0]).toEqual(Array(1536).fill(0.1));
+    });
+
+    it('should throw error on batch failure', async () => {
+      mockOpenAI.embeddings.create.mockRejectedValue(new Error('Batch failed'));
+
+      await expect(embeddings.embedBatch(['a', 'b']))
+        .rejects.toThrow('Batch embedding failed: Batch failed');
+    });
+  });
+
+  describe('cosineSimilarity', () => {
+    it('should calculate cosine similarity between vectors', () => {
+      const vec1 = [1, 0, 0];
+      const vec2 = [1, 0, 0];
+
+      const similarity = embeddings.cosineSimilarity(vec1, vec2);
+      expect(similarity).toBeCloseTo(1.0, 5);
+    });
+
+    it('should return 0 for orthogonal vectors', () => {
+      const vec1 = [1, 0, 0];
+      const vec2 = [0, 1, 0];
+
+      const similarity = embeddings.cosineSimilarity(vec1, vec2);
+      expect(similarity).toBeCloseTo(0, 5);
+    });
+
+    it('should return -1 for opposite vectors', () => {
+      const vec1 = [1, 0, 0];
+      const vec2 = [-1, 0, 0];
+
+      const similarity = embeddings.cosineSimilarity(vec1, vec2);
+      expect(similarity).toBeCloseTo(-1.0, 5);
+    });
+
+    it('should throw error for vectors of different lengths', () => {
+      const vec1 = [1, 2, 3];
+      const vec2 = [1, 2];
+
+      expect(() => embeddings.cosineSimilarity(vec1, vec2))
+        .toThrow('Vectors must have same length');
+    });
+
+    it('should handle normalized vectors correctly', () => {
+      const vec1 = [0.6, 0.8, 0];
+      const vec2 = [0.6, 0.8, 0];
+
+      const similarity = embeddings.cosineSimilarity(vec1, vec2);
+      expect(similarity).toBeCloseTo(1.0, 5);
+    });
+  });
+
+  describe('storeWithEmbedding', () => {
+    it('should store item with generated embedding', async () => {
+      const mockEmbedding = Array(1536).fill(0.5);
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: mockEmbedding }]
+      });
+
+      const item = { content: 'Test content', title: 'Test' };
+      const result = await embeddings.storeWithEmbedding('holon1', 'lens1', item);
+
+      expect(result._embedding).toEqual(mockEmbedding);
+      expect(result._embeddedField).toBe('auto');
+      expect(result._embeddedAt).toBeDefined();
+      expect(mockHolosphere.put).toHaveBeenCalledWith('holon1', 'lens1', expect.objectContaining({
+        content: 'Test content',
+        _embedding: mockEmbedding
+      }));
+    });
+
+    it('should use specified text field for embedding', async () => {
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: Array(1536).fill(0) }]
+      });
+
+      const item = { title: 'Title', description: 'Description text' };
+      await embeddings.storeWithEmbedding('holon1', 'lens1', item, 'description');
+
+      expect(mockOpenAI.embeddings.create).toHaveBeenCalledWith({
+        model: 'text-embedding-3-small',
+        input: 'Description text'
+      });
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const emb = new Embeddings(mockOpenAI);
+
+      await expect(emb.storeWithEmbedding('holon', 'lens', { text: 'test' }))
+        .rejects.toThrow('HoloSphere instance required for storage');
+    });
+
+    it('should throw error if no text found to embed', async () => {
+      const item = { id: 123, number: 456 };
+
+      await expect(embeddings.storeWithEmbedding('holon', 'lens', item, 'missing'))
+        .rejects.toThrow('No text found to embed');
+    });
+
+    it('should fall back to JSON stringify for objects without text fields', async () => {
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: Array(1536).fill(0) }]
+      });
+
+      const item = { id: 123, data: [1, 2, 3] };
+      await embeddings.storeWithEmbedding('holon', 'lens', item);
+
+      expect(mockOpenAI.embeddings.create).toHaveBeenCalledWith({
+        model: 'text-embedding-3-small',
+        input: JSON.stringify(item)
+      });
+    });
+  });
+
+  describe('semanticSearch', () => {
+    it('should search for similar items using embeddings', async () => {
+      const queryEmbedding = Array(1536).fill(0.5);
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: queryEmbedding }]
+      });
+
+      const storedItems = [
+        { id: 1, text: 'Similar item', _embedding: Array(1536).fill(0.5) },
+        { id: 2, text: 'Less similar', _embedding: Array(1536).fill(0.1) },
+        { id: 3, text: 'No embedding' }
+      ];
+      mockHolosphere.getAll.mockResolvedValue(storedItems);
+
+      const results = await embeddings.semanticSearch('query', 'holon1', 'lens1');
+
+      expect(results).toHaveLength(2); // Only items with embeddings
+      expect(results[0].similarity).toBeGreaterThan(results[1].similarity);
+      expect(results[0].item._embedding).toBeUndefined(); // Embedding not returned
+    });
+
+    it('should respect threshold option', async () => {
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: Array(1536).fill(1) }]
+      });
+
+      mockHolosphere.getAll.mockResolvedValue([
+        { id: 1, _embedding: Array(1536).fill(0.9) },  // High similarity
+        { id: 2, _embedding: Array(1536).fill(0.1) }   // Low similarity
+      ]);
+
+      const results = await embeddings.semanticSearch('query', 'holon', 'lens', { threshold: 0.8 });
+
+      expect(results.length).toBeLessThanOrEqual(2);
+      results.forEach(r => expect(r.similarity).toBeGreaterThanOrEqual(0.8));
+    });
+
+    it('should respect limit option', async () => {
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: Array(1536).fill(0.5) }]
+      });
+
+      const manyItems = Array(20).fill(null).map((_, i) => ({
+        id: i,
+        _embedding: Array(1536).fill(0.5)
+      }));
+      mockHolosphere.getAll.mockResolvedValue(manyItems);
+
+      const results = await embeddings.semanticSearch('query', 'holon', 'lens', { limit: 5 });
+
+      expect(results).toHaveLength(5);
+    });
+
+    it('should throw error if HoloSphere not available', async () => {
+      const emb = new Embeddings(mockOpenAI);
+
+      await expect(emb.semanticSearch('query', 'holon', 'lens'))
+        .rejects.toThrow('HoloSphere instance required for search');
+    });
+  });
+
+  describe('findSimilar', () => {
+    it('should find items similar to given item', async () => {
+      mockOpenAI.embeddings.create.mockResolvedValue({
+        data: [{ embedding: Array(1536).fill(0.5) }]
+      });
+
+      mockHolosphere.getAll.mockResolvedValue([
+        { id: 1, _embedding: Array(1536).fill(0.5) }
+      ]);
+
+      const item = { content: 'Test item' };
+      const results = await embeddings.findSimilar(item, 'holon', 'lens');
+
+      expect(mockOpenAI.embeddings.create).toHaveBeenCalledWith({
+        model: 'text-embedding-3-small',
+        input: 'Test item'
+      });
+      expect(results).toBeDefined();
+    });
+  });
+
+  describe('cluster', () => {
+    it('should cluster items by semantic similarity', async () => {
+      const items = [
+        { id: 1, text: 'Item 1' },
+        { id: 2, text: 'Item 2' },
+        { id: 3, text: 'Item 3' }
+      ];
+
+      // Mock embeddings for each item
+      mockOpenAI.embeddings.create
+        .mockResolvedValueOnce({ data: [{ embedding: Array(1536).fill(0.1) }] })
+        .mockResolvedValueOnce({ data: [{ embedding: Array(1536).fill(0.5) }] })
+        .mockResolvedValueOnce({ data: [{ embedding: Array(1536).fill(0.9) }] });
+
+      const clusters = await embeddings.cluster(items, 2);
+
+      expect(Array.isArray(clusters)).toBe(true);
+      expect(clusters.length).toBeLessThanOrEqual(2);
+      // Embeddings should not be included in output
+      clusters.forEach(cluster => {
+        cluster.forEach(item => {
+          expect(item._embedding).toBeUndefined();
+        });
+      });
+    });
+
+    it('should use existing embeddings if available', async () => {
+      const items = [
+        { id: 1, _embedding: Array(1536).fill(0.1) },
+        { id: 2, _embedding: Array(1536).fill(0.2) }
+      ];
+
+      const clusters = await embeddings.cluster(items, 2);
+
+      expect(mockOpenAI.embeddings.create).not.toHaveBeenCalled();
+      expect(clusters).toBeDefined();
+    });
+
+    it('should return individual items as clusters when fewer items than k', async () => {
+      const items = [
+        { id: 1, _embedding: Array(1536).fill(0.1) },
+        { id: 2, _embedding: Array(1536).fill(0.2) }
+      ];
+
+      const clusters = await embeddings.cluster(items, 5);
+
+      expect(clusters).toHaveLength(2);
+      expect(clusters[0]).toHaveLength(1);
+      expect(clusters[1]).toHaveLength(1);
+    });
+  });
+
+  describe('_kMeans', () => {
+    it('should perform k-means clustering', () => {
+      // Use consistent dimensions (1536 is the default)
+      const dim = 1536;
+      const items = [
+        { id: 1, _embedding: Array(dim).fill(0).map((_, i) => i < dim/2 ? 0.9 : 0.1) },
+        { id: 2, _embedding: Array(dim).fill(0).map((_, i) => i < dim/2 ? 0.85 : 0.15) },
+        { id: 3, _embedding: Array(dim).fill(0).map((_, i) => i < dim/2 ? 0.1 : 0.9) },
+        { id: 4, _embedding: Array(dim).fill(0).map((_, i) => i < dim/2 ? 0.15 : 0.85) }
+      ];
+
+      const clusters = embeddings._kMeans(items, 2);
+
+      expect(clusters).toHaveLength(2);
+      // Each cluster should have 2 items (the similar pairs)
+    });
+
+    it('should handle items less than k', () => {
+      const dim = 1536;
+      const items = [
+        { id: 1, _embedding: Array(dim).fill(0.5) }
+      ];
+
+      const clusters = embeddings._kMeans(items, 3);
+
+      expect(clusters).toHaveLength(1);
+    });
+
+    it('should converge within max iterations', () => {
+      const dim = 1536;
+      const items = Array(10).fill(null).map((_, i) => ({
+        id: i,
+        _embedding: Array(dim).fill(0).map(() => Math.random())
+      }));
+
+      const clusters = embeddings._kMeans(items, 3, 10);
+
+      expect(clusters.length).toBeGreaterThan(0);
+      expect(clusters.length).toBeLessThanOrEqual(3);
+    });
+  });
+});