@mastra/mcp-docs-server 0.0.3 → 0.0.4-alpha.1

package/.docs/raw/reference/voice/sarvam.mdx

@@ -0,0 +1,260 @@
+---
+title: "Reference: Sarvam Voice | Voice Providers | Mastra Docs"
+description: "Documentation for the Sarvam class, providing text-to-speech and speech-to-text capabilities."
+---
+
+# Sarvam
+
+The SarvamVoice class in Mastra provides text-to-speech and speech-to-text capabilities using Sarvam AI models.
+
+## Usage Example
+
+```typescript
+import { SarvamVoice } from "@mastra/voice-sarvam";
+
+// Initialize with default configuration using environment variables
+const voice = new SarvamVoice();
+
+// Or initialize with specific configuration
+const voiceWithConfig = new SarvamVoice({
+   speechModel: {
+    model: "bulbul:v1",
+    apiKey: process.env.SARVAM_API_KEY!,
+    language: "en-IN",
+    properties: {
+      pitch: 0,
+      pace: 1.65,
+      loudness: 1.5,
+      speech_sample_rate: 8000,
+      enable_preprocessing: false,
+      eng_interpolation_wt: 123,
+    },
+  },
+  listeningModel: {
+    model: "saarika:v2",
+    apiKey: process.env.SARVAM_API_KEY!,
+    languageCode: "en-IN",
+     filetype?: 'wav';
+  },
+  speaker: "meera", // Default voice
+});
+
+
+// Convert text to speech
+const audioStream = await voice.speak("Hello, how can I help you?");
+
+
+// Convert speech to text
+const text = await voice.listen(audioStream, {
+  filetype: "wav",
+});
+```
+
+### Sarvam API Docs -
+
+https://docs.sarvam.ai/api-reference-docs/endpoints/text-to-speech
+
+## Configuration
+
+### Constructor Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "speechModel",
+      type: "SarvamVoiceConfig",
+      description: "Configuration for text-to-speech synthesis.",
+      isOptional: true,
+      defaultValue: "{ model: 'bulbul:v1', language: 'en-IN' }",
+    },
+    {
+      name: "speaker",
+      type: "SarvamVoiceId",
+      description:
+        "The speaker to be used for the output audio. If not provided, Meera will be used as default. AvailableOptions - meera, pavithra, maitreyi, arvind, amol, amartya, diya, neel, misha, vian, arjun, maya",
+      isOptional: true,
+      defaultValue: "'meera'",
+    },
+    {
+      name: "listeningModel",
+      type: "SarvamListenOptions",
+      description: "Configuration for speech-to-text recognition.",
+      isOptional: true,
+      defaultValue: "{ model: 'saarika:v2', language_code: 'unknown' }",
+    },
+  ]}
+/>
+
+### SarvamVoiceConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "apiKey",
+      type: "string",
+      description:
+        "Sarvam API key. Falls back to SARVAM_API_KEY environment variable.",
+      isOptional: true,
+    },
+    {
+      name: "model",
+      type: "SarvamTTSModel",
+      description: "Specifies the model to use for text-to-speech conversion.",
+      isOptional: true,
+      defaultValue: "'bulbul:v1'",
+    },
+    {
+      name: "language",
+      type: "SarvamTTSLanguage",
+      description:
+        "Target language for speech synthesis. Available options: hi-IN, bn-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN, en-IN, gu-IN",
+      isOptional: false,
+      defaultValue: "'en-IN'",
+    },
+    {
+      name: "properties",
+      type: "object",
+      description: "Additional voice properties for customization.",
+      isOptional: true,
+    },
+    {
+      name: "properties.pitch",
+      type: "number",
+      description:
+        "Controls the pitch of the audio. Lower values result in a deeper voice, while higher values make it sharper. The suitable range is between -0.75 and 0.75.",
+      isOptional: true,
+    },
+    {
+      name: "properties.pace",
+      type: "number",
+      description:
+        "Controls the speed of the audio. Lower values result in slower speech, while higher values make it faster. The suitable range is between 0.5 and 2.0. Default is 1.0. Required range: 0.3 <= x <= 3",
+      isOptional: true,
+    },
+    {
+      name: "properties.loudness",
+      type: "number",
+      description:
+        "Controls the loudness of the audio. Lower values result in quieter audio, while higher values make it louder. The suitable range is between 0.3 and 3.0. Required range: 0 <= x <= 3",
+      isOptional: true,
+    },
+    {
+      name: "properties.speech_sample_rate",
+      type: "8000 | 16000 | 22050",
+      description: "Audio sample rate in Hz.",
+      isOptional: true,
+    },
+    {
+      name: "properties.enable_preprocessing",
+      type: "boolean",
+      description:
+        "Controls whether normalization of English words and numeric entities (e.g., numbers, dates) is performed. Set to true for better handling of mixed-language text. Default is false.",
+      isOptional: true,
+    },
+    {
+      name: "properties.eng_interpolation_wt",
+      type: "number",
+      description: "Weight for interpolating with English speaker at encoder.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### SarvamListenOptions
+
+<PropertiesTable
+  content={[
+    {
+      name: "apiKey",
+      type: "string",
+      description:
+        "Sarvam API key. Falls back to SARVAM_API_KEY environment variable.",
+      isOptional: true,
+    },
+    {
+      name: "model",
+      type: "SarvamSTTModel",
+      description:
+        "Specifies the model to use for speech-to-text conversion. Note:- Default model is saarika:v2 . Available options: saarika:v1, saarika:v2, saarika:flash ",
+      isOptional: true,
+      defaultValue: "'saarika:v2'",
+    },
+    {
+      name: "languageCode",
+      type: "SarvamSTTLanguage",
+      description:
+        "Specifies the language of the input audio. This parameter is required to ensure accurate transcription. For the saarika:v1 model, this parameter is mandatory. For the saarika:v2 model, it is optional. unknown: Use this when the language is not known; the API will detect it automatically. Note:- that the saarika:v1 model does not support unknown language code. Available options: unknown, hi-IN, bn-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN, en-IN, gu-IN ",
+      isOptional: true,
+      defaultValue: "'unknown'",
+    },
+    {
+      name: "filetype",
+      type: "'mp3' | 'wav'",
+      description: "Audio format of the input stream.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Methods
+
+### speak()
+
+Converts text to speech using Sarvam's text-to-speech models.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "string | NodeJS.ReadableStream",
+      description: "Text or text stream to convert to speech.",
+      isOptional: false,
+    },
+    {
+      name: "options.speaker",
+      type: "SarvamVoiceId",
+      description: "Voice ID to use for speech synthesis.",
+      isOptional: true,
+      defaultValue: "Constructor's speaker value",
+    },
+  ]}
+/>
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### listen()
+
+Transcribes audio using Sarvam's speech recognition models.
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "NodeJS.ReadableStream",
+      description: "Audio stream to transcribe.",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "SarvamListenOptions",
+      description: "Configuration options for speech recognition.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+Returns: `Promise<string>`
+
+### getSpeakers()
+
+Returns an array of available voice options.
+
+Returns: `Promise<Array<{voiceId: SarvamVoiceId}>>`
+
+## Notes
+
+- API key can be provided via constructor options or the `SARVAM_API_KEY` environment variable
+- If no API key is provided, the constructor will throw an error
+- The service communicates with the Sarvam AI API at `https://api.sarvam.ai`
+- Audio is returned as a stream containing binary audio data
+- Speech recognition supports mp3 and wav audio formats

package/.docs/raw/reference/workflows/afterEvent.mdx

@@ -0,0 +1,76 @@
+---
+title: ".afterEvent() Method | Mastra Docs"
+description: "Reference for the afterEvent method in Mastra workflows that creates event-based suspension points."
+---
+
+# afterEvent()
+
+The `afterEvent()` method creates a suspension point in your workflow that waits for a specific event to occur before continuing execution.
+
+## Syntax
+
+```typescript
+workflow.afterEvent(eventName: string): Workflow
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| eventName | string | The name of the event to wait for. Must match an event defined in the workflow's `events` configuration. |
+
+## Return Value
+
+Returns the workflow instance for method chaining.
+
+## Description
+
+The `afterEvent()` method is used to create an automatic suspension point in your workflow that waits for a specific named event. It's essentially a declarative way to define a point where your workflow should pause and wait for an external event to occur.
+
+When you call `afterEvent()`, Mastra:
+
+1. Creates a special step with ID `__eventName_event`
+2. This step automatically suspends the workflow execution
+3. The workflow remains suspended until the specified event is triggered via `resumeWithEvent()`
+4. When the event occurs, execution continues with the step following the `afterEvent()` call
+
+This method is part of Mastra's event-driven workflow capabilities, allowing you to create workflows that coordinate with external systems or user interactions without manually implementing suspension logic.
+
+## Usage Notes
+
+- The event specified in `afterEvent()` must be defined in the workflow's `events` configuration with a schema
+- The special step created has a predictable ID format: `__eventName_event` (e.g., `__approvalReceived_event`)
+- Any step following `afterEvent()` can access the event data via `context.inputData.resumedEvent`
+- Event data is validated against the schema defined for that event when `resumeWithEvent()` is called
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Define workflow with events
+const workflow = new Workflow({
+  name: 'approval-workflow',
+  events: {
+    approval: {
+      schema: z.object({
+        approved: z.boolean(),
+        approverName: z.string(),
+      }),
+    },
+  },
+});
+
+// Build workflow with event suspension point
+workflow
+  .step(submitRequest)
+  .afterEvent('approval')    // Workflow suspends here
+  .step(processApproval)     // This step runs after the event occurs
+  .commit();
+```
+## Related
+
+- [Event-Driven Workflows](./events.mdx)
+- [resumeWithEvent()](./resumeWithEvent.mdx)
+- [Suspend and Resume](../../workflows/suspend-and-resume.mdx)
+- [Workflow Class](./workflow.mdx)

package/.docs/raw/reference/workflows/events.mdx

@@ -0,0 +1,305 @@
+---
+title: "Event-Driven Workflows | Mastra Docs"
+description: "Learn how to create event-driven workflows using afterEvent and resumeWithEvent methods in Mastra."
+---
+
+# Event-Driven Workflows
+
+Mastra provides built-in support for event-driven workflows through the `afterEvent` and `resumeWithEvent` methods. These methods allow you to create workflows that pause execution while waiting for specific events to occur, then resume with the event data when it's available.
+
+## Overview
+
+Event-driven workflows are useful for scenarios where:
+
+- You need to wait for external systems to complete processing
+- User approval or input is required at specific points
+- Asynchronous operations need to be coordinated
+- Long-running processes need to break up execution across different services
+
+## Defining Events
+
+Before using event-driven methods, you must define the events your workflow will listen for in the workflow configuration:
+
+```typescript
+import { Workflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+const workflow = new Workflow({
+  name: 'approval-workflow',
+  triggerSchema: z.object({ requestId: z.string() }),
+  events: {
+    // Define events with their validation schemas
+    approvalReceived: {
+      schema: z.object({
+        approved: z.boolean(),
+        approverName: z.string(),
+        comment: z.string().optional(),
+      }),
+    },
+    documentUploaded: {
+      schema: z.object({
+        documentId: z.string(),
+        documentType: z.enum(['invoice', 'receipt', 'contract']),
+        metadata: z.record(z.string()).optional(),
+      }),
+    },
+  },
+});
+```
+
+Each event must have a name and a schema that defines the structure of data expected when the event occurs.
+
+## afterEvent()
+
+The `afterEvent` method creates a suspension point in your workflow that automatically waits for a specific event.
+
+### Syntax
+
+```typescript
+workflow.afterEvent(eventName: string): Workflow
+```
+
+### Parameters
+
+- `eventName`: The name of the event to wait for (must be defined in the workflow's `events` configuration)
+
+### Return Value
+
+Returns the workflow instance for method chaining.
+
+### How It Works
+
+When `afterEvent` is called, Mastra:
+
+1. Creates a special step with ID `__eventName_event`
+2. Configures this step to automatically suspend workflow execution
+3. Sets up the continuation point after the event is received
+
+### Usage Example
+
+```typescript
+workflow
+  .step(initialProcessStep)
+  .afterEvent('approvalReceived')  // Workflow suspends here
+  .step(postApprovalStep)          // This runs after event is received
+  .then(finalStep)
+  .commit();
+```
+
+## resumeWithEvent()
+
+The `resumeWithEvent` method resumes a suspended workflow by providing data for a specific event.
+
+### Syntax
+
+```typescript
+run.resumeWithEvent(eventName: string, data: any): Promise<WorkflowRunResult>
+```
+
+### Parameters
+
+- `eventName`: The name of the event being triggered
+- `data`: The event data (must conform to the schema defined for this event)
+
+### Return Value
+
+Returns a Promise that resolves to the workflow execution results after resumption.
+
+### How It Works
+
+When `resumeWithEvent` is called, Mastra:
+
+1. Validates the event data against the schema defined for that event
+2. Loads the workflow snapshot
+3. Updates the context with the event data
+4. Resumes execution from the event step
+5. Continues workflow execution with the subsequent steps
+
+### Usage Example
+
+```typescript
+// Create a workflow run
+const run = workflow.createRun();
+
+// Start the workflow
+await run.start({ triggerData: { requestId: 'req-123' } });
+
+// Later, when the event occurs:
+const result = await run.resumeWithEvent('approvalReceived', {
+  approved: true,
+  approverName: 'John Doe',
+  comment: 'Looks good to me!'
+});
+
+console.log(result.results);
+```
+
+## Accessing Event Data
+
+When a workflow is resumed with event data, that data is available in the step context as `context.inputData.resumedEvent`:
+
+```typescript
+const processApprovalStep = new Step({
+  id: 'processApproval',
+  execute: async ({ context }) => {
+    // Access the event data
+    const eventData = context.inputData.resumedEvent;
+
+    return {
+      processingResult: `Processed approval from ${eventData.approverName}`,
+      wasApproved: eventData.approved,
+    };
+  },
+});
+```
+
+## Multiple Events
+
+You can create workflows that wait for multiple different events at various points:
+
+```typescript
+workflow
+  .step(createRequest)
+  .afterEvent('approvalReceived')
+  .step(processApproval)
+  .afterEvent('documentUploaded')
+  .step(processDocument)
+  .commit();
+```
+
+When resuming a workflow with multiple event suspension points, you need to provide the correct event name and data for the current suspension point.
+
+## Practical Example
+
+This example shows a complete workflow that requires both approval and document upload:
+
+```typescript
+import { Workflow, Step } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+// Define steps
+const createRequest = new Step({
+  id: 'createRequest',
+  execute: async () => ({ requestId: `req-${Date.now()}` }),
+});
+
+const processApproval = new Step({
+  id: 'processApproval',
+  execute: async ({ context }) => {
+    const approvalData = context.inputData.resumedEvent;
+    return {
+      approved: approvalData.approved,
+      approver: approvalData.approverName,
+    };
+  },
+});
+
+const processDocument = new Step({
+  id: 'processDocument',
+  execute: async ({ context }) => {
+    const documentData = context.inputData.resumedEvent;
+    return {
+      documentId: documentData.documentId,
+      processed: true,
+      type: documentData.documentType,
+    };
+  },
+});
+
+const finalizeRequest = new Step({
+  id: 'finalizeRequest',
+  execute: async ({ context }) => {
+    const requestId = context.steps.createRequest.output.requestId;
+    const approved = context.steps.processApproval.output.approved;
+    const documentId = context.steps.processDocument.output.documentId;
+
+    return {
+      finalized: true,
+      summary: `Request ${requestId} was ${approved ? 'approved' : 'rejected'} with document ${documentId}`
+    };
+  },
+});
+
+// Create workflow
+const requestWorkflow = new Workflow({
+  name: 'document-request-workflow',
+  events: {
+    approvalReceived: {
+      schema: z.object({
+        approved: z.boolean(),
+        approverName: z.string(),
+      }),
+    },
+    documentUploaded: {
+      schema: z.object({
+        documentId: z.string(),
+        documentType: z.enum(['invoice', 'receipt', 'contract']),
+      }),
+    },
+  },
+});
+
+// Build workflow
+requestWorkflow
+  .step(createRequest)
+  .afterEvent('approvalReceived')
+  .step(processApproval)
+  .afterEvent('documentUploaded')
+  .step(processDocument)
+  .then(finalizeRequest)
+  .commit();
+
+// Export workflow
+export { requestWorkflow };
+```
+
+### Running the Example Workflow
+
+```typescript
+import { requestWorkflow } from './workflows';
+import { mastra } from './mastra';
+
+async function runWorkflow() {
+  // Get the workflow
+  const workflow = mastra.getWorkflow('document-request-workflow');
+  const run = workflow.createRun();
+
+  // Start the workflow
+  const initialResult = await run.start();
+  console.log('Workflow started:', initialResult.results);
+
+  // Simulate receiving approval
+  const afterApprovalResult = await run.resumeWithEvent('approvalReceived', {
+    approved: true,
+    approverName: 'Jane Smith',
+  });
+  console.log('After approval:', afterApprovalResult.results);
+
+  // Simulate document upload
+  const finalResult = await run.resumeWithEvent('documentUploaded', {
+    documentId: 'doc-456',
+    documentType: 'invoice',
+  });
+  console.log('Final result:', finalResult.results);
+}
+
+runWorkflow().catch(console.error);
+```
+
+## Best Practices
+
+1. **Define Clear Event Schemas**: Use Zod to create precise schemas for event data validation
+2. **Use Descriptive Event Names**: Choose event names that clearly communicate their purpose
+3. **Handle Missing Events**: Ensure your workflow can handle cases where events don't occur or time out
+4. **Include Monitoring**: Use the `watch` method to monitor suspended workflows waiting for events
+5. **Consider Timeouts**: Implement timeout mechanisms for events that may never occur
+6. **Document Events**: Clearly document the events your workflow depends on for other developers
+
+## Related
+
+- [Suspend and Resume in Workflows](../../workflows/suspend-and-resume.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Resume Method Reference](./resume.mdx)
+- [Watch Method Reference](./watch.mdx)
+- [After Event Reference](./afterEvent.mdx)
+- [Resume With Event Reference](./resumeWithEvent.mdx)