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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @mastra/duckdb
 
+## 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
 
 ### Minor Changes

package/dist/docs/README.md

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

package/dist/docs/SKILL.md

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

package/dist/docs/SOURCE_MAP.json

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

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

@@ -0,0 +1,249 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: DuckDBVector Store
+
+> Documentation for the DuckDBVector class in Mastra, which provides embedded high-performance vector search using DuckDB with HNSW indexing.
+
+The DuckDB storage implementation provides an embedded high-performance vector search solution using [DuckDB](https://duckdb.org/), an in-process analytical database. It uses the VSS extension for vector similarity search with HNSW indexing, offering a lightweight and efficient vector database that requires no external server.
+
+It's part of the `@mastra/duckdb` package and offers efficient vector similarity search with metadata filtering.
+
+## Installation
+
+```bash
+npm install @mastra/duckdb@beta
+```
+
+## Usage
+
+```typescript
+import { DuckDBVector } from "@mastra/duckdb";
+
+// Create a new vector store instance
+const store = new DuckDBVector({
+  id: "duckdb-vector",
+  path: ":memory:", // or './vectors.duckdb' for file persistence
+});
+
+// Create an index
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+  metric: "cosine",
+});
+
+// Add vectors with metadata
+const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
+const metadata = [
+  { text: "first document", category: "A" },
+  { text: "second document", category: "B" },
+];
+await store.upsert({
+  indexName: "myCollection",
+  vectors,
+  metadata,
+});
+
+// Query similar vectors
+const queryVector = [0.1, 0.2, ...];
+const results = await store.query({
+  indexName: "myCollection",
+  queryVector,
+  topK: 10,
+  filter: { category: "A" },
+});
+
+// Clean up
+await store.close();
+```
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+Creates a new vector collection with optional HNSW index for fast approximate nearest neighbor search.
+
+### upsert()
+
+Adds or updates vectors and their metadata in the index.
+
+### query()
+
+Searches for similar vectors with optional metadata filtering.
+
+### describeIndex()
+
+Gets information about an 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 database.
+
+Returns: `Promise<string[]>`
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+### deleteVector()
+
+Deletes a specific vector entry from an index by its ID.
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### close()
+
+Closes the database connection and releases resources.
+
+```typescript
+await store.close();
+```
+
+## 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
+}
+```
+
+## Filter Operators
+
+DuckDB vector store supports MongoDB-like filter operators:
+
+| Category   | Operators                            |
+| ---------- | ------------------------------------ |
+| Comparison | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` |
+| Logical    | `$and`, `$or`, `$not`, `$nor`        |
+| Array      | `$in`, `$nin`                        |
+| Element    | `$exists`                            |
+| Text       | `$contains`                          |
+
+### Filter Examples
+
+```typescript
+// Allegato operators
+const results = await store.query({
+  indexName: "docs",
+  queryVector: [...],
+  filter: {
+    $and: [
+      { category: "electronics" },
+      { price: { $gte: 100, $lte: 500 } },
+    ],
+  },
+});
+
+// Nested field access
+const results = await store.query({
+  indexName: "docs",
+  queryVector: [...],
+  filter: { "user.profile.tier": "premium" },
+});
+```
+
+## Distance Metrics
+
+| Metric       | Description       | Score Interpretation         | Best For                              |
+| ------------ | ----------------- | ---------------------------- | ------------------------------------- |
+| `cosine`     | Cosine similarity | 0-1 (1 = most similar)       | Text embeddings, normalized vectors   |
+| `euclidean`  | L2 distance       | 0-∞ (0 = most similar)       | Image embeddings, spatial data        |
+| `dotproduct` | Inner product     | Higher = more similar        | When vector magnitude matters         |
+
+## Error Handling
+
+The store throws specific errors for different failure cases:
+
+```typescript
+try {
+  await store.query({
+    indexName: "my-collection",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error.message.includes("not found")) {
+    console.error("The specified index does not exist");
+  } else if (error.message.includes("Invalid identifier")) {
+    console.error("Index name contains invalid characters");
+  } else {
+    console.error("Vector store error:", error.message);
+  }
+}
+```
+
+Common error cases include:
+
+- Invalid index name format
+- Index/table not found
+- Dimension mismatch between query vector and index
+- Empty filter or ids array in delete/update operations
+- Mutual exclusivity violations (providing both `id` and `filter`)
+
+## Use Cases
+
+### Embedded Semantic Search
+
+Build offline-capable AI applications with semantic search that runs entirely in-process:
+
+```typescript
+const store = new DuckDBVector({
+  id: "offline-search",
+  path: "./search.duckdb",
+});
+```
+
+### Local RAG Pipelines
+
+Process sensitive documents locally without sending data to cloud vector databases:
+
+```typescript
+const store = new DuckDBVector({
+  id: "private-rag",
+  path: "./confidential.duckdb",
+  dimensions: 1536,
+});
+```
+
+### Development and Testing
+
+Rapidly prototype vector search features with zero infrastructure:
+
+```typescript
+const store = new DuckDBVector({
+  id: "dev-store",
+  path: ":memory:", // Fast in-memory for tests
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)
+- [DuckDB Documentation](https://duckdb.org/docs/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/duckdb",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "DuckDB vector store provider for Mastra - embedded high-performance vector storage with HNSW indexing",
   "type": "module",
   "main": "dist/index.js",
@@ -23,19 +23,18 @@
     "@duckdb/node-api": "1.4.2-r.1"
   },
   "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",
     "rimraf": "^5.0.7",
     "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.6",
-    "@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"
@@ -57,7 +56,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/duckdb",
     "build:watch": "tsup --watch --silent --config tsup.config.ts",
     "test": "vitest run",
     "lint": "eslint .",