@mastra/chroma 0.11.4 → 0.11.7-alpha.0

package/src/vector/index.ts

@@ -1,418 +0,0 @@
-import { MastraError, ErrorDomain, ErrorCategory } from '@mastra/core/error';
-import { MastraVector } from '@mastra/core/vector';
-import type {
-  QueryResult,
-  IndexStats,
-  CreateIndexParams,
-  UpsertVectorParams,
-  QueryVectorParams,
-  DescribeIndexParams,
-  DeleteIndexParams,
-  DeleteVectorParams,
-  UpdateVectorParams,
-} from '@mastra/core/vector';
-import { ChromaClient, CloudClient } from 'chromadb';
-import type { ChromaClientArgs, RecordSet, Where, WhereDocument, Collection, Metadata } from 'chromadb';
-import type { ChromaVectorFilter } from './filter';
-import { ChromaFilterTranslator } from './filter';
-
-interface ChromaUpsertVectorParams extends UpsertVectorParams {
-  documents?: string[];
-}
-
-interface ChromaQueryVectorParams extends QueryVectorParams<ChromaVectorFilter> {
-  documentFilter?: WhereDocument | null;
-}
-
-interface ChromaGetRecordsParams {
-  indexName: string;
-  ids?: string[];
-  filter?: ChromaVectorFilter;
-  documentFilter?: WhereDocument | null;
-  includeVector?: boolean;
-  limit?: number;
-  offset?: number;
-}
-
-type MastraMetadata = {
-  dimension?: number;
-};
-
-type ChromaVectorArgs = ChromaClientArgs & { apiKey?: string };
-
-const spaceMappings = {
-  cosine: 'cosine',
-  euclidean: 'l2',
-  dotproduct: 'ip',
-  l2: 'euclidean',
-  ip: 'dotproduct',
-};
-
-export class ChromaVector extends MastraVector<ChromaVectorFilter> {
-  private client: ChromaClient;
-  private collections: Map<string, Collection>;
-
-  constructor(chromaClientArgs?: ChromaVectorArgs) {
-    super();
-    if (chromaClientArgs?.apiKey) {
-      this.client = new CloudClient({
-        apiKey: chromaClientArgs.apiKey,
-        tenant: chromaClientArgs.tenant,
-        database: chromaClientArgs.database,
-      });
-    } else {
-      this.client = new ChromaClient(chromaClientArgs);
-    }
-    this.collections = new Map();
-  }
-
-  async getCollection({ indexName, forceUpdate = false }: { indexName: string; forceUpdate?: boolean }) {
-    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 MastraError({
-          id: 'CHROMA_COLLECTION_GET_FAILED',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        });
-      }
-    }
-    return collection;
-  }
-
-  private validateVectorDimensions(vectors: number[][], dimension: number): void {
-    for (let i = 0; i < vectors.length; i++) {
-      if (vectors?.[i]?.length !== dimension) {
-        throw new Error(
-          `Vector at index ${i} has invalid dimension ${vectors?.[i]?.length}. Expected ${dimension} dimensions.`,
-        );
-      }
-    }
-  }
-
-  async upsert({ indexName, vectors, metadata, ids, documents }: ChromaUpsertVectorParams): Promise<string[]> {
-    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: documents,
-      });
-
-      return generatedIds;
-    } catch (error: any) {
-      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,
-      );
-    }
-  }
-
-  async createIndex({ indexName, dimension, metric = 'cosine' }: CreateIndexParams): Promise<void> {
-    if (!Number.isInteger(dimension) || dimension <= 0) {
-      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 = spaceMappings[metric] as 'cosine' | 'l2' | 'ip' | undefined;
-
-    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 {
-      const collection = await this.client.createCollection({
-        name: indexName,
-        metadata: { dimension },
-        configuration: { hnsw: { space: hnswSpace } },
-        embeddingFunction: null,
-      });
-      this.collections.set(indexName, collection);
-    } catch (error: any) {
-      // Check for 'already exists' error
-      const message = error?.message || error?.toString();
-      if (message && message.toLowerCase().includes('already exists')) {
-        // Fetch collection info and check dimension
-        await this.validateExistingIndex(indexName, dimension, metric);
-        return;
-      }
-      throw new MastraError(
-        {
-          id: 'CHROMA_VECTOR_CREATE_INDEX_FAILED',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  transformFilter(filter?: ChromaVectorFilter) {
-    const translator = new ChromaFilterTranslator();
-    const translatedFilter = translator.translate(filter);
-    return translatedFilter ? (translatedFilter as Where) : undefined;
-  }
-
-  async query<T extends Metadata = Metadata>({
-    indexName,
-    queryVector,
-    topK = 10,
-    filter,
-    includeVector = false,
-    documentFilter,
-  }: ChromaQueryVectorParams): Promise<QueryResult[]> {
-    try {
-      const collection = await this.getCollection({ indexName });
-
-      const defaultInclude: ['documents', 'metadatas', 'distances'] = ['documents', 'metadatas', 'distances'];
-
-      const translatedFilter = this.transformFilter(filter);
-      const results = await collection.query<T>({
-        queryEmbeddings: [queryVector],
-        nResults: topK,
-        where: translatedFilter ?? undefined,
-        whereDocument: documentFilter ?? undefined,
-        include: includeVector ? [...defaultInclude, 'embeddings'] : defaultInclude,
-      });
-
-      return (results.ids[0] || []).map((id: string, index: number) => ({
-        id,
-        score: results.distances?.[0]?.[index] || 0,
-        metadata: results.metadatas?.[0]?.[index] || {},
-        document: results.documents?.[0]?.[index] ?? undefined,
-        ...(includeVector && { vector: results.embeddings?.[0]?.[index] || [] }),
-      }));
-    } catch (error: any) {
-      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 get<T extends Metadata = Metadata>({
-    indexName,
-    ids,
-    filter,
-    includeVector = false,
-    documentFilter,
-    offset,
-    limit,
-  }: ChromaGetRecordsParams) {
-    try {
-      const collection = await this.getCollection({ indexName });
-
-      const defaultInclude: ['documents', 'metadatas'] = ['documents', 'metadatas'];
-      const translatedFilter = this.transformFilter(filter);
-
-      const result = await collection.get<T>({
-        ids,
-        where: translatedFilter ?? undefined,
-        whereDocument: documentFilter ?? undefined,
-        offset,
-        limit,
-        include: includeVector ? [...defaultInclude, 'embeddings'] : defaultInclude,
-      });
-      return result.rows();
-    } catch (error: any) {
-      if (error instanceof MastraError) throw error;
-      throw new MastraError(
-        {
-          id: 'CHROMA_VECTOR_GET_FAILED',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  async listIndexes(): Promise<string[]> {
-    try {
-      const collections = await this.client.listCollections();
-      return collections.map(collection => collection.name);
-    } catch (error: any) {
-      throw new MastraError(
-        {
-          id: 'CHROMA_VECTOR_LIST_INDEXES_FAILED',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-        },
-        error,
-      );
-    }
-  }
-
-  /**
-   * 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 }: DescribeIndexParams): Promise<IndexStats> {
-    try {
-      const collection = await this.getCollection({ indexName });
-      const count = await collection.count();
-      const metadata = collection.metadata as MastraMetadata | undefined;
-      const space = collection.configuration.hnsw?.space || collection.configuration.spann?.space || undefined;
-
-      return {
-        dimension: metadata?.dimension || 0,
-        count,
-        metric: space ? (spaceMappings[space] as 'cosine' | 'euclidean' | 'dotproduct') : undefined,
-      };
-    } catch (error: any) {
-      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 }: DeleteIndexParams): Promise<void> {
-    try {
-      await this.client.deleteCollection({ name: indexName });
-      this.collections.delete(indexName);
-    } catch (error: any) {
-      throw new MastraError(
-        {
-          id: 'CHROMA_VECTOR_DELETE_INDEX_FAILED',
-          domain: ErrorDomain.MASTRA_VECTOR,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { indexName },
-        },
-        error,
-      );
-    }
-  }
-
-  async forkIndex({ indexName, newIndexName }: { indexName: string; newIndexName: string }): Promise<void> {
-    try {
-      const collection = await this.getCollection({ indexName, forceUpdate: true });
-      const forkedCollection = await collection.fork({ name: newIndexName });
-      this.collections.set(newIndexName, forkedCollection);
-    } catch (error: any) {
-      if (error instanceof MastraError) throw error;
-      throw new MastraError(
-        {
-          id: 'CHROMA_INDEX_FORK_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.
-   * @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 }: UpdateVectorParams): Promise<void> {
-    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 {
-      const collection: Collection = await this.getCollection({ indexName });
-
-      const updateRecordSet: RecordSet = { 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: any) {
-      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,
-      );
-    }
-  }
-
-  async deleteVector({ indexName, id }: DeleteVectorParams): Promise<void> {
-    try {
-      const collection: Collection = await this.getCollection({ indexName });
-      await collection.delete({ ids: [id] });
-    } catch (error: any) {
-      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/src/vector/prompt.ts

@@ -1,72 +0,0 @@
-/**
- * Vector store specific prompt that details supported operators and examples.
- * This prompt helps users construct valid filters for Chroma Vector.
- */
-export const 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 }
-    ]}
-  ]
-}`;

package/tsconfig.build.json

@@ -1,9 +0,0 @@
-{
-  "extends": ["./tsconfig.json", "../../tsconfig.build.json"],
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "**/*.test.ts", "src/**/*.mock.ts"]
-}

package/tsconfig.json

@@ -1,5 +0,0 @@
-{
-  "extends": "../../tsconfig.node.json",
-  "include": ["src/**/*", "tsup.config.ts"],
-  "exclude": ["node_modules", "**/*.test.ts"]
-}

package/tsup.config.ts

@@ -1,17 +0,0 @@
-import { generateTypes } from '@internal/types-builder';
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: ['src/index.ts'],
-  format: ['esm', 'cjs'],
-  clean: true,
-  dts: false,
-  splitting: true,
-  treeshake: {
-    preset: 'smallest',
-  },
-  sourcemap: true,
-  onSuccess: async () => {
-    await generateTypes(process.cwd());
-  },
-});

package/vitest.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    environment: 'node',
-    include: ['src/**/*.test.ts'],
-  },
-});