@mastra/chroma 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/docs/vectors/01-reference.md

@@ -0,0 +1,189 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: Chroma Vector Store
+
+> Documentation for the ChromaVector class in Mastra, which provides vector search using ChromaDB.
+
+The ChromaVector class provides vector search using [Chroma](https://docs.trychroma.com/docs/overview/getting-started), an open-source embedding database.
+It offers efficient vector search with metadata filtering and hybrid search capabilities.
+
+> **Note:**
+
+<b>Chroma Cloud</b>
+
+    Chroma Cloud powers serverless vector and full-text search. It's extremely fast, cost-effective, scalable and painless. Create a DB and try it out in under 30 seconds with $5 of free credits.
+
+    [Get started with Chroma Cloud](https://trychroma.com/signup)
+
+## Constructor Options
+
+## Running a Chroma Server
+
+If you are a Chroma Cloud user, simply provide the `ChromaVector` constructor your API key, tenant, and database name.
+
+When you install the `@mastra/chroma` package, you get access to the [Chroma CLI](https://docs.trychroma.com/docs/cli/db), which can set these as environment variables for you: `chroma db connect [DB-NAME] --env-file`.
+
+Otherwise, you have several options for setting up your single-node Chroma server:
+
+- Run one locally using the Chroma CLI: `chroma run`. You can find more configuration options on the [Chroma docs](https://docs.trychroma.com/docs/cli/run).
+- Run on [Docker](https://docs.trychroma.com/guides/deploy/docker) using the official Chroma image.
+- Deploy your own Chroma server on your provider of choice. Chroma offers example templates for [AWS](https://docs.trychroma.com/guides/deploy/aws), [Azure](https://docs.trychroma.com/guides/deploy/azure), and [GCP](https://docs.trychroma.com/guides/deploy/gcp).
+
+## Methods
+
+### createIndex()
+
+### forkIndex()
+
+Note: Forking is only supported on Chroma Cloud, or if you deploy your own OSS **distributed** Chroma.
+
+`forkIndex` lets you fork an existing Chroma index instantly. Operations on the forked index do not affect the original one. Learn more on the [Chroma docs](https://docs.trychroma.com/cloud/collection-forking).
+
+### upsert()
+
+### query()
+
+Query an index using a `queryVector`. Returns an array of semantically similar records in order of distance from the `queryVector`. Each record has the shape:
+
+```typescript
+{
+  id: string;
+  score: number;
+  document?: string;
+  metadata?: Record<string, string | number | boolean>;
+  embedding?: number[]
+}
+```
+
+You can also provide the shape of your metadata to a `query` call for type inference: `query<T>()`.
+
+### get()
+
+Get records from your Chroma index by IDs, metadata, and document filters. It returns an array of records of the shape:
+
+```typescript
+{
+  id: string;
+  document?: string;
+  metadata?: Record<string, string | number | boolean>;
+  embedding?: number[]
+}
+```
+
+You can also provide the shape of your metadata to a `get` call for type inference: `get<T>()`.
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+The `update` object can contain:
+
+Example:
+
+```typescript
+// Update by ID
+await vectorStore.updateVector({
+  indexName: 'docs',
+  id: 'vec_123',
+  update: { metadata: { status: 'reviewed' } }
+});
+
+// Update by filter
+await vectorStore.updateVector({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' },
+  update: { metadata: { version: 2 } }
+});
+```
+
+### deleteVector()
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. This method enables bulk deletion and source-based vector management. Either `ids` or `filter` must be provided, but not both.
+
+Example:
+
+```typescript
+// Delete all chunks from a document
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' }
+});
+
+// Delete multiple vectors by ID
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  ids: ['vec_1', 'vec_2', 'vec_3']
+});
+
+// Delete old temporary documents
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: {
+    $and: [
+      { bucket: 'temp' },
+      { indexed_at: { $lt: '2025-01-01' } }
+    ]
+  }
+});
+```
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  document?: string; // Chroma-specific: Original document if it was stored
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: "index_name",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details); // Additional error context
+  }
+}
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/chroma",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "description": "Chroma vector store provider for Mastra",
   "type": "module",
   "main": "dist/index.js",
@@ -23,18 +23,17 @@
     "chromadb": "^3.1.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.52.8",
     "@types/node": "22.13.17",
     "@vitest/coverage-v8": "4.0.12",
     "@vitest/ui": "4.0.12",
     "eslint": "^9.37.0",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
-    "vitest": "4.0.12",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.16",
     "@internal/lint": "0.0.53",
     "@internal/storage-test-utils": "0.0.49",
-    "@mastra/core": "1.0.0-beta.11",
-    "@internal/types-builder": "0.0.28"
+    "@internal/types-builder": "0.0.28",
+    "@mastra/core": "1.0.0-beta.20"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.0.0-0 <2.0.0-0"
@@ -56,7 +55,8 @@
     "node": ">=22.13.0"
   },
   "scripts": {
-    "build": "tsup --silent --config tsup.config.ts",
+    "build:lib": "tsup --silent --config tsup.config.ts",
+    "build:docs": "pnpx tsx ../../scripts/generate-package-docs.ts stores/chroma",
     "build:watch": "tsup --watch --silent --config tsup.config.ts",
     "pretest": "docker compose up -d",
     "posttest": "docker compose down -v",