@mastra/chroma 0.1.5 → 0.1.6-alpha.1

package/.turbo/turbo-build.log

@@ -1,18 +1,18 @@
 
-> @mastra/chroma@0.1.5-alpha.2 build /home/runner/work/mastra/mastra/stores/chroma
+> @mastra/chroma@0.1.6-alpha.1 build /home/runner/work/mastra/mastra/stores/chroma
 > tsup src/index.ts --format esm --experimental-dts --clean --treeshake
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.3.6
 TSC Build start
-TSC ⚡️ Build success in 7860ms
+TSC ⚡️ Build success in 6980ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.7.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/chroma/dist/_tsup-dts-rollup.d.ts
-DTS ⚡️ Build success in 6074ms
+DTS ⚡️ Build success in 6006ms
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 6.49 KB
-ESM ⚡️ Build success in 438ms
+ESM dist/index.js 7.03 KB
+ESM ⚡️ Build success in 410ms

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @mastra/chroma
 
+## 0.1.6-alpha.1
+
+### Patch Changes
+
+- 5f28f44: Updated Chroma Vector to allow for document storage
+- Updated dependencies [0d185b1]
+- Updated dependencies [ed55f1d]
+- Updated dependencies [8d13b14]
+- Updated dependencies [3ee4831]
+- Updated dependencies [108793c]
+- Updated dependencies [5f28f44]
+  - @mastra/core@0.4.3-alpha.1
+
+## 0.1.6-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [06aa827]
+  - @mastra/core@0.4.3-alpha.0
+
 ## 0.1.5
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @mastra/chroma
 
-Vector store implementation for ChromaDB using the official chromadb client with added dimension validation and collection management.
+Vector store implementation for ChromaDB using the official chromadb client with added dimension validation, collection management, and document storage capabilities.
 
 ## Installation
 
@@ -24,18 +24,26 @@ const vectorStore = new ChromaVector({
 // Create a new collection
 await vectorStore.createIndex('my-collection', 1536, 'cosine');
 
-// Add vectors
+// Add vectors with documents
 const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
 const metadata = [{ text: 'doc1' }, { text: 'doc2' }];
-const ids = await vectorStore.upsert('my-collection', vectors, metadata);
+const documents = ['full text 1', 'full text 2'];
+const ids = await vectorStore.upsert(
+  'my-collection',
+  vectors,
+  metadata,
+  undefined, // auto-generate IDs
+  documents  // store original text
+);
 
-// Query vectors
+// Query vectors with document filtering
 const results = await vectorStore.query(
   'my-collection',
   [0.1, 0.2, ...],
   10, // topK
-  { text: { $eq: 'doc1' } }, // optional filter
-  false // includeVector
+  { text: { $eq: 'doc1' } }, // metadata filter
+  false, // includeVector
+  { $contains: 'specific text' } // document content filter
 );
 ```
 
@@ -54,6 +62,8 @@ Optional:
 ## Features
 
 - Vector similarity search with cosine, euclidean, and dot product metrics
+- Document storage and retrieval
+- Document content filtering
 - Strict vector dimension validation
 - Collection-based organization
 - Metadata filtering support
@@ -65,8 +75,8 @@ Optional:
 ## Methods
 
 - `createIndex(indexName, dimension, metric?)`: Create a new collection
-- `upsert(indexName, vectors, metadata?, ids?)`: Add or update vectors
-- `query(indexName, queryVector, topK?, filter?, includeVector?)`: Search for similar vectors
+- `upsert(indexName, vectors, metadata?, ids?, documents?)`: Add or update vectors with optional document storage
+- `query(indexName, queryVector, topK?, filter?, includeVector?, documentFilter?)`: Search for similar vectors with optional document filtering
 - `listIndexes()`: List all collections
 - `describeIndex(indexName)`: Get collection statistics
 - `deleteIndex(indexName)`: Delete a collection
@@ -78,6 +88,7 @@ Query results include:
 - `id`: Vector ID
 - `score`: Distance/similarity score
 - `metadata`: Associated metadata
+- `document`: Original document text (if stored)
 - `vector`: Original vector (if includeVector is true)
 
 ## Related Links

package/dist/_tsup-dts-rollup.d.ts

@@ -1,9 +1,9 @@
 import { BaseFilterTranslator } from '@mastra/core/filter';
-import { Filter } from '@mastra/core/filter';
-import { IndexStats } from '@mastra/core/vector';
+import type { Filter } from '@mastra/core/filter';
+import type { IndexStats } from '@mastra/core/vector';
 import { MastraVector } from '@mastra/core/vector';
-import { OperatorSupport } from '@mastra/core/filter';
-import { QueryResult } from '@mastra/core/vector';
+import type { OperatorSupport } from '@mastra/core/filter';
+import type { QueryResult } from '@mastra/core/vector';
 
 /**
  * Translator for Chroma filter queries.
@@ -27,12 +27,13 @@ declare class ChromaVector extends MastraVector {
             credentials: string;
         };
     });
-    private getCollection;
+    getCollection(indexName: string, throwIfNotExists?: boolean): Promise<any>;
     private validateVectorDimensions;
-    upsert(indexName: string, vectors: number[][], metadata?: Record<string, any>[], ids?: string[]): Promise<string[]>;
+    upsert(indexName: string, vectors: number[][], metadata?: Record<string, any>[], ids?: string[], documents?: string[]): Promise<string[]>;
+    private HnswSpaceMap;
     createIndex(indexName: string, dimension: number, metric?: 'cosine' | 'euclidean' | 'dotproduct'): Promise<void>;
     transformFilter(filter?: Filter): Filter | undefined;
-    query(indexName: string, queryVector: number[], topK?: number, filter?: Filter, includeVector?: boolean): Promise<QueryResult[]>;
+    query(indexName: string, queryVector: number[], topK?: number, filter?: Filter, includeVector?: boolean, documentFilter?: Filter): Promise<QueryResult[]>;
     listIndexes(): Promise<string[]>;
     describeIndex(indexName: string): Promise<IndexStats>;
     deleteIndex(indexName: string): Promise<void>;
@@ -40,4 +41,11 @@ declare class ChromaVector extends MastraVector {
 export { ChromaVector }
 export { ChromaVector as ChromaVector_alias_1 }
 
+declare interface DocumentMetadata {
+    content?: string;
+    metadata?: Record<string, any>;
+}
+export { DocumentMetadata }
+export { DocumentMetadata as DocumentMetadata_alias_1 }
+
 export { }

package/dist/index.d.ts

@@ -1 +1,2 @@
+export { DocumentMetadata } from './_tsup-dts-rollup.js';
 export { ChromaVector } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -1,6 +1,6 @@
-import { BaseFilterTranslator } from '@mastra/core/filter';
 import { MastraVector } from '@mastra/core/vector';
 import { ChromaClient } from 'chromadb';
+import { BaseFilterTranslator } from '@mastra/core/filter';
 
 // src/vector/index.ts
 var ChromaFilterTranslator = class extends BaseFilterTranslator {
@@ -105,7 +105,7 @@ var ChromaVector = class extends MastraVector {
     try {
       const collection = await this.client.getCollection({ name: indexName, embeddingFunction: void 0 });
       this.collections.set(indexName, collection);
-    } catch (error) {
+    } catch {
       if (throwIfNotExists) {
         throw new Error(`Index ${indexName} does not exist`);
       }
@@ -122,7 +122,7 @@ var ChromaVector = class extends MastraVector {
       }
     }
   }
-  async upsert(indexName, vectors, metadata, ids) {
+  async upsert(indexName, vectors, metadata, ids, documents) {
     const collection = await this.getCollection(indexName);
     const stats = await this.describeIndex(indexName);
     this.validateVectorDimensions(vectors, stats.dimension);
@@ -131,19 +131,31 @@ var ChromaVector = class extends MastraVector {
     await collection.upsert({
       ids: generatedIds,
       embeddings: vectors,
-      metadatas: normalizedMetadata
+      metadatas: normalizedMetadata,
+      documents
     });
     return generatedIds;
   }
+  HnswSpaceMap = {
+    cosine: "cosine",
+    euclidean: "l2",
+    dotproduct: "ip",
+    l2: "euclidean",
+    ip: "dotproduct"
+  };
   async createIndex(indexName, dimension, metric = "cosine") {
     if (!Number.isInteger(dimension) || dimension <= 0) {
       throw new Error("Dimension must be a positive integer");
     }
+    const hnswSpace = this.HnswSpaceMap[metric];
+    if (!["cosine", "l2", "ip"].includes(hnswSpace)) {
+      throw new Error(`Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`);
+    }
     await this.client.createCollection({
       name: indexName,
       metadata: {
         dimension,
-        metric
+        "hnsw:space": this.HnswSpaceMap[metric]
       }
     });
   }
@@ -152,7 +164,7 @@ var ChromaVector = class extends MastraVector {
     const translatedFilter = chromaFilter.translate(filter);
     return translatedFilter;
   }
-  async query(indexName, queryVector, topK = 10, filter, includeVector = false) {
+  async query(indexName, queryVector, topK = 10, filter, includeVector = false, documentFilter) {
     const collection = await this.getCollection(indexName, true);
     const defaultInclude = ["documents", "metadatas", "distances"];
     const translatedFilter = this.transformFilter(filter);
@@ -160,12 +172,14 @@ var ChromaVector = class extends MastraVector {
       queryEmbeddings: [queryVector],
       nResults: topK,
       where: translatedFilter,
+      whereDocument: documentFilter,
       include: includeVector ? [...defaultInclude, "embeddings"] : defaultInclude
     });
     return (results.ids[0] || []).map((id, index) => ({
       id,
       score: results.distances?.[0]?.[index] || 0,
       metadata: results.metadatas?.[0]?.[index] || {},
+      document: results.documents?.[0]?.[index],
       ...includeVector && { vector: results.embeddings?.[0]?.[index] || [] }
     }));
   }
@@ -177,10 +191,11 @@ var ChromaVector = class extends MastraVector {
     const collection = await this.getCollection(indexName);
     const count = await collection.count();
     const metadata = collection.metadata;
+    const hnswSpace = metadata?.["hnsw:space"];
     return {
       dimension: metadata?.dimension || 0,
       count,
-      metric: metadata?.metric
+      metric: this.HnswSpaceMap[hnswSpace]
     };
   }
   async deleteIndex(indexName) {

package/docker-compose.yaml

@@ -0,0 +1,7 @@
+services:
+  chroma:
+    image: chromadb/chroma
+    ports:
+      - 8000:8000
+volumes:
+  pgdata:

package/eslint.config.js

@@ -0,0 +1,6 @@
+import { createConfig } from '@internal/lint/eslint';
+
+const config = await createConfig();
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [...config];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/chroma",
-  "version": "0.1.5",
+  "version": "0.1.6-alpha.1",
   "description": "Chroma vector store provider for Mastra",
   "type": "module",
   "main": "dist/index.js",
@@ -16,18 +16,21 @@
   },
   "dependencies": {
     "chromadb": "^1.9.4",
-    "@mastra/core": "^0.4.2"
+    "@mastra/core": "^0.4.3-alpha.1"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.49.2",
     "@types/node": "^22.13.1",
     "tsup": "^8.0.1",
     "typescript": "^5.7.3",
-    "vitest": "^3.0.4"
+    "vitest": "^3.0.4",
+    "eslint": "^9.20.1",
+    "@internal/lint": "0.0.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --experimental-dts --clean --treeshake",
     "build:watch": "pnpm build --watch",
-    "test": "vitest run"
+    "test": "vitest run",
+    "lint": "eslint ."
   }
 }

package/src/vector/filter.ts

@@ -1,10 +1,5 @@
-import {
-  BaseFilterTranslator,
-  type FieldCondition,
-  type Filter,
-  type OperatorSupport,
-  type QueryOperator,
-} from '@mastra/core/filter';
+import { BaseFilterTranslator } from '@mastra/core/filter';
+import type { FieldCondition, Filter, OperatorSupport, QueryOperator } from '@mastra/core/filter';
 
 /**
  * Translator for Chroma filter queries.

package/src/vector/index.test.ts

@@ -1,4 +1,4 @@
-import { QueryResult, IndexStats } from '@mastra/core/vector';
+import type { QueryResult, IndexStats } from '@mastra/core/vector';
 import { describe, expect, beforeEach, afterEach, it, beforeAll, afterAll } from 'vitest';
 
 import { ChromaVector } from './';
@@ -10,13 +10,14 @@ describe('ChromaVector Integration Tests', () => {
 
   const testIndexName = 'test-index';
   const testIndexName2 = 'test-index-2';
+  const testIndexName3 = 'test-index-3';
   const dimension = 3;
 
   beforeEach(async () => {
     // Clean up any existing test index
     try {
       await vectorDB.deleteIndex(testIndexName);
-    } catch (error) {
+    } catch {
       // Ignore errors if index doesn't exist
     }
     await vectorDB.createIndex(testIndexName, dimension);
@@ -26,7 +27,7 @@ describe('ChromaVector Integration Tests', () => {
     // Cleanup after tests
     try {
       await vectorDB.deleteIndex(testIndexName);
-    } catch (error) {
+    } catch {
       // Ignore cleanup errors
     }
   }, 5000);
@@ -309,7 +310,7 @@ describe('ChromaVector Integration Tests', () => {
     beforeAll(async () => {
       try {
         await vectorDB.deleteIndex(testIndexName2);
-      } catch (error) {
+      } catch {
         // Ignore errors if index doesn't exist
       }
       await vectorDB.createIndex(testIndexName2, dimension);
@@ -357,7 +358,7 @@ describe('ChromaVector Integration Tests', () => {
       // Cleanup after tests
       try {
         await vectorDB.deleteIndex(testIndexName2);
-      } catch (error) {
+      } catch {
         // Ignore cleanup errors
       }
     });
@@ -886,4 +887,159 @@ describe('ChromaVector Integration Tests', () => {
       });
     });
   });
+
+  describe('Document Operations and Filtering', () => {
+    const testDocuments = [
+      'The quick brown fox jumps over the lazy dog',
+      'Pack my box with five dozen liquor jugs',
+      'How vexingly quick daft zebras JUMP',
+    ];
+
+    beforeAll(async () => {
+      try {
+        await vectorDB.deleteIndex(testIndexName3);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+      await vectorDB.createIndex(testIndexName3, dimension);
+
+      const testVectors = [
+        [1.0, 0.0, 0.0],
+        [0.0, 1.0, 0.0],
+        [0.0, 0.0, 1.0],
+      ];
+
+      const testMetadata = [
+        { source: 'pangram1', length: 43 },
+        { source: 'pangram2', length: 32 },
+        { source: 'pangram3', length: 30 },
+      ];
+      const testIds = ['doc1', 'doc2', 'doc3'];
+
+      await vectorDB.upsert(testIndexName3, testVectors, testMetadata, testIds, testDocuments);
+
+      // Wait for indexing
+      await new Promise(resolve => setTimeout(resolve, 2000));
+    });
+
+    afterAll(async () => {
+      // Cleanup after tests
+      try {
+        await vectorDB.deleteIndex(testIndexName3);
+      } catch {
+        // Ignore cleanup errors
+      }
+    });
+
+    describe('Basic Document Operations', () => {
+      it('should store and retrieve documents', async () => {
+        const results = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3);
+        expect(results).toHaveLength(3);
+        // Verify documents are returned
+        expect(results[0].document).toBe(testDocuments[0]);
+      });
+
+      it('should filter documents using $contains', async () => {
+        const results = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $contains: 'quick',
+        });
+        expect(results).toHaveLength(2);
+      });
+
+      it('should filter with $not_contains', async () => {
+        const results = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $not_contains: 'fox',
+        });
+        expect(results.every(r => !r.document?.includes('fox'))).toBe(true);
+      });
+
+      it('should combine metadata and document filters', async () => {
+        const results = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, { source: 'pangram1' }, false, {
+          $contains: 'fox',
+        });
+        expect(results).toHaveLength(1);
+        expect(results[0].metadata?.source).toBe('pangram1');
+        expect(results[0].document).toContain('fox');
+      });
+    });
+
+    describe('Complex Document Filtering', () => {
+      it('should handle $and conditions', async () => {
+        const results = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $and: [{ $contains: 'quick' }, { $not_contains: 'fox' }],
+        });
+        expect(results).toHaveLength(1);
+        expect(results[0].document).toContain('quick');
+        expect(results[0].document).not.toContain('fox');
+      });
+
+      it('should handle $or conditions', async () => {
+        const results = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $or: [{ $contains: 'fox' }, { $contains: 'zebras' }],
+        });
+        expect(results).toHaveLength(2);
+      });
+    });
+
+    describe('Edge Cases and Validation', () => {
+      it('should reject empty string in $contains', async () => {
+        await expect(
+          vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, { $contains: '' }),
+        ).rejects.toThrow('Expected where document operand value for operator $contains to be a non-empty str');
+      });
+
+      it('should be case sensitive', async () => {
+        // First verify lowercase works
+        const lowerResults = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $contains: 'quick',
+        });
+        expect(lowerResults.length).toBe(2);
+
+        // Then verify uppercase doesn't match
+        const upperResults = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $contains: 'QUICK',
+        });
+        expect(upperResults.length).toBe(0);
+
+        const upperResults2 = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $contains: 'JUMP',
+        });
+        expect(upperResults2.length).toBe(1);
+      });
+
+      it('should handle exact string matches', async () => {
+        const results = await vectorDB.query(
+          testIndexName3,
+          [1.0, 0.0, 0.0],
+          3,
+          undefined,
+          false,
+          { $contains: 'quick brown' }, // Test multi-word match
+        );
+        expect(results.length).toBe(1);
+        expect(results[0].document).toContain('quick brown');
+      });
+
+      it('should handle deeply nested logical operators', async () => {
+        const results = await vectorDB.query(testIndexName3, [1.0, 0.0, 0.0], 3, undefined, false, {
+          $or: [
+            {
+              $and: [{ $contains: 'quick' }, { $not_contains: 'fox' }],
+            },
+            {
+              $and: [{ $contains: 'box' }, { $not_contains: 'quick' }],
+            },
+          ],
+        });
+        expect(results.length).toBeGreaterThan(0);
+        results.forEach(result => {
+          if (result.document?.includes('quick')) {
+            expect(result.document).not.toContain('fox');
+          } else if (result.document?.includes('box')) {
+            expect(result.document).not.toContain('quick');
+          }
+        });
+      });
+    });
+  });
 });

package/src/vector/index.ts

@@ -1,9 +1,15 @@
-import { type Filter } from '@mastra/core/filter';
-import { MastraVector, type QueryResult, type IndexStats } from '@mastra/core/vector';
+import type { Filter } from '@mastra/core/filter';
+import { MastraVector } from '@mastra/core/vector';
+import type { QueryResult, IndexStats } from '@mastra/core/vector';
 import { ChromaClient } from 'chromadb';
 
 import { ChromaFilterTranslator } from './filter';
 
+export interface DocumentMetadata {
+  content?: string;
+  metadata?: Record<string, any>;
+}
+
 export class ChromaVector extends MastraVector {
   private client: ChromaClient;
   private collections: Map<string, any>;
@@ -26,11 +32,11 @@ export class ChromaVector extends MastraVector {
     this.collections = new Map();
   }
 
-  private async getCollection(indexName: string, throwIfNotExists: boolean = true) {
+  async getCollection(indexName: string, throwIfNotExists: boolean = true) {
     try {
       const collection = await this.client.getCollection({ name: indexName, embeddingFunction: undefined as any });
       this.collections.set(indexName, collection);
-    } catch (error) {
+    } catch {
       if (throwIfNotExists) {
         throw new Error(`Index ${indexName} does not exist`);
       }
@@ -54,6 +60,7 @@ export class ChromaVector extends MastraVector {
     vectors: number[][],
     metadata?: Record<string, any>[],
     ids?: string[],
+    documents?: string[],
   ): Promise<string[]> {
     const collection = await this.getCollection(indexName);
 
@@ -73,11 +80,20 @@ export class ChromaVector extends MastraVector {
       ids: generatedIds,
       embeddings: vectors,
       metadatas: normalizedMetadata,
+      documents: documents,
     });
 
     return generatedIds;
   }
 
+  private HnswSpaceMap = {
+    cosine: 'cosine',
+    euclidean: 'l2',
+    dotproduct: 'ip',
+    l2: 'euclidean',
+    ip: 'dotproduct',
+  };
+
   async createIndex(
     indexName: string,
     dimension: number,
@@ -86,11 +102,15 @@ export class ChromaVector extends MastraVector {
     if (!Number.isInteger(dimension) || dimension <= 0) {
       throw new Error('Dimension must be a positive integer');
     }
+    const hnswSpace = this.HnswSpaceMap[metric];
+    if (!['cosine', 'l2', 'ip'].includes(hnswSpace)) {
+      throw new Error(`Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`);
+    }
     await this.client.createCollection({
       name: indexName,
       metadata: {
         dimension,
-        metric,
+        'hnsw:space': this.HnswSpaceMap[metric],
       },
     });
   }
@@ -106,17 +126,18 @@ export class ChromaVector extends MastraVector {
     topK: number = 10,
     filter?: Filter,
     includeVector: boolean = false,
+    documentFilter?: Filter,
   ): Promise<QueryResult[]> {
     const collection = await this.getCollection(indexName, true);
 
     const defaultInclude = ['documents', 'metadatas', 'distances'];
 
     const translatedFilter = this.transformFilter(filter);
-
     const results = await collection.query({
       queryEmbeddings: [queryVector],
       nResults: topK,
       where: translatedFilter,
+      whereDocument: documentFilter,
       include: includeVector ? [...defaultInclude, 'embeddings'] : defaultInclude,
     });
 
@@ -125,6 +146,7 @@ export class ChromaVector extends MastraVector {
       id,
       score: results.distances?.[0]?.[index] || 0,
       metadata: results.metadatas?.[0]?.[index] || {},
+      document: results.documents?.[0]?.[index],
       ...(includeVector && { vector: results.embeddings?.[0]?.[index] || [] }),
     }));
   }
@@ -139,10 +161,12 @@ export class ChromaVector extends MastraVector {
     const count = await collection.count();
     const metadata = collection.metadata;
 
+    const hnswSpace = metadata?.['hnsw:space'] as 'cosine' | 'l2' | 'ip';
+
     return {
       dimension: metadata?.dimension || 0,
       count,
-      metric: metadata?.metric as 'cosine' | 'euclidean' | 'dotproduct',
+      metric: this.HnswSpaceMap[hnswSpace] as 'cosine' | 'euclidean' | 'dotproduct',
     };
   }