@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (556) hide show
  1. package/.docs/docs/agents/adding-voice.md +349 -0
  2. package/.docs/docs/agents/agent-approval.md +558 -0
  3. package/.docs/docs/agents/agent-memory.md +209 -0
  4. package/.docs/docs/agents/guardrails.md +374 -0
  5. package/.docs/docs/agents/network-approval.md +275 -0
  6. package/.docs/docs/agents/networks.md +299 -0
  7. package/.docs/docs/agents/overview.md +304 -0
  8. package/.docs/docs/agents/processors.md +622 -0
  9. package/.docs/docs/agents/structured-output.md +273 -0
  10. package/.docs/docs/agents/supervisor-agents.md +304 -0
  11. package/.docs/docs/agents/using-tools.md +214 -0
  12. package/.docs/docs/build-with-ai/mcp-docs-server.md +238 -0
  13. package/.docs/docs/build-with-ai/skills.md +35 -0
  14. package/.docs/docs/community/contributing-templates.md +3 -0
  15. package/.docs/docs/community/discord.md +9 -0
  16. package/.docs/docs/community/licensing.md +66 -0
  17. package/.docs/docs/deployment/cloud-providers.md +15 -0
  18. package/.docs/docs/deployment/mastra-server.md +122 -0
  19. package/.docs/docs/deployment/monorepo.md +142 -0
  20. package/.docs/docs/deployment/overview.md +62 -0
  21. package/.docs/docs/deployment/studio.md +239 -0
  22. package/.docs/docs/deployment/web-framework.md +52 -0
  23. package/.docs/docs/deployment/workflow-runners.md +9 -0
  24. package/.docs/docs/evals/built-in-scorers.md +47 -0
  25. package/.docs/docs/evals/custom-scorers.md +519 -0
  26. package/.docs/docs/evals/overview.md +141 -0
  27. package/.docs/docs/evals/running-in-ci.md +124 -0
  28. package/.docs/docs/getting-started/build-with-ai.md +68 -0
  29. package/.docs/docs/getting-started/manual-install.md +226 -0
  30. package/.docs/docs/getting-started/project-structure.md +60 -0
  31. package/.docs/docs/getting-started/start.md +28 -0
  32. package/.docs/docs/getting-started/studio.md +101 -0
  33. package/.docs/docs/index.md +43 -0
  34. package/.docs/docs/mastra-cloud/deployment.md +77 -0
  35. package/.docs/docs/mastra-cloud/observability.md +38 -0
  36. package/.docs/docs/mastra-cloud/overview.md +23 -0
  37. package/.docs/docs/mastra-cloud/setup.md +42 -0
  38. package/.docs/docs/mastra-cloud/studio.md +24 -0
  39. package/.docs/docs/mastra-code/configuration.md +299 -0
  40. package/.docs/docs/mastra-code/customization.md +228 -0
  41. package/.docs/docs/mastra-code/modes.md +104 -0
  42. package/.docs/docs/mastra-code/overview.md +135 -0
  43. package/.docs/docs/mastra-code/tools.md +229 -0
  44. package/.docs/docs/mcp/overview.md +373 -0
  45. package/.docs/docs/mcp/publishing-mcp-server.md +95 -0
  46. package/.docs/docs/memory/memory-processors.md +314 -0
  47. package/.docs/docs/memory/message-history.md +260 -0
  48. package/.docs/docs/memory/observational-memory.md +248 -0
  49. package/.docs/docs/memory/overview.md +45 -0
  50. package/.docs/docs/memory/semantic-recall.md +272 -0
  51. package/.docs/docs/memory/storage.md +261 -0
  52. package/.docs/docs/memory/working-memory.md +400 -0
  53. package/.docs/docs/observability/datasets/overview.md +198 -0
  54. package/.docs/docs/observability/datasets/running-experiments.md +274 -0
  55. package/.docs/docs/observability/logging.md +99 -0
  56. package/.docs/docs/observability/overview.md +70 -0
  57. package/.docs/docs/observability/tracing/bridges/otel.md +209 -0
  58. package/.docs/docs/observability/tracing/exporters/arize.md +272 -0
  59. package/.docs/docs/observability/tracing/exporters/braintrust.md +111 -0
  60. package/.docs/docs/observability/tracing/exporters/cloud.md +127 -0
  61. package/.docs/docs/observability/tracing/exporters/datadog.md +187 -0
  62. package/.docs/docs/observability/tracing/exporters/default.md +209 -0
  63. package/.docs/docs/observability/tracing/exporters/laminar.md +100 -0
  64. package/.docs/docs/observability/tracing/exporters/langfuse.md +213 -0
  65. package/.docs/docs/observability/tracing/exporters/langsmith.md +198 -0
  66. package/.docs/docs/observability/tracing/exporters/otel.md +476 -0
  67. package/.docs/docs/observability/tracing/exporters/posthog.md +148 -0
  68. package/.docs/docs/observability/tracing/exporters/sentry.md +208 -0
  69. package/.docs/docs/observability/tracing/overview.md +1112 -0
  70. package/.docs/docs/observability/tracing/processors/sensitive-data-filter.md +300 -0
  71. package/.docs/docs/rag/chunking-and-embedding.md +183 -0
  72. package/.docs/docs/rag/graph-rag.md +215 -0
  73. package/.docs/docs/rag/overview.md +72 -0
  74. package/.docs/docs/rag/retrieval.md +515 -0
  75. package/.docs/docs/rag/vector-databases.md +645 -0
  76. package/.docs/docs/server/auth/auth0.md +220 -0
  77. package/.docs/docs/server/auth/better-auth.md +203 -0
  78. package/.docs/docs/server/auth/clerk.md +132 -0
  79. package/.docs/docs/server/auth/composite-auth.md +234 -0
  80. package/.docs/docs/server/auth/custom-auth-provider.md +513 -0
  81. package/.docs/docs/server/auth/firebase.md +272 -0
  82. package/.docs/docs/server/auth/jwt.md +110 -0
  83. package/.docs/docs/server/auth/simple-auth.md +180 -0
  84. package/.docs/docs/server/auth/supabase.md +117 -0
  85. package/.docs/docs/server/auth/workos.md +186 -0
  86. package/.docs/docs/server/auth.md +38 -0
  87. package/.docs/docs/server/custom-adapters.md +378 -0
  88. package/.docs/docs/server/custom-api-routes.md +267 -0
  89. package/.docs/docs/server/mastra-client.md +243 -0
  90. package/.docs/docs/server/mastra-server.md +71 -0
  91. package/.docs/docs/server/middleware.md +225 -0
  92. package/.docs/docs/server/request-context.md +471 -0
  93. package/.docs/docs/server/server-adapters.md +547 -0
  94. package/.docs/docs/streaming/events.md +237 -0
  95. package/.docs/docs/streaming/overview.md +175 -0
  96. package/.docs/docs/streaming/tool-streaming.md +175 -0
  97. package/.docs/docs/streaming/workflow-streaming.md +109 -0
  98. package/.docs/docs/voice/overview.md +959 -0
  99. package/.docs/docs/voice/speech-to-speech.md +102 -0
  100. package/.docs/docs/voice/speech-to-text.md +79 -0
  101. package/.docs/docs/voice/text-to-speech.md +83 -0
  102. package/.docs/docs/workflows/agents-and-tools.md +166 -0
  103. package/.docs/docs/workflows/control-flow.md +822 -0
  104. package/.docs/docs/workflows/error-handling.md +360 -0
  105. package/.docs/docs/workflows/human-in-the-loop.md +215 -0
  106. package/.docs/docs/workflows/overview.md +370 -0
  107. package/.docs/docs/workflows/snapshots.md +238 -0
  108. package/.docs/docs/workflows/suspend-and-resume.md +205 -0
  109. package/.docs/docs/workflows/time-travel.md +309 -0
  110. package/.docs/docs/workflows/workflow-state.md +181 -0
  111. package/.docs/docs/workspace/filesystem.md +164 -0
  112. package/.docs/docs/workspace/overview.md +239 -0
  113. package/.docs/docs/workspace/sandbox.md +63 -0
  114. package/.docs/docs/workspace/search.md +243 -0
  115. package/.docs/docs/workspace/skills.md +169 -0
  116. package/.docs/guides/agent-frameworks/ai-sdk.md +140 -0
  117. package/.docs/guides/build-your-ui/ai-sdk-ui.md +1499 -0
  118. package/.docs/guides/build-your-ui/assistant-ui.md +156 -0
  119. package/.docs/guides/build-your-ui/copilotkit.md +289 -0
  120. package/.docs/guides/deployment/amazon-ec2.md +130 -0
  121. package/.docs/guides/deployment/aws-lambda.md +248 -0
  122. package/.docs/guides/deployment/azure-app-services.md +114 -0
  123. package/.docs/guides/deployment/cloudflare.md +99 -0
  124. package/.docs/guides/deployment/digital-ocean.md +168 -0
  125. package/.docs/guides/deployment/inngest.md +682 -0
  126. package/.docs/guides/deployment/netlify.md +77 -0
  127. package/.docs/guides/deployment/vercel.md +101 -0
  128. package/.docs/guides/getting-started/astro.md +398 -0
  129. package/.docs/guides/getting-started/electron.md +504 -0
  130. package/.docs/guides/getting-started/express.md +251 -0
  131. package/.docs/guides/getting-started/hono.md +190 -0
  132. package/.docs/guides/getting-started/next-js.md +347 -0
  133. package/.docs/guides/getting-started/nuxt.md +497 -0
  134. package/.docs/guides/getting-started/quickstart.md +67 -0
  135. package/.docs/guides/getting-started/sveltekit.md +296 -0
  136. package/.docs/guides/getting-started/vite-react.md +425 -0
  137. package/.docs/guides/guide/ai-recruiter.md +226 -0
  138. package/.docs/guides/guide/chef-michel.md +211 -0
  139. package/.docs/guides/guide/code-review-bot.md +226 -0
  140. package/.docs/guides/guide/dev-assistant.md +307 -0
  141. package/.docs/guides/guide/docs-manager.md +238 -0
  142. package/.docs/guides/guide/github-actions-pr-description.md +236 -0
  143. package/.docs/guides/guide/notes-mcp-server.md +416 -0
  144. package/.docs/guides/guide/research-assistant.md +348 -0
  145. package/.docs/guides/guide/research-coordinator.md +416 -0
  146. package/.docs/guides/guide/stock-agent.md +132 -0
  147. package/.docs/guides/guide/web-search.md +320 -0
  148. package/.docs/guides/guide/whatsapp-chat-bot.md +405 -0
  149. package/.docs/guides/index.md +3 -0
  150. package/.docs/guides/migrations/agentnetwork.md +97 -0
  151. package/.docs/guides/migrations/ai-sdk-v4-to-v5.md +112 -0
  152. package/.docs/guides/migrations/network-to-supervisor.md +261 -0
  153. package/.docs/guides/migrations/upgrade-to-v1/agent.md +404 -0
  154. package/.docs/guides/migrations/upgrade-to-v1/cli.md +57 -0
  155. package/.docs/guides/migrations/upgrade-to-v1/client.md +337 -0
  156. package/.docs/guides/migrations/upgrade-to-v1/deployment.md +37 -0
  157. package/.docs/guides/migrations/upgrade-to-v1/evals.md +239 -0
  158. package/.docs/guides/migrations/upgrade-to-v1/mastra.md +143 -0
  159. package/.docs/guides/migrations/upgrade-to-v1/mcp.md +97 -0
  160. package/.docs/guides/migrations/upgrade-to-v1/memory.md +285 -0
  161. package/.docs/guides/migrations/upgrade-to-v1/overview.md +119 -0
  162. package/.docs/guides/migrations/upgrade-to-v1/processors.md +68 -0
  163. package/.docs/guides/migrations/upgrade-to-v1/rag.md +42 -0
  164. package/.docs/guides/migrations/upgrade-to-v1/storage.md +553 -0
  165. package/.docs/guides/migrations/upgrade-to-v1/tools.md +180 -0
  166. package/.docs/guides/migrations/upgrade-to-v1/tracing.md +412 -0
  167. package/.docs/guides/migrations/upgrade-to-v1/vectors.md +87 -0
  168. package/.docs/guides/migrations/upgrade-to-v1/voice.md +30 -0
  169. package/.docs/guides/migrations/upgrade-to-v1/workflows.md +341 -0
  170. package/.docs/guides/migrations/vnext-to-standard-apis.md +362 -0
  171. package/.docs/models/embeddings.md +161 -0
  172. package/.docs/models/gateways/azure-openai.md +128 -0
  173. package/.docs/models/gateways/custom-gateways.md +545 -0
  174. package/.docs/models/gateways/netlify.md +88 -0
  175. package/.docs/models/gateways/openrouter.md +219 -0
  176. package/.docs/models/gateways/vercel.md +225 -0
  177. package/.docs/models/gateways.md +14 -0
  178. package/.docs/models/index.md +286 -0
  179. package/.docs/models/providers/302ai.md +134 -0
  180. package/.docs/models/providers/abacus.md +125 -0
  181. package/.docs/models/providers/agentrouter.md +90 -0
  182. package/.docs/models/providers/aihubmix.md +107 -0
  183. package/.docs/models/providers/alibaba-cn.md +135 -0
  184. package/.docs/models/providers/alibaba.md +111 -0
  185. package/.docs/models/providers/amazon-bedrock.md +33 -0
  186. package/.docs/models/providers/anthropic.md +153 -0
  187. package/.docs/models/providers/azure.md +33 -0
  188. package/.docs/models/providers/bailing.md +72 -0
  189. package/.docs/models/providers/baseten.md +77 -0
  190. package/.docs/models/providers/berget.md +78 -0
  191. package/.docs/models/providers/cerebras.md +101 -0
  192. package/.docs/models/providers/chutes.md +136 -0
  193. package/.docs/models/providers/cloudflare-ai-gateway.md +33 -0
  194. package/.docs/models/providers/cloudflare-workers-ai.md +109 -0
  195. package/.docs/models/providers/cohere.md +33 -0
  196. package/.docs/models/providers/cortecs.md +91 -0
  197. package/.docs/models/providers/deepinfra.md +112 -0
  198. package/.docs/models/providers/deepseek.md +88 -0
  199. package/.docs/models/providers/fastrouter.md +84 -0
  200. package/.docs/models/providers/fireworks-ai.md +89 -0
  201. package/.docs/models/providers/firmware.md +85 -0
  202. package/.docs/models/providers/friendli.md +78 -0
  203. package/.docs/models/providers/github-models.md +125 -0
  204. package/.docs/models/providers/google-vertex.md +33 -0
  205. package/.docs/models/providers/google.md +159 -0
  206. package/.docs/models/providers/groq.md +107 -0
  207. package/.docs/models/providers/helicone.md +161 -0
  208. package/.docs/models/providers/huggingface.md +90 -0
  209. package/.docs/models/providers/iflowcn.md +84 -0
  210. package/.docs/models/providers/inception.md +72 -0
  211. package/.docs/models/providers/inference.md +79 -0
  212. package/.docs/models/providers/io-intelligence.md +87 -0
  213. package/.docs/models/providers/io-net.md +87 -0
  214. package/.docs/models/providers/jiekou.md +131 -0
  215. package/.docs/models/providers/kilo.md +333 -0
  216. package/.docs/models/providers/kimi-for-coding.md +100 -0
  217. package/.docs/models/providers/kuae-cloud-coding-plan.md +71 -0
  218. package/.docs/models/providers/llama.md +77 -0
  219. package/.docs/models/providers/lmstudio.md +73 -0
  220. package/.docs/models/providers/lucidquery.md +72 -0
  221. package/.docs/models/providers/minimax-cn-coding-plan.md +102 -0
  222. package/.docs/models/providers/minimax-cn.md +102 -0
  223. package/.docs/models/providers/minimax-coding-plan.md +102 -0
  224. package/.docs/models/providers/minimax.md +104 -0
  225. package/.docs/models/providers/mistral.md +124 -0
  226. package/.docs/models/providers/moark.md +72 -0
  227. package/.docs/models/providers/modelscope.md +77 -0
  228. package/.docs/models/providers/moonshotai-cn.md +76 -0
  229. package/.docs/models/providers/moonshotai.md +76 -0
  230. package/.docs/models/providers/morph.md +73 -0
  231. package/.docs/models/providers/nano-gpt.md +103 -0
  232. package/.docs/models/providers/nebius.md +116 -0
  233. package/.docs/models/providers/nova.md +72 -0
  234. package/.docs/models/providers/novita-ai.md +154 -0
  235. package/.docs/models/providers/nvidia.md +141 -0
  236. package/.docs/models/providers/ollama-cloud.md +103 -0
  237. package/.docs/models/providers/ollama.md +33 -0
  238. package/.docs/models/providers/openai.md +193 -0
  239. package/.docs/models/providers/opencode.md +100 -0
  240. package/.docs/models/providers/ovhcloud.md +83 -0
  241. package/.docs/models/providers/perplexity.md +100 -0
  242. package/.docs/models/providers/poe.md +183 -0
  243. package/.docs/models/providers/privatemode-ai.md +75 -0
  244. package/.docs/models/providers/requesty.md +90 -0
  245. package/.docs/models/providers/scaleway.md +84 -0
  246. package/.docs/models/providers/siliconflow-cn.md +138 -0
  247. package/.docs/models/providers/siliconflow.md +140 -0
  248. package/.docs/models/providers/stackit.md +78 -0
  249. package/.docs/models/providers/stepfun.md +73 -0
  250. package/.docs/models/providers/submodel.md +79 -0
  251. package/.docs/models/providers/synthetic.md +96 -0
  252. package/.docs/models/providers/togetherai.md +115 -0
  253. package/.docs/models/providers/upstage.md +73 -0
  254. package/.docs/models/providers/venice.md +95 -0
  255. package/.docs/models/providers/vivgrid.md +106 -0
  256. package/.docs/models/providers/vultr.md +75 -0
  257. package/.docs/models/providers/wandb.md +80 -0
  258. package/.docs/models/providers/xai.md +141 -0
  259. package/.docs/models/providers/xiaomi.md +71 -0
  260. package/.docs/models/providers/zai-coding-plan.md +80 -0
  261. package/.docs/models/providers/zai.md +79 -0
  262. package/.docs/models/providers/zenmux.md +161 -0
  263. package/.docs/models/providers/zhipuai-coding-plan.md +79 -0
  264. package/.docs/models/providers/zhipuai.md +79 -0
  265. package/.docs/models/providers.md +81 -0
  266. package/.docs/reference/agents/agent.md +141 -0
  267. package/.docs/reference/agents/generate.md +186 -0
  268. package/.docs/reference/agents/generateLegacy.md +173 -0
  269. package/.docs/reference/agents/getDefaultGenerateOptions.md +36 -0
  270. package/.docs/reference/agents/getDefaultOptions.md +34 -0
  271. package/.docs/reference/agents/getDefaultStreamOptions.md +36 -0
  272. package/.docs/reference/agents/getDescription.md +21 -0
  273. package/.docs/reference/agents/getInstructions.md +34 -0
  274. package/.docs/reference/agents/getLLM.md +37 -0
  275. package/.docs/reference/agents/getMemory.md +34 -0
  276. package/.docs/reference/agents/getModel.md +34 -0
  277. package/.docs/reference/agents/getTools.md +29 -0
  278. package/.docs/reference/agents/getVoice.md +34 -0
  279. package/.docs/reference/agents/listAgents.md +35 -0
  280. package/.docs/reference/agents/listScorers.md +34 -0
  281. package/.docs/reference/agents/listTools.md +34 -0
  282. package/.docs/reference/agents/listWorkflows.md +34 -0
  283. package/.docs/reference/agents/network.md +133 -0
  284. package/.docs/reference/ai-sdk/chat-route.md +82 -0
  285. package/.docs/reference/ai-sdk/handle-chat-stream.md +53 -0
  286. package/.docs/reference/ai-sdk/handle-network-stream.md +37 -0
  287. package/.docs/reference/ai-sdk/handle-workflow-stream.md +55 -0
  288. package/.docs/reference/ai-sdk/network-route.md +74 -0
  289. package/.docs/reference/ai-sdk/to-ai-sdk-stream.md +231 -0
  290. package/.docs/reference/ai-sdk/to-ai-sdk-v4-messages.md +79 -0
  291. package/.docs/reference/ai-sdk/to-ai-sdk-v5-messages.md +76 -0
  292. package/.docs/reference/ai-sdk/with-mastra.md +59 -0
  293. package/.docs/reference/ai-sdk/workflow-route.md +79 -0
  294. package/.docs/reference/auth/auth0.md +73 -0
  295. package/.docs/reference/auth/better-auth.md +71 -0
  296. package/.docs/reference/auth/clerk.md +36 -0
  297. package/.docs/reference/auth/firebase.md +80 -0
  298. package/.docs/reference/auth/jwt.md +26 -0
  299. package/.docs/reference/auth/supabase.md +33 -0
  300. package/.docs/reference/auth/workos.md +84 -0
  301. package/.docs/reference/cli/create-mastra.md +137 -0
  302. package/.docs/reference/cli/mastra.md +336 -0
  303. package/.docs/reference/client-js/agents.md +437 -0
  304. package/.docs/reference/client-js/error-handling.md +16 -0
  305. package/.docs/reference/client-js/logs.md +24 -0
  306. package/.docs/reference/client-js/mastra-client.md +63 -0
  307. package/.docs/reference/client-js/memory.md +221 -0
  308. package/.docs/reference/client-js/observability.md +72 -0
  309. package/.docs/reference/client-js/telemetry.md +20 -0
  310. package/.docs/reference/client-js/tools.md +44 -0
  311. package/.docs/reference/client-js/vectors.md +79 -0
  312. package/.docs/reference/client-js/workflows.md +199 -0
  313. package/.docs/reference/configuration.md +752 -0
  314. package/.docs/reference/core/addGateway.md +42 -0
  315. package/.docs/reference/core/getAgent.md +21 -0
  316. package/.docs/reference/core/getAgentById.md +21 -0
  317. package/.docs/reference/core/getDeployer.md +22 -0
  318. package/.docs/reference/core/getGateway.md +38 -0
  319. package/.docs/reference/core/getGatewayById.md +41 -0
  320. package/.docs/reference/core/getLogger.md +22 -0
  321. package/.docs/reference/core/getMCPServer.md +47 -0
  322. package/.docs/reference/core/getMCPServerById.md +55 -0
  323. package/.docs/reference/core/getMemory.md +50 -0
  324. package/.docs/reference/core/getScorer.md +54 -0
  325. package/.docs/reference/core/getScorerById.md +54 -0
  326. package/.docs/reference/core/getServer.md +22 -0
  327. package/.docs/reference/core/getStorage.md +22 -0
  328. package/.docs/reference/core/getStoredAgentById.md +89 -0
  329. package/.docs/reference/core/getTelemetry.md +22 -0
  330. package/.docs/reference/core/getVector.md +22 -0
  331. package/.docs/reference/core/getWorkflow.md +42 -0
  332. package/.docs/reference/core/listAgents.md +21 -0
  333. package/.docs/reference/core/listGateways.md +40 -0
  334. package/.docs/reference/core/listLogs.md +38 -0
  335. package/.docs/reference/core/listLogsByRunId.md +36 -0
  336. package/.docs/reference/core/listMCPServers.md +55 -0
  337. package/.docs/reference/core/listMemory.md +56 -0
  338. package/.docs/reference/core/listScorers.md +29 -0
  339. package/.docs/reference/core/listStoredAgents.md +93 -0
  340. package/.docs/reference/core/listVectors.md +22 -0
  341. package/.docs/reference/core/listWorkflows.md +21 -0
  342. package/.docs/reference/core/mastra-class.md +66 -0
  343. package/.docs/reference/core/mastra-model-gateway.md +153 -0
  344. package/.docs/reference/core/setLogger.md +26 -0
  345. package/.docs/reference/core/setStorage.md +27 -0
  346. package/.docs/reference/datasets/addItem.md +37 -0
  347. package/.docs/reference/datasets/addItems.md +35 -0
  348. package/.docs/reference/datasets/compareExperiments.md +52 -0
  349. package/.docs/reference/datasets/create.md +51 -0
  350. package/.docs/reference/datasets/dataset.md +82 -0
  351. package/.docs/reference/datasets/datasets-manager.md +94 -0
  352. package/.docs/reference/datasets/delete.md +25 -0
  353. package/.docs/reference/datasets/deleteExperiment.md +27 -0
  354. package/.docs/reference/datasets/deleteItem.md +27 -0
  355. package/.docs/reference/datasets/deleteItems.md +29 -0
  356. package/.docs/reference/datasets/get.md +31 -0
  357. package/.docs/reference/datasets/getDetails.md +47 -0
  358. package/.docs/reference/datasets/getExperiment.md +30 -0
  359. package/.docs/reference/datasets/getItem.md +33 -0
  360. package/.docs/reference/datasets/getItemHistory.md +31 -0
  361. package/.docs/reference/datasets/list.md +31 -0
  362. package/.docs/reference/datasets/listExperimentResults.md +39 -0
  363. package/.docs/reference/datasets/listExperiments.md +33 -0
  364. package/.docs/reference/datasets/listItems.md +46 -0
  365. package/.docs/reference/datasets/listVersions.md +33 -0
  366. package/.docs/reference/datasets/startExperiment.md +62 -0
  367. package/.docs/reference/datasets/startExperimentAsync.md +43 -0
  368. package/.docs/reference/datasets/update.md +48 -0
  369. package/.docs/reference/datasets/updateItem.md +38 -0
  370. package/.docs/reference/deployer/cloudflare.md +79 -0
  371. package/.docs/reference/deployer/netlify.md +80 -0
  372. package/.docs/reference/deployer/vercel.md +91 -0
  373. package/.docs/reference/deployer.md +100 -0
  374. package/.docs/reference/evals/answer-relevancy.md +105 -0
  375. package/.docs/reference/evals/answer-similarity.md +99 -0
  376. package/.docs/reference/evals/bias.md +120 -0
  377. package/.docs/reference/evals/completeness.md +136 -0
  378. package/.docs/reference/evals/content-similarity.md +101 -0
  379. package/.docs/reference/evals/context-precision.md +196 -0
  380. package/.docs/reference/evals/context-relevance.md +531 -0
  381. package/.docs/reference/evals/create-scorer.md +270 -0
  382. package/.docs/reference/evals/faithfulness.md +114 -0
  383. package/.docs/reference/evals/hallucination.md +213 -0
  384. package/.docs/reference/evals/keyword-coverage.md +128 -0
  385. package/.docs/reference/evals/mastra-scorer.md +123 -0
  386. package/.docs/reference/evals/noise-sensitivity.md +675 -0
  387. package/.docs/reference/evals/prompt-alignment.md +614 -0
  388. package/.docs/reference/evals/run-evals.md +179 -0
  389. package/.docs/reference/evals/scorer-utils.md +326 -0
  390. package/.docs/reference/evals/textual-difference.md +113 -0
  391. package/.docs/reference/evals/tone-consistency.md +119 -0
  392. package/.docs/reference/evals/tool-call-accuracy.md +533 -0
  393. package/.docs/reference/evals/toxicity.md +123 -0
  394. package/.docs/reference/harness/harness-class.md +708 -0
  395. package/.docs/reference/index.md +277 -0
  396. package/.docs/reference/logging/pino-logger.md +117 -0
  397. package/.docs/reference/mastra-code/createMastraCode.md +108 -0
  398. package/.docs/reference/memory/clone-utilities.md +199 -0
  399. package/.docs/reference/memory/cloneThread.md +130 -0
  400. package/.docs/reference/memory/createThread.md +68 -0
  401. package/.docs/reference/memory/deleteMessages.md +38 -0
  402. package/.docs/reference/memory/getThreadById.md +24 -0
  403. package/.docs/reference/memory/listThreads.md +145 -0
  404. package/.docs/reference/memory/memory-class.md +147 -0
  405. package/.docs/reference/memory/observational-memory.md +565 -0
  406. package/.docs/reference/memory/recall.md +91 -0
  407. package/.docs/reference/observability/tracing/bridges/otel.md +131 -0
  408. package/.docs/reference/observability/tracing/configuration.md +178 -0
  409. package/.docs/reference/observability/tracing/exporters/arize.md +141 -0
  410. package/.docs/reference/observability/tracing/exporters/braintrust.md +93 -0
  411. package/.docs/reference/observability/tracing/exporters/cloud-exporter.md +163 -0
  412. package/.docs/reference/observability/tracing/exporters/console-exporter.md +138 -0
  413. package/.docs/reference/observability/tracing/exporters/datadog.md +116 -0
  414. package/.docs/reference/observability/tracing/exporters/default-exporter.md +174 -0
  415. package/.docs/reference/observability/tracing/exporters/laminar.md +78 -0
  416. package/.docs/reference/observability/tracing/exporters/langfuse.md +134 -0
  417. package/.docs/reference/observability/tracing/exporters/langsmith.md +108 -0
  418. package/.docs/reference/observability/tracing/exporters/otel.md +199 -0
  419. package/.docs/reference/observability/tracing/exporters/posthog.md +92 -0
  420. package/.docs/reference/observability/tracing/exporters/sentry.md +184 -0
  421. package/.docs/reference/observability/tracing/instances.md +107 -0
  422. package/.docs/reference/observability/tracing/interfaces.md +743 -0
  423. package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md +144 -0
  424. package/.docs/reference/observability/tracing/spans.md +224 -0
  425. package/.docs/reference/processors/batch-parts-processor.md +61 -0
  426. package/.docs/reference/processors/language-detector.md +82 -0
  427. package/.docs/reference/processors/message-history-processor.md +85 -0
  428. package/.docs/reference/processors/moderation-processor.md +104 -0
  429. package/.docs/reference/processors/pii-detector.md +108 -0
  430. package/.docs/reference/processors/processor-interface.md +521 -0
  431. package/.docs/reference/processors/prompt-injection-detector.md +72 -0
  432. package/.docs/reference/processors/semantic-recall-processor.md +117 -0
  433. package/.docs/reference/processors/system-prompt-scrubber.md +80 -0
  434. package/.docs/reference/processors/token-limiter-processor.md +115 -0
  435. package/.docs/reference/processors/tool-call-filter.md +85 -0
  436. package/.docs/reference/processors/tool-search-processor.md +111 -0
  437. package/.docs/reference/processors/unicode-normalizer.md +62 -0
  438. package/.docs/reference/processors/working-memory-processor.md +152 -0
  439. package/.docs/reference/rag/chunk.md +221 -0
  440. package/.docs/reference/rag/database-config.md +261 -0
  441. package/.docs/reference/rag/document.md +114 -0
  442. package/.docs/reference/rag/embeddings.md +92 -0
  443. package/.docs/reference/rag/extract-params.md +168 -0
  444. package/.docs/reference/rag/graph-rag.md +111 -0
  445. package/.docs/reference/rag/metadata-filters.md +216 -0
  446. package/.docs/reference/rag/rerank.md +75 -0
  447. package/.docs/reference/rag/rerankWithScorer.md +80 -0
  448. package/.docs/reference/server/create-route.md +262 -0
  449. package/.docs/reference/server/express-adapter.md +176 -0
  450. package/.docs/reference/server/fastify-adapter.md +90 -0
  451. package/.docs/reference/server/hono-adapter.md +162 -0
  452. package/.docs/reference/server/koa-adapter.md +127 -0
  453. package/.docs/reference/server/mastra-server.md +298 -0
  454. package/.docs/reference/server/register-api-route.md +249 -0
  455. package/.docs/reference/server/routes.md +306 -0
  456. package/.docs/reference/storage/cloudflare-d1.md +218 -0
  457. package/.docs/reference/storage/cloudflare.md +88 -0
  458. package/.docs/reference/storage/composite.md +235 -0
  459. package/.docs/reference/storage/convex.md +161 -0
  460. package/.docs/reference/storage/dynamodb.md +282 -0
  461. package/.docs/reference/storage/lance.md +131 -0
  462. package/.docs/reference/storage/libsql.md +135 -0
  463. package/.docs/reference/storage/mongodb.md +262 -0
  464. package/.docs/reference/storage/mssql.md +157 -0
  465. package/.docs/reference/storage/overview.md +121 -0
  466. package/.docs/reference/storage/postgresql.md +526 -0
  467. package/.docs/reference/storage/upstash.md +160 -0
  468. package/.docs/reference/streaming/ChunkType.md +292 -0
  469. package/.docs/reference/streaming/agents/MastraModelOutput.md +182 -0
  470. package/.docs/reference/streaming/agents/stream.md +221 -0
  471. package/.docs/reference/streaming/agents/streamLegacy.md +142 -0
  472. package/.docs/reference/streaming/workflows/observeStream.md +42 -0
  473. package/.docs/reference/streaming/workflows/resumeStream.md +61 -0
  474. package/.docs/reference/streaming/workflows/stream.md +88 -0
  475. package/.docs/reference/streaming/workflows/timeTravelStream.md +142 -0
  476. package/.docs/reference/templates/overview.md +194 -0
  477. package/.docs/reference/tools/create-tool.md +237 -0
  478. package/.docs/reference/tools/document-chunker-tool.md +89 -0
  479. package/.docs/reference/tools/graph-rag-tool.md +182 -0
  480. package/.docs/reference/tools/mcp-client.md +954 -0
  481. package/.docs/reference/tools/mcp-server.md +1271 -0
  482. package/.docs/reference/tools/vector-query-tool.md +459 -0
  483. package/.docs/reference/vectors/astra.md +121 -0
  484. package/.docs/reference/vectors/chroma.md +264 -0
  485. package/.docs/reference/vectors/convex.md +300 -0
  486. package/.docs/reference/vectors/couchbase.md +226 -0
  487. package/.docs/reference/vectors/duckdb.md +318 -0
  488. package/.docs/reference/vectors/elasticsearch.md +189 -0
  489. package/.docs/reference/vectors/lance.md +220 -0
  490. package/.docs/reference/vectors/libsql.md +305 -0
  491. package/.docs/reference/vectors/mongodb.md +295 -0
  492. package/.docs/reference/vectors/opensearch.md +99 -0
  493. package/.docs/reference/vectors/pg.md +408 -0
  494. package/.docs/reference/vectors/pinecone.md +168 -0
  495. package/.docs/reference/vectors/qdrant.md +222 -0
  496. package/.docs/reference/vectors/s3vectors.md +277 -0
  497. package/.docs/reference/vectors/turbopuffer.md +157 -0
  498. package/.docs/reference/vectors/upstash.md +294 -0
  499. package/.docs/reference/vectors/vectorize.md +147 -0
  500. package/.docs/reference/voice/azure.md +148 -0
  501. package/.docs/reference/voice/cloudflare.md +83 -0
  502. package/.docs/reference/voice/composite-voice.md +121 -0
  503. package/.docs/reference/voice/deepgram.md +79 -0
  504. package/.docs/reference/voice/elevenlabs.md +98 -0
  505. package/.docs/reference/voice/google-gemini-live.md +378 -0
  506. package/.docs/reference/voice/google.md +228 -0
  507. package/.docs/reference/voice/mastra-voice.md +311 -0
  508. package/.docs/reference/voice/murf.md +122 -0
  509. package/.docs/reference/voice/openai-realtime.md +203 -0
  510. package/.docs/reference/voice/openai.md +88 -0
  511. package/.docs/reference/voice/playai.md +80 -0
  512. package/.docs/reference/voice/sarvam.md +126 -0
  513. package/.docs/reference/voice/speechify.md +75 -0
  514. package/.docs/reference/voice/voice.addInstructions.md +55 -0
  515. package/.docs/reference/voice/voice.addTools.md +67 -0
  516. package/.docs/reference/voice/voice.answer.md +54 -0
  517. package/.docs/reference/voice/voice.close.md +51 -0
  518. package/.docs/reference/voice/voice.connect.md +94 -0
  519. package/.docs/reference/voice/voice.events.md +37 -0
  520. package/.docs/reference/voice/voice.getSpeakers.md +129 -0
  521. package/.docs/reference/voice/voice.listen.md +164 -0
  522. package/.docs/reference/voice/voice.off.md +54 -0
  523. package/.docs/reference/voice/voice.on.md +111 -0
  524. package/.docs/reference/voice/voice.send.md +65 -0
  525. package/.docs/reference/voice/voice.speak.md +157 -0
  526. package/.docs/reference/voice/voice.updateConfig.md +60 -0
  527. package/.docs/reference/workflows/run-methods/cancel.md +86 -0
  528. package/.docs/reference/workflows/run-methods/restart.md +33 -0
  529. package/.docs/reference/workflows/run-methods/resume.md +59 -0
  530. package/.docs/reference/workflows/run-methods/start.md +58 -0
  531. package/.docs/reference/workflows/run-methods/startAsync.md +67 -0
  532. package/.docs/reference/workflows/run-methods/timeTravel.md +142 -0
  533. package/.docs/reference/workflows/run.md +59 -0
  534. package/.docs/reference/workflows/step.md +119 -0
  535. package/.docs/reference/workflows/workflow-methods/branch.md +25 -0
  536. package/.docs/reference/workflows/workflow-methods/commit.md +17 -0
  537. package/.docs/reference/workflows/workflow-methods/create-run.md +63 -0
  538. package/.docs/reference/workflows/workflow-methods/dountil.md +25 -0
  539. package/.docs/reference/workflows/workflow-methods/dowhile.md +25 -0
  540. package/.docs/reference/workflows/workflow-methods/foreach.md +118 -0
  541. package/.docs/reference/workflows/workflow-methods/map.md +93 -0
  542. package/.docs/reference/workflows/workflow-methods/parallel.md +21 -0
  543. package/.docs/reference/workflows/workflow-methods/sleep.md +35 -0
  544. package/.docs/reference/workflows/workflow-methods/sleepUntil.md +35 -0
  545. package/.docs/reference/workflows/workflow-methods/then.md +21 -0
  546. package/.docs/reference/workflows/workflow.md +157 -0
  547. package/.docs/reference/workspace/e2b-sandbox.md +289 -0
  548. package/.docs/reference/workspace/filesystem.md +255 -0
  549. package/.docs/reference/workspace/gcs-filesystem.md +174 -0
  550. package/.docs/reference/workspace/local-filesystem.md +343 -0
  551. package/.docs/reference/workspace/local-sandbox.md +301 -0
  552. package/.docs/reference/workspace/s3-filesystem.md +175 -0
  553. package/.docs/reference/workspace/sandbox.md +87 -0
  554. package/.docs/reference/workspace/workspace-class.md +244 -0
  555. package/CHANGELOG.md +8 -0
  556. package/package.json +5 -5
@@ -0,0 +1,114 @@
1
+ # MDocument
2
+
3
+ The MDocument class processes documents for RAG applications. The main methods are `.chunk()` and `.extractMetadata()`.
4
+
5
+ ## Constructor
6
+
7
+ **docs:** (`Array<{ text: string, metadata?: Record<string, any> }>`): Array of document chunks with their text content and optional metadata
8
+
9
+ **type:** (`'text' | 'html' | 'markdown' | 'json' | 'latex'`): Type of document content
10
+
11
+ ## Static Methods
12
+
13
+ ### fromText()
14
+
15
+ Creates a document from plain text content.
16
+
17
+ ```typescript
18
+ static fromText(text: string, metadata?: Record<string, any>): MDocument
19
+ ```
20
+
21
+ ### fromHTML()
22
+
23
+ Creates a document from HTML content.
24
+
25
+ ```typescript
26
+ static fromHTML(html: string, metadata?: Record<string, any>): MDocument
27
+ ```
28
+
29
+ ### fromMarkdown()
30
+
31
+ Creates a document from Markdown content.
32
+
33
+ ```typescript
34
+ static fromMarkdown(markdown: string, metadata?: Record<string, any>): MDocument
35
+ ```
36
+
37
+ ### fromJSON()
38
+
39
+ Creates a document from JSON content.
40
+
41
+ ```typescript
42
+ static fromJSON(json: string, metadata?: Record<string, any>): MDocument
43
+ ```
44
+
45
+ ## Instance Methods
46
+
47
+ ### chunk()
48
+
49
+ Splits document into chunks and optionally extracts metadata.
50
+
51
+ ```typescript
52
+ async chunk(params?: ChunkParams): Promise<Chunk[]>
53
+ ```
54
+
55
+ See [chunk() reference](https://mastra.ai/reference/rag/chunk) for detailed options.
56
+
57
+ ### getDocs()
58
+
59
+ Returns array of processed document chunks.
60
+
61
+ ```typescript
62
+ getDocs(): Chunk[]
63
+ ```
64
+
65
+ ### getText()
66
+
67
+ Returns array of text strings from chunks.
68
+
69
+ ```typescript
70
+ getText(): string[]
71
+ ```
72
+
73
+ ### getMetadata()
74
+
75
+ Returns array of metadata objects from chunks.
76
+
77
+ ```typescript
78
+ getMetadata(): Record<string, any>[]
79
+ ```
80
+
81
+ ### extractMetadata()
82
+
83
+ Extracts metadata using specified extractors. See [ExtractParams reference](https://mastra.ai/reference/rag/extract-params) for details.
84
+
85
+ ```typescript
86
+ async extractMetadata(params: ExtractParams): Promise<MDocument>
87
+ ```
88
+
89
+ ## Examples
90
+
91
+ ```typescript
92
+ import { MDocument } from '@mastra/rag'
93
+
94
+ // Create document from text
95
+ const doc = MDocument.fromText('Your content here')
96
+
97
+ // Split into chunks with metadata extraction
98
+ const chunks = await doc.chunk({
99
+ strategy: 'markdown',
100
+ headers: [
101
+ ['#', 'title'],
102
+ ['##', 'section'],
103
+ ],
104
+ extract: {
105
+ summary: true, // Extract summaries with default settings
106
+ keywords: true, // Extract keywords with default settings
107
+ },
108
+ })
109
+
110
+ // Get processed chunks
111
+ const docs = doc.getDocs()
112
+ const texts = doc.getText()
113
+ const metadata = doc.getMetadata()
114
+ ```
@@ -0,0 +1,92 @@
1
+ # Embed
2
+
3
+ Mastra uses the AI SDK's `embed` and `embedMany` functions to generate vector embeddings for text inputs, enabling similarity search and RAG workflows.
4
+
5
+ ## Single Embedding
6
+
7
+ The `embed` function generates a vector embedding for a single text input:
8
+
9
+ ```typescript
10
+ import { embed } from 'ai'
11
+ import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
12
+
13
+ const result = await embed({
14
+ model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
15
+ value: 'Your text to embed',
16
+ maxRetries: 2, // optional, defaults to 2
17
+ })
18
+ ```
19
+
20
+ ### Parameters
21
+
22
+ **model:** (`EmbeddingModel`): The embedding model to use (e.g. openai.embedding('text-embedding-3-small'))
23
+
24
+ **value:** (`string | Record<string, any>`): The text content or object to embed
25
+
26
+ **maxRetries?:** (`number`): Maximum number of retries per embedding call. Set to 0 to disable retries. (Default: `2`)
27
+
28
+ **abortSignal?:** (`AbortSignal`): Optional abort signal to cancel the request
29
+
30
+ **headers?:** (`Record<string, string>`): Additional HTTP headers for the request (only for HTTP-based providers)
31
+
32
+ ### Return Value
33
+
34
+ **embedding:** (`number[]`): The embedding vector for the input
35
+
36
+ ## Multiple Embeddings
37
+
38
+ For embedding multiple texts at once, use the `embedMany` function:
39
+
40
+ ```typescript
41
+ import { embedMany } from 'ai'
42
+
43
+ const result = await embedMany({
44
+ model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
45
+ values: ['First text', 'Second text', 'Third text'],
46
+ maxRetries: 2, // optional, defaults to 2
47
+ })
48
+ ```
49
+
50
+ ### Parameters
51
+
52
+ **model:** (`EmbeddingModel`): The embedding model to use (e.g. openai.embedding('text-embedding-3-small'))
53
+
54
+ **values:** (`string[] | Record<string, any>[]`): Array of text content or objects to embed
55
+
56
+ **maxRetries?:** (`number`): Maximum number of retries per embedding call. Set to 0 to disable retries. (Default: `2`)
57
+
58
+ **abortSignal?:** (`AbortSignal`): Optional abort signal to cancel the request
59
+
60
+ **headers?:** (`Record<string, string>`): Additional HTTP headers for the request (only for HTTP-based providers)
61
+
62
+ ### Return Value
63
+
64
+ **embeddings:** (`number[][]`): Array of embedding vectors corresponding to the input values
65
+
66
+ ## Example Usage
67
+
68
+ ```typescript
69
+ import { embed, embedMany } from 'ai'
70
+
71
+ // Single embedding
72
+ const singleResult = await embed({
73
+ model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
74
+ value: 'What is the meaning of life?',
75
+ })
76
+
77
+ // Multiple embeddings
78
+ const multipleResult = await embedMany({
79
+ model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
80
+ values: [
81
+ 'First question about life',
82
+ 'Second question about universe',
83
+ 'Third question about everything',
84
+ ],
85
+ })
86
+ ```
87
+
88
+ For more detailed information about embeddings in the Vercel AI SDK, see:
89
+
90
+ - [AI SDK Embeddings Overview](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings)
91
+ - [embed()](https://sdk.vercel.ai/docs/reference/ai-sdk-core/embed)
92
+ - [embedMany()](https://sdk.vercel.ai/docs/reference/ai-sdk-core/embed-many)
@@ -0,0 +1,168 @@
1
+ # ExtractParams
2
+
3
+ ExtractParams configures metadata extraction from document chunks using LLM analysis.
4
+
5
+ ## Example
6
+
7
+ ```typescript
8
+ import { MDocument } from '@mastra/rag'
9
+
10
+ const doc = MDocument.fromText(text)
11
+ const chunks = await doc.chunk({
12
+ extract: {
13
+ title: true, // Extract titles using default settings
14
+ summary: true, // Generate summaries using default settings
15
+ keywords: true, // Extract keywords using default settings
16
+ },
17
+ })
18
+
19
+ // Example output:
20
+ // chunks[0].metadata = {
21
+ // documentTitle: "AI Systems Overview",
22
+ // sectionSummary: "Overview of artificial intelligence concepts and applications",
23
+ // excerptKeywords: "KEYWORDS: AI, machine learning, algorithms"
24
+ // }
25
+ ```
26
+
27
+ ## Parameters
28
+
29
+ The `extract` parameter accepts the following fields:
30
+
31
+ **title?:** (`boolean | TitleExtractorsArgs`): Enable title extraction. Set to true for default settings, or provide custom configuration.
32
+
33
+ **summary?:** (`boolean | SummaryExtractArgs`): Enable summary extraction. Set to true for default settings, or provide custom configuration.
34
+
35
+ **questions?:** (`boolean | QuestionAnswerExtractArgs`): Enable question generation. Set to true for default settings, or provide custom configuration.
36
+
37
+ **keywords?:** (`boolean | KeywordExtractArgs`): Enable keyword extraction. Set to true for default settings, or provide custom configuration.
38
+
39
+ **schema?:** (`SchemaExtractArgs`): Enable structured metadata extraction using a Zod schema.
40
+
41
+ ## Extractor Arguments
42
+
43
+ ### TitleExtractorsArgs
44
+
45
+ **llm?:** (`MastraLanguageModel`): AI SDK language model to use for title extraction
46
+
47
+ **nodes?:** (`number`): Number of title nodes to extract
48
+
49
+ **nodeTemplate?:** (`string`): Custom prompt template for title node extraction. Must include {context} placeholder
50
+
51
+ **combineTemplate?:** (`string`): Custom prompt template for combining titles. Must include {context} placeholder
52
+
53
+ ### SummaryExtractArgs
54
+
55
+ **llm?:** (`MastraLanguageModel`): AI SDK language model to use for summary extraction
56
+
57
+ **summaries?:** (`('self' | 'prev' | 'next')[]`): List of summary types to generate. Can only include 'self' (current chunk), 'prev' (previous chunk), or 'next' (next chunk)
58
+
59
+ **promptTemplate?:** (`string`): Custom prompt template for summary generation. Must include {context} placeholder
60
+
61
+ ### QuestionAnswerExtractArgs
62
+
63
+ **llm?:** (`MastraLanguageModel`): AI SDK language model to use for question generation
64
+
65
+ **questions?:** (`number`): Number of questions to generate
66
+
67
+ **promptTemplate?:** (`string`): Custom prompt template for question generation. Must include both {context} and {numQuestions} placeholders
68
+
69
+ **embeddingOnly?:** (`boolean`): If true, only generate embeddings without actual questions
70
+
71
+ ### KeywordExtractArgs
72
+
73
+ **llm?:** (`MastraLanguageModel`): AI SDK language model to use for keyword extraction
74
+
75
+ **keywords?:** (`number`): Number of keywords to extract
76
+
77
+ **promptTemplate?:** (`string`): Custom prompt template for keyword extraction. Must include both {context} and {maxKeywords} placeholders
78
+
79
+ ### SchemaExtractArgs
80
+
81
+ **schema:** (`ZodType`): Zod schema defining the structure of the data to extract.
82
+
83
+ **llm?:** (`MastraLanguageModel`): AI SDK language model to use for extraction.
84
+
85
+ **instructions?:** (`string`): Instructions for the LLM on what to extract.
86
+
87
+ **metadataKey?:** (`string`): Key to nest extraction results under. If omitted, results are spread into the metadata object.
88
+
89
+ ## Advanced Example
90
+
91
+ ```typescript
92
+ import { MDocument } from '@mastra/rag'
93
+
94
+ const doc = MDocument.fromText(text)
95
+ const chunks = await doc.chunk({
96
+ extract: {
97
+ // Title extraction with custom settings
98
+ title: {
99
+ nodes: 2, // Extract 2 title nodes
100
+ nodeTemplate: 'Generate a title for this: {context}',
101
+ combineTemplate: 'Combine these titles: {context}',
102
+ },
103
+
104
+ // Summary extraction with custom settings
105
+ summary: {
106
+ summaries: ['self'], // Generate summaries for current chunk
107
+ promptTemplate: 'Summarize this: {context}',
108
+ },
109
+
110
+ // Question generation with custom settings
111
+ questions: {
112
+ questions: 3, // Generate 3 questions
113
+ promptTemplate: 'Generate {numQuestions} questions about: {context}',
114
+ embeddingOnly: false,
115
+ },
116
+
117
+ // Keyword extraction with custom settings
118
+ keywords: {
119
+ keywords: 5, // Extract 5 keywords
120
+ promptTemplate: 'Extract {maxKeywords} key terms from: {context}',
121
+ },
122
+
123
+ // Schema extraction with Zod
124
+ schema: {
125
+ schema: z.object({
126
+ productName: z.string(),
127
+ category: z.enum(['electronics', 'clothing']),
128
+ }),
129
+ instructions: 'Extract product information.',
130
+ metadataKey: 'product',
131
+ },
132
+ },
133
+ })
134
+
135
+ // Example output:
136
+ // chunks[0].metadata = {
137
+ // documentTitle: "AI in Modern Computing",
138
+ // sectionSummary: "Overview of AI concepts and their applications in computing",
139
+ // questionsThisExcerptCanAnswer: "1. What is machine learning?\n2. How do neural networks work?",
140
+ // excerptKeywords: "1. Machine learning\n2. Neural networks\n3. Training data",
141
+ // product: {
142
+ // productName: "Neural Net 2000",
143
+ // category: "electronics"
144
+ // }
145
+ // }
146
+ ```
147
+
148
+ ## Document Grouping for Title Extraction
149
+
150
+ When using the `TitleExtractor`, you can group multiple chunks together for title extraction by specifying a shared `docId` in the `metadata` field of each chunk. All chunks with the same `docId` will receive the same extracted title. If no `docId` is set, each chunk is treated as its own document for title extraction.
151
+
152
+ **Example:**
153
+
154
+ ```ts
155
+ import { MDocument } from '@mastra/rag'
156
+
157
+ const doc = new MDocument({
158
+ docs: [
159
+ { text: 'chunk 1', metadata: { docId: 'docA' } },
160
+ { text: 'chunk 2', metadata: { docId: 'docA' } },
161
+ { text: 'chunk 3', metadata: { docId: 'docB' } },
162
+ ],
163
+ type: 'text',
164
+ })
165
+
166
+ await doc.extractMetadata({ title: true })
167
+ // The first two chunks will share a title, while the third chunk will be assigned a separate title.
168
+ ```
@@ -0,0 +1,111 @@
1
+ # GraphRAG
2
+
3
+ The `GraphRAG` class implements a graph-based approach to retrieval augmented generation. It creates a knowledge graph from document chunks where nodes represent documents and edges represent semantic relationships, enabling both direct similarity matching and discovery of related content through graph traversal.
4
+
5
+ ## Basic Usage
6
+
7
+ ```typescript
8
+ import { GraphRAG } from '@mastra/rag'
9
+
10
+ const graphRag = new GraphRAG({
11
+ dimension: 1536,
12
+ threshold: 0.7,
13
+ })
14
+
15
+ // Create the graph from chunks and embeddings
16
+ graphRag.createGraph(documentChunks, embeddings)
17
+
18
+ // Query the graph with embedding
19
+ const results = await graphRag.query({
20
+ query: queryEmbedding,
21
+ topK: 10,
22
+ randomWalkSteps: 100,
23
+ restartProb: 0.15,
24
+ })
25
+ ```
26
+
27
+ ## Constructor Parameters
28
+
29
+ **dimension?:** (`number`): Dimension of the embedding vectors (Default: `1536`)
30
+
31
+ **threshold?:** (`number`): Similarity threshold for creating edges between nodes (0-1) (Default: `0.7`)
32
+
33
+ ## Methods
34
+
35
+ ### createGraph
36
+
37
+ Creates a knowledge graph from document chunks and their embeddings.
38
+
39
+ ```typescript
40
+ createGraph(chunks: GraphChunk[], embeddings: GraphEmbedding[]): void
41
+ ```
42
+
43
+ #### Parameters
44
+
45
+ **chunks:** (`GraphChunk[]`): Array of document chunks with text and metadata
46
+
47
+ **embeddings:** (`GraphEmbedding[]`): Array of embeddings corresponding to chunks
48
+
49
+ ### query
50
+
51
+ Performs a graph-based search combining vector similarity and graph traversal.
52
+
53
+ ```typescript
54
+ query({
55
+ query,
56
+ topK = 10,
57
+ randomWalkSteps = 100,
58
+ restartProb = 0.15
59
+ }: {
60
+ query: number[];
61
+ topK?: number;
62
+ randomWalkSteps?: number;
63
+ restartProb?: number;
64
+ }): RankedNode[]
65
+ ```
66
+
67
+ #### Parameters
68
+
69
+ **query:** (`number[]`): Query embedding vector
70
+
71
+ **topK?:** (`number`): Number of results to return (Default: `10`)
72
+
73
+ **randomWalkSteps?:** (`number`): Number of steps in random walk (Default: `100`)
74
+
75
+ **restartProb?:** (`number`): Probability of restarting walk from query node (Default: `0.15`)
76
+
77
+ #### Returns
78
+
79
+ Returns an array of `RankedNode` objects, where each node contains:
80
+
81
+ **id:** (`string`): Unique identifier for the node
82
+
83
+ **content:** (`string`): Text content of the document chunk
84
+
85
+ **metadata:** (`Record<string, any>`): Additional metadata associated with the chunk
86
+
87
+ **score:** (`number`): Combined relevance score from graph traversal
88
+
89
+ ## Advanced Example
90
+
91
+ ```typescript
92
+ const graphRag = new GraphRAG({
93
+ dimension: 1536,
94
+ threshold: 0.8, // Stricter similarity threshold
95
+ })
96
+
97
+ // Create graph from chunks and embeddings
98
+ graphRag.createGraph(documentChunks, embeddings)
99
+
100
+ // Query with custom parameters
101
+ const results = await graphRag.query({
102
+ query: queryEmbedding,
103
+ topK: 5,
104
+ randomWalkSteps: 200,
105
+ restartProb: 0.2,
106
+ })
107
+ ```
108
+
109
+ ## Related
110
+
111
+ - [createGraphRAGTool](https://mastra.ai/reference/tools/graph-rag-tool)
@@ -0,0 +1,216 @@
1
+ # Metadata Filters
2
+
3
+ Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.
4
+
5
+ ## Basic Example
6
+
7
+ ```typescript
8
+ import { PgVector } from '@mastra/pg'
9
+
10
+ const store = new PgVector({
11
+ id: 'pg-vector',
12
+ connectionString,
13
+ })
14
+
15
+ const results = await store.query({
16
+ indexName: 'my_index',
17
+ queryVector: queryVector,
18
+ topK: 10,
19
+ filter: {
20
+ category: 'electronics', // Simple equality
21
+ price: { $gt: 100 }, // Numeric comparison
22
+ tags: { $in: ['sale', 'new'] }, // Array membership
23
+ },
24
+ })
25
+ ```
26
+
27
+ ## Supported Operators
28
+
29
+ ### Basic Comparison
30
+
31
+ `$eq`Matches values equal to specified value{ age: { $eq: 25 } }Supported by: All except Couchbase`$ne`Matches values not equal{ status: { $ne: 'inactive' } }Supported by: All except Couchbase`$gt`Greater than{ price: { $gt: 100 } }Supported by: All except Couchbase`$gte`Greater than or equal{ rating: { $gte: 4.5 } }Supported by: All except Couchbase`$lt`Less than{ stock: { $lt: 20 } }Supported by: All except Couchbase`$lte`Less than or equal{ priority: { $lte: 3 } }Supported by: All except Couchbase
32
+
33
+ ### Array Operators
34
+
35
+ `$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB
36
+
37
+ ### Logical Operators
38
+
39
+ `$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB
40
+
41
+ ### Element Operators
42
+
43
+ `$exists`Matches documents with field{ rating: { $exists: true } }Supported by: All except Vectorize, Chroma, Couchbase
44
+
45
+ ### Custom Operators
46
+
47
+ `$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB`$size`Array length check{ tags: { $size: { $gt: 2 } } }Supported by: Astra, libSQL, PgVector, MongoDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
48
+
49
+ ## Common Rules and Restrictions
50
+
51
+ 1. Field names cannot:
52
+
53
+ - Contain dots (.) unless referring to nested fields
54
+ - Start with $ or contain null characters
55
+ - Be empty strings
56
+
57
+ 2. Values must be:
58
+
59
+ - Valid JSON types (string, number, boolean, object, array)
60
+ - Not undefined
61
+ - Properly typed for the operator (e.g., numbers for numeric comparisons)
62
+
63
+ 3. Logical operators:
64
+
65
+ - Must contain valid conditions
66
+ - Cannot be empty
67
+ - Must be properly nested
68
+ - Can only be used at top level or nested within other logical operators
69
+ - Cannot be used at field level or nested inside a field
70
+ - Cannot be used inside an operator
71
+ - Valid: `{ "$and": [{ "field": { "$gt": 100 } }] }`
72
+ - Valid: `{ "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }`
73
+ - Invalid: `{ "field": { "$and": [{ "$gt": 100 }] } }`
74
+ - Invalid: `{ "field": { "$gt": { "$and": [{...}] } } }`
75
+
76
+ 4. $not operator:
77
+
78
+ - Must be an object
79
+ - Cannot be empty
80
+ - Can be used at field level or top level
81
+ - Valid: `{ "$not": { "field": "value" } }`
82
+ - Valid: `{ "field": { "$not": { "$eq": "value" } } }`
83
+
84
+ 5. Operator nesting:
85
+
86
+ - Logical operators must contain field conditions, not direct operators
87
+ - Valid: `{ "$and": [{ "field": { "$gt": 100 } }] }`
88
+ - Invalid: `{ "$and": [{ "$gt": 100 }] }`
89
+
90
+ ## Store-Specific Notes
91
+
92
+ ### Astra
93
+
94
+ - Nested field queries are supported using dot notation
95
+ - Array fields must be explicitly defined as arrays in the metadata
96
+ - Metadata values are case-sensitive
97
+
98
+ ### ChromaDB
99
+
100
+ - Where filters only return results where the filtered field exists in metadata
101
+ - Empty metadata fields are not included in filter results
102
+ - Metadata fields must be present for negative matches (e.g., $ne won't match documents missing the field)
103
+
104
+ ### Cloudflare Vectorize
105
+
106
+ - Requires explicit metadata indexing before filtering can be used
107
+ - Use `createMetadataIndex()` to index fields you want to filter on
108
+ - Up to 10 metadata indexes per Vectorize index
109
+ - String values are indexed up to first 64 bytes (truncated on UTF-8 boundaries)
110
+ - Number values use float64 precision
111
+ - Filter JSON must be under 2048 bytes
112
+ - Field names cannot contain dots (.) or start with $
113
+ - Field names limited to 512 characters
114
+ - Vectors must be re-upserted after creating new metadata indexes to be included in filtered results
115
+ - Range queries may have reduced accuracy with very large datasets (\~10M+ vectors)
116
+
117
+ ### libSQL
118
+
119
+ - Supports nested object queries with dot notation
120
+ - Array fields are validated to ensure they contain valid JSON arrays
121
+ - Numeric comparisons maintain proper type handling
122
+ - Empty arrays in conditions are handled gracefully
123
+ - Metadata is stored in a JSONB column for efficient querying
124
+
125
+ ### PgVector
126
+
127
+ - Full support for PostgreSQL's native JSON querying capabilities
128
+ - Efficient handling of array operations using native array functions
129
+ - Proper type handling for numbers, strings, and booleans
130
+ - Nested field queries use PostgreSQL's JSON path syntax internally
131
+ - Metadata is stored in a JSONB column for efficient indexing
132
+
133
+ ### Pinecone
134
+
135
+ - Metadata field names are limited to 512 characters
136
+ - Numeric values must be within the range of ±1e38
137
+ - Arrays in metadata are limited to 64KB total size
138
+ - Nested objects are flattened with dot notation
139
+ - Metadata updates replace the entire metadata object
140
+
141
+ ### Qdrant
142
+
143
+ - Supports advanced filtering with nested conditions
144
+ - Payload (metadata) fields must be explicitly indexed for filtering
145
+ - Use `createPayloadIndex()` to index fields you want to filter on:
146
+
147
+ ```typescript
148
+ // Index a field before filtering on it
149
+ await store.createPayloadIndex({
150
+ indexName: 'my_index',
151
+ fieldName: 'source',
152
+ fieldSchema: 'keyword', // 'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'
153
+ })
154
+
155
+ // Now filtering works
156
+ const results = await store.query({
157
+ indexName: 'my_index',
158
+ queryVector: queryVector,
159
+ filter: { source: 'document-a' },
160
+ })
161
+ ```
162
+
163
+ - Efficient handling of geo-spatial queries
164
+ - Special handling for null and empty values
165
+ - Vector-specific filtering capabilities
166
+ - Datetime values must be in RFC 3339 format
167
+
168
+ ### Upstash
169
+
170
+ - 512-character limit for metadata field keys
171
+ - Query size is limited (avoid large IN clauses)
172
+ - No support for null/undefined values in filters
173
+ - Translates to SQL-like syntax internally
174
+ - Case-sensitive string comparisons
175
+ - Metadata updates are atomic
176
+
177
+ ### MongoDB
178
+
179
+ - Full support for MongoDB/Sift query syntax for metadata filters
180
+ - Supports all standard comparison, array, logical, and element operators
181
+ - Supports nested fields and arrays in metadata
182
+ - Filtering can be applied to both `metadata` and the original document content using the `filter` and `documentFilter` options, respectively
183
+ - `filter` applies to the metadata object; `documentFilter` applies to the original document fields
184
+ - No artificial limits on filter size or complexity (subject to MongoDB query limits)
185
+ - Indexing metadata fields is recommended for optimal performance
186
+
187
+ ### Couchbase
188
+
189
+ - Currently does not have support for metadata filters. Filtering must be done client-side after retrieving results or by using the Couchbase SDK's Search capabilities directly for more complex queries.
190
+
191
+ ### Amazon S3 Vectors
192
+
193
+ - Equality values must be primitives (string/number/boolean). `null`/`undefined`, arrays, objects, and Date are not allowed for equality. Range operators accept numbers or Date (Dates are normalized to epoch ms).
194
+ - `$in`/`$nin` require **non-empty arrays of primitives**; Date elements are allowed and normalized to epoch ms. **Array equality** is not supported.
195
+ - Implicit AND is canonicalized (`{a:1,b:2}` → `{$and:[{a:1},{b:2}]}`). Logical operators must contain field conditions, use non-empty arrays, and appear only at the root or within other logical operators (not inside field values).
196
+ - Keys listed in `nonFilterableMetadataKeys` at index creation are stored but not filterable; this setting is immutable.
197
+ - $exists requires a boolean value.
198
+ - undefined/null/empty filters are treated as no filter.
199
+ - Each metadata key name limited to 63 characters.
200
+ - Total metadata per vector: Up to 40 KB (filterable + non-filterable)
201
+ - Total metadata keys per vector: Up to 10
202
+ - Filterable metadata per vector: Up to 2 KB
203
+ - Non-filterable metadata keys per vector index: Up to 10
204
+
205
+ ## Related
206
+
207
+ - [Astra](https://mastra.ai/reference/vectors/astra)
208
+ - [Chroma](https://mastra.ai/reference/vectors/chroma)
209
+ - [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
210
+ - [libSQL](https://mastra.ai/reference/vectors/libsql)
211
+ - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
212
+ - [PgStore](https://mastra.ai/reference/vectors/pg)
213
+ - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
214
+ - [Qdrant](https://mastra.ai/reference/vectors/qdrant)
215
+ - [Upstash](https://mastra.ai/reference/vectors/upstash)
216
+ - [Amazon S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)