@mastra/astra 1.0.0-beta.2 → 1.0.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @mastra/astra
 
+## 1.0.0-beta.3
+
+### 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.2
 
 ### Patch Changes

package/dist/docs/README.md

@@ -0,0 +1,32 @@
+# @mastra/astra 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/ (2 files)
+├── vectors/ (1 files)
+```
+
+## Version
+
+Package: @mastra/astra
+Version: 1.0.0-beta.3

package/dist/docs/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mastra-astra-docs
+description: Documentation for @mastra/astra. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/astra Documentation
+
+> **Version**: 1.0.0-beta.3
+> **Package**: @mastra/astra
+
+## 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/) - 2 file(s)
+- [Vectors](vectors/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.0-beta.3",
+  "package": "@mastra/astra",
+  "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/rag/02-retrieval.md

@@ -0,0 +1,549 @@
+> Guide on retrieval processes in Mastra
+
+# Retrieval in RAG Systems
+
+After storing embeddings, you need to retrieve relevant chunks to answer user queries.
+
+Mastra provides flexible retrieval options with support for semantic search, filtering, and re-ranking.
+
+## How Retrieval Works
+
+1. The user's query is converted to an embedding using the same model used for document embeddings
+2. This embedding is compared to stored embeddings using vector similarity
+3. The most similar chunks are retrieved and can be optionally:
+
+- Filtered by metadata
+- Re-ranked for better relevance
+- Processed through a knowledge graph
+
+## Basic Retrieval
+
+The simplest approach is direct semantic search. This method uses vector similarity to find chunks that are semantically similar to the query:
+
+```ts
+import { embed } from "ai";
+import { PgVector } from "@mastra/pg";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+// Convert query to embedding
+const { embedding } = await embed({
+  value: "What are the main points in the article?",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+});
+
+// Query vector store
+const pgVector = new PgVector({
+  id: 'pg-vector',
+  connectionString: process.env.POSTGRES_CONNECTION_STRING,
+});
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+});
+
+// Display results
+console.log(results);
+```
+
+The `topK` parameter specifies the maximum number of most similar results to return from the vector search.
+
+Results include both the text content and a similarity score:
+
+```ts
+[
+  {
+    text: "Climate change poses significant challenges...",
+    score: 0.89,
+    metadata: { source: "article1.txt" },
+  },
+  {
+    text: "Rising temperatures affect crop yields...",
+    score: 0.82,
+    metadata: { source: "article1.txt" },
+  },
+];
+```
+
+## Advanced Retrieval options
+
+### Metadata Filtering
+
+Filter results based on metadata fields to narrow down the search space. This approach - combining vector similarity search with metadata filters - is sometimes called hybrid vector search, as it merges semantic search with structured filtering criteria.
+
+This is useful when you have documents from different sources, time periods, or with specific attributes. Mastra provides a unified MongoDB-style query syntax that works across all supported vector stores.
+
+For detailed information about available operators and syntax, see the [Metadata Filters Reference](https://mastra.ai/reference/v1/rag/metadata-filters).
+
+Basic filtering examples:
+
+```ts
+// Simple equality filter
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    source: "article1.txt",
+  },
+});
+
+// Numeric comparison
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    price: { $gt: 100 },
+  },
+});
+
+// Multiple conditions
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    category: "electronics",
+    price: { $lt: 1000 },
+    inStock: true,
+  },
+});
+
+// Array operations
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    tags: { $in: ["sale", "new"] },
+  },
+});
+
+// Logical operators
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    $or: [{ category: "electronics" }, { category: "accessories" }],
+    $and: [{ price: { $gt: 50 } }, { price: { $lt: 200 } }],
+  },
+});
+```
+
+Common use cases for metadata filtering:
+
+- Filter by document source or type
+- Filter by date ranges
+- Filter by specific categories or tags
+- Filter by numerical ranges (e.g., price, rating)
+- Combine multiple conditions for precise querying
+- Filter by document attributes (e.g., language, author)
+
+### Vector Query Tool
+
+Sometimes you want to give your agent the ability to query a vector database directly. The Vector Query Tool allows your agent to be in charge of retrieval decisions, combining semantic search with optional filtering and reranking based on the agent's understanding of the user's needs.
+
+```ts
+import { createVectorQueryTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+});
+```
+
+When creating the tool, pay special attention to the tool's name and description - these help the agent understand when and how to use the retrieval capabilities. For example, you might name it "SearchKnowledgeBase" and describe it as "Search through our documentation to find relevant information about X topic."
+
+This is particularly useful when:
+
+- Your agent needs to dynamically decide what information to retrieve
+- The retrieval process requires complex decision-making
+- You want the agent to combine multiple retrieval strategies based on context
+
+#### Database-Specific Configurations
+
+The Vector Query Tool supports database-specific configurations that enable you to leverage unique features and optimizations of different vector stores.
+
+> **Note:**
+These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup. 
+
+Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ connectionUrl: '...' })`).
+
+```ts
+import { createVectorQueryTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+// Pinecone with namespace
+const pineconeQueryTool = createVectorQueryTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    pinecone: {
+      namespace: "production", // Isolate data by environment
+    },
+  },
+});
+
+// pgVector with performance tuning
+const pgVectorQueryTool = createVectorQueryTool({
+  vectorStoreName: "postgres",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    pgvector: {
+      minScore: 0.7, // Filter low-quality results
+      ef: 200, // HNSW search parameter
+      probes: 10, // IVFFlat probe parameter
+    },
+  },
+});
+
+// Chroma with advanced filtering
+const chromaQueryTool = createVectorQueryTool({
+  vectorStoreName: "chroma",
+  indexName: "documents",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    chroma: {
+      where: { category: "technical" },
+      whereDocument: { $contains: "API" },
+    },
+  },
+});
+
+// LanceDB with table specificity
+const lanceQueryTool = createVectorQueryTool({
+  vectorStoreName: "lance",
+  indexName: "documents",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    lance: {
+      tableName: "myVectors", // Specify which table to query
+      includeAllColumns: true, // Include all metadata columns in results
+    },
+  },
+});
+```
+
+**Key Benefits:**
+
+- **Pinecone namespaces**: Organize vectors by tenant, environment, or data type
+- **pgVector optimization**: Control search accuracy and speed with ef/probes parameters
+- **Quality filtering**: Set minimum similarity thresholds to improve result relevance
+- **LanceDB tables**: Separate data into tables for better organization and performance
+- **Runtime flexibility**: Override configurations dynamically based on context
+
+**Common Use Cases:**
+
+- Multi-tenant applications using Pinecone namespaces
+- Performance optimization in high-load scenarios
+- Environment-specific configurations (dev/staging/prod)
+- Quality-gated search results
+- Embedded, file-based vector storage with LanceDB for edge deployment scenarios
+
+You can also override these configurations at runtime using the request context:
+
+```ts
+import { RequestContext } from "@mastra/core/request-context";
+
+const requestContext = new RequestContext();
+requestContext.set("databaseConfig", {
+  pinecone: {
+    namespace: "runtime-namespace",
+  },
+});
+
+await pineconeQueryTool.execute({
+  context: { queryText: "search query" },
+  mastra,
+  requestContext,
+});
+```
+
+For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/v1/tools/vector-query-tool).
+
+### Vector Store Prompts
+
+Vector store prompts define query patterns and filtering capabilities for each vector database implementation.
+When implementing filtering, these prompts are required in the agent's instructions to specify valid operators and syntax for each vector store implementation.
+
+  **pgvector:**
+
+```ts
+import { PGVECTOR_PROMPT } from "@mastra/pg";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${PGVECTOR_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **pinecone:**
+
+```ts title="vector-store.ts"
+import { PINECONE_PROMPT } from "@mastra/pinecone";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${PINECONE_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **qdrant:**
+
+```ts title="vector-store.ts"
+import { QDRANT_PROMPT } from "@mastra/qdrant";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${QDRANT_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **chroma:**
+
+```ts title="vector-store.ts"
+import { CHROMA_PROMPT } from "@mastra/chroma";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${CHROMA_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **astra:**
+
+```ts title="vector-store.ts"
+import { ASTRA_PROMPT } from "@mastra/astra";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${ASTRA_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **libsql:**
+
+```ts title="vector-store.ts"
+import { LIBSQL_PROMPT } from "@mastra/libsql";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${LIBSQL_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **upstash:**
+
+```ts title="vector-store.ts"
+import { UPSTASH_PROMPT } from "@mastra/upstash";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${UPSTASH_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **vectorize:**
+
+```ts title="vector-store.ts"
+import { VECTORIZE_PROMPT } from "@mastra/vectorize";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${VECTORIZE_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **mongodb:**
+
+```ts title="vector-store.ts"
+import { MONGODB_PROMPT } from "@mastra/mongodb";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${MONGODB_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **opensearch:**
+
+```ts title="vector-store.ts"
+import { OPENSEARCH_PROMPT } from "@mastra/opensearch";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${OPENSEARCH_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+  **s3vectors:**
+
+```ts title="vector-store.ts"
+import { S3VECTORS_PROMPT } from "@mastra/s3vectors";
+
+export const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  model: "openai/gpt-5.1",
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${S3VECTORS_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+  
+
+### Re-ranking
+
+Initial vector similarity search can sometimes miss nuanced relevance. Re-ranking is a more computationally expensive process, but more accurate algorithm that improves results by:
+
+- Considering word order and exact matches
+- Applying more sophisticated relevance scoring
+- Using a method called cross-attention between query and documents
+
+Here's how to use re-ranking:
+
+```ts
+import {
+  rerankWithScorer as rerank,
+  MastraAgentRelevanceScorer
+} from "@mastra/rag";
+
+// Get initial results from vector search
+const initialResults = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: queryEmbedding,
+  topK: 10,
+});
+
+// Create a relevance scorer
+const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', "openai/gpt-5.1");
+
+// Re-rank the results
+const rerankedResults = await rerank({
+  results: initialResults,
+  query,
+  scorer: relevanceProvider,
+  options: {
+    weights: {
+      semantic: 0.5, // How well the content matches the query semantically
+      vector: 0.3, // Original vector similarity score
+      position: 0.2, // Preserves original result ordering
+    },
+    topK: 10,
+  },
+);
+```
+
+The weights control how different factors influence the final ranking:
+
+- `semantic`: Higher values prioritize semantic understanding and relevance to the query
+- `vector`: Higher values favor the original vector similarity scores
+- `position`: Higher values help maintain the original ordering of results
+
+> **Note:**
+For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+
+You can also use other relevance score providers like Cohere or ZeroEntropy:
+
+```ts
+const relevanceProvider = new CohereRelevanceScorer("rerank-v3.5");
+```
+
+```ts
+const relevanceProvider = new ZeroEntropyRelevanceScorer("zerank-1");
+```
+
+The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
+
+For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/v1/rag/rerankWithScorer) method.
+
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/v1/rag/graph-rag) documentation.

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

@@ -0,0 +1,87 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: Astra Vector Store
+
+> Documentation for the AstraVector class in Mastra, which provides vector search using DataStax Astra DB.
+
+The AstraVector class provides vector search using [DataStax Astra DB](https://www.datastax.com/products/datastax-astra), a cloud-native, serverless database built on Apache Cassandra.
+It provides vector search capabilities with enterprise-grade scalability and high availability.
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+### upsert()
+
+### query()
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+### updateVector()
+
+### deleteVector()
+
+## 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: "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
+  }
+}
+```
+
+## Environment Variables
+
+Required environment variables:
+
+- `ASTRA_DB_TOKEN`: Your Astra DB API token
+- `ASTRA_DB_ENDPOINT`: Your Astra DB API endpoint
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/astra",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "Astra DB provider for Mastra - includes vector store capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -27,17 +27,16 @@
     "@datastax/astra-db-ts": "^1.5.0"
   },
   "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/types-builder": "0.0.28",
-    "@mastra/core": "1.0.0-beta.7"
+    "@mastra/core": "1.0.0-beta.20"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.0.0-0 <2.0.0-0"
@@ -55,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/astra",
     "build:watch": "tsup --watch --silent --config tsup.config.ts",
     "test": "vitest run",
     "lint": "eslint ."