@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

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 (254) hide show
  1. package/.docs/organized/changelogs/%40mastra%2Fastra.md +302 -0
  2. package/.docs/organized/changelogs/%40mastra%2Fchroma.md +302 -0
  3. package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +161 -0
  4. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +302 -0
  5. package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +110 -0
  6. package/.docs/organized/changelogs/%40mastra%2Fcore.md +302 -0
  7. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +302 -0
  8. package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +302 -0
  9. package/.docs/organized/changelogs/%40mastra%2Fdeployer-vercel.md +302 -0
  10. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +302 -0
  11. package/.docs/organized/changelogs/%40mastra%2Fevals.md +302 -0
  12. package/.docs/organized/changelogs/%40mastra%2Ffirecrawl.md +302 -0
  13. package/.docs/organized/changelogs/%40mastra%2Fgithub.md +302 -0
  14. package/.docs/organized/changelogs/%40mastra%2Floggers.md +302 -0
  15. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +302 -0
  16. package/.docs/organized/changelogs/%40mastra%2Fmcp-registry-registry.md +26 -0
  17. package/.docs/organized/changelogs/%40mastra%2Fmcp.md +302 -0
  18. package/.docs/organized/changelogs/%40mastra%2Fmem0.md +196 -0
  19. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +302 -0
  20. package/.docs/organized/changelogs/%40mastra%2Fpg.md +302 -0
  21. package/.docs/organized/changelogs/%40mastra%2Fpinecone.md +302 -0
  22. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +302 -0
  23. package/.docs/organized/changelogs/%40mastra%2Fqdrant.md +302 -0
  24. package/.docs/organized/changelogs/%40mastra%2Frag.md +302 -0
  25. package/.docs/organized/changelogs/%40mastra%2Fragie.md +302 -0
  26. package/.docs/organized/changelogs/%40mastra%2Fserver.md +302 -0
  27. package/.docs/organized/changelogs/%40mastra%2Fspeech-azure.md +302 -0
  28. package/.docs/organized/changelogs/%40mastra%2Fspeech-deepgram.md +302 -0
  29. package/.docs/organized/changelogs/%40mastra%2Fspeech-elevenlabs.md +302 -0
  30. package/.docs/organized/changelogs/%40mastra%2Fspeech-google.md +302 -0
  31. package/.docs/organized/changelogs/%40mastra%2Fspeech-ibm.md +302 -0
  32. package/.docs/organized/changelogs/%40mastra%2Fspeech-murf.md +302 -0
  33. package/.docs/organized/changelogs/%40mastra%2Fspeech-openai.md +302 -0
  34. package/.docs/organized/changelogs/%40mastra%2Fspeech-playai.md +302 -0
  35. package/.docs/organized/changelogs/%40mastra%2Fspeech-replicate.md +302 -0
  36. package/.docs/organized/changelogs/%40mastra%2Fspeech-speechify.md +302 -0
  37. package/.docs/organized/changelogs/%40mastra%2Fturbopuffer.md +302 -0
  38. package/.docs/organized/changelogs/%40mastra%2Fupstash.md +302 -0
  39. package/.docs/organized/changelogs/%40mastra%2Fvectorize.md +302 -0
  40. package/.docs/organized/changelogs/%40mastra%2Fvoice-azure.md +250 -0
  41. package/.docs/organized/changelogs/%40mastra%2Fvoice-cloudflare.md +250 -0
  42. package/.docs/organized/changelogs/%40mastra%2Fvoice-deepgram.md +302 -0
  43. package/.docs/organized/changelogs/%40mastra%2Fvoice-elevenlabs.md +302 -0
  44. package/.docs/organized/changelogs/%40mastra%2Fvoice-google.md +302 -0
  45. package/.docs/organized/changelogs/%40mastra%2Fvoice-murf.md +302 -0
  46. package/.docs/organized/changelogs/%40mastra%2Fvoice-openai-realtime.md +302 -0
  47. package/.docs/organized/changelogs/%40mastra%2Fvoice-openai.md +302 -0
  48. package/.docs/organized/changelogs/%40mastra%2Fvoice-playai.md +302 -0
  49. package/.docs/organized/changelogs/%40mastra%2Fvoice-sarvam.md +302 -0
  50. package/.docs/organized/changelogs/%40mastra%2Fvoice-speechify.md +302 -0
  51. package/.docs/organized/changelogs/create-mastra.md +302 -0
  52. package/.docs/organized/changelogs/mastra.md +302 -0
  53. package/.docs/organized/code-examples/agent-network.md +282 -0
  54. package/.docs/organized/code-examples/agent.md +388 -0
  55. package/.docs/organized/code-examples/ai-sdk-useChat.md +378 -0
  56. package/.docs/organized/code-examples/assistant-ui.md +37 -0
  57. package/.docs/organized/code-examples/bird-checker-with-express.md +235 -0
  58. package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md +360 -0
  59. package/.docs/organized/code-examples/bird-checker-with-nextjs.md +250 -0
  60. package/.docs/organized/code-examples/client-side-tools.md +69 -0
  61. package/.docs/organized/code-examples/crypto-chatbot.md +96 -0
  62. package/.docs/organized/code-examples/fireworks-r1.md +159 -0
  63. package/.docs/organized/code-examples/mcp-registry-registry.md +63 -0
  64. package/.docs/organized/code-examples/memory-todo-agent.md +164 -0
  65. package/.docs/organized/code-examples/memory-with-context.md +167 -0
  66. package/.docs/organized/code-examples/memory-with-libsql.md +204 -0
  67. package/.docs/organized/code-examples/memory-with-mem0.md +121 -0
  68. package/.docs/organized/code-examples/memory-with-pg.md +224 -0
  69. package/.docs/organized/code-examples/memory-with-upstash.md +268 -0
  70. package/.docs/organized/code-examples/quick-start.md +129 -0
  71. package/.docs/organized/code-examples/stock-price-tool.md +124 -0
  72. package/.docs/organized/code-examples/weather-agent.md +353 -0
  73. package/.docs/organized/code-examples/workflow-ai-recruiter.md +159 -0
  74. package/.docs/organized/code-examples/workflow-with-inline-steps.md +111 -0
  75. package/.docs/organized/code-examples/workflow-with-memory.md +393 -0
  76. package/.docs/organized/code-examples/workflow-with-separate-steps.md +131 -0
  77. package/.docs/raw/agents/adding-tools.mdx +317 -0
  78. package/.docs/raw/agents/adding-voice.mdx +175 -0
  79. package/.docs/raw/agents/agent-memory.mdx +62 -0
  80. package/.docs/raw/agents/mcp-guide.mdx +215 -0
  81. package/.docs/raw/agents/overview.mdx +303 -0
  82. package/.docs/raw/community/discord.mdx +12 -0
  83. package/.docs/raw/community/licensing.mdx +63 -0
  84. package/.docs/raw/deployment/client.mdx +120 -0
  85. package/.docs/raw/deployment/deployment.mdx +127 -0
  86. package/.docs/raw/deployment/server.mdx +282 -0
  87. package/.docs/raw/evals/custom-eval.mdx +22 -0
  88. package/.docs/raw/evals/overview.mdx +95 -0
  89. package/.docs/raw/evals/running-in-ci.mdx +81 -0
  90. package/.docs/raw/evals/textual-evals.mdx +54 -0
  91. package/.docs/raw/faq/index.mdx +63 -0
  92. package/.docs/raw/frameworks/ai-sdk.mdx +296 -0
  93. package/.docs/raw/frameworks/next-js.mdx +238 -0
  94. package/.docs/raw/getting-started/installation.mdx +442 -0
  95. package/.docs/raw/getting-started/mcp-docs-server.mdx +141 -0
  96. package/.docs/raw/getting-started/project-structure.mdx +80 -0
  97. package/.docs/raw/index.mdx +22 -0
  98. package/.docs/raw/integrations/index.mdx +213 -0
  99. package/.docs/raw/local-dev/add-to-existing-project.mdx +48 -0
  100. package/.docs/raw/local-dev/creating-a-new-project.mdx +54 -0
  101. package/.docs/raw/local-dev/mastra-dev.mdx +108 -0
  102. package/.docs/raw/memory/memory-processors.mdx +131 -0
  103. package/.docs/raw/memory/overview.mdx +119 -0
  104. package/.docs/raw/memory/semantic-recall.mdx +122 -0
  105. package/.docs/raw/memory/working-memory.mdx +87 -0
  106. package/.docs/raw/observability/logging.mdx +38 -0
  107. package/.docs/raw/observability/nextjs-tracing.mdx +108 -0
  108. package/.docs/raw/observability/tracing.mdx +115 -0
  109. package/.docs/raw/rag/chunking-and-embedding.mdx +156 -0
  110. package/.docs/raw/rag/overview.mdx +85 -0
  111. package/.docs/raw/rag/retrieval.mdx +365 -0
  112. package/.docs/raw/rag/vector-databases.mdx +340 -0
  113. package/.docs/raw/reference/agents/createTool.mdx +229 -0
  114. package/.docs/raw/reference/agents/generate.mdx +334 -0
  115. package/.docs/raw/reference/agents/getAgent.mdx +54 -0
  116. package/.docs/raw/reference/agents/stream.mdx +369 -0
  117. package/.docs/raw/reference/cli/build.mdx +55 -0
  118. package/.docs/raw/reference/cli/dev.mdx +134 -0
  119. package/.docs/raw/reference/cli/init.mdx +43 -0
  120. package/.docs/raw/reference/client-js/agents.mdx +107 -0
  121. package/.docs/raw/reference/client-js/error-handling.mdx +38 -0
  122. package/.docs/raw/reference/client-js/logs.mdx +24 -0
  123. package/.docs/raw/reference/client-js/memory.mdx +97 -0
  124. package/.docs/raw/reference/client-js/telemetry.mdx +20 -0
  125. package/.docs/raw/reference/client-js/tools.mdx +44 -0
  126. package/.docs/raw/reference/client-js/vectors.mdx +79 -0
  127. package/.docs/raw/reference/client-js/workflows.mdx +136 -0
  128. package/.docs/raw/reference/core/mastra-class.mdx +232 -0
  129. package/.docs/raw/reference/deployer/cloudflare.mdx +207 -0
  130. package/.docs/raw/reference/deployer/deployer.mdx +159 -0
  131. package/.docs/raw/reference/deployer/netlify.mdx +109 -0
  132. package/.docs/raw/reference/deployer/vercel.mdx +117 -0
  133. package/.docs/raw/reference/evals/answer-relevancy.mdx +186 -0
  134. package/.docs/raw/reference/evals/bias.mdx +186 -0
  135. package/.docs/raw/reference/evals/completeness.mdx +174 -0
  136. package/.docs/raw/reference/evals/content-similarity.mdx +183 -0
  137. package/.docs/raw/reference/evals/context-position.mdx +190 -0
  138. package/.docs/raw/reference/evals/context-precision.mdx +189 -0
  139. package/.docs/raw/reference/evals/context-relevancy.mdx +188 -0
  140. package/.docs/raw/reference/evals/contextual-recall.mdx +191 -0
  141. package/.docs/raw/reference/evals/faithfulness.mdx +193 -0
  142. package/.docs/raw/reference/evals/hallucination.mdx +219 -0
  143. package/.docs/raw/reference/evals/keyword-coverage.mdx +176 -0
  144. package/.docs/raw/reference/evals/prompt-alignment.mdx +238 -0
  145. package/.docs/raw/reference/evals/summarization.mdx +205 -0
  146. package/.docs/raw/reference/evals/textual-difference.mdx +161 -0
  147. package/.docs/raw/reference/evals/tone-consistency.mdx +181 -0
  148. package/.docs/raw/reference/evals/toxicity.mdx +165 -0
  149. package/.docs/raw/reference/index.mdx +12 -0
  150. package/.docs/raw/reference/memory/Memory.mdx +212 -0
  151. package/.docs/raw/reference/memory/createThread.mdx +95 -0
  152. package/.docs/raw/reference/memory/getThreadById.mdx +46 -0
  153. package/.docs/raw/reference/memory/getThreadsByResourceId.mdx +48 -0
  154. package/.docs/raw/reference/memory/query.mdx +167 -0
  155. package/.docs/raw/reference/networks/agent-network.mdx +159 -0
  156. package/.docs/raw/reference/observability/create-logger.mdx +106 -0
  157. package/.docs/raw/reference/observability/logger.mdx +55 -0
  158. package/.docs/raw/reference/observability/otel-config.mdx +120 -0
  159. package/.docs/raw/reference/observability/providers/braintrust.mdx +40 -0
  160. package/.docs/raw/reference/observability/providers/dash0.mdx +40 -0
  161. package/.docs/raw/reference/observability/providers/index.mdx +16 -0
  162. package/.docs/raw/reference/observability/providers/laminar.mdx +41 -0
  163. package/.docs/raw/reference/observability/providers/langfuse.mdx +51 -0
  164. package/.docs/raw/reference/observability/providers/langsmith.mdx +48 -0
  165. package/.docs/raw/reference/observability/providers/langwatch.mdx +45 -0
  166. package/.docs/raw/reference/observability/providers/new-relic.mdx +40 -0
  167. package/.docs/raw/reference/observability/providers/signoz.mdx +40 -0
  168. package/.docs/raw/reference/observability/providers/traceloop.mdx +40 -0
  169. package/.docs/raw/reference/rag/astra.mdx +258 -0
  170. package/.docs/raw/reference/rag/chroma.mdx +281 -0
  171. package/.docs/raw/reference/rag/chunk.mdx +235 -0
  172. package/.docs/raw/reference/rag/document.mdx +127 -0
  173. package/.docs/raw/reference/rag/embeddings.mdx +160 -0
  174. package/.docs/raw/reference/rag/extract-params.mdx +226 -0
  175. package/.docs/raw/reference/rag/graph-rag.mdx +182 -0
  176. package/.docs/raw/reference/rag/libsql.mdx +357 -0
  177. package/.docs/raw/reference/rag/metadata-filters.mdx +298 -0
  178. package/.docs/raw/reference/rag/pg.mdx +477 -0
  179. package/.docs/raw/reference/rag/pinecone.mdx +281 -0
  180. package/.docs/raw/reference/rag/qdrant.mdx +236 -0
  181. package/.docs/raw/reference/rag/rerank.mdx +212 -0
  182. package/.docs/raw/reference/rag/turbopuffer.mdx +249 -0
  183. package/.docs/raw/reference/rag/upstash.mdx +247 -0
  184. package/.docs/raw/reference/rag/vectorize.mdx +298 -0
  185. package/.docs/raw/reference/storage/libsql.mdx +74 -0
  186. package/.docs/raw/reference/storage/postgresql.mdx +48 -0
  187. package/.docs/raw/reference/storage/upstash.mdx +86 -0
  188. package/.docs/raw/reference/tools/client.mdx +207 -0
  189. package/.docs/raw/reference/tools/document-chunker-tool.mdx +141 -0
  190. package/.docs/raw/reference/tools/graph-rag-tool.mdx +154 -0
  191. package/.docs/raw/reference/tools/mcp-configuration.mdx +206 -0
  192. package/.docs/raw/reference/tools/vector-query-tool.mdx +212 -0
  193. package/.docs/raw/reference/voice/composite-voice.mdx +140 -0
  194. package/.docs/raw/reference/voice/deepgram.mdx +164 -0
  195. package/.docs/raw/reference/voice/elevenlabs.mdx +216 -0
  196. package/.docs/raw/reference/voice/google.mdx +198 -0
  197. package/.docs/raw/reference/voice/mastra-voice.mdx +394 -0
  198. package/.docs/raw/reference/voice/murf.mdx +251 -0
  199. package/.docs/raw/reference/voice/openai-realtime.mdx +431 -0
  200. package/.docs/raw/reference/voice/openai.mdx +168 -0
  201. package/.docs/raw/reference/voice/playai.mdx +159 -0
  202. package/.docs/raw/reference/voice/sarvam.mdx +260 -0
  203. package/.docs/raw/reference/voice/speechify.mdx +145 -0
  204. package/.docs/raw/reference/voice/voice.answer.mdx +122 -0
  205. package/.docs/raw/reference/voice/voice.connect.mdx +124 -0
  206. package/.docs/raw/reference/voice/voice.listen.mdx +195 -0
  207. package/.docs/raw/reference/voice/voice.on.mdx +189 -0
  208. package/.docs/raw/reference/voice/voice.send.mdx +118 -0
  209. package/.docs/raw/reference/voice/voice.speak.mdx +203 -0
  210. package/.docs/raw/reference/workflows/after.mdx +88 -0
  211. package/.docs/raw/reference/workflows/afterEvent.mdx +76 -0
  212. package/.docs/raw/reference/workflows/commit.mdx +37 -0
  213. package/.docs/raw/reference/workflows/createRun.mdx +77 -0
  214. package/.docs/raw/reference/workflows/else.mdx +72 -0
  215. package/.docs/raw/reference/workflows/events.mdx +305 -0
  216. package/.docs/raw/reference/workflows/execute.mdx +110 -0
  217. package/.docs/raw/reference/workflows/if.mdx +107 -0
  218. package/.docs/raw/reference/workflows/resume.mdx +155 -0
  219. package/.docs/raw/reference/workflows/resumeWithEvent.mdx +133 -0
  220. package/.docs/raw/reference/workflows/snapshots.mdx +207 -0
  221. package/.docs/raw/reference/workflows/start.mdx +84 -0
  222. package/.docs/raw/reference/workflows/step-class.mdx +100 -0
  223. package/.docs/raw/reference/workflows/step-condition.mdx +134 -0
  224. package/.docs/raw/reference/workflows/step-function.mdx +92 -0
  225. package/.docs/raw/reference/workflows/step-options.mdx +69 -0
  226. package/.docs/raw/reference/workflows/step-retries.mdx +203 -0
  227. package/.docs/raw/reference/workflows/suspend.mdx +70 -0
  228. package/.docs/raw/reference/workflows/then.mdx +74 -0
  229. package/.docs/raw/reference/workflows/until.mdx +165 -0
  230. package/.docs/raw/reference/workflows/watch.mdx +118 -0
  231. package/.docs/raw/reference/workflows/while.mdx +168 -0
  232. package/.docs/raw/reference/workflows/workflow.mdx +233 -0
  233. package/.docs/raw/storage/overview.mdx +378 -0
  234. package/.docs/raw/voice/overview.mdx +135 -0
  235. package/.docs/raw/voice/speech-to-text.mdx +45 -0
  236. package/.docs/raw/voice/text-to-speech.mdx +52 -0
  237. package/.docs/raw/voice/voice-to-voice.mdx +310 -0
  238. package/.docs/raw/workflows/control-flow.mdx +778 -0
  239. package/.docs/raw/workflows/dynamic-workflows.mdx +236 -0
  240. package/.docs/raw/workflows/error-handling.mdx +183 -0
  241. package/.docs/raw/workflows/nested-workflows.mdx +352 -0
  242. package/.docs/raw/workflows/overview.mdx +203 -0
  243. package/.docs/raw/workflows/steps.mdx +108 -0
  244. package/.docs/raw/workflows/suspend-and-resume.mdx +404 -0
  245. package/.docs/raw/workflows/variables.mdx +313 -0
  246. package/LICENSE.md +46 -0
  247. package/README.md +129 -0
  248. package/dist/_tsup-dts-rollup.d.ts +149 -0
  249. package/dist/chunk-QWYMT5LP.js +194 -0
  250. package/dist/prepare-docs/prepare.d.ts +1 -0
  251. package/dist/prepare-docs/prepare.js +1 -0
  252. package/dist/stdio.d.ts +1 -0
  253. package/dist/stdio.js +518 -0
  254. package/package.json +60 -0
package/.docs/raw/observability/tracing.mdx ADDED
@@ -0,0 +1,115 @@
1
+ ---
2
+ title: "Tracing | Mastra Observability Documentation"
3
+ description: "Set up OpenTelemetry tracing for Mastra applications"
4
+ ---
5
+
6
+ import Image from "next/image";
7
+
8
+ # Tracing
9
+
10
+ Mastra supports the OpenTelemetry Protocol (OTLP) for tracing and monitoring your application. When telemetry is enabled, Mastra automatically traces all core primitives including agent operations, LLM interactions, tool executions, integration calls, workflow runs, and database operations. Your telemetry data can then be exported to any OTEL collector.
11
+
12
+ ### Basic Configuration
13
+
14
+ Here's a simple example of enabling telemetry:
15
+
16
+ ```ts filename="mastra.config.ts" showLineNumbers copy
17
+ export const mastra = new Mastra({
18
+ // ... other config
19
+ telemetry: {
20
+ serviceName: "my-app",
21
+ enabled: true,
22
+ sampling: {
23
+ type: "always_on",
24
+ },
25
+ export: {
26
+ type: "otlp",
27
+ endpoint: "http://localhost:4318", // SigNoz local endpoint
28
+ },
29
+ },
30
+ });
31
+ ```
32
+
33
+ ### Configuration Options
34
+
35
+ The telemetry config accepts these properties:
36
+
37
+ ```ts
38
+ type OtelConfig = {
39
+ // Name to identify your service in traces (optional)
40
+ serviceName?: string;
41
+
42
+ // Enable/disable telemetry (defaults to true)
43
+ enabled?: boolean;
44
+
45
+ // Control how many traces are sampled
46
+ sampling?: {
47
+ type: "ratio" | "always_on" | "always_off" | "parent_based";
48
+ probability?: number; // For ratio sampling
49
+ root?: {
50
+ probability: number; // For parent_based sampling
51
+ };
52
+ };
53
+
54
+ // Where to send telemetry data
55
+ export?: {
56
+ type: "otlp" | "console";
57
+ endpoint?: string;
58
+ headers?: Record<string, string>;
59
+ };
60
+ };
61
+ ```
62
+
63
+ See the [OtelConfig reference documentation](../../reference/observability/otel-config.mdx) for more details.
64
+
65
+ ### Environment Variables
66
+
67
+ You can configure the OTLP endpoint and headers through environment variables:
68
+
69
+ ```env filename=".env" copy
70
+ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
71
+ OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key
72
+ ```
73
+
74
+ Then in your config:
75
+
76
+ ```ts filename="mastra.config.ts" showLineNumbers copy
77
+ export const mastra = new Mastra({
78
+ // ... other config
79
+ telemetry: {
80
+ serviceName: "my-app",
81
+ enabled: true,
82
+ export: {
83
+ type: "otlp",
84
+ // endpoint and headers will be picked up from env vars
85
+ },
86
+ },
87
+ });
88
+ ```
89
+
90
+ ### Example: SigNoz Integration
91
+
92
+ Here's what a traced agent interaction looks like in [SigNoz](https://signoz.io):
93
+
94
+ <img
95
+ src="/docs/signoz-telemetry-demo.png"
96
+ alt="Agent interaction trace showing spans, LLM calls, and tool executions"
97
+ style={{ maxWidth: "800px", width: "100%", margin: "8px 0" }}
98
+ className="nextra-image rounded-md"
99
+ data-zoom
100
+ width={800}
101
+ height={400}
102
+ />
103
+
104
+ ### Other Supported Providers
105
+
106
+ For a complete list of supported observability providers and their configuration details, see the [Observability Providers reference](../../reference/observability/providers/).
107
+
108
+ ### Next.js-specific Tracing steps
109
+
110
+ If you're using Next.js, you have three additional configuration steps:
111
+ 1. Enable the instrumentation hook in `next.config.ts`
112
+ 2. Configure Mastra telemetry settings
113
+ 3. Set up an OpenTelemetry exporter
114
+
115
+ For implementation details, see the [Next.js Tracing](./nextjs-tracing) guide.
package/.docs/raw/rag/chunking-and-embedding.mdx ADDED
@@ -0,0 +1,156 @@
1
+ ---
2
+ title: Chunking and Embedding Documents | RAG | Mastra Docs
3
+ description: Guide on chunking and embedding documents in Mastra for efficient processing and retrieval.
4
+ ---
5
+
6
+ ## Chunking and Embedding Documents
7
+
8
+ Before processing, create a MDocument instance from your content. You can initialize it from various formats:
9
+
10
+ ```ts showLineNumbers copy
11
+ const docFromText = MDocument.fromText("Your plain text content...");
12
+ const docFromHTML = MDocument.fromHTML("<html>Your HTML content...</html>");
13
+ const docFromMarkdown = MDocument.fromMarkdown("# Your Markdown content...");
14
+ const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`);
15
+ ```
16
+
17
+ ## Step 1: Document Processing
18
+
19
+ Use `chunk` to split documents into manageable pieces. Mastra supports multiple chunking strategies optimized for different document types:
20
+
21
+ - `recursive`: Smart splitting based on content structure
22
+ - `character`: Simple character-based splits
23
+ - `token`: Token-aware splitting
24
+ - `markdown`: Markdown-aware splitting
25
+ - `html`: HTML structure-aware splitting
26
+ - `json`: JSON structure-aware splitting
27
+ - `latex`: LaTeX structure-aware splitting
28
+
29
+ Here's an example of how to use the `recursive` strategy:
30
+
31
+ ```ts showLineNumbers copy
32
+ const chunks = await doc.chunk({
33
+ strategy: "recursive",
34
+ size: 512,
35
+ overlap: 50,
36
+ separator: "\n",
37
+ extract: {
38
+ metadata: true, // Optionally extract metadata
39
+ },
40
+ });
41
+ ```
42
+
43
+ **Note:** Metadata extraction may use LLM calls, so ensure your API key is set.
44
+
45
+ We go deeper into chunking strategies in our [chunk documentation](/reference/rag/chunk.mdx).
46
+
47
+ ## Step 2: Embedding Generation
48
+
49
+ Transform chunks into embeddings using your preferred provider. Mastra supports many embedding providers, including OpenAI and Cohere:
50
+
51
+ ### Using OpenAI
52
+
53
+ ```ts showLineNumbers copy
54
+ import { openai } from "@ai-sdk/openai";
55
+ import { embedMany } from "ai";
56
+
57
+ const { embeddings } = await embedMany({
58
+ model: openai.embedding('text-embedding-3-small'),
59
+ values: chunks.map(chunk => chunk.text),
60
+ });
61
+ ```
62
+
63
+ ### Using Cohere
64
+
65
+ ```ts showLineNumbers copy
66
+ import { cohere } from '@ai-sdk/cohere';
67
+ import { embedMany } from 'ai';
68
+
69
+ const { embeddings } = await embedMany({
70
+ model: cohere.embedding('embed-english-v3.0'),
71
+ values: chunks.map(chunk => chunk.text),
72
+ });
73
+ ```
74
+
75
+ The embedding functions return vectors, arrays of numbers representing the semantic meaning of your text, ready for similarity searches in your vector database.
76
+
77
+ ### Configuring Embedding Dimensions
78
+
79
+ Embedding models typically output vectors with a fixed number of dimensions (e.g., 1536 for OpenAI's `text-embedding-3-small`).
80
+ Some models support reducing this dimensionality, which can help:
81
+ - Decrease storage requirements in vector databases
82
+ - Reduce computational costs for similarity searches
83
+
84
+ Here are some supported models:
85
+
86
+ OpenAI (text-embedding-3 models):
87
+ ```ts
88
+ const { embeddings } = await embedMany({
89
+ model: openai.embedding('text-embedding-3-small', {
90
+ dimensions: 256 // Only supported in text-embedding-3 and later
91
+ }),
92
+ values: chunks.map(chunk => chunk.text),
93
+ });
94
+ ```
95
+
96
+ Google (text-embedding-004):
97
+ ```ts
98
+ const { embeddings } = await embedMany({
99
+ model: google.textEmbeddingModel('text-embedding-004', {
100
+ outputDimensionality: 256 // Truncates excessive values from the end
101
+ }),
102
+ values: chunks.map(chunk => chunk.text),
103
+ });
104
+ ```
105
+
106
+ ## Example: Complete Pipeline
107
+
108
+ Here's an example showing document processing and embedding generation with both providers:
109
+
110
+ ```ts showLineNumbers copy
111
+ import { embedMany } from "ai";
112
+ import { openai } from "@ai-sdk/openai";
113
+ import { cohere } from "@ai-sdk/cohere";
114
+
115
+ import { MDocument } from "@mastra/rag";
116
+
117
+ // Initialize document
118
+ const doc = MDocument.fromText(`
119
+ Climate change poses significant challenges to global agriculture.
120
+ Rising temperatures and changing precipitation patterns affect crop yields.
121
+ `);
122
+
123
+ // Create chunks
124
+ const chunks = await doc.chunk({
125
+ strategy: "recursive",
126
+ size: 256,
127
+ overlap: 50,
128
+ });
129
+
130
+ // Generate embeddings with OpenAI
131
+ const { embeddings: openAIEmbeddings } = await embedMany({
132
+ model: openai.embedding('text-embedding-3-small'),
133
+ values: chunks.map(chunk => chunk.text),
134
+ });
135
+
136
+ // OR
137
+
138
+ // Generate embeddings with Cohere
139
+ const { embeddings: cohereEmbeddings } = await embedMany({
140
+ model: cohere.embedding('embed-english-v3.0'),
141
+ values: chunks.map(chunk => chunk.text),
142
+ });
143
+
144
+ // Store embeddings in your vector database
145
+ await vectorStore.upsert({
146
+ indexName: "embeddings",
147
+ vectors: embeddings,
148
+ });
149
+ ```
150
+
151
+ ##
152
+ For more examples of different chunking strategies and embedding configurations, see:
153
+
154
+ - [Adjust Chunk Size](/reference/rag/chunk.mdx#adjust-chunk-size)
155
+ - [Adjust Chunk Delimiters](/reference/rag/chunk.mdx#adjust-chunk-delimiters)
156
+ - [Embed Text with Cohere](/reference/rag/embeddings.mdx#using-cohere)
package/.docs/raw/rag/overview.mdx ADDED
@@ -0,0 +1,85 @@
1
+ ---
2
+ title: RAG (Retrieval-Augmented Generation) in Mastra | Mastra Docs
3
+ description: Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
4
+ ---
5
+
6
+ # RAG (Retrieval-Augmented Generation) in Mastra
7
+
8
+ RAG in Mastra helps you enhance LLM outputs by incorporating relevant context from your own data sources, improving accuracy and grounding responses in real information.
9
+
10
+ Mastra's RAG system provides:
11
+
12
+ - Standardized APIs to process and embed documents
13
+ - Support for multiple vector stores
14
+ - Chunking and embedding strategies for optimal retrieval
15
+ - Observability for tracking embedding and retrieval performance
16
+
17
+ ## Example
18
+
19
+ To implement RAG, you process your documents into chunks, create embeddings, store them in a vector database, and then retrieve relevant context at query time.
20
+
21
+ ```ts showLineNumbers copy
22
+ import { embedMany } from "ai";
23
+ import { openai } from "@ai-sdk/openai";
24
+ import { PgVector } from "@mastra/pg";
25
+ import { MDocument } from "@mastra/rag";
26
+ import { z } from "zod";
27
+
28
+ // 1. Initialize document
29
+ const doc = MDocument.fromText(`Your document text here...`);
30
+
31
+ // 2. Create chunks
32
+ const chunks = await doc.chunk({
33
+ strategy: "recursive",
34
+ size: 512,
35
+ overlap: 50,
36
+ });
37
+
38
+ // 3. Generate embeddings; we need to pass the text of each chunk
39
+ const { embeddings } = await embedMany({
40
+ values: chunks.map(chunk => chunk.text),
41
+ model: openai.embedding("text-embedding-3-small"),
42
+ });
43
+
44
+ // 4. Store in vector database
45
+ const pgVector = new PgVector(process.env.POSTGRES_CONNECTION_STRING);
46
+ await pgVector.upsert({
47
+ indexName: "embeddings",
48
+ vectors: embeddings,
49
+ }); // using an index name of 'embeddings'
50
+
51
+ // 5. Query similar chunks
52
+ const results = await pgVector.query({
53
+ indexName: "embeddings",
54
+ queryVector: queryVector,
55
+ topK: 3,
56
+ }); // queryVector is the embedding of the query
57
+
58
+ console.log("Similar chunks:", results);
59
+ ```
60
+
61
+ This example shows the essentials: initialize a document, create chunks, generate embeddings, store them, and query for similar content.
62
+
63
+ ## Document Processing
64
+
65
+ The basic building block of RAG is document processing. Documents can be chunked using various strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](./chunking-and-embedding.mdx).
66
+
67
+ ## Vector Storage
68
+
69
+ Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, and Qdrant. See the [vector database doc](./vector-databases.mdx).
70
+
71
+ ## Observability and Debugging
72
+
73
+ Mastra's RAG system includes observability features to help you optimize your retrieval pipeline:
74
+
75
+ - Track embedding generation performance and costs
76
+ - Monitor chunk quality and retrieval relevance
77
+ - Analyze query patterns and cache hit rates
78
+ - Export metrics to your observability platform
79
+
80
+ See the [OTel Configuration](../reference/observability/otel-config.mdx) page for more details.
81
+
82
+ ## More resources
83
+
84
+ - [Chain of Thought RAG Example](../../examples/rag/usage/cot-rag.mdx)
85
+ - [All RAG Examples](../../examples/) (including different chunking strategies, embedding models, and vector stores)