@mastra/chroma 0.10.3 → 0.10.4-alpha.1

package/dist/index.js

@@ -1,3 +1,4 @@
+import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
 import { MastraVector } from '@mastra/core/vector';
 import { ChromaClient } from 'chromadb';
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
@@ -123,18 +124,31 @@ var ChromaVector = class extends MastraVector {
     }
   }
   async upsert({ indexName, vectors, metadata, ids, documents }) {
-    const collection = await this.getCollection(indexName);
-    const stats = await this.describeIndex({ indexName });
-    this.validateVectorDimensions(vectors, stats.dimension);
-    const generatedIds = ids || vectors.map(() => crypto.randomUUID());
-    const normalizedMetadata = metadata || vectors.map(() => ({}));
-    await collection.upsert({
-      ids: generatedIds,
-      embeddings: vectors,
-      metadatas: normalizedMetadata,
-      documents
-    });
-    return generatedIds;
+    try {
+      const collection = await this.getCollection(indexName);
+      const stats = await this.describeIndex({ indexName });
+      this.validateVectorDimensions(vectors, stats.dimension);
+      const generatedIds = ids || vectors.map(() => crypto.randomUUID());
+      const normalizedMetadata = metadata || vectors.map(() => ({}));
+      await collection.upsert({
+        ids: generatedIds,
+        embeddings: vectors,
+        metadatas: normalizedMetadata,
+        documents
+      });
+      return generatedIds;
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_UPSERT_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error
+      );
+    }
   }
   HnswSpaceMap = {
     cosine: "cosine",
@@ -145,11 +159,23 @@ var ChromaVector = class extends MastraVector {
   };
   async createIndex({ indexName, dimension, metric = "cosine" }) {
     if (!Number.isInteger(dimension) || dimension <= 0) {
-      throw new Error("Dimension must be a positive integer");
+      throw new MastraError({
+        id: "CHROMA_VECTOR_CREATE_INDEX_INVALID_DIMENSION",
+        text: "Dimension must be a positive integer",
+        domain: ErrorDomain.MASTRA_VECTOR,
+        category: ErrorCategory.USER,
+        details: { dimension }
+      });
     }
     const hnswSpace = this.HnswSpaceMap[metric];
-    if (!["cosine", "l2", "ip"].includes(hnswSpace)) {
-      throw new Error(`Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`);
+    if (!hnswSpace || !["cosine", "l2", "ip"].includes(hnswSpace)) {
+      throw new MastraError({
+        id: "CHROMA_VECTOR_CREATE_INDEX_INVALID_METRIC",
+        text: `Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`,
+        domain: ErrorDomain.MASTRA_VECTOR,
+        category: ErrorCategory.USER,
+        details: { metric }
+      });
     }
     try {
       await this.client.createCollection({
@@ -165,7 +191,15 @@ var ChromaVector = class extends MastraVector {
         await this.validateExistingIndex(indexName, dimension, metric);
         return;
       }
-      throw error;
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_CREATE_INDEX_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error
+      );
     }
   }
   transformFilter(filter) {
@@ -180,27 +214,51 @@ var ChromaVector = class extends MastraVector {
     includeVector = false,
     documentFilter
   }) {
-    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
-    });
-    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] || [] }
-    }));
+    try {
+      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
+      });
+      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] || [] }
+      }));
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_QUERY_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error
+      );
+    }
   }
   async listIndexes() {
-    const collections = await this.client.listCollections();
-    return collections.map((collection) => collection);
+    try {
+      const collections = await this.client.listCollections();
+      return collections.map((collection) => collection);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_LIST_INDEXES_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+    }
   }
   /**
    * Retrieves statistics about a vector index.
@@ -209,19 +267,44 @@ var ChromaVector = class extends MastraVector {
    * @returns A promise that resolves to the index statistics including dimension, count and metric
    */
   async describeIndex({ indexName }) {
-    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: this.HnswSpaceMap[hnswSpace]
-    };
+    try {
+      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: this.HnswSpaceMap[hnswSpace]
+      };
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_DESCRIBE_INDEX_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error
+      );
+    }
   }
   async deleteIndex({ indexName }) {
-    await this.client.deleteCollection({ name: indexName });
-    this.collections.delete(indexName);
+    try {
+      await this.client.deleteCollection({ name: indexName });
+      this.collections.delete(indexName);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_DELETE_INDEX_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error
+      );
+    }
   }
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
@@ -234,10 +317,16 @@ var ChromaVector = class extends MastraVector {
    * @throws Will throw an error if no updates are provided or if the update operation fails.
    */
   async updateVector({ indexName, id, update }) {
+    if (!update.vector && !update.metadata) {
+      throw new MastraError({
+        id: "CHROMA_VECTOR_UPDATE_NO_PAYLOAD",
+        text: "No updates provided for vector",
+        domain: ErrorDomain.MASTRA_VECTOR,
+        category: ErrorCategory.USER,
+        details: { indexName, id }
+      });
+    }
     try {
-      if (!update.vector && !update.metadata) {
-        throw new Error("No updates provided");
-      }
       const collection = await this.getCollection(indexName, true);
       const updateOptions = { ids: [id] };
       if (update?.vector) {
@@ -250,22 +339,33 @@ var ChromaVector = class extends MastraVector {
       }
       return await collection.update(updateOptions);
     } catch (error) {
-      throw new Error(`Failed to update vector by id: ${id} for index name: ${indexName}: ${error.message}`);
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_UPDATE_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, id }
+        },
+        error
+      );
     }
   }
-  /**
-   * Deletes a vector by its ID.
-   * @param indexName - The name of the index containing the vector.
-   * @param id - The ID of the vector to delete.
-   * @returns A promise that resolves when the deletion is complete.
-   * @throws Will throw an error if the deletion operation fails.
-   */
   async deleteVector({ indexName, id }) {
     try {
       const collection = await this.getCollection(indexName, true);
       await collection.delete({ ids: [id] });
     } catch (error) {
-      throw new Error(`Failed to delete vector by id: ${id} for index name: ${indexName}: ${error.message}`);
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: "CHROMA_VECTOR_DELETE_FAILED",
+          domain: ErrorDomain.MASTRA_VECTOR,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, id }
+        },
+        error
+      );
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/chroma",
-  "version": "0.10.3",
+  "version": "0.10.4-alpha.1",
   "description": "Chroma vector store provider for Mastra",
   "type": "module",
   "main": "dist/index.js",
@@ -25,12 +25,12 @@
   "devDependencies": {
     "@microsoft/api-extractor": "^7.52.8",
     "@types/node": "^20.19.0",
-    "eslint": "^9.28.0",
+    "eslint": "^9.29.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.3",
     "@internal/lint": "0.0.13",
-    "@mastra/core": "0.10.6"
+    "@mastra/core": "0.10.7-alpha.2"
   },
   "peerDependencies": {
     "@mastra/core": ">=0.10.4-0 <0.11.0"

package/src/vector/filter.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 
+import type { ChromaVectorFilter } from './filter';
 import { ChromaFilterTranslator } from './filter';
 
 describe('ChromaFilterTranslator', () => {
@@ -13,17 +14,17 @@ describe('ChromaFilterTranslator', () => {
   describe('basic operations', () => {
     it('handles empty filters', () => {
       expect(translator.translate({})).toEqual({});
-      expect(translator.translate(null as any)).toEqual(null);
-      expect(translator.translate(undefined as any)).toEqual(undefined);
+      expect(translator.translate(null)).toEqual(null);
+      expect(translator.translate(undefined)).toEqual(undefined);
     });
 
     it('retains implicit equality', () => {
-      const filter = { field: 'value' };
+      const filter: ChromaVectorFilter = { field: 'value' };
       expect(translator.translate(filter)).toEqual({ field: 'value' });
     });
 
     it('converts multiple top-level fields to $and', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         field1: 'value1',
         field2: 'value2',
       };
@@ -33,7 +34,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('handles multiple operators on same field', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         price: { $gt: 100, $lt: 200 },
         quantity: { $gte: 10, $lte: 20 },
       };
@@ -49,7 +50,7 @@ describe('ChromaFilterTranslator', () => {
 
     it('normalizes date values', () => {
       const date = new Date('2024-01-01');
-      const filter = { timestamp: { $gt: date } };
+      const filter: ChromaVectorFilter = { timestamp: { $gt: date } };
       expect(translator.translate(filter)).toEqual({ timestamp: { $gt: date.toISOString() } });
     });
   });
@@ -57,7 +58,7 @@ describe('ChromaFilterTranslator', () => {
   // Array Operations
   describe('array operations', () => {
     it('handles arrays as $in operator', () => {
-      const filter = { tags: ['tag1', 'tag2'] };
+      const filter: ChromaVectorFilter = { tags: ['tag1', 'tag2'] };
       expect(translator.translate(filter)).toEqual({ tags: { $in: ['tag1', 'tag2'] } });
     });
 
@@ -68,10 +69,14 @@ describe('ChromaFilterTranslator', () => {
 
     it('handles arrays as direct values', () => {
       // Direct array value should be converted to $in
-      expect(translator.translate({ field: ['value1', 'value2'] })).toEqual({ field: { $in: ['value1', 'value2'] } });
+      const filter: ChromaVectorFilter = { field: ['value1', 'value2'] };
+      expect(translator.translate(filter)).toEqual({
+        field: { $in: ['value1', 'value2'] },
+      });
 
       // Empty direct array
-      expect(translator.translate({ field: [] })).toEqual({ field: { $in: [] } });
+      const filter2 = { field: [] };
+      expect(translator.translate(filter2)).toEqual({ field: { $in: [] } });
     });
 
     describe('$in operator variations', () => {
@@ -99,7 +104,7 @@ describe('ChromaFilterTranslator', () => {
   // Logical Operators
   describe('logical operators', () => {
     it('handles logical operators', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         $or: [{ status: { $eq: 'active' } }, { age: { $gt: 25 } }],
       };
       expect(translator.translate(filter)).toEqual({
@@ -108,7 +113,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('handles nested logical operators', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         $and: [
           { status: { $eq: 'active' } },
           {
@@ -142,7 +147,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('handles complex nested conditions', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         $or: [
           { age: { $gt: 25 } },
           {
@@ -176,7 +181,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('preserves empty objects as exact match conditions', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         metadata: {},
         'user.profile': {},
       };
@@ -187,7 +192,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('handles empty objects in logical operators', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         $or: [{}, { status: 'active' }],
       };
 
@@ -211,7 +216,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('handles empty objects in comparison operators', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         metadata: { $eq: {} },
       };
 
@@ -221,7 +226,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('handles empty objects in array operators', () => {
-      const filter = {
+      const filter: ChromaVectorFilter = {
         tags: { $in: [{}] },
       };
 
@@ -335,7 +340,7 @@ describe('ChromaFilterTranslator', () => {
       });
 
       it('throws error for unsupported logical operators', () => {
-        const invalidFilters = [
+        const invalidFilters: any = [
           {
             $not: { field: 'value' },
           },
@@ -374,7 +379,7 @@ describe('ChromaFilterTranslator', () => {
     });
 
     it('throws error for unsupported operators', () => {
-      const unsupportedFilters = [
+      const unsupportedFilters: any = [
         { field: { $regex: 'pattern' } },
         { field: { $contains: 'value' } },
         { field: { $exists: true } },
@@ -395,7 +400,7 @@ describe('ChromaFilterTranslator', () => {
       expect(() => translator.translate(filter)).toThrow();
     });
     it('throws error for non-logical operators at top level', () => {
-      const invalidFilters = [{ $gt: 100 }, { $in: ['value1', 'value2'] }, { $eq: true }];
+      const invalidFilters: any = [{ $gt: 100 }, { $in: ['value1', 'value2'] }, { $eq: true }];
 
       invalidFilters.forEach(filter => {
         expect(() => translator.translate(filter)).toThrow(/Invalid top-level operator/);

package/src/vector/filter.ts

@@ -1,12 +1,43 @@
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
-import type { FieldCondition, VectorFilter, OperatorSupport, QueryOperator } from '@mastra/core/vector/filter';
+import type {
+  VectorFilter,
+  OperatorSupport,
+  QueryOperator,
+  OperatorValueMap,
+  LogicalOperatorValueMap,
+  BlacklistedRootOperators,
+} from '@mastra/core/vector/filter';
+
+type ChromaOperatorValueMap = Omit<OperatorValueMap, '$exists' | '$elemMatch' | '$regex' | '$options'>;
+
+type ChromaLogicalOperatorValueMap = Omit<LogicalOperatorValueMap, '$nor' | '$not'>;
+
+type ChromaBlacklisted = BlacklistedRootOperators | '$nor' | '$not';
+
+export type ChromaVectorFilter = VectorFilter<
+  keyof ChromaOperatorValueMap,
+  ChromaOperatorValueMap,
+  ChromaLogicalOperatorValueMap,
+  ChromaBlacklisted
+>;
+
+type ChromaDocumentOperatorValueMap = ChromaOperatorValueMap;
+
+type ChromaDocumentBlacklisted = Exclude<ChromaBlacklisted, '$contains'>;
+
+export type ChromaVectorDocumentFilter = VectorFilter<
+  keyof ChromaDocumentOperatorValueMap,
+  ChromaDocumentOperatorValueMap,
+  ChromaLogicalOperatorValueMap,
+  ChromaDocumentBlacklisted
+>;
 
 /**
  * Translator for Chroma filter queries.
  * Maintains MongoDB-compatible syntax while ensuring proper validation
  * and normalization of values.
  */
-export class ChromaFilterTranslator extends BaseFilterTranslator {
+export class ChromaFilterTranslator extends BaseFilterTranslator<ChromaVectorFilter> {
   protected override getSupportedOperators(): OperatorSupport {
     return {
       ...BaseFilterTranslator.DEFAULT_OPERATORS,
@@ -18,14 +49,14 @@ export class ChromaFilterTranslator extends BaseFilterTranslator {
     };
   }
 
-  translate(filter?: VectorFilter): VectorFilter {
+  translate(filter?: ChromaVectorFilter): ChromaVectorFilter {
     if (this.isEmpty(filter)) return filter;
     this.validateFilter(filter);
 
     return this.translateNode(filter);
   }
 
-  private translateNode(node: VectorFilter | FieldCondition, currentPath: string = ''): any {
+  private translateNode(node: ChromaVectorFilter, currentPath: string = ''): any {
     // Handle primitive values and arrays
     if (this.isRegex(node)) {
       throw new Error('Regex is not supported in Chroma');

package/src/vector/index.test.ts

@@ -378,7 +378,7 @@ describe('ChromaVector Integration Tests', () => {
           indexName: testIndexName,
           queryVector: [1, 0, 0],
           filter: {
-            tags: { $in: null },
+            tags: { $in: null } as any,
           },
         }),
       ).rejects.toThrow();
@@ -479,9 +479,9 @@ describe('ChromaVector Integration Tests', () => {
           indexName: testIndexName,
           queryVector: [1, 0, 0],
           filter: {
-            field1: { $in: 'not-array' },
-            field2: { $exists: 'not-boolean' },
-            field3: { $gt: 'not-number' },
+            field1: { $in: 'not-array' } as any,
+            field2: { $exists: 'not-boolean' } as any,
+            field3: { $gt: 'not-number' } as any,
           },
         }),
       ).rejects.toThrow();