@mastra/mcp-docs-server 0.13.7-alpha.1 → 0.13.7-alpha.3

package/.docs/raw/reference/rag/upstash.mdx

@@ -5,7 +5,7 @@ description: Documentation for the UpstashVector class in Mastra, which provides
 
 # Upstash Vector Store
 
-The UpstashVector class provides vector search using [Upstash Vector](https://upstash.com/vector), a serverless vector database service that provides vector similarity search with metadata filtering capabilities.
+The UpstashVector class provides vector search using [Upstash Vector](https://upstash.com/vector), a serverless vector database service that provides vector similarity search with metadata filtering capabilities and hybrid search support.
 
 ## Constructor Options
 
@@ -66,6 +66,12 @@ Note: This method is a no-op for Upstash as indexes are created automatically.
       type: "number[][]",
       description: "Array of embedding vectors",
     },
+    {
+      name: "sparseVectors",
+      type: "{ indices: number[], values: number[] }[]",
+      isOptional: true,
+      description: "Array of sparse vectors for hybrid search. Each sparse vector must have matching indices and values arrays.",
+    },
     {
       name: "metadata",
       type: "Record<string, any>[]",
@@ -95,6 +101,12 @@ Note: This method is a no-op for Upstash as indexes are created automatically.
       type: "number[]",
       description: "Query vector to find similar vectors",
     },
+    {
+      name: "sparseVector",
+      type: "{ indices: number[], values: number[] }",
+      isOptional: true,
+      description: "Optional sparse vector for hybrid search. Must have matching indices and values arrays.",
+    },
     {
       name: "topK",
       type: "number",
@@ -115,6 +127,18 @@ Note: This method is a no-op for Upstash as indexes are created automatically.
       defaultValue: "false",
       description: "Whether to include vectors in the results",
     },
+    {
+      name: "fusionAlgorithm",
+      type: "FusionAlgorithm",
+      isOptional: true,
+      description: "Algorithm used to combine dense and sparse search results in hybrid search (e.g., RRF - Reciprocal Rank Fusion)",
+    },
+    {
+      name: "queryMode",
+      type: "QueryMode",
+      isOptional: true,
+      description: "Search mode: 'DENSE' for dense-only, 'SPARSE' for sparse-only, or 'HYBRID' for combined search",
+    },
   ]}
 />
 
@@ -173,18 +197,17 @@ interface IndexStats {
     {
       name: "update",
       type: "object",
-      description: "Update object containing vector and/or metadata",
+      description: "Update object containing vector, sparse vector, and/or metadata",
     },
   ]}
 />
 
 The `update` object can have the following properties:
 
-- `vector` (optional): An array of numbers representing the new vector.
+- `vector` (optional): An array of numbers representing the new dense vector.
+- `sparseVector` (optional): A sparse vector object with `indices` and `values` arrays for hybrid indexes.
 - `metadata` (optional): A record of key-value pairs for metadata.
 
-Throws an error if neither `vector` nor `metadata` is provided, or if only `metadata` is provided.
-
 ### deleteVector()
 
 <PropertiesTable
@@ -204,6 +227,90 @@ Throws an error if neither `vector` nor `metadata` is provided, or if only `meta
 
 Attempts to delete an item by its ID from the specified index. Logs an error message if the deletion fails.
 
+## Hybrid Vector Search
+
+Upstash Vector supports hybrid search that combines semantic search (dense vectors) with keyword-based search (sparse vectors) for improved relevance and accuracy.
+
+### Basic Hybrid Usage
+
+```typescript copy
+import { UpstashVector } from '@mastra/upstash';
+
+const vectorStore = new UpstashVector({
+  url: process.env.UPSTASH_VECTOR_URL,
+  token: process.env.UPSTASH_VECTOR_TOKEN
+});
+
+// Upsert vectors with both dense and sparse components
+const denseVectors = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]];
+const sparseVectors = [
+  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
+  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] }
+];
+
+await vectorStore.upsert({
+  indexName: 'hybrid-index',
+  vectors: denseVectors,
+  sparseVectors: sparseVectors,
+  metadata: [{ title: 'Document 1' }, { title: 'Document 2' }]
+});
+
+// Query with hybrid search
+const results = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  topK: 10
+});
+```
+
+### Advanced Hybrid Search Options
+
+```typescript copy
+import { FusionAlgorithm, QueryMode } from '@upstash/vector';
+
+// Query with specific fusion algorithm
+const fusionResults = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  fusionAlgorithm: FusionAlgorithm.RRF,
+  topK: 10
+});
+
+// Dense-only search
+const denseResults = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3],
+  queryMode: QueryMode.DENSE,
+  topK: 10
+});
+
+// Sparse-only search
+const sparseResults = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  queryMode: QueryMode.SPARSE,
+  topK: 10
+});
+```
+
+### Updating Hybrid Vectors
+
+```typescript copy
+// Update both dense and sparse components
+await vectorStore.updateVector({
+  indexName: 'hybrid-index',
+  id: 'vector-id',
+  update: {
+    vector: [0.2, 0.3, 0.4],
+    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
+    metadata: { title: 'Updated Document' }
+  }
+});
+```
+
 ## Response Types
 
 Query results are returned in this format:

package/.docs/raw/reference/scorers/answer-relevancy.mdx

@@ -111,5 +111,4 @@ The scorer evaluates relevancy through query-answer alignment, considering compl
 
 ## Related
 
-- [Prompt Alignment Scorer](./prompt-alignment)
 - [Faithfulness Scorer](./faithfulness)

package/.docs/raw/reference/scorers/faithfulness.mdx

@@ -120,4 +120,3 @@ Final score: `(supported_claims / total_claims) * scale`
 
 - [Answer Relevancy Scorer](./answer-relevancy)
 - [Hallucination Scorer](./hallucination)
-- [Context Relevancy Scorer](./context-relevancy)

package/.docs/raw/reference/scorers/hallucination.mdx

@@ -131,5 +131,3 @@ Final score: `(hallucinated_statements / total_statements) * scale`
 
 - [Faithfulness Scorer](./faithfulness)
 - [Answer Relevancy Scorer](./answer-relevancy)
-- [Context Precision Scorer](./context-precision)
-- [Context Relevancy Scorer](./context-relevancy)

package/.docs/raw/reference/scorers/llm-scorer.mdx

@@ -3,7 +3,7 @@ title: "Reference: createLLMScorer | Scorers | Mastra Docs"
 description: Documentation for creating LLM-based scorers in Mastra, allowing users to define evaluation logic using language models.
 ---
 
-# LLM Scorer
+# createLLMScorer
 
 The `createLLMScorer()` function lets you define custom scorers that use a language model (LLM) as a judge for evaluation. LLM scorers are ideal for tasks where you want to use prompt-based evaluation, such as answer relevancy, faithfulness, or custom prompt-based metrics. LLM scorers integrate seamlessly with the Mastra scoring framework and can be used anywhere built-in scorers are used.
 
@@ -138,6 +138,50 @@ This function returns an instance of the MastraScorer class. See the [MastraScor
   ]}
 />
 
+## Calculate Score Function
+
+The `calculateScore` function converts the LLM's structured analysis into a numerical score. This function receives the results from previous steps but not the score itself (since that's what it calculates).
+
+<PropertiesTable
+  content={[
+    {
+      name: "input",
+      type: "Record<string, any>[]",
+      required: true,
+      description:
+        "Input records provided to the scorer. If the scorer is added to an agent, this will be an array of user messages, e.g. `[{ role: 'user', content: 'hello world' }]`. If the scorer is used in a workflow, this will be the input of the workflow.",
+    },
+    {
+      name: "output",
+      type: "Record<string, any>",
+      required: true,
+      description:
+        "Output record provided to the scorer. For agents, this is usually the agent's response. For workflows, this is the workflow's output.",
+    },
+    {
+      name: "runtimeContext",
+      type: "object",
+      required: false,
+      description: "Runtime context from the agent or workflow step being evaluated (optional).",
+    },
+    {
+      name: "extractStepResult",
+      type: "object",
+      required: false,
+      description: "Result of the extract step, if defined (optional).",
+    },
+    {
+      name: "analyzeStepResult",
+      type: "object",
+      required: true,
+      description: "Structured result from the analyze step, conforming to the outputSchema defined in the analyze step.",
+    },
+  ]}
+/>
+
+Returns: `number`  
+The function must return a numerical score, typically in the 0-1 range where 1 represents the best possible score.
+
 ## Reason Object
 <PropertiesTable
   content={[

package/.docs/raw/reference/storage/libsql.mdx

@@ -65,7 +65,10 @@ For production use cases, use a persistent database URL: `libsql://your-database
 
 The storage implementation handles schema creation and updates automatically. It creates the following tables:
 
-- `threads`: Stores conversation threads
-- `messages`: Stores individual messages
-- `resources`: Stores user-specific data for resource-scoped working memory
-- `metadata`: Stores additional metadata for threads and messages
+- `mastra_workflow_snapshot`: Stores workflow state and execution data
+- `mastra_evals`: Stores evaluation results and metadata  
+- `mastra_threads`: Stores conversation threads
+- `mastra_messages`: Stores individual messages
+- `mastra_traces`: Stores telemetry and tracing data
+- `mastra_scorers`: Stores scoring and evaluation data
+- `mastra_resources`: Stores resource working memory data

package/.docs/raw/reference/storage/mssql.mdx

@@ -88,9 +88,13 @@ const store5 = new MSSQLStore({
 
 The storage implementation handles schema creation and updates automatically. It creates the following tables:
 
-- `threads`: Stores conversation threads
-- `messages`: Stores individual messages
-- `metadata`: Stores additional metadata for threads and messages
+- `mastra_workflow_snapshot`: Stores workflow state and execution data
+- `mastra_evals`: Stores evaluation results and metadata  
+- `mastra_threads`: Stores conversation threads
+- `mastra_messages`: Stores individual messages
+- `mastra_traces`: Stores telemetry and tracing data
+- `mastra_scorers`: Stores scoring and evaluation data
+- `mastra_resources`: Stores resource working memory data
 
 ### Direct Database and Pool Access
 

package/.docs/raw/reference/storage/postgresql.mdx

@@ -88,9 +88,13 @@ const store5 = new PostgresStore({
 
 The storage implementation handles schema creation and updates automatically. It creates the following tables:
 
-- `threads`: Stores conversation threads
-- `messages`: Stores individual messages
-- `metadata`: Stores additional metadata for threads and messages
+- `mastra_workflow_snapshot`: Stores workflow state and execution data
+- `mastra_evals`: Stores evaluation results and metadata  
+- `mastra_threads`: Stores conversation threads
+- `mastra_messages`: Stores individual messages
+- `mastra_traces`: Stores telemetry and tracing data
+- `mastra_scorers`: Stores scoring and evaluation data
+- `mastra_resources`: Stores resource working memory data
 
 ### Direct Database and Pool Access
 

package/.docs/raw/reference/templates.mdx

@@ -70,7 +70,7 @@ All templates follow this standardized structure:
           <FileTree.File name="example-agent.ts" />
         </FileTree.Folder>
         <FileTree.Folder name="tools">
-          <FileTree.File name="custom-tool.ts" />
+          <FileTree.File name="example-tool.ts" />
         </FileTree.Folder>
         <FileTree.Folder name="workflows">
           <FileTree.File name="example-workflow.ts" />
@@ -126,8 +126,10 @@ Use the standard Mastra TypeScript configuration:
 Include a `.env.example` file with all required environment variables:
 
 ```bash filename=".env.example"
-# OpenAI API key for LLM operations
+# LLM provider API keys (choose one or more)
 OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
 
 # Other service API keys as needed
 OTHER_SERVICE_API_KEY=your_api_key_here
@@ -137,15 +139,17 @@ OTHER_SERVICE_API_KEY=your_api_key_here
 
 #### LLM Provider
 
-Use OpenAI as the default provider unless demonstrating specific integrations:
+We recommend using OpenAI, Anthropic, or Google model providers for templates. Choose the provider that best fits your use case:
 
 ```typescript filename="src/mastra/agents/example-agent.ts"
-import { Agent } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
 import { openai } from '@ai-sdk/openai';
+// Or use: import { anthropic } from '@ai-sdk/anthropic';
+// Or use: import { google } from '@ai-sdk/google';
 
 const agent = new Agent({
   name: 'example-agent',
-  model: openai('gpt-4'),
+  model: openai('gpt-4'), // or anthropic('') or google('')
   instructions: 'Your agent instructions here',
   // ... other configuration
 });
@@ -186,6 +190,8 @@ Detailed explanation of the template's functionality and use case.
 ## Environment Variables
 
 - `OPENAI_API_KEY`: Your OpenAI API key. Get one at [OpenAI Platform](https://platform.openai.com/api-keys)
+- `ANTHROPIC_API_KEY`: Your Anthropic API key. Get one at [Anthropic Console](https://console.anthropic.com/settings/keys)
+- `GOOGLE_GENERATIVE_AI_API_KEY`: Your Google AI API key. Get one at [Google AI Studio](https://makersuite.google.com/app/apikey)
 - `OTHER_API_KEY`: Description of what this key is for
 
 ## Usage

package/.docs/raw/scorers/custom-scorers.mdx

@@ -0,0 +1,319 @@
+## Creating scorers
+
+Mastra provides two approaches for creating custom scorers:
+
+**Code scorers** use programmatic logic and algorithms. They're ideal for deterministic evaluations, performance-critical scenarios, and cases where you have clear algorithmic criteria.
+
+**LLM scorers** use language models as judges. They're perfect for subjective evaluations, complex criteria that are difficult to code algorithmically, and cases where human-like judgment is needed.
+
+### Code-based scorers
+
+Code scorers use `createScorer` to build evaluation logic with programmatic algorithms. They're ideal for deterministic evaluations, performance-critical scenarios, and cases where you have clear algorithmic criteria or need integration with existing libraries.
+
+Code scorers follow Mastra's three-step evaluation pipeline: 
+- an optional **extract** step for preprocessing complex data
+- a required **analyze** step for core evaluation and scoring
+- and an optional **reason** step for generating explanations.
+
+For the complete API reference, see [`createScorer`](/reference/scorers/custom-code-scorer), and for a detailed explanation of the pipeline, see [evaluation process](/docs/scorers/overview#evaluation-pipeline).
+
+#### Extract Step
+
+This optional step preprocesses input/output data when you need to evaluate multiple distinct elements, filter content, or focus analysis on specific parts of complex data.
+
+- **Receives:**
+  - `input`: User messages (when used with agents) or workflow step input (when used with workflow steps)
+  - `output`: Agent's response (when used with agents) or workflow step output (when used with workflow steps)
+  - `runtimeContext`: Runtime context from the agent or workflow step being evaluated
+- **Must return:** `{ results: any }`
+- **Data flow:** The `results` value is passed to the analyze step as `extractStepResult`
+
+```typescript filename="src/mastra/scorers/keyword-coverage-scorer.ts" showLineNumbers copy
+import { createScorer } from "@mastra/core/scores";
+import keywordExtractor from "keyword-extractor";
+
+export const keywordCoverageScorer = createScorer({
+  name: "Keyword Coverage",
+  description: "Evaluates how well the output covers keywords from the input",
+
+  // Step 1: Extract keywords from input and output
+  extract: async ({ input, output }) => {
+    const inputText = input?.map(i => i.content).join(", ") || "";
+    const outputText = output.text;
+
+    const extractKeywords = (text: string) => {
+      return keywordExtractor.extract(text);
+    };
+
+    const inputKeywords = new Set(extractKeywords(inputText));
+    const outputKeywords = new Set(extractKeywords(outputText));
+    
+    return {
+      results: {
+        inputKeywords,
+        outputKeywords,
+      },
+    };
+  },
+
+  // ... analyze and reason steps
+});
+```
+
+#### Analyze Step
+
+This required step performs the core evaluation and generates the numerical score for all scorers.
+
+- **Receives:** Everything from extract step, plus:
+  - `extractStepResult`: Results from the extract step (if extract step was defined)
+- **Must return:** `{ score: number, results?: any }`
+- **Data flow:** The `score` and optional `results` are passed to the reason step
+
+```typescript filename="src/mastra/scorers/keyword-coverage-scorer.ts" showLineNumbers copy
+export const keywordCoverageScorer = createScorer({
+  // ... name, description, extract step
+
+  // Step 2: Analyze keyword coverage and calculate score
+  analyze: async ({ input, output, extractStepResult }) => {
+    const { inputKeywords, outputKeywords } = extractStepResult.results;
+    
+    if (inputKeywords.size === 0) {
+      return { score: 1, results: { coverage: 1, matched: 0, total: 0 } };
+    }
+
+    const matchedKeywords = [...inputKeywords].filter(keyword =>
+      outputKeywords.has(keyword)
+    );
+    
+    const coverage = matchedKeywords.length / inputKeywords.size;
+
+    return {
+      score: coverage,
+      results: {
+        coverage,
+        matched: matchedKeywords.length,
+        total: inputKeywords.size,
+        matchedKeywords,
+      },
+    };
+  },
+
+  // ... reason step
+});
+```
+
+#### Reason Step
+
+This optional step generates human-readable explanations for scores, useful for actionable feedback, debugging transparency, or compliance documentation.
+
+- **Receives:** Everything from analyze step, plus:
+  - `score`: The numerical score (0-1) calculated by the analyze step
+  - `analyzeStepResult`: Results from the analyze step (contains the score and any additional results)
+- **Must return:** `{ reason: string }`
+
+```typescript filename="src/mastra/scorers/keyword-coverage-scorer.ts" showLineNumbers copy
+export const keywordCoverageScorer = createScorer({
+  // ... name, description, extract and analyze steps
+
+  // Step 3: Generate explanation for the score
+  reason: async ({ score, analyzeStepResult, extractStepResult }) => {
+    const { matched, total, matchedKeywords } = analyzeStepResult.results;
+    const { inputKeywords } = extractStepResult.results;
+    
+    const percentage = Math.round(score * 100);
+    const missedKeywords = [...inputKeywords].filter(
+      keyword => !matchedKeywords.includes(keyword)
+    );
+
+    let reason = `The output achieved ${percentage}% keyword coverage (${matched}/${total} keywords).`;
+    
+    if (matchedKeywords.length > 0) {
+      reason += ` Covered keywords: ${matchedKeywords.join(", ")}.`;
+    }
+    
+    if (missedKeywords.length > 0) {
+      reason += ` Missing keywords: ${missedKeywords.join(", ")}.`;
+    }
+
+    return { reason };
+  },
+});
+```
+
+**Examples and Resources:**
+- [Custom Native JavaScript Scorer Example](/examples/scorers/custom-native-javascript-eval) - Example walkthrough.
+- [Built-in Code Scorers](https://github.com/mastra-ai/mastra/tree/main/packages/evals/src/scorers/code) - Real implementations for reference
+  
+### LLM-based scorers
+
+LLM scorers use `createLLMScorer` to build evaluations that leverage language models as judges. They're perfect for subjective evaluations that require understanding context, complex criteria that are difficult to code algorithmically, natural language understanding tasks, and cases where human-like judgment is needed.
+
+LLM scorers follow the same evaluation pipeline as code scorers with an additional `calculateScore` function:
+- an optional **extract** step where the LLM processes input/output and returns structured data
+- a required **analyze** step where the LLM performs evaluation and returns structured analysis  
+- a required **calculateScore** function that converts LLM analysis into numerical score
+- and an optional **reason** step where the LLM generates human-readable explanations
+
+The `calculateScore` function leverages the best of both approaches: LLMs excel at qualitative analysis and understanding, while deterministic functions ensure precise and consistent numerical scoring.
+
+For the complete API reference, see [`createLLMScorer`](/reference/scorers/llm-scorer), and for a detailed explanation of the pipeline, see [evaluation process](/docs/scorers/overview#evaluation-pipeline).
+
+#### Judge Configuration
+
+All LLM scorer steps share this required configuration that defines the model and system instructions.
+
+- **Configuration:** `judge` object containing:
+  - **model:** The LLM model instance for evaluation
+  - **instructions:** System prompt that guides the LLM's behavior
+
+```typescript filename="src/mastra/scorers/tone-scorer.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { createLLMScorer } from "@mastra/core/scores";
+
+export const toneScorer = createLLMScorer({
+  name: 'Tone Scorer',
+  description: 'Evaluates the tone of the output',
+  
+  // Shared judge configuration
+  judge: {
+    model: openai('gpt-4o'),
+    instructions: 'You are an expert in analyzing text tone and communication style.',
+  },
+  
+  // ... other steps
+});
+```
+
+#### Extract Step
+
+This optional step uses an LLM to preprocess input/output data when you need to evaluate multiple distinct elements, filter content, or focus analysis on specific parts of complex data.
+
+- **Configuration:** `{ description, outputSchema, createPrompt }`
+- **Data flow:** The structured output (defined by outputSchema) is passed to the analyze step as `extractStepResult`
+
+```typescript filename="src/mastra/scorers/content-scorer.ts" showLineNumbers copy
+export const contentScorer = createLLMScorer({
+  // ... judge configuration
+  
+  extract: {
+    description: 'Extract key themes and topics from the content',
+    outputSchema: z.object({
+      themes: z.array(z.string()),
+      topics: z.array(z.string()),
+      keyPhrases: z.array(z.string())
+    }),
+    createPrompt: ({ run }) => `
+      Analyze this content and extract:
+      1. Main themes (3-5 high-level concepts)
+      2. Specific topics mentioned
+      3. Key phrases that capture the essence
+      
+      Content: ${run.output.text}
+      
+      Return a JSON object with themes, topics, and keyPhrases arrays.
+    `,
+  },
+  
+  // ... other steps
+});
+```
+
+#### Analyze Step
+
+This required step uses an LLM to perform the core evaluation and return structured analysis that will be converted to a numerical score.
+
+- **Configuration:** `{ description, outputSchema, createPrompt }`
+- **Data flow:** The structured output is passed to the calculateScore function and then to the reason step
+
+```typescript filename="src/mastra/scorers/quality-scorer.ts" showLineNumbers copy
+export const qualityScorer = createLLMScorer({
+  // ... judge configuration
+  
+  analyze: {
+    description: 'Evaluate content quality across multiple dimensions',
+    outputSchema: z.object({
+      clarity: z.number().min(1).max(5),
+      accuracy: z.number().min(1).max(5),
+      completeness: z.number().min(1).max(5),
+      relevance: z.number().min(1).max(5)
+    }),
+    createPrompt: ({ run }) => `
+      Evaluate this content on a scale of 1-5 for:
+      - Clarity: How clear and understandable is it?
+      - Accuracy: How factually correct does it appear?
+      - Completeness: How thorough is the response?
+      - Relevance: How well does it address the input?
+      
+      Input: ${run.input.map(i => i.content).join(', ')}
+      Output: ${run.output.text}
+      
+      Return a JSON object with numeric scores for each dimension.
+    `,
+  },
+  
+  // ... other steps
+});
+```
+
+#### Calculate Score Step
+
+This required function converts the LLM's structured analysis into a numerical score, providing deterministic scoring logic since LLMs aren't reliable for consistent numerical outputs.
+
+- **Configuration:** `calculateScore` function that receives `{ run }` and returns a number
+- **Data flow:** Converts the analyze step's structured output into a numerical score (0-1 range)
+
+```typescript filename="src/mastra/scorers/quality-scorer.ts" showLineNumbers copy
+export const qualityScorer = createLLMScorer({
+  // ... previous steps
+  
+  calculateScore: ({ run }) => {
+    const { clarity, accuracy, completeness, relevance } = run.analyzeStepResult;
+    
+    // Calculate weighted average (scale of 1-5 to 0-1)
+    const weights = { clarity: 0.3, accuracy: 0.3, completeness: 0.2, relevance: 0.2 };
+    const weightedSum = (clarity * weights.clarity) + 
+                       (accuracy * weights.accuracy) + 
+                       (completeness * weights.completeness) + 
+                       (relevance * weights.relevance);
+    
+    // Convert from 1-5 scale to 0-1 scale
+    return (weightedSum - 1) / 4;
+  },
+  
+  // ... other steps
+});
+```
+
+#### Reason Step
+
+This optional step uses an LLM to generate human-readable explanations for scores, useful for actionable feedback, debugging transparency, or compliance documentation.
+
+- **Configuration:** `{ description, createPrompt }`
+- **Data flow:** Receives all previous step results and score, returns a string explanation
+
+```typescript filename="src/mastra/scorers/quality-scorer.ts" showLineNumbers copy
+export const qualityScorer = createLLMScorer({
+  // ... previous steps
+  
+  reason: {
+    createPrompt: ({ run }) => {
+      const { clarity, accuracy, completeness, relevance } = run.analyzeStepResult;
+      const percentage = Math.round(run.score * 100);
+      
+      return `
+        The content received a ${percentage}% quality score based on:
+        - Clarity: ${clarity}/5
+        - Accuracy: ${accuracy}/5  
+        - Completeness: ${completeness}/5
+        - Relevance: ${relevance}/5
+        
+        Provide a brief explanation of what contributed to this score.
+      `;
+    },
+  },
+});
+```
+
+**Examples and Resources:**
+- [Custom LLM Judge Scorer Example](/examples/scorers/custom-llm-judge-eval) - Example Walkthrough with gluten checker
+- [Built-in LLM Scorers](https://github.com/mastra-ai/mastra/tree/main/packages/evals/src/scorers/llm) - Real implementations for reference