@mastra/mcp-docs-server 0.13.44 → 0.13.45-alpha.0

package/.docs/raw/reference/scorers/content-similarity.mdx

@@ -78,116 +78,46 @@ The scorer evaluates textual similarity through character-level matching and con
 
 Final score: `similarity_value * scale`
 
-## Examples
+## Example
 
-### High similarity example
+Evaluate textual similarity between expected and actual agent outputs:
 
-In this example, the response closely resembles the query in both structure and meaning. Minor differences in tense and phrasing do not significantly affect the overall similarity.
-
-```typescript title="src/example-high-similarity.ts" showLineNumbers copy
-import { createContentSimilarityScorer } from "@mastra/evals/scorers/llm";
+```typescript title="src/example-content-similarity.ts" showLineNumbers copy
+import { runExperiment } from "@mastra/core/scores";
+import { createContentSimilarityScorer } from "@mastra/evals/scorers/code";
+import { myAgent } from "./agent";
 
 const scorer = createContentSimilarityScorer();
 
-const query = "The quick brown fox jumps over the lazy dog.";
-const response = "A quick brown fox jumped over a lazy dog.";
-
-const result = await scorer.run({
-  input: [{ role: "user", content: query }],
-  output: { text: response },
-});
-
-console.log(result);
-```
-
-#### High similarity output
-
-The output receives a high score because the response preserves the intent and content of the query with only subtle wording changes.
-
-```typescript
-{
-  score: 0.7761194029850746,
-  analyzeStepResult: {
-    similarity: 0.7761194029850746
+const result = await runExperiment({
+  data: [
+    {
+      input: "Summarize the benefits of TypeScript",
+      groundTruth:
+        "TypeScript provides static typing, better tooling support, and improved code maintainability.",
+    },
+    {
+      input: "What is machine learning?",
+      groundTruth:
+        "Machine learning is a subset of AI that enables systems to learn from data without explicit programming.",
+    },
+  ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.name].score,
+      groundTruth: scorerResults[scorer.name].groundTruth,
+    });
   },
-}
-```
-
-### Moderate similarity example
-
-In this example, the response shares some conceptual overlap with the query but diverges in structure and wording. Key elements remain present, but the phrasing introduces moderate variation.
-
-```typescript title="src/example-moderate-similarity.ts" showLineNumbers copy
-import { createContentSimilarityScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createContentSimilarityScorer();
-
-const query = "A brown fox quickly leaps across a sleeping dog.";
-const response = "The quick brown fox jumps over the lazy dog.";
-
-const result = await scorer.run({
-  input: [{ role: "user", content: query }],
-  output: { text: response },
 });
 
-console.log(result);
+console.log(result.scores);
 ```
 
-#### Moderate similarity output
-
-The output receives a mid-range score because the response captures the general idea of the query, though it differs enough in wording to reduce overall similarity.
-
-```typescript
-{
-  score: 0.40540540540540543,
-  analyzeStepResult: {
-    similarity: 0.40540540540540543
-  }
-}
-```
-
-### Low similarity example
-
-In this example, the response and query are unrelated in meaning, despite having a similar grammatical structure. There is little to no shared content overlap.
-
-```typescript title="src/example-low-similarity.ts" showLineNumbers copy
-import { createContentSimilarityScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createContentSimilarityScorer();
-
-const query = "The cat sleeps on the windowsill.";
-const response = "The quick brown fox jumps over the lazy dog.";
-
-const result = await scorer.run({
-  input: [{ role: "user", content: query }],
-  output: { text: response },
-});
-
-console.log(result);
-```
-
-#### Low similarity output
-
-The output receives a low score because the response does not align with the content or intent of the query.
-
-```typescript
-{
-  score: 0.25806451612903225,
-  analyzeStepResult: {
-    similarity: 0.25806451612903225
-  },
-}
-```
-
-### Score interpretation
-
-A similarity score between 0 and 1:
+For more details on `runExperiment`, see the [runExperiment reference](/reference/scorers/run-experiment).
 
-- **1.0**: Perfect match – content is nearly identical.
-- **0.7–0.9**: High similarity – minor differences in word choice or structure.
-- **0.4–0.6**: Moderate similarity – general overlap with noticeable variation.
-- **0.1–0.3**: Low similarity – few common elements or shared meaning.
-- **0.0**: No similarity – completely different content.
+To add this scorer to an agent, see the [Scorers overview](/docs/scorers/overview#adding-scorers-to-agents) guide.
 
 ## Related
 

package/.docs/raw/reference/scorers/context-precision.mdx

@@ -152,7 +152,7 @@ MAP = (1.0 + 0.67) / 2 = 0.835 ≈ **0.83**
 
 ```typescript
 const scorer = createContextPrecisionScorer({
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   options: {
     contextExtractor: (input, output) => {
       // Extract context dynamically based on the query
@@ -171,7 +171,7 @@ const scorer = createContextPrecisionScorer({
 
 ```typescript
 const scorer = createContextPrecisionScorer({
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   options: {
     context: [
       // Simulate retrieved documents from vector database
@@ -186,152 +186,50 @@ const scorer = createContextPrecisionScorer({
 });
 ```
 
-## Examples
+## Example
 
-### High precision example
+Evaluate RAG system context retrieval precision for different queries:
 
-This example shows perfect context precision where all relevant context appears early:
-
-```typescript
-import { createContextPrecisionScorer } from "@mastra/evals";
+```typescript title="src/example-context-precision.ts" showLineNumbers copy
+import { runExperiment } from "@mastra/core/scores";
+import { createContextPrecisionScorer } from "@mastra/evals/scorers/llm";
+import { myAgent } from "./agent";
 
 const scorer = createContextPrecisionScorer({
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-4o",
   options: {
-    context: [
-      "Photosynthesis is the process by which plants convert sunlight, carbon dioxide, and water into glucose and oxygen.",
-      "The process occurs in the chloroplasts of plant cells, specifically in the thylakoids.",
-      "Light-dependent reactions happen in the thylakoid membranes, while the Calvin cycle occurs in the stroma.",
-    ],
-    scale: 1,
+    contextExtractor: (input, output) => {
+      // Extract context from agent's retrieved documents
+      return output.metadata?.retrievedContext || [];
+    },
   },
 });
 
-const result = await scorer.run({
-  input: {
-    inputMessages: [
-      {
-        id: "1",
-        role: "user",
-        content: "How does photosynthesis work in plants?",
-      },
-    ],
-  },
-  output: [
+const result = await runExperiment({
+  data: [
     {
-      id: "2",
-      role: "assistant",
-      content:
-        "Photosynthesis is the process where plants convert sunlight, CO2, and water into glucose and oxygen using chloroplasts.",
+      input: "How does photosynthesis work in plants?",
     },
-  ],
-});
-
-console.log(result);
-// Output:
-// {
-//   score: 1.0,
-//   reason: "The score is 1.0 because all context pieces are highly relevant to explaining photosynthesis and are optimally ordered to support the expected output."
-// }
-```
-
-### Mixed precision example
-
-This example shows moderate precision with both relevant and irrelevant context:
-
-```typescript
-import { createContextPrecisionScorer } from "@mastra/evals";
-
-const scorer = createContextPrecisionScorer({
-  model: "openai/gpt-4o-mini",
-  options: {
-    context: [
-      "Regular exercise improves cardiovascular health by strengthening the heart muscle.",
-      "A balanced diet should include fruits, vegetables, and whole grains.",
-      "Physical activity releases endorphins which improve mood and reduce stress.",
-      "The average person should drink 8 glasses of water per day.",
-      "Exercise also helps maintain healthy body weight and muscle mass.",
-    ],
-    scale: 1,
-  },
-});
-
-const result = await scorer.run({
-  input: {
-    inputMessages: [
-      {
-        id: "1",
-        role: "user",
-        content: "What are the mental and physical benefits of exercise?",
-      },
-    ],
-  },
-  output: [
     {
-      id: "2",
-      role: "assistant",
-      content:
-        "Exercise provides cardiovascular benefits, improves mood through endorphin release, and helps maintain healthy body composition.",
+      input: "What are the mental and physical benefits of exercise?",
     },
   ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.name].score,
+      reason: scorerResults[scorer.name].reason,
+    });
+  },
 });
 
-console.log(result);
-// Output:
-// {
-//   score: 0.72,
-//   reason: "The score is 0.72 because contexts 1, 3, and 5 are relevant to exercise benefits, but irrelevant contexts about diet and hydration reduce the precision score."
-// }
+console.log(result.scores);
 ```
 
-### Low precision example
-
-This example shows poor context precision with mostly irrelevant context:
-
-```typescript
-import { createContextPrecisionScorer } from "@mastra/evals";
-
-const scorer = createContextPrecisionScorer({
-  model: "openai/gpt-4o-mini",
-  options: {
-    context: [
-      "The weather forecast shows sunny skies this weekend.",
-      "Coffee is one of the world's most popular beverages.",
-      "Machine learning requires large amounts of training data.",
-      "Cats typically sleep 12-16 hours per day.",
-      "The capital of France is Paris.",
-    ],
-    scale: 1,
-  },
-});
-
-const result = await scorer.run({
-  input: {
-    inputMessages: [
-      {
-        id: "1",
-        role: "user",
-        content: "How does photosynthesis work?",
-      },
-    ],
-  },
-  output: [
-    {
-      id: "2",
-      role: "assistant",
-      content:
-        "Photosynthesis is the process by which plants convert sunlight into energy using chlorophyll.",
-    },
-  ],
-});
+For more details on `runExperiment`, see the [runExperiment reference](/reference/scorers/run-experiment).
 
-console.log(result);
-// Output:
-// {
-//   score: 0.0,
-//   reason: "The score is 0.0 because none of the retrieved context pieces are relevant to explaining photosynthesis."
-// }
-```
+To add this scorer to an agent, see the [Scorers overview](/docs/scorers/overview#adding-scorers-to-agents) guide.
 
 ## Comparison with Context Relevance
 

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

@@ -122,118 +122,45 @@ A faithfulness score between 0 and 1:
 - **0.1–0.3**: Most of the content is inaccurate or unsupported.
 - **0.0**: All claims are false or contradict the context.
 
-## Examples
+## Example
 
-### High faithfulness example
+Evaluate agent responses for faithfulness to provided context:
 
-In this example, the response closely aligns with the context. Each statement in the output is verifiable and supported by the provided context entries, resulting in a high score.
-
-```typescript title="src/example-high-faithfulness.ts" showLineNumbers copy
-import { createFaithfulnessScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createFaithfulnessScorer({ model: 'openai/gpt-4o-mini', options: {
-  context: [
-    "The Tesla Model 3 was launched in 2017.",
-    "It has a range of up to 358 miles.",
-    "The base model accelerates 0-60 mph in 5.8 seconds."
-  ]
-});
-
-const query = "Tell me about the Tesla Model 3.";
-const response = "The Tesla Model 3 was introduced in 2017. It can travel up to 358 miles on a single charge and the base version goes from 0 to 60 mph in 5.8 seconds.";
-
-const result = await scorer.run({
-  input: [{ role: 'user', content: query }],
-  output: { text: response },
-});
-
-console.log(result);
-```
-
-#### High faithfulness output
-
-The output receives a score of 1 because all the information it provides can be directly traced to the context. There are no missing or contradictory facts.
-
-```typescript
-{
-  score: 1,
-  reason: 'The score is 1 because all claims made in the output are supported by the provided context.'
-}
-```
-
-### Mixed faithfulness example
-
-In this example, there are a mix of supported and unsupported claims. Some parts of the response are backed by the context, while others introduce new information not found in the source material.
-
-```typescript title="src/example-mixed-faithfulness.ts" showLineNumbers copy
-import { createFaithfulnessScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createFaithfulnessScorer({ model: 'openai/gpt-4o-mini', options: {
-  context: [
-    "Python was created by Guido van Rossum.",
-    "The first version was released in 1991.",
-    "Python emphasizes code readability."
-  ]
-});
-
-const query = "What can you tell me about Python?";
-const response = "Python was created by Guido van Rossum and released in 1991. It is the most popular programming language today and is used by millions of developers worldwide.";
-
-const result = await scorer.run({
-  input: [{ role: 'user', content: query }],
-  output: { text: response },
-});
-
-console.log(result);
-```
-
-#### Mixed faithfulness output
-
-The score is lower because only a portion of the response is verifiable. While some claims match the context, others are unconfirmed or out of scope, reducing the overall faithfulness.
-
-```typescript
-{
-  score: 0.5,
-  reason: "The score is 0.5 because while two claims are supported by the context (Python was created by Guido van Rossum and Python was released in 1991), the other two claims regarding Python's popularity and usage cannot be verified as they are not mentioned in the context."
-}
-```
-
-### Low faithfulness example
-
-In this example, the response directly contradicts the context. None of the claims are supported, and several conflict with the facts provided.
-
-```typescript title="src/example-low-faithfulness.ts" showLineNumbers copy
+```typescript title="src/example-faithfulness.ts" showLineNumbers copy
+import { runExperiment } from "@mastra/core/scores";
 import { createFaithfulnessScorer } from "@mastra/evals/scorers/llm";
+import { myAgent } from "./agent";
 
-const scorer = createFaithfulnessScorer({ model: 'openai/gpt-4o-mini', options: {
-  context: [
-    "Mars is the fourth planet from the Sun.",
-    "It has a thin atmosphere of mostly carbon dioxide.",
-    "Two small moons orbit Mars: Phobos and Deimos."
-  ]
+// Context is typically populated from agent tool calls or RAG retrieval
+const scorer = createFaithfulnessScorer({
+  model: "openai/gpt-4o",
 });
 
-const query = "What do we know about Mars?";
-const response = "Mars is the third planet from the Sun. It has a thick atmosphere rich in oxygen and nitrogen, and is orbited by three large moons.";
-
-const result = await scorer.run({
-  input: [{ role: 'user', content: query }],
-  output: { text: response },
+const result = await runExperiment({
+  data: [
+    {
+      input: "Tell me about the Tesla Model 3.",
+    },
+    {
+      input: "What are the key features of this electric vehicle?",
+    },
+  ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.name].score,
+      reason: scorerResults[scorer.name].reason,
+    });
+  },
 });
 
-console.log(result);
+console.log(result.scores);
 ```
 
-#### Low faithfulness output
+For more details on `runExperiment`, see the [runExperiment reference](/reference/scorers/run-experiment).
 
-Each claim is inaccurate or conflicts with the context, resulting in a score of 0.
-
-```typescript
-{
-  score: 0,
-  reason: "The score is 0 because all claims made in the output contradict the provided context. The output states that Mars is the third planet from the Sun, while the context clearly states it is the fourth. Additionally, it claims that Mars has a thick atmosphere rich in oxygen and nitrogen, contradicting the context's description of a thin atmosphere mostly composed of carbon dioxide. Finally, the output mentions that Mars is orbited by three large moons, while the context specifies that it has only two small moons, Phobos and Deimos. Therefore, there are no supported claims, leading to a score of 0."
-}
-```
+To add this scorer to an agent, see the [Scorers overview](/docs/scorers/overview#adding-scorers-to-agents) guide.
 
 ## Related
 

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

@@ -131,120 +131,45 @@ A hallucination score between 0 and 1:
 
 **Note:** The score represents the degree of hallucination - lower scores indicate better factual alignment with the provided context
 
-## Examples
+## Example
 
-### No hallucination example
+Evaluate agent responses for hallucinations against provided context:
 
-In this example, the response is fully aligned with the provided context. All claims are factually correct and directly supported by the source material, resulting in a low hallucination score.
-
-```typescript title="src/example-no-hallucination.ts" showLineNumbers copy
-import { createHallucinationScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createHallucinationScorer({ model: 'openai/gpt-4o-mini', options: {
-  context: [
-    "The iPhone was first released in 2007.",
-    "Steve Jobs unveiled it at Macworld.",
-    "The original model had a 3.5-inch screen."
-  ]
-});
-
-const query = "When was the first iPhone released?";
-const response = "The iPhone was first released in 2007, when Steve Jobs unveiled it at Macworld. The original iPhone featured a 3.5-inch screen.";
-
-const result = await scorer.run({
-  input: [{ role: 'user', content: query }],
-  output: { text: response },
-});
-
-console.log(result);
-```
-
-#### No hallucination output
-
-The response receives a score of 0 because there are no contradictions. Every statement is consistent with the context, and no new or fabricated information has been introduced.
-
-```typescript
-{
-  score: 0,
-  reason: 'The score is 0 because none of the statements from the context were contradicted by the output.'
-}
-```
-
-### Mixed hallucination example
-
-In this example, the response includes both accurate and inaccurate claims. Some details align with the context, while others directly contradict it—such as inflated numbers or incorrect locations. These contradictions increase the hallucination score.
-
-```typescript title="src/example-mixed-hallucination.ts" showLineNumbers copy
+```typescript title="src/example-hallucination.ts" showLineNumbers copy
+import { runExperiment } from "@mastra/core/scores";
 import { createHallucinationScorer } from "@mastra/evals/scorers/llm";
+import { myAgent } from "./agent";
 
-const scorer = createHallucinationScorer({ model: 'openai/gpt-4o-mini', options: {
-  context: [
-    "The first Star Wars movie was released in 1977.",
-    "It was directed by George Lucas.",
-    "The film earned $775 million worldwide.",
-    "The movie was filmed in Tunisia and England."
-  ]
+// Context is typically populated from agent tool calls or RAG retrieval
+const scorer = createHallucinationScorer({
+  model: "openai/gpt-4o",
 });
 
-const query = "Tell me about the first Star Wars movie.";
-const response = "The first Star Wars movie came out in 1977 and was directed by George Lucas. It made over $1 billion at the box office and was filmed entirely in California.";
-
-const result = await scorer.run({
-  input: [{ role: 'user', content: query }],
-  output: { text: response },
-});
-
-console.log(result);
-```
-
-#### Mixed hallucination output
-
-The Scorer assigns a mid-range score because parts of the response conflict with the context. While some facts are correct, others are inaccurate or fabricated, reducing overall reliability.
-
-```typescript
-{
-  score: 0.5,
-  reason: 'The score is 0.5 because two out of four statements from the output were contradicted by claims in the context, indicating a balance of accurate and inaccurate information.'
-}
-```
-
-### Complete hallucination example
-
-In this example, the response contradicts every key fact in the context. None of the claims can be verified, and all presented details are factually incorrect.
-
-```typescript title="src/example-complete-hallucination.ts" showLineNumbers copy
-import { createHallucinationScorer } from "@mastra/evals/scorers/llm";
-
-const scorer = createHallucinationScorer({ model: 'openai/gpt-4o-mini', options: {
-  context: [
-    "The Wright brothers made their first flight in 1903.",
-    "The flight lasted 12 seconds.",
-    "It covered a distance of 120 feet."
-  ]
-});
-
-const query = "When did the Wright brothers first fly?";
-const response = "The Wright brothers achieved their historic first flight in 1908. The flight lasted about 2 minutes and covered nearly a mile.";
-
-const result = await scorer.run({
-  input: [{ role: 'user', content: query }],
-  output: { text: response },
+const result = await runExperiment({
+  data: [
+    {
+      input: "When was the first iPhone released?",
+    },
+    {
+      input: "Tell me about the original iPhone announcement.",
+    },
+  ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.name].score,
+      reason: scorerResults[scorer.name].reason,
+    });
+  },
 });
 
-console.log(result);
-
+console.log(result.scores);
 ```
 
-#### Complete hallucination output
+For more details on `runExperiment`, see the [runExperiment reference](/reference/scorers/run-experiment).
 
-The Scorer assigns a score of 1 because every statement in the response conflicts with the context. The details are fabricated or inaccurate across the board.
-
-```typescript
-{
-  score: 1,
-  reason: 'The score is 1.0 because all three statements from the output directly contradict the context: the first flight was in 1903, not 1908; it lasted 12 seconds, not about 2 minutes; and it covered 120 feet, not nearly a mile.'
-}
-```
+To add this scorer to an agent, see the [Scorers overview](/docs/scorers/overview#adding-scorers-to-agents) guide.
 
 ## Related