@mastra/rag 2.0.0-beta.4 → 2.0.0-beta.5

package/dist/tools/graph-rag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-rag.d.ts","sourceRoot":"","sources":["../../src/tools/graph-rag.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAGnD,eAAO,MAAM,kBAAkB,GAAI,SAAS,mBAAmB,KAkJvD,OAAO;;;;;;;;;;;;;;;;;;;;;kCAAqB,GAAG,CACtC,CAAC"}
+{"version":3,"file":"graph-rag.d.ts","sourceRoot":"","sources":["../../src/tools/graph-rag.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,SAAS,CAAC;AAGpE,eAAO,MAAM,kBAAkB,GAAI,SAAS,mBAAmB,KA+HvD,OAAO;;;;;;;;;;;;;;;;;;;;;kCAAqB,GAAG,CACtC,CAAC"}

package/dist/tools/index.d.ts

@@ -1,4 +1,5 @@
 export * from './document-chunker.js';
 export * from './graph-rag.js';
 export * from './vector-query.js';
+export type { VectorStoreResolver, VectorStoreResolverContext, VectorQueryToolOptions, GraphRagToolOptions, DatabaseConfig, PineconeConfig, PgVectorConfig, ChromaConfig, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/tools/types.d.ts

@@ -1,5 +1,33 @@
-import type { MastraVector, MastraEmbeddingModel } from '@mastra/core/vector';
+import type { MastraUnion } from '@mastra/core/action';
+import type { RequestContext } from '@mastra/core/request-context';
+import type { MastraVector, MastraEmbeddingModel, MastraEmbeddingOptions } from '@mastra/core/vector';
 import type { RerankConfig } from '../rerank/index.js';
+/**
+ * Context passed to dynamic vector store resolver functions.
+ * Enables multi-tenant setups where the vector store is selected based on request context.
+ */
+export interface VectorStoreResolverContext {
+    /** The request context containing tenant/schema information */
+    requestContext?: RequestContext;
+    /** The Mastra instance for accessing registered resources */
+    mastra?: MastraUnion;
+}
+/**
+ * A function that dynamically resolves a vector store based on the execution context.
+ * Useful for multi-tenant applications where each tenant has a separate schema/database.
+ *
+ * @example
+ * ```typescript
+ * const vectorStoreResolver: VectorStoreResolver = async ({ requestContext }) => {
+ *   const schemaId = requestContext?.get('schemaId');
+ *   return new PgVector({
+ *     connectionString: process.env.DATABASE_URL,
+ *     schemaName: `tenant_${schemaId}`,
+ *   });
+ * };
+ * ```
+ */
+export type VectorStoreResolver = (context: VectorStoreResolverContext) => MastraVector | Promise<MastraVector>;
 export interface PineconeConfig {
     namespace?: string;
     sparseVector?: {
@@ -42,38 +70,175 @@ export type DatabaseConfig = {
     chroma?: ChromaConfig;
     [key: string]: any;
 };
+/**
+ * Configuration options for creating a vector query tool.
+ *
+ * This type uses a discriminated union pattern for vector store configuration,
+ * allowing two mutually exclusive approaches:
+ *
+ * 1. **By name**: Use `vectorStoreName` to reference a vector store registered with Mastra
+ * 2. **Direct instance**: Use `vectorStore` to provide a vector store instance or resolver function
+ *
+ * @example Using a named vector store (registered with Mastra)
+ * ```typescript
+ * const tool = createVectorQueryTool({
+ *   vectorStoreName: 'myVectorStore',
+ *   indexName: 'documents',
+ *   model: openai.embedding('text-embedding-3-small'),
+ * });
+ * ```
+ *
+ * @example Using a direct vector store instance
+ * ```typescript
+ * const tool = createVectorQueryTool({
+ *   vectorStore: new PgVector({ connectionString: '...' }),
+ *   indexName: 'documents',
+ *   model: openai.embedding('text-embedding-3-small'),
+ * });
+ * ```
+ *
+ * @example With filtering and reranking enabled
+ * ```typescript
+ * const tool = createVectorQueryTool({
+ *   vectorStoreName: 'myVectorStore',
+ *   indexName: 'documents',
+ *   model: openai.embedding('text-embedding-3-small'),
+ *   enableFilter: true,
+ *   reranker: {
+ *     model: cohere.rerank('rerank-v3.5'),
+ *     options: { topK: 5 },
+ *   },
+ * });
+ * ```
+ */
 export type VectorQueryToolOptions = {
+    /** Custom tool ID. Defaults to `VectorQuery {storeName} {indexName} Tool` */
     id?: string;
+    /** Custom tool description for the LLM */
     description?: string;
+    /** Name of the index to query within the vector store */
     indexName: string;
+    /** Embedding model used to convert query text into vectors */
     model: MastraEmbeddingModel<string>;
+    /** When true, enables metadata filtering in queries. Adds a `filter` input to the tool schema */
     enableFilter?: boolean;
+    /** When true, includes vector embeddings in the results. Defaults to false */
     includeVectors?: boolean;
+    /** When true, includes source documents in the response. Defaults to true */
     includeSources?: boolean;
+    /** Optional reranker configuration to improve result relevance */
     reranker?: RerankConfig;
     /** Database-specific configuration options */
     databaseConfig?: DatabaseConfig;
 } & ProviderOptions & ({
+    /** Name of a vector store registered with Mastra */
     vectorStoreName: string;
 } | {
     vectorStoreName?: string;
-    vectorStore: MastraVector;
+    /**
+     * The vector store instance or a resolver function for dynamic selection.
+     *
+     * For multi-tenant applications, pass a function that receives the request context
+     * and returns the appropriate vector store for the current tenant/schema.
+     *
+     * @example Static vector store
+     * ```typescript
+     * vectorStore: new PgVector({ connectionString: '...' })
+     * ```
+     *
+     * @example Dynamic resolver for multi-tenant
+     * ```typescript
+     * vectorStore: async ({ requestContext }) => {
+     *   const schemaId = requestContext?.get('schemaId');
+     *   return getVectorStoreForSchema(schemaId);
+     * }
+     * ```
+     */
+    vectorStore: MastraVector | VectorStoreResolver;
 });
+/**
+ * Configuration options for creating a GraphRAG tool.
+ *
+ * GraphRAG combines vector similarity search with graph-based retrieval for improved
+ * context relevance through random walk algorithms.
+ *
+ * This type uses a discriminated union pattern for vector store configuration,
+ * allowing two mutually exclusive approaches:
+ *
+ * 1. **By name**: Use `vectorStoreName` to reference a vector store registered with Mastra
+ * 2. **Direct instance**: Use `vectorStore` to provide a vector store instance or resolver function
+ *
+ * @example Using a named vector store
+ * ```typescript
+ * const tool = createGraphRAGTool({
+ *   vectorStoreName: 'myVectorStore',
+ *   indexName: 'documents',
+ *   model: openai.embedding('text-embedding-3-small'),
+ * });
+ * ```
+ *
+ * @example With custom graph options
+ * ```typescript
+ * const tool = createGraphRAGTool({
+ *   vectorStoreName: 'myVectorStore',
+ *   indexName: 'documents',
+ *   model: openai.embedding('text-embedding-3-small'),
+ *   graphOptions: {
+ *     randomWalkSteps: 200,
+ *     restartProb: 0.2,
+ *   },
+ * });
+ * ```
+ */
 export type GraphRagToolOptions = {
+    /** Custom tool ID. Defaults to `GraphRAG {storeName} {indexName} Tool` */
     id?: string;
+    /** Custom tool description for the LLM */
     description?: string;
+    /** Name of the index to query within the vector store */
     indexName: string;
-    vectorStoreName: string;
+    /** Embedding model used to convert query text into vectors */
     model: MastraEmbeddingModel<string>;
+    /** When true, enables metadata filtering in queries. Adds a `filter` input to the tool schema */
     enableFilter?: boolean;
+    /** When true, includes source documents in the response. Defaults to true */
     includeSources?: boolean;
+    /** Configuration options for the graph-based retrieval algorithm */
     graphOptions?: {
+        /** Vector dimension size. Defaults to 1536 */
         dimension?: number;
+        /** Number of steps in the random walk. Defaults to 100 */
         randomWalkSteps?: number;
+        /** Probability of restarting the random walk. Defaults to 0.15 */
         restartProb?: number;
+        /** Similarity threshold for graph edges. Defaults to 0.7 */
         threshold?: number;
     };
-} & ProviderOptions;
+} & ProviderOptions & ({
+    vectorStoreName: string;
+} | {
+    vectorStoreName?: string;
+    /**
+     * The vector store instance or a resolver function for dynamic selection.
+     *
+     * For multi-tenant applications, pass a function that receives the request context
+     * and returns the appropriate vector store for the current tenant/schema.
+     *
+     * @example Static vector store
+     * ```typescript
+     * vectorStore: new PgVector({ connectionString: '...' })
+     * ```
+     *
+     * @example Dynamic resolver for multi-tenant
+     * ```typescript
+     * vectorStore: async ({ requestContext }) => {
+     *   const schemaId = requestContext?.get('schemaId');
+     *   return getVectorStoreForSchema(schemaId);
+     * }
+     * ```
+     */
+    vectorStore: MastraVector | VectorStoreResolver;
+});
 export type ProviderOptions = {
     /**
      * Provider-specific options for the embedding model (e.g., outputDimensionality).
@@ -86,19 +251,11 @@ export type ProviderOptions = {
      * **For v2 models**: Use providerOptions:
      * ✅ providerOptions: { openai: { dimensions: 512 } }
      */
-    providerOptions?: Record<string, Record<string, any>>;
+    providerOptions?: MastraEmbeddingOptions['providerOptions'];
 };
 /**
  * Default options for GraphRAG
- * @default
- * ```json
- * {
- *   "dimension": 1536,
- *   "randomWalkSteps": 100,
- *   "restartProb": 0.15,
- *   "threshold": 0.7
- * }
- * ```
+ * @default { dimension: 1536, randomWalkSteps: 100, restartProb: 0.15, threshold: 0.7 }
  */
 export declare const defaultGraphOptions: {
     dimension: number;

package/dist/tools/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"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"}

package/dist/tools/vector-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector-query.d.ts","sourceRoot":"","sources":["../../src/tools/vector-query.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEtD,eAAO,MAAM,qBAAqB,GAAI,SAAS,sBAAsB,KA8J7D,OAAO;;;;;;;;;;;;;;;;;;;;;kCAAqB,GAAG,CACtC,CAAC"}
+{"version":3,"file":"vector-query.d.ts","sourceRoot":"","sources":["../../src/tools/vector-query.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,KAAK,EAAmB,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEvE,eAAO,MAAM,qBAAqB,GAAI,SAAS,sBAAsB,KAoI7D,OAAO;;;;;;;;;;;;;;;;;;;;;kCAAqB,GAAG,CACtC,CAAC"}

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './vector-search.js';
 export * from './default-settings.js';
 export * from './tool-schemas.js';
+export * from './tool-helpers.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/utils/tool-helpers.d.ts

@@ -0,0 +1,54 @@
+import type { MastraUnion } from '@mastra/core/action';
+import type { RequestContext } from '@mastra/core/request-context';
+import type { MastraVector } from '@mastra/core/vector';
+import type { VectorStoreResolver } from '../tools/types.js';
+interface Logger {
+    error(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Context for resolving vector stores.
+ */
+export interface ResolveVectorStoreContext {
+    requestContext?: RequestContext;
+    mastra?: MastraUnion;
+    /** Fallback vector store name to look up from mastra if vectorStore option is not provided */
+    vectorStoreName: string;
+    /**
+     * When true, logs a warning and falls back to mastra.getVector if an explicitly provided
+     * vectorStore is invalid. When false (default), throws an error for invalid vectorStore.
+     * @default false
+     */
+    fallbackOnInvalid?: boolean;
+}
+/**
+ * Resolves a vector store from options, supporting both static instances and dynamic resolver functions.
+ * For multi-tenant setups, the resolver function receives the request context to select the appropriate store.
+ *
+ * @param options - Tool options object that may contain a vectorStore property
+ * @param context - Context including requestContext, mastra instance, and fallback vectorStoreName
+ * @param logger - Optional logger for warning/error reporting
+ * @returns The resolved MastraVector instance, or undefined if not found
+ * @throws Error if an explicit vectorStore was provided but is invalid (unless fallbackOnInvalid is true)
+ */
+export declare function resolveVectorStore(options: {
+    vectorStore?: MastraVector | VectorStoreResolver;
+} | Record<string, unknown>, context: ResolveVectorStoreContext, logger?: Logger | null): Promise<MastraVector | undefined>;
+/**
+ * Coerces a topK value to a number, handling string inputs and providing a default.
+ * Validates that the result is a finite positive number greater than zero.
+ * @param topK - The value to coerce (number, string, or undefined)
+ * @param defaultValue - Default value if coercion fails (defaults to 10)
+ * @returns A valid positive number for topK, or defaultValue if invalid/non-finite/zero/negative
+ */
+export declare function coerceTopK(topK: number | string | undefined, defaultValue?: number): number;
+/**
+ * Parses a filter value, handling both string (JSON) and object inputs.
+ * @param filter - The filter value to parse (string or object)
+ * @param logger - Optional logger for error reporting
+ * @returns Parsed filter object
+ * @throws Error if filter is a string that cannot be parsed as JSON or if filter is not a plain object
+ */
+export declare function parseFilterValue(filter: unknown, logger?: Logger | null): Record<string, any>;
+export {};
+//# sourceMappingURL=tool-helpers.d.ts.map

package/dist/utils/tool-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/tool-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,UAAU,MAAM;IACd,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8FAA8F;IAC9F,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAoCD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,YAAY,GAAG,mBAAmB,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvF,OAAO,EAAE,yBAAyB,EAClC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CA+DnC;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,YAAY,GAAE,MAAW,GAAG,MAAM,CAe/F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA2B7F"}

package/dist/utils/vector-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector-search.d.ts","sourceRoot":"","sources":["../../src/utils/vector-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAqB,MAAM,qBAAqB,CAAC;AAE9G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtE,KAAK,uBAAuB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,YAAY,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,GAAG,eAAe,CAAC;AAEpB,UAAU,uBAAuB;IAC/B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAWD,eAAO,MAAM,iBAAiB,GAAU,+HAWrC,uBAAuB,KAAG,OAAO,CAAC,uBAAuB,CAwC3D,CAAC"}
+{"version":3,"file":"vector-search.d.ts","sourceRoot":"","sources":["../../src/utils/vector-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAqB,MAAM,qBAAqB,CAAC;AAE9G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtE,KAAK,uBAAuB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,YAAY,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,GAAG,eAAe,CAAC;AAEpB,UAAU,uBAAuB;IAC/B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAWD,eAAO,MAAM,iBAAiB,GAAU,+HAWrC,uBAAuB,KAAG,OAAO,CAAC,uBAAuB,CA0C3D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/rag",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.5",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
   "dependencies": {
     "@paralleldrive/cuid2": "^2.3.1",
     "big.js": "^7.0.1",
-    "js-tiktoken": "^1.0.20",
+    "js-tiktoken": "^1.0.21",
     "node-html-better-parser": "^1.5.8",
     "pathe": "^2.0.3",
     "zeroentropy": "0.1.0-alpha.6"
@@ -48,13 +48,13 @@
     "dotenv": "^17.0.0",
     "eslint": "^9.37.0",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
-    "vitest": "4.0.12",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.16",
     "zod": "^3.25.76",
     "@internal/ai-sdk-v4": "0.0.0",
     "@internal/lint": "0.0.53",
     "@internal/types-builder": "0.0.28",
-    "@mastra/core": "1.0.0-beta.14"
+    "@mastra/core": "1.0.0-beta.20"
   },
   "keywords": [
     "rag",
@@ -85,8 +85,9 @@
     "node": ">=22.13.0"
   },
   "scripts": {
-    "build": "tsup --silent --config tsup.config.ts",
-    "build:watch": "pnpm build --watch",
+    "build:lib": "tsup --silent --config tsup.config.ts",
+    "build:docs": "pnpx tsx ../../scripts/generate-package-docs.ts packages/rag",
+    "build:watch": "pnpm build:lib --watch",
     "vitest": "vitest",
     "test": "vitest run",
     "lint": "eslint ."