@mastra/chroma 0.0.0-switch-to-core-20250424015131 → 0.0.0-vector-query-sources-20250516172905

package/dist/index.cjs

@@ -128,7 +128,7 @@ var ChromaVector = class extends vector.MastraVector {
     const params = this.normalizeArgs("upsert", args, ["documents"]);
     const { indexName, vectors, metadata, ids, documents } = params;
     const collection = await this.getCollection(indexName);
-    const stats = await this.describeIndex(indexName);
+    const stats = await this.describeIndex({ indexName });
     this.validateVectorDimensions(vectors, stats.dimension);
     const generatedIds = ids || vectors.map(() => crypto.randomUUID());
     const normalizedMetadata = metadata || vectors.map(() => ({}));
@@ -157,13 +157,22 @@ var ChromaVector = class extends vector.MastraVector {
     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,
-        "hnsw:space": this.HnswSpaceMap[metric]
+    try {
+      await this.client.createCollection({
+        name: indexName,
+        metadata: {
+          dimension,
+          "hnsw:space": hnswSpace
+        }
+      });
+    } catch (error) {
+      const message = error?.message || error?.toString();
+      if (message && message.toLowerCase().includes("already exists")) {
+        await this.validateExistingIndex(indexName, dimension, metric);
+        return;
       }
-    });
+      throw error;
+    }
   }
   transformFilter(filter) {
     const translator = new ChromaFilterTranslator();
@@ -194,7 +203,16 @@ var ChromaVector = class extends vector.MastraVector {
     const collections = await this.client.listCollections();
     return collections.map((collection) => collection);
   }
-  async describeIndex(indexName) {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param params - The parameters for describing an index
+   * @param params.indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex(...args) {
+    const params = this.normalizeArgs("describeIndex", args);
+    const { indexName } = params;
     const collection = await this.getCollection(indexName);
     const count = await collection.count();
     const metadata = collection.metadata;
@@ -205,32 +223,167 @@ var ChromaVector = class extends vector.MastraVector {
       metric: this.HnswSpaceMap[hnswSpace]
     };
   }
-  async deleteIndex(indexName) {
+  async deleteIndex(...args) {
+    const params = this.normalizeArgs("deleteIndex", args);
+    const { indexName } = params;
     await this.client.deleteCollection({ name: indexName });
     this.collections.delete(indexName);
   }
+  /**
+   * @deprecated Use {@link updateVector} instead. This method will be removed on May 20th, 2025.
+   *
+   * Updates a vector by its ID with the provided vector and/or metadata.
+   * @param indexName - The name of the index containing the vector.
+   * @param id - The ID of the vector to update.
+   * @param update - An object containing the vector and/or metadata to update.
+   * @param update.vector - An optional array of numbers representing the new vector.
+   * @param update.metadata - An optional record containing the new metadata.
+   * @returns A promise that resolves when the update is complete.
+   * @throws Will throw an error if no updates are provided or if the update operation fails.
+   */
   async updateIndexById(indexName, id, update) {
-    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) {
-      updateOptions.embeddings = [update.vector];
-    }
-    if (update?.metadata) {
-      updateOptions.metadatas = [update.metadata];
+    this.logger.warn(
+      `Deprecation Warning: updateIndexById() is deprecated. 
+    Please use updateVector() instead. 
+    updateIndexById() will be removed on May 20th, 2025.`
+    );
+    await this.updateVector({ indexName, id, update });
+  }
+  /**
+   * Updates a vector by its ID with the provided vector and/or metadata.
+   * @param indexName - The name of the index containing the vector.
+   * @param id - The ID of the vector to update.
+   * @param update - An object containing the vector and/or metadata to update.
+   * @param update.vector - An optional array of numbers representing the new vector.
+   * @param update.metadata - An optional record containing the new metadata.
+   * @returns A promise that resolves when the update is complete.
+   * @throws Will throw an error if no updates are provided or if the update operation fails.
+   */
+  async updateVector(...args) {
+    const params = this.normalizeArgs("updateVector", args);
+    const { indexName, id, update } = params;
+    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) {
+        const stats = await this.describeIndex({ indexName });
+        this.validateVectorDimensions([update.vector], stats.dimension);
+        updateOptions.embeddings = [update.vector];
+      }
+      if (update?.metadata) {
+        updateOptions.metadatas = [update.metadata];
+      }
+      return await collection.update(updateOptions);
+    } catch (error) {
+      throw new Error(`Failed to update vector by id: ${id} for index name: ${indexName}: ${error.message}`);
     }
-    return await collection.update(updateOptions);
   }
+  /**
+   * @deprecated Use {@link deleteVector} instead. This method will be removed on May 20th, 2025.
+   *
+   * 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 deleteIndexById(indexName, id) {
+    this.logger.warn(
+      `Deprecation Warning: deleteIndexById() is deprecated. Please use deleteVector() instead. deleteIndexById() will be removed on May 20th.`
+    );
+    await this.deleteVector(indexName, id);
+  }
+  /**
+   * 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(...args) {
+    const params = this.normalizeArgs("deleteVector", args);
+    const { indexName, id } = params;
     try {
       const collection = await this.getCollection(indexName, true);
       await collection.delete({ ids: [id] });
     } catch (error) {
-      throw new Error(`Failed to delete index by id: ${id} for index name: ${indexName}: ${error.message}`);
+      throw new Error(`Failed to delete vector by id: ${id} for index name: ${indexName}: ${error.message}`);
     }
   }
 };
 
+// src/vector/prompt.ts
+var CHROMA_PROMPT = `When querying Chroma, you can ONLY use the operators listed below. Any other operators will be rejected.
+Important: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.
+If a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.
+
+Basic Comparison Operators:
+- $eq: Exact match (default when using field: value)
+  Example: { "category": "electronics" }
+- $ne: Not equal
+  Example: { "category": { "$ne": "electronics" } }
+- $gt: Greater than
+  Example: { "price": { "$gt": 100 } }
+- $gte: Greater than or equal
+  Example: { "price": { "$gte": 100 } }
+- $lt: Less than
+  Example: { "price": { "$lt": 100 } }
+- $lte: Less than or equal
+  Example: { "price": { "$lte": 100 } }
+
+Array Operators:
+- $in: Match any value in array
+  Example: { "category": { "$in": ["electronics", "books"] } }
+- $nin: Does not match any value in array
+  Example: { "category": { "$nin": ["electronics", "books"] } }
+
+Logical Operators:
+- $and: Logical AND
+  Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Restrictions:
+- Regex patterns are not supported
+- Element operators are not supported
+- Only $and and $or logical operators are supported
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Empty arrays in $in/$nin will return no results
+- If multiple top-level fields exist, they're wrapped in $and
+- Only logical operators ($and, $or) can be used at the top level
+- All other operators must be used within a field condition
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$gt": 100 }
+  Invalid: { "$in": [...] }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- Logical operators ($and, $or):
+  - Can only be used at top level or nested within other logical operators
+  - Can not be used on a field level, or be nested inside a field
+  - Can not be used inside an operator
+  - Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  - Valid: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
+  - Invalid: { "field": { "$and": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$or": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$gt": { "$and": [{...}] } } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "$or": [
+      { "inStock": true },
+      { "preorder": true }
+    ]}
+  ]
+}`;
+
+exports.CHROMA_PROMPT = CHROMA_PROMPT;
 exports.ChromaVector = ChromaVector;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -126,7 +126,7 @@ var ChromaVector = class extends MastraVector {
     const params = this.normalizeArgs("upsert", args, ["documents"]);
     const { indexName, vectors, metadata, ids, documents } = params;
     const collection = await this.getCollection(indexName);
-    const stats = await this.describeIndex(indexName);
+    const stats = await this.describeIndex({ indexName });
     this.validateVectorDimensions(vectors, stats.dimension);
     const generatedIds = ids || vectors.map(() => crypto.randomUUID());
     const normalizedMetadata = metadata || vectors.map(() => ({}));
@@ -155,13 +155,22 @@ var ChromaVector = class extends MastraVector {
     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,
-        "hnsw:space": this.HnswSpaceMap[metric]
+    try {
+      await this.client.createCollection({
+        name: indexName,
+        metadata: {
+          dimension,
+          "hnsw:space": hnswSpace
+        }
+      });
+    } catch (error) {
+      const message = error?.message || error?.toString();
+      if (message && message.toLowerCase().includes("already exists")) {
+        await this.validateExistingIndex(indexName, dimension, metric);
+        return;
       }
-    });
+      throw error;
+    }
   }
   transformFilter(filter) {
     const translator = new ChromaFilterTranslator();
@@ -192,7 +201,16 @@ var ChromaVector = class extends MastraVector {
     const collections = await this.client.listCollections();
     return collections.map((collection) => collection);
   }
-  async describeIndex(indexName) {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param params - The parameters for describing an index
+   * @param params.indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex(...args) {
+    const params = this.normalizeArgs("describeIndex", args);
+    const { indexName } = params;
     const collection = await this.getCollection(indexName);
     const count = await collection.count();
     const metadata = collection.metadata;
@@ -203,32 +221,166 @@ var ChromaVector = class extends MastraVector {
       metric: this.HnswSpaceMap[hnswSpace]
     };
   }
-  async deleteIndex(indexName) {
+  async deleteIndex(...args) {
+    const params = this.normalizeArgs("deleteIndex", args);
+    const { indexName } = params;
     await this.client.deleteCollection({ name: indexName });
     this.collections.delete(indexName);
   }
+  /**
+   * @deprecated Use {@link updateVector} instead. This method will be removed on May 20th, 2025.
+   *
+   * Updates a vector by its ID with the provided vector and/or metadata.
+   * @param indexName - The name of the index containing the vector.
+   * @param id - The ID of the vector to update.
+   * @param update - An object containing the vector and/or metadata to update.
+   * @param update.vector - An optional array of numbers representing the new vector.
+   * @param update.metadata - An optional record containing the new metadata.
+   * @returns A promise that resolves when the update is complete.
+   * @throws Will throw an error if no updates are provided or if the update operation fails.
+   */
   async updateIndexById(indexName, id, update) {
-    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) {
-      updateOptions.embeddings = [update.vector];
-    }
-    if (update?.metadata) {
-      updateOptions.metadatas = [update.metadata];
+    this.logger.warn(
+      `Deprecation Warning: updateIndexById() is deprecated. 
+    Please use updateVector() instead. 
+    updateIndexById() will be removed on May 20th, 2025.`
+    );
+    await this.updateVector({ indexName, id, update });
+  }
+  /**
+   * Updates a vector by its ID with the provided vector and/or metadata.
+   * @param indexName - The name of the index containing the vector.
+   * @param id - The ID of the vector to update.
+   * @param update - An object containing the vector and/or metadata to update.
+   * @param update.vector - An optional array of numbers representing the new vector.
+   * @param update.metadata - An optional record containing the new metadata.
+   * @returns A promise that resolves when the update is complete.
+   * @throws Will throw an error if no updates are provided or if the update operation fails.
+   */
+  async updateVector(...args) {
+    const params = this.normalizeArgs("updateVector", args);
+    const { indexName, id, update } = params;
+    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) {
+        const stats = await this.describeIndex({ indexName });
+        this.validateVectorDimensions([update.vector], stats.dimension);
+        updateOptions.embeddings = [update.vector];
+      }
+      if (update?.metadata) {
+        updateOptions.metadatas = [update.metadata];
+      }
+      return await collection.update(updateOptions);
+    } catch (error) {
+      throw new Error(`Failed to update vector by id: ${id} for index name: ${indexName}: ${error.message}`);
     }
-    return await collection.update(updateOptions);
   }
+  /**
+   * @deprecated Use {@link deleteVector} instead. This method will be removed on May 20th, 2025.
+   *
+   * 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 deleteIndexById(indexName, id) {
+    this.logger.warn(
+      `Deprecation Warning: deleteIndexById() is deprecated. Please use deleteVector() instead. deleteIndexById() will be removed on May 20th.`
+    );
+    await this.deleteVector(indexName, id);
+  }
+  /**
+   * 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(...args) {
+    const params = this.normalizeArgs("deleteVector", args);
+    const { indexName, id } = params;
     try {
       const collection = await this.getCollection(indexName, true);
       await collection.delete({ ids: [id] });
     } catch (error) {
-      throw new Error(`Failed to delete index by id: ${id} for index name: ${indexName}: ${error.message}`);
+      throw new Error(`Failed to delete vector by id: ${id} for index name: ${indexName}: ${error.message}`);
     }
   }
 };
 
-export { ChromaVector };
+// src/vector/prompt.ts
+var CHROMA_PROMPT = `When querying Chroma, you can ONLY use the operators listed below. Any other operators will be rejected.
+Important: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.
+If a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.
+
+Basic Comparison Operators:
+- $eq: Exact match (default when using field: value)
+  Example: { "category": "electronics" }
+- $ne: Not equal
+  Example: { "category": { "$ne": "electronics" } }
+- $gt: Greater than
+  Example: { "price": { "$gt": 100 } }
+- $gte: Greater than or equal
+  Example: { "price": { "$gte": 100 } }
+- $lt: Less than
+  Example: { "price": { "$lt": 100 } }
+- $lte: Less than or equal
+  Example: { "price": { "$lte": 100 } }
+
+Array Operators:
+- $in: Match any value in array
+  Example: { "category": { "$in": ["electronics", "books"] } }
+- $nin: Does not match any value in array
+  Example: { "category": { "$nin": ["electronics", "books"] } }
+
+Logical Operators:
+- $and: Logical AND
+  Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Restrictions:
+- Regex patterns are not supported
+- Element operators are not supported
+- Only $and and $or logical operators are supported
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Empty arrays in $in/$nin will return no results
+- If multiple top-level fields exist, they're wrapped in $and
+- Only logical operators ($and, $or) can be used at the top level
+- All other operators must be used within a field condition
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$gt": 100 }
+  Invalid: { "$in": [...] }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- Logical operators ($and, $or):
+  - Can only be used at top level or nested within other logical operators
+  - Can not be used on a field level, or be nested inside a field
+  - Can not be used inside an operator
+  - Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  - Valid: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
+  - Invalid: { "field": { "$and": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$or": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$gt": { "$and": [{...}] } } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "$or": [
+      { "inStock": true },
+      { "preorder": true }
+    ]}
+  ]
+}`;
+
+export { CHROMA_PROMPT, ChromaVector };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/chroma",
-  "version": "0.0.0-switch-to-core-20250424015131",
+  "version": "0.0.0-vector-query-sources-20250516172905",
   "description": "Chroma vector store provider for Mastra",
   "type": "module",
   "main": "dist/index.js",
@@ -21,16 +21,16 @@
   "license": "MIT",
   "dependencies": {
     "chromadb": "^2.2.0",
-    "@mastra/core": "0.0.0-switch-to-core-20250424015131"
+    "@mastra/core": "0.0.0-vector-query-sources-20250516172905"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.52.1",
+    "@microsoft/api-extractor": "^7.52.5",
     "@types/node": "^20.17.27",
     "eslint": "^9.23.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.2",
-    "vitest": "^3.0.9",
-    "@internal/lint": "0.0.2"
+    "vitest": "^3.1.2",
+    "@internal/lint": "0.0.0-vector-query-sources-20250516172905"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting",

package/src/index.ts

@@ -1 +1,2 @@
 export * from './vector/index';
+export { CHROMA_PROMPT } from './vector/prompt';