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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @mastra/couchbase
 
+## 1.0.0-beta.4
+
+### Patch Changes
+
+- Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
+
+  Mastra packages now include embedded documentation in the published npm package under `dist/docs/`. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from `node_modules`.
+
+  Each package includes:
+  - **SKILL.md** - Entry point explaining the package's purpose and capabilities
+  - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
+  - **Topic folders** - Conceptual documentation organized by feature area
+
+  Documentation is driven by the `packages` frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
+
+- Updated dependencies [[`d2d3e22`](https://github.com/mastra-ai/mastra/commit/d2d3e22a419ee243f8812a84e3453dd44365ecb0), [`bc72b52`](https://github.com/mastra-ai/mastra/commit/bc72b529ee4478fe89ecd85a8be47ce0127b82a0), [`05b8bee`](https://github.com/mastra-ai/mastra/commit/05b8bee9e50e6c2a4a2bf210eca25ee212ca24fa), [`c042bd0`](https://github.com/mastra-ai/mastra/commit/c042bd0b743e0e86199d0cb83344ca7690e34a9c), [`940a2b2`](https://github.com/mastra-ai/mastra/commit/940a2b27480626ed7e74f55806dcd2181c1dd0c2), [`e0941c3`](https://github.com/mastra-ai/mastra/commit/e0941c3d7fc75695d5d258e7008fd5d6e650800c), [`0c0580a`](https://github.com/mastra-ai/mastra/commit/0c0580a42f697cd2a7d5973f25bfe7da9055038a), [`28f5f89`](https://github.com/mastra-ai/mastra/commit/28f5f89705f2409921e3c45178796c0e0d0bbb64), [`e601b27`](https://github.com/mastra-ai/mastra/commit/e601b272c70f3a5ecca610373aa6223012704892), [`3d3366f`](https://github.com/mastra-ai/mastra/commit/3d3366f31683e7137d126a3a57174a222c5801fb), [`5a4953f`](https://github.com/mastra-ai/mastra/commit/5a4953f7d25bb15ca31ed16038092a39cb3f98b3), [`eb9e522`](https://github.com/mastra-ai/mastra/commit/eb9e522ce3070a405e5b949b7bf5609ca51d7fe2), [`20e6f19`](https://github.com/mastra-ai/mastra/commit/20e6f1971d51d3ff6dd7accad8aaaae826d540ed), [`4f0b3c6`](https://github.com/mastra-ai/mastra/commit/4f0b3c66f196c06448487f680ccbb614d281e2f7), [`74c4f22`](https://github.com/mastra-ai/mastra/commit/74c4f22ed4c71e72598eacc346ba95cdbc00294f), [`81b6a8f`](https://github.com/mastra-ai/mastra/commit/81b6a8ff79f49a7549d15d66624ac1a0b8f5f971), [`e4d366a`](https://github.com/mastra-ai/mastra/commit/e4d366aeb500371dd4210d6aa8361a4c21d87034), [`a4f010b`](https://github.com/mastra-ai/mastra/commit/a4f010b22e4355a5fdee70a1fe0f6e4a692cc29e), [`73b0bb3`](https://github.com/mastra-ai/mastra/commit/73b0bb394dba7c9482eb467a97ab283dbc0ef4db), [`5627a8c`](https://github.com/mastra-ai/mastra/commit/5627a8c6dc11fe3711b3fa7a6ffd6eb34100a306), [`3ff45d1`](https://github.com/mastra-ai/mastra/commit/3ff45d10e0c80c5335a957ab563da72feb623520), [`251df45`](https://github.com/mastra-ai/mastra/commit/251df4531407dfa46d805feb40ff3fb49769f455), [`f894d14`](https://github.com/mastra-ai/mastra/commit/f894d148946629af7b1f452d65a9cf864cec3765), [`c2b9547`](https://github.com/mastra-ai/mastra/commit/c2b9547bf435f56339f23625a743b2147ab1c7a6), [`580b592`](https://github.com/mastra-ai/mastra/commit/580b5927afc82fe460dfdf9a38a902511b6b7e7f), [`58e3931`](https://github.com/mastra-ai/mastra/commit/58e3931af9baa5921688566210f00fb0c10479fa), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`4fba91b`](https://github.com/mastra-ai/mastra/commit/4fba91bec7c95911dc28e369437596b152b04cd0), [`12b0cc4`](https://github.com/mastra-ai/mastra/commit/12b0cc4077d886b1a552637dedb70a7ade93528c)]:
+  - @mastra/core@1.0.0-beta.20
+
 ## 1.0.0-beta.3
 
 ### Patch Changes

package/dist/docs/README.md

@@ -0,0 +1,32 @@
+# @mastra/couchbase Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── rag/ (1 files)
+├── vectors/ (1 files)
+```
+
+## Version
+
+Package: @mastra/couchbase
+Version: 1.0.0-beta.4

package/dist/docs/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mastra-couchbase-docs
+description: Documentation for @mastra/couchbase. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/couchbase Documentation
+
+> **Version**: 1.0.0-beta.4
+> **Package**: @mastra/couchbase
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Rag](rag/) - 1 file(s)
+- [Vectors](vectors/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.0-beta.4",
+  "package": "@mastra/couchbase",
+  "exports": {},
+  "modules": {}
+}

package/dist/docs/rag/01-vector-databases.md

@@ -0,0 +1,638 @@
+> Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
+
+# Storing Embeddings in A Vector Database
+
+After generating embeddings, you need to store them in a database that supports vector similarity search. Mastra provides a consistent interface for storing and querying embeddings across various vector databases.
+
+## Supported Databases
+
+  **mongodb:**
+
+```ts title="vector-store.ts"
+import { MongoDBVector } from "@mastra/mongodb";
+
+const store = new MongoDBVector({
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+});
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+### Using MongoDB Atlas Vector search
+
+For detailed setup instructions and best practices, see the [official MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=mastra-docs).
+
+  
+
+  **pg-vector:**
+
+```ts title="vector-store.ts"
+import { PgVector } from "@mastra/pg";
+
+const store = new PgVector({
+  id: 'pg-vector',
+  connectionString: process.env.POSTGRES_CONNECTION_STRING,
+});
+
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+### Using PostgreSQL with pgvector
+
+PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity.
+For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
+
+  
+
+  **pinecone:**
+
+```ts title="vector-store.ts"
+import { PineconeVector } from "@mastra/pinecone";
+
+const store = new PineconeVector({
+  id: 'pinecone-vector',
+  apiKey: process.env.PINECONE_API_KEY,
+});
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **qdrant:**
+
+```ts title="vector-store.ts"
+import { QdrantVector } from "@mastra/qdrant";
+
+const store = new QdrantVector({
+  id: 'qdrant-vector',
+  url: process.env.QDRANT_URL,
+  apiKey: process.env.QDRANT_API_KEY,
+});
+
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **chroma:**
+
+```ts title="vector-store.ts"
+import { ChromaVector } from "@mastra/chroma";
+
+// Running Chroma locally
+// const store = new ChromaVector()
+
+// Running on Chroma Cloud
+const store = new ChromaVector({
+  id: 'chroma-vector',
+  apiKey: process.env.CHROMA_API_KEY,
+  tenant: process.env.CHROMA_TENANT,
+  database: process.env.CHROMA_DATABASE,
+});
+
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **astra:**
+
+```ts title="vector-store.ts"
+import { AstraVector } from "@mastra/astra";
+
+const store = new AstraVector({
+  token: process.env.ASTRA_DB_TOKEN,
+  endpoint: process.env.ASTRA_DB_ENDPOINT,
+  keyspace: process.env.ASTRA_DB_KEYSPACE,
+});
+
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **libsql:**
+
+```ts title="vector-store.ts"
+import { LibSQLVector } from "@mastra/core/vector/libsql";
+
+const store = new LibSQLVector({
+  id: 'libsql-vector',
+  connectionUrl: process.env.DATABASE_URL,
+  authToken: process.env.DATABASE_AUTH_TOKEN, // Optional: for Turso cloud databases
+});
+
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **upstash:**
+
+```ts title="vector-store.ts"
+import { UpstashVector } from "@mastra/upstash";
+
+// In upstash they refer to the store as an index
+const store = new UpstashVector({
+  id: 'upstash-vector',
+  url: process.env.UPSTASH_URL,
+  token: process.env.UPSTASH_TOKEN,
+});
+
+// There is no store.createIndex call here, Upstash creates indexes (known as namespaces in Upstash) automatically
+// when you upsert if that namespace does not exist yet.
+await store.upsert({
+  indexName: "myCollection", // the namespace name in Upstash
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **cloudflare:**
+
+```ts title="vector-store.ts"
+import { CloudflareVector } from "@mastra/vectorize";
+
+const store = new CloudflareVector({
+  accountId: process.env.CF_ACCOUNT_ID,
+  apiToken: process.env.CF_API_TOKEN,
+});
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **opensearch:**
+
+```ts title="vector-store.ts"
+import { OpenSearchVector } from "@mastra/opensearch";
+
+const store = new OpenSearchVector({ url: process.env.OPENSEARCH_URL });
+
+await store.createIndex({
+  indexName: "my-collection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  indexName: "my-collection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+  **elasticsearch:**
+
+```ts title="vector-store.ts"
+import { ElasticSearchVector } from "@mastra/elasticsearch";
+
+const store = new ElasticSearchVector({ url: process.env.ELASTICSEARCH_URL });
+
+await store.createIndex({
+  indexName: "my-collection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  indexName: "my-collection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+  **couchbase:**
+
+```ts title="vector-store.ts"
+import { CouchbaseVector } from "@mastra/couchbase";
+
+const store = new CouchbaseVector({
+  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
+  username: process.env.COUCHBASE_USERNAME,
+  password: process.env.COUCHBASE_PASSWORD,
+  bucketName: process.env.COUCHBASE_BUCKET,
+  scopeName: process.env.COUCHBASE_SCOPE,
+  collectionName: process.env.COUCHBASE_COLLECTION,
+});
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+  **lancedb:**
+
+```ts title="vector-store.ts"
+import { LanceVectorStore } from "@mastra/lance";
+
+const store = await LanceVectorStore.create("/path/to/db");
+
+await store.createIndex({
+  tableName: "myVectors",
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+await store.upsert({
+  tableName: "myVectors",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+### Using LanceDB
+
+LanceDB is an embedded vector database built on the Lance columnar format, suitable for local development or cloud deployment.
+For detailed setup instructions and best practices, see the [official LanceDB documentation](https://lancedb.github.io/lancedb/).
+
+  
+  **s3vectors:**
+
+```ts title="vector-store.ts"
+import { S3Vectors } from "@mastra/s3vectors";
+
+const store = new S3Vectors({
+  vectorBucketName: "my-vector-bucket",
+  clientConfig: {
+    region: "us-east-1",
+  },
+  nonFilterableMetadataKeys: ["content"],
+});
+
+await store.createIndex({
+  indexName: "my-index",
+  dimension: 1536,
+});
+await store.upsert({
+  indexName: "my-index",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  
+
+## Using Vector Storage
+
+Once initialized, all vector stores share the same interface for creating indexes, upserting embeddings, and querying.
+
+### Creating Indexes
+
+Before storing embeddings, you need to create an index with the appropriate dimension size for your embedding model:
+
+```ts title="store-embeddings.ts"
+// Create an index with dimension 1536 (for text-embedding-3-small)
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+```
+
+The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
+
+- OpenAI text-embedding-3-small: 1536 dimensions (or custom, e.g., 256)
+- Cohere embed-multilingual-v3: 1024 dimensions
+- Google text-embedding-004: 768 dimensions (or custom)
+
+important
+Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
+
+### Naming Rules for Databases
+
+Each vector database enforces specific naming conventions for indexes and collections to ensure compatibility and prevent conflicts.
+
+  **mongodb:**
+
+    Collection (index) names must:
+    - Start with a letter or underscore
+    - Be up to 120 bytes long
+    - Contain only letters, numbers, underscores, or dots
+    - Cannot contain `$` or the null character
+    - Example: `my_collection.123` is valid
+    - Example: `my-index` is not valid (contains hyphen)
+    - Example: `My$Collection` is not valid (contains `$`)
+  
+  **pgVector:**
+
+    Index names must:
+    - Start with a letter or underscore
+    - Contain only letters, numbers, and underscores
+    - Example: `my_index_123` is valid
+    - Example: `my-index` is not valid (contains hyphen)
+  
+  **pinecone:**
+
+    Index names must:
+    - Use only lowercase letters, numbers, and dashes
+    - Not contain dots (used for DNS routing)
+    - Not use non-Latin characters or emojis
+    - Have a combined length (with project ID) under 52 characters
+      - Example: `my-index-123` is valid
+      - Example: `my.index` is not valid (contains dot)
+  
+  **qdrant:**
+
+    Collection names must:
+    - Be 1-255 characters long
+    - Not contain any of these special characters:
+      - `< > : " / \ | ? *`
+      - Null character (`\0`)
+      - Unit separator (`\u{1F}`)
+    - Example: `my_collection_123` is valid
+    - Example: `my/collection` is not valid (contains slash)
+  
+  **chroma:**
+
+    Collection names must:
+    - Be 3-63 characters long
+    - Start and end with a letter or number
+    - Contain only letters, numbers, underscores, or hyphens
+    - Not contain consecutive periods (..)
+    - Not be a valid IPv4 address
+    - Example: `my-collection-123` is valid
+    - Example: `my..collection` is not valid (consecutive periods)
+  
+  **astra:**
+
+    Collection names must:
+    - Not be empty
+    - Be 48 characters or less
+    - Contain only letters, numbers, and underscores
+    - Example: `my_collection_123` is valid
+    - Example: `my-collection` is not valid (contains hyphen)
+  
+  **libsql:**
+
+    Index names must:
+    - Start with a letter or underscore
+    - Contain only letters, numbers, and underscores
+    - Example: `my_index_123` is valid
+    - Example: `my-index` is not valid (contains hyphen)
+  
+  **upstash:**
+
+    Namespace names must:
+    - Be 2-100 characters long
+    - Contain only:
+      - Alphanumeric characters (a-z, A-Z, 0-9)
+      - Underscores, hyphens, dots
+    - Not start or end with special characters (_, -, .)
+    - Can be case-sensitive
+    - Example: `MyNamespace123` is valid
+    - Example: `_namespace` is not valid (starts with underscore)
+  
+  **cloudflare:**
+
+    Index names must:
+    - Start with a letter
+    - Be shorter than 32 characters
+    - Contain only lowercase ASCII letters, numbers, and dashes
+    - Use dashes instead of spaces
+    - Example: `my-index-123` is valid
+    - Example: `My_Index` is not valid (uppercase and underscore)
+  
+  **opensearch:**
+
+    Index names must:
+    - Use only lowercase letters
+    - Not begin with underscores or hyphens
+    - Not contain spaces, commas
+    - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
+    - Example: `my-index-123` is valid
+    - Example: `My_Index` is not valid (contains uppercase letters)
+    - Example: `_myindex` is not valid (begins with underscore)
+  
+  **elasticsearch:**
+
+    Index names must:
+    - Use only lowercase letters
+    - Not exceed 255 bytes (counting multi-byte characters)
+    - Not begin with underscores, hyphens, or plus signs
+    - Not contain spaces, commas
+    - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
+    - Not be "." or ".."
+    - Not start with "." (deprecated except for system/hidden indices)
+    - Example: `my-index-123` is valid
+    - Example: `My_Index` is not valid (contains uppercase letters)
+    - Example: `_myindex` is not valid (begins with underscore)
+    - Example: `.myindex` is not valid (begins with dot, deprecated)
+  
+  **s3vectors:**
+
+    Index names must:
+    - Be unique within the same vector bucket
+    - Be 3–63 characters long
+    - Use only lowercase letters (`a–z`), numbers (`0–9`), hyphens (`-`), and dots (`.`)
+    - Begin and end with a letter or number
+    - Example: `my-index.123` is valid
+    - Example: `my_index` is not valid (contains underscore)
+    - Example: `-myindex` is not valid (begins with hyphen)
+    - Example: `myindex-` is not valid (ends with hyphen)
+    - Example: `MyIndex` is not valid (contains uppercase letters)
+  
+
+### Upserting Embeddings
+
+After creating an index, you can store embeddings along with their basic metadata:
+
+```ts title="store-embeddings.ts"
+// Store embeddings with their corresponding metadata
+await store.upsert({
+  indexName: "myCollection", // index name
+  vectors: embeddings, // array of embedding vectors
+  metadata: chunks.map((chunk) => ({
+    text: chunk.text, // The original text content
+    id: chunk.id, // Optional unique identifier
+  })),
+});
+```
+
+The upsert operation:
+
+- Takes an array of embedding vectors and their corresponding metadata
+- Updates existing vectors if they share the same ID
+- Creates new vectors if they don't exist
+- Automatically handles batching for large datasets
+
+## Adding Metadata
+
+Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
+
+important
+Metadata is crucial for vector storage - without it, you'd only have numerical embeddings with no way to return the original text or filter results. Always store at least the source text as metadata.
+
+```ts
+// Store embeddings with rich metadata for better organization and filtering
+await store.upsert({
+  indexName: "myCollection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({
+    // Basic content
+    text: chunk.text,
+    id: chunk.id,
+
+    // Document organization
+    source: chunk.source,
+    category: chunk.category,
+
+    // Temporal metadata
+    createdAt: new Date().toISOString(),
+    version: "1.0",
+
+    // Custom fields
+    language: chunk.language,
+    author: chunk.author,
+    confidenceScore: chunk.score,
+  })),
+});
+```
+
+Key metadata considerations:
+
+- Be strict with field naming - inconsistencies like 'category' vs 'Category' will affect queries
+- Only include fields you plan to filter or sort by - extra fields add overhead
+- Add timestamps (e.g., 'createdAt', 'lastUpdated') to track content freshness
+
+## Deleting Vectors
+
+When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it easy to remove all embeddings associated with a specific document.
+
+### Delete by Metadata Filter
+
+The most common use case is deleting all vectors for a specific document when a user deletes it:
+
+```ts title="delete-vectors.ts"
+// Delete all vectors for a specific document
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: { docId: "document-123" },
+});
+```
+
+This is particularly useful when:
+- A user deletes a document and you need to remove all its chunks
+- You're re-indexing a document and want to remove old vectors first
+- You need to clean up vectors for a specific user or tenant
+
+### Delete Multiple Documents
+
+You can also use complex filters to delete vectors matching multiple conditions:
+
+```ts title="delete-vectors-advanced.ts"
+// Delete all vectors for multiple documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    docId: { $in: ["doc-1", "doc-2", "doc-3"] },
+  },
+});
+
+// Delete vectors for a specific user's documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    $and: [
+      { userId: "user-123" },
+      { status: "archived" },
+    ],
+  },
+});
+```
+
+### Delete by Vector IDs
+
+If you have specific vector IDs to delete, you can pass them directly:
+
+```ts title="delete-by-ids.ts"
+// Delete specific vectors by their IDs
+await store.deleteVectors({
+  indexName: "myCollection",
+  ids: ["vec-1", "vec-2", "vec-3"],
+});
+```
+
+## Best Practices
+
+- Create indexes before bulk insertions
+- Use batch operations for large insertions (the upsert method handles batching automatically)
+- Only store metadata you'll query against
+- Match embedding dimensions to your model (e.g., 1536 for `text-embedding-3-small`)

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

@@ -0,0 +1,155 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: Couchbase Vector Store
+
+> Documentation for the CouchbaseVector class in Mastra, which provides vector search using Couchbase Vector Search.
+
+The `CouchbaseVector` class provides vector search using [Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html). It enables efficient similarity search and metadata filtering within your Couchbase collections.
+
+## Requirements
+
+- **Couchbase Server 7.6.4+** or a compatible Capella cluster
+- **Search Service enabled** on your Couchbase deployment
+
+## Installation
+
+```bash
+npm install @mastra/couchbase@beta
+```
+
+## Usage Example
+
+```typescript
+import { CouchbaseVector } from "@mastra/couchbase";
+
+const store = new CouchbaseVector({
+  id: 'couchbase-vector',
+  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
+  username: process.env.COUCHBASE_USERNAME,
+  password: process.env.COUCHBASE_PASSWORD,
+  bucketName: process.env.COUCHBASE_BUCKET,
+  scopeName: process.env.COUCHBASE_SCOPE,
+  collectionName: process.env.COUCHBASE_COLLECTION,
+});
+```
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+Creates a new vector index in Couchbase.
+
+> **Note:** Index creation is asynchronous. After calling `createIndex`, allow time (typically 1–5 seconds for small datasets, longer for large ones) before querying. For production, implement polling to check index status rather than using fixed delays.
+
+### upsert()
+
+Adds or updates vectors and their metadata in the collection.
+
+> **Note:** You can upsert data before or after creating the index. The `upsert` method does not require the index to exist. Couchbase allows multiple Search indexes over the same collection.
+
+### query()
+
+Searches for similar vectors.
+
+> **Warning:** The `filter` and `includeVector` parameters are not currently supported. Filtering must be performed client-side after retrieving results, or by using the Couchbase SDK's Search capabilities directly. To retrieve the vector embedding, fetch the full document by ID using the Couchbase SDK.
+
+### describeIndex()
+
+Returns information about the index.
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+Deletes an index and all its data.
+
+### listIndexes()
+
+Lists all vector indexes in the Couchbase bucket.
+
+Returns: `Promise<string[]>`
+
+### updateVector()
+
+Updates a specific vector entry by its ID with new vector data and/or metadata. **Note:** Filter-based updates are not yet implemented for Couchbase.
+
+### deleteVector()
+
+Deletes a single vector by its ID from the index.
+
+### deleteVectors()
+
+Deletes multiple vectors by their IDs. **Note:** Filter-based deletion is not yet implemented for Couchbase.
+
+### disconnect()
+
+Closes the Couchbase client connection. Should be called when done using the store.
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  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: "my_index",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes("Invalid index name")) {
+    console.error(
+      "Index name must start with a letter or underscore and contain only valid characters.",
+    );
+  } else if (error.message.includes("Index not found")) {
+    console.error("The specified index does not exist");
+  } else {
+    console.error("Vector store error:", error.message);
+  }
+}
+```
+
+## Notes
+
+- **Index Deletion Caveat:** Deleting a Search index does NOT delete the vectors/documents in the associated Couchbase collection. Data remains unless explicitly removed.
+- **Required Permissions:** The Couchbase user must have permissions to connect, read/write documents in the target collection (`kv` role), and manage Search Indexes (`search_admin` role on the relevant bucket/scope).
+- **Index Definition Details & Document Structure:** The `createIndex` method constructs a Search Index definition that indexes the `embedding` field (as type `vector`) and the `content` field (as type `text`), targeting documents within the specified `scopeName.collectionName`. Each document stores the vector in the `embedding` field and metadata in the `metadata` field. If `metadata` contains a `text` property, its value is also copied to a top-level `content` field, which is indexed for text search.
+- **Replication & Durability:** Consider using Couchbase's built-in replication and persistence features for data durability. Monitor index statistics regularly to ensure efficient search.
+
+## Limitations
+
+- Index creation delays may impact immediate querying after creation.
+- No hard enforcement of vector dimension at ingest time (dimension mismatches will error at query time).
+- Vector insertion and index updates are eventually consistent; strong consistency is not guaranteed immediately after writes.
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/couchbase",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "description": "Couchbase vector store provider for Mastra",
   "type": "module",
   "main": "dist/index.js",
@@ -22,19 +22,17 @@
     "couchbase": "^4.6.0"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.52.8",
     "@types/node": "22.13.17",
     "@vitest/coverage-v8": "4.0.12",
     "@vitest/ui": "4.0.12",
-    "axios": "^1.12.2",
     "eslint": "^9.37.0",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
-    "vitest": "4.0.12",
-    "@internal/lint": "0.0.53",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.16",
+    "@internal/types-builder": "0.0.28",
     "@internal/storage-test-utils": "0.0.49",
-    "@mastra/core": "1.0.0-beta.7",
-    "@internal/types-builder": "0.0.28"
+    "@internal/lint": "0.0.53",
+    "@mastra/core": "1.0.0-beta.20"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.0.0-0 <2.0.0-0"
@@ -56,7 +54,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/couchbase",
     "build:watch": "tsup --watch --silent --config tsup.config.ts",
     "lint": "eslint .",
     "coverage": "vitest run --coverage",