---
title: "Reference: MastraScorer | Evals"
description: Documentation for the MastraScorer base class in Mastra, which provides the foundation for all custom and built-in scorers.
packages:
  - "@mastra/core"
---

# MastraScorer

The `MastraScorer` class is the base class for all scorers in Mastra. It provides a standard `.run()` method for evaluating input/output pairs and supports multi-step scoring workflows with preprocess → analyze → generateScore → generateReason execution flow.

**Note:** Most users should use [`createScorer`](./create-scorer) to create scorer instances. Direct instantiation of `MastraScorer` is not recommended.

## How to Get a MastraScorer Instance

Use the `createScorer` factory function, which returns a `MastraScorer` instance:

```typescript
import { createScorer } from "@mastra/core/evals";

const scorer = createScorer({
  name: "My Custom Scorer",
  description: "Evaluates responses based on custom criteria",
}).generateScore(({ run, results }) => {
  // scoring logic
  return 0.85;
});

// scorer is now a MastraScorer instance
```

## .run() Method

The `.run()` method is the primary way to execute your scorer and evaluate input/output pairs. It processes the data through your defined steps (preprocess → analyze → generateScore → generateReason) and returns a comprehensive result object with the score, reasoning, and intermediate results.

```typescript
const result = await scorer.run({
  input: "What is machine learning?",
  output: "Machine learning is a subset of artificial intelligence...",
  runId: "optional-run-id",
  requestContext: {
    /* optional context */
  },
});
```

## .run() Input

<PropertiesTable
  content={[
    {
      name: "input",
      type: "any",
      required: true,
      description:
        "Input data to be evaluated. Can be any type depending on your scorer's requirements.",
    },
    {
      name: "output",
      type: "any",
      required: true,
      description:
        "Output data to be evaluated. Can be any type depending on your scorer's requirements.",
    },
    {
      name: "runId",
      type: "string",
      required: false,
      description: "Optional unique identifier for this scoring run.",
    },
    {
      name: "requestContext",
      type: "any",
      required: false,
      description:
        "Optional request context from the agent or workflow step being evaluated.",
    },
    {
      name: "groundTruth",
      type: "any",
      required: false,
      description:
        "Optional expected or reference output for comparison during scoring. Automatically passed when using runEvals.",
    },
  ]}
/>

## .run() Returns

<PropertiesTable
  content={[
    {
      name: "runId",
      type: "string",
      description: "The unique identifier for this scoring run.",
    },
    {
      name: "score",
      type: "number",
      description: "Numerical score computed by the generateScore step.",
    },
    {
      name: "reason",
      type: "string",
      description:
        "Explanation for the score, if generateReason step was defined (optional).",
    },
    {
      name: "preprocessStepResult",
      type: "any",
      description: "Result of the preprocess step, if defined (optional).",
    },
    {
      name: "analyzeStepResult",
      type: "any",
      description: "Result of the analyze step, if defined (optional).",
    },
    {
      name: "preprocessPrompt",
      type: "string",
      description: "Preprocess prompt, if defined (optional).",
    },
    {
      name: "analyzePrompt",
      type: "string",
      description: "Analyze prompt, if defined (optional).",
    },
    {
      name: "generateScorePrompt",
      type: "string",
      description: "Generate score prompt, if defined (optional).",
    },
    {
      name: "generateReasonPrompt",
      type: "string",
      description: "Generate reason prompt, if defined (optional).",
    },
  ]}
/>

## Step Execution Flow

When you call `.run()`, the MastraScorer executes the defined steps in this order:

1. **preprocess** (optional) - Extracts or transforms data
2. **analyze** (optional) - Processes the input/output and preprocessed data
3. **generateScore** (required) - Computes the numerical score
4. **generateReason** (optional) - Provides explanation for the score

Each step receives the results from previous steps, allowing you to build complex evaluation pipelines.

## Usage Example

```typescript
const scorer = createScorer({
  name: "Quality Scorer",
  description: "Evaluates response quality",
})
  .preprocess(({ run }) => {
    // Extract key information
    return { wordCount: run.output.split(" ").length };
  })
  .analyze(({ run, results }) => {
    // Analyze the response
    const hasSubstance = results.preprocessStepResult.wordCount > 10;
    return { hasSubstance };
  })
  .generateScore(({ results }) => {
    // Calculate score
    return results.analyzeStepResult.hasSubstance ? 1.0 : 0.0;
  })
  .generateReason(({ score, results }) => {
    // Explain the score
    const wordCount = results.preprocessStepResult.wordCount;
    return `Score: ${score}. Response has ${wordCount} words.`;
  });

// Use the scorer
const result = await scorer.run({
  input: "What is machine learning?",
  output: "Machine learning is a subset of artificial intelligence...",
});

console.log(result.score); // 1.0
console.log(result.reason); // "Score: 1.0. Response has 12 words."
```

## Integration

MastraScorer instances can be used for agents and workflow steps

See the [createScorer reference](./create-scorer) for detailed information on defining custom scoring logic.
