@mastra/chroma 0.0.0-vnext-inngest-20250508122351 → 0.0.0-vnext-20251104230439

package/LICENSE.md

@@ -1,7 +1,15 @@
-Copyright 2025 Mastra AI, Inc.
+# Apache License 2.0
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Copyright (c) 2025 Kepler Software, Inc.
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,6 +1,6 @@
 # @mastra/chroma
 
-Vector store implementation for ChromaDB using the official chromadb client with added dimension validation, collection management, and document storage capabilities.
+Vector store implementation for Chroma using the official `chromadb` client with added dimension validation, collection management, and document storage capabilities.
 
 ## Installation
 
@@ -8,18 +8,56 @@ Vector store implementation for ChromaDB using the official chromadb client with
 npm install @mastra/chroma
 ```
 
-## Usage
+## Instantiation
+
+### Local or Self-Deployments
+
+To run a Chroma server, use the [Chroma CLI](https://docs.trychroma.com/docs/cli/db). It is available to you when you install this package.
+
+```shell
+chroma run
+```
+
+You will now have a Chroma server running on `localhost:8000`.
+
+```typescript
+import { ChromaVector } from '@mastra/chroma';
+
+const vectorStore = new ChromaVector();
+```
+
+If you run a Chroma server locally with a different configuration, or [deploy](https://docs.trychroma.com/guides/deploy/client-server-mode) a Chroma server yourself, you can configure your `ChromaVector` instantiation with specific connection details:
+
+```typescript
+import { ChromaVector } from '@mastra/chroma';
+
+const vectorStore = new ChromaVector({
+  host: 'your-host-address',
+  port: 8000,
+  ssl: false,
+  headers: {}, // any HTTP headers to send,
+});
+```
+
+### Chroma Cloud
+
+Provide your Chroma Cloud API key, tenant, and database.
+
+You can use the [Chroma CLI](https://docs.trychroma.com/docs/cli/db) to set these as environment variables: `chroma db connect [DB-NAME] --env-file`.
 
 ```typescript
 import { ChromaVector } from '@mastra/chroma';
 
 const vectorStore = new ChromaVector({
-  path: 'http://localhost:8000',  // ChromaDB server URL
-  auth: {                         // Optional authentication
-    provider: 'token',
-    credentials: 'your-token'
-  }
+  apiKey: process.env.CHROMA_API_KEY,
+  tenant: process.env.CHROMA_TENANT,
+  database: process.env.CHROMA_DATABASE,
 });
+```
+
+## Usage
+
+```typescript
 
 // Create a new collection
 await vectorStore.createIndex({ indexName: 'myCollection', dimension: 1536, metric: 'cosine' });
@@ -46,18 +84,6 @@ const results = await vectorStore.query({
 });
 ```
 
-## Configuration
-
-Required:
-
-- `path`: URL of your ChromaDB server
-
-Optional:
-
-- `auth`: Authentication configuration
-  - `provider`: Authentication provider
-  - `credentials`: Authentication credentials
-
 ## Features
 
 - Vector similarity search with cosine, euclidean, and dot product metrics
@@ -92,5 +118,5 @@ Query results include:
 
 ## Related Links
 
-- [ChromaDB Documentation](https://docs.trychroma.com/)
-- [ChromaDB API Reference](https://docs.trychroma.com/api/client)
+- [Chroma Documentation](https://docs.trychroma.com/)
+- [Chroma API Reference](https://docs.trychroma.com/api/client)

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var error = require('@mastra/core/error');
 var vector = require('@mastra/core/vector');
 var chromadb = require('chromadb');
 var filter = require('@mastra/core/vector/filter');
@@ -23,7 +24,7 @@ var ChromaFilterTranslator = class extends filter.BaseFilterTranslator {
   }
   translateNode(node, currentPath = "") {
     if (this.isRegex(node)) {
-      throw new Error("Regex is not supported in Chroma");
+      throw new Error("Regex is supported in Chroma via the `documentFilter` argument");
     }
     if (this.isPrimitive(node)) return this.normalizeComparisonValue(node);
     if (Array.isArray(node)) return { $in: this.normalizeArrayValues(node) };
@@ -32,6 +33,9 @@ var ChromaFilterTranslator = class extends filter.BaseFilterTranslator {
     if (entries.length === 1 && firstEntry && this.isOperator(firstEntry[0])) {
       const [operator, value] = firstEntry;
       const translated = this.translateOperator(operator, value);
+      if (this.isLogicalOperator(operator) && Array.isArray(translated) && translated.length === 1) {
+        return translated[0];
+      }
       return this.isLogicalOperator(operator) ? { [operator]: translated } : translated;
     }
     const result = {};
@@ -89,31 +93,46 @@ var ChromaFilterTranslator = class extends filter.BaseFilterTranslator {
 };
 
 // src/vector/index.ts
+var spaceMappings = {
+  cosine: "cosine",
+  euclidean: "l2",
+  dotproduct: "ip",
+  l2: "euclidean",
+  ip: "dotproduct"
+};
 var ChromaVector = class extends vector.MastraVector {
   client;
   collections;
-  constructor({
-    path,
-    auth
-  }) {
+  constructor(chromaClientArgs) {
     super();
-    this.client = new chromadb.ChromaClient({
-      path,
-      auth
-    });
+    if (chromaClientArgs?.apiKey) {
+      this.client = new chromadb.CloudClient({
+        apiKey: chromaClientArgs.apiKey,
+        tenant: chromaClientArgs.tenant,
+        database: chromaClientArgs.database
+      });
+    } else {
+      this.client = new chromadb.ChromaClient(chromaClientArgs);
+    }
     this.collections = /* @__PURE__ */ new Map();
   }
-  async getCollection(indexName, throwIfNotExists = true) {
-    try {
-      const collection = await this.client.getCollection({ name: indexName, embeddingFunction: void 0 });
-      this.collections.set(indexName, collection);
-    } catch {
-      if (throwIfNotExists) {
-        throw new Error(`Index ${indexName} does not exist`);
+  async getCollection({ indexName, forceUpdate = false }) {
+    let collection = this.collections.get(indexName);
+    if (forceUpdate || !collection) {
+      try {
+        collection = await this.client.getCollection({ name: indexName });
+        this.collections.set(indexName, collection);
+        return collection;
+      } catch {
+        throw new error.MastraError({
+          id: "CHROMA_COLLECTION_GET_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        });
       }
-      return null;
     }
-    return this.collections.get(indexName);
+    return collection;
   }
   validateVectorDimensions(vectors, dimension) {
     for (let i = 0; i < vectors.length; i++) {
@@ -124,120 +143,295 @@ var ChromaVector = class extends vector.MastraVector {
       }
     }
   }
-  async upsert(...args) {
-    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);
-    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;
+  async upsert({ indexName, vectors, metadata, ids, documents }) {
+    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());
+      await collection.upsert({
+        ids: generatedIds,
+        embeddings: vectors,
+        metadatas: metadata,
+        documents
+      });
+      return generatedIds;
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_UPSERT_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error$1
+      );
+    }
   }
-  HnswSpaceMap = {
-    cosine: "cosine",
-    euclidean: "l2",
-    dotproduct: "ip",
-    l2: "euclidean",
-    ip: "dotproduct"
-  };
-  async createIndex(...args) {
-    const params = this.normalizeArgs("createIndex", args);
-    const { indexName, dimension, metric = "cosine" } = params;
+  async createIndex({ indexName, dimension, metric = "cosine" }) {
     if (!Number.isInteger(dimension) || dimension <= 0) {
-      throw new Error("Dimension must be a positive integer");
+      throw new error.MastraError({
+        id: "CHROMA_VECTOR_CREATE_INDEX_INVALID_DIMENSION",
+        text: "Dimension must be a positive integer",
+        domain: error.ErrorDomain.MASTRA_VECTOR,
+        category: error.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`);
+    const hnswSpace = spaceMappings[metric];
+    if (!hnswSpace || !["cosine", "l2", "ip"].includes(hnswSpace)) {
+      throw new error.MastraError({
+        id: "CHROMA_VECTOR_CREATE_INDEX_INVALID_METRIC",
+        text: `Invalid metric: "${metric}". Must be one of: cosine, euclidean, dotproduct`,
+        domain: error.ErrorDomain.MASTRA_VECTOR,
+        category: error.ErrorCategory.USER,
+        details: { metric }
+      });
     }
     try {
-      await this.client.createCollection({
+      const collection = await this.client.createCollection({
         name: indexName,
-        metadata: {
-          dimension,
-          "hnsw:space": hnswSpace
-        }
+        metadata: { dimension },
+        configuration: { hnsw: { space: hnswSpace } },
+        embeddingFunction: null
       });
-    } catch (error) {
-      const message = error?.message || error?.toString();
+      this.collections.set(indexName, collection);
+    } catch (error$1) {
+      const message = error$1?.message || error$1?.toString();
       if (message && message.toLowerCase().includes("already exists")) {
         await this.validateExistingIndex(indexName, dimension, metric);
         return;
       }
-      throw error;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_CREATE_INDEX_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error$1
+      );
     }
   }
   transformFilter(filter) {
     const translator = new ChromaFilterTranslator();
-    return translator.translate(filter);
+    const translatedFilter = translator.translate(filter);
+    return translatedFilter ? translatedFilter : void 0;
   }
-  async query(...args) {
-    const params = this.normalizeArgs("query", args, ["documentFilter"]);
-    const { indexName, queryVector, topK = 10, filter, includeVector = false, documentFilter } = params;
-    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] || [] }
-    }));
+  async query({
+    indexName,
+    queryVector,
+    topK = 10,
+    filter,
+    includeVector = false,
+    documentFilter
+  }) {
+    try {
+      const collection = await this.getCollection({ indexName });
+      const defaultInclude = ["documents", "metadatas", "distances"];
+      const translatedFilter = this.transformFilter(filter);
+      const results = await collection.query({
+        queryEmbeddings: [queryVector],
+        nResults: topK,
+        where: translatedFilter ?? void 0,
+        whereDocument: documentFilter ?? void 0,
+        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] ?? void 0,
+        ...includeVector && { vector: results.embeddings?.[0]?.[index] || [] }
+      }));
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_QUERY_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error$1
+      );
+    }
+  }
+  async get({
+    indexName,
+    ids,
+    filter,
+    includeVector = false,
+    documentFilter,
+    offset,
+    limit
+  }) {
+    try {
+      const collection = await this.getCollection({ indexName });
+      const defaultInclude = ["documents", "metadatas"];
+      const translatedFilter = this.transformFilter(filter);
+      const result = await collection.get({
+        ids,
+        where: translatedFilter ?? void 0,
+        whereDocument: documentFilter ?? void 0,
+        offset,
+        limit,
+        include: includeVector ? [...defaultInclude, "embeddings"] : defaultInclude
+      });
+      return result.rows();
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_GET_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error$1
+      );
+    }
   }
   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.name);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_LIST_INDEXES_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY
+        },
+        error$1
+      );
+    }
   }
-  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]
-    };
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param {string} indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex({ indexName }) {
+    try {
+      const collection = await this.getCollection({ indexName });
+      const count = await collection.count();
+      const metadata = collection.metadata;
+      const space = collection.configuration.hnsw?.space || collection.configuration.spann?.space || void 0;
+      return {
+        dimension: metadata?.dimension || 0,
+        count,
+        metric: space ? spaceMappings[space] : void 0
+      };
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_DESCRIBE_INDEX_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error$1
+      );
+    }
   }
-  async deleteIndex(indexName) {
-    await this.client.deleteCollection({ name: indexName });
-    this.collections.delete(indexName);
+  async deleteIndex({ indexName }) {
+    try {
+      await this.client.deleteCollection({ name: indexName });
+      this.collections.delete(indexName);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_DELETE_INDEX_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error$1
+      );
+    }
   }
-  async updateIndexById(indexName, id, update) {
-    if (!update.vector && !update.metadata) {
-      throw new Error("No updates provided");
+  async forkIndex({ indexName, newIndexName }) {
+    try {
+      const collection = await this.getCollection({ indexName, forceUpdate: true });
+      const forkedCollection = await collection.fork({ name: newIndexName });
+      this.collections.set(newIndexName, forkedCollection);
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_INDEX_FORK_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName }
+        },
+        error$1
+      );
     }
-    const collection = await this.getCollection(indexName, true);
-    const updateOptions = { ids: [id] };
-    if (update?.vector) {
-      updateOptions.embeddings = [update.vector];
+  }
+  /**
+   * 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({ indexName, id, update }) {
+    if (!update.vector && !update.metadata) {
+      throw new error.MastraError({
+        id: "CHROMA_VECTOR_UPDATE_NO_PAYLOAD",
+        text: "No updates provided for vector",
+        domain: error.ErrorDomain.MASTRA_VECTOR,
+        category: error.ErrorCategory.USER,
+        details: { indexName, id }
+      });
     }
-    if (update?.metadata) {
-      updateOptions.metadatas = [update.metadata];
+    try {
+      const collection = await this.getCollection({ indexName });
+      const updateRecordSet = { ids: [id] };
+      if (update?.vector) {
+        const stats = await this.describeIndex({ indexName });
+        this.validateVectorDimensions([update.vector], stats.dimension);
+        updateRecordSet.embeddings = [update.vector];
+      }
+      if (update?.metadata) {
+        updateRecordSet.metadatas = [update.metadata];
+      }
+      return await collection.update(updateRecordSet);
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_UPDATE_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName, id }
+        },
+        error$1
+      );
     }
-    return await collection.update(updateOptions);
   }
-  async deleteIndexById(indexName, id) {
+  async deleteVector({ indexName, id }) {
     try {
-      const collection = await this.getCollection(indexName, true);
+      const collection = await this.getCollection({ indexName });
       await collection.delete({ ids: [id] });
-    } catch (error) {
-      throw new Error(`Failed to delete index by id: ${id} for index name: ${indexName}: ${error.message}`);
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: "CHROMA_VECTOR_DELETE_FAILED",
+          domain: error.ErrorDomain.MASTRA_VECTOR,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { indexName, id }
+        },
+        error$1
+      );
     }
   }
 };
@@ -314,3 +508,5 @@ Example Complex Query:
 
 exports.CHROMA_PROMPT = CHROMA_PROMPT;
 exports.ChromaVector = ChromaVector;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map