---
title: "Reference: Content Similarity Scorer | Evals"
description: Documentation for the Content Similarity Scorer in Mastra, which measures textual similarity between strings and provides a matching score.
packages:
  - "@mastra/core"
  - "@mastra/evals"
---

# Content Similarity Scorer

The `createContentSimilarityScorer()` function measures the textual similarity between two strings, providing a score that indicates how closely they match. It supports configurable options for case sensitivity and whitespace handling.

## Parameters

The `createContentSimilarityScorer()` function accepts a single options object with the following properties:

<PropertiesTable
  content={[
    {
      name: "ignoreCase",
      type: "boolean",
      required: false,
      defaultValue: "true",
      description: "Whether to ignore case differences when comparing strings.",
    },
    {
      name: "ignoreWhitespace",
      type: "boolean",
      required: false,
      defaultValue: "true",
      description: "Whether to normalize whitespace when comparing strings.",
    },
  ]}
/>

This function returns an instance of the MastraScorer class. See the [MastraScorer reference](./mastra-scorer) for details on the `.run()` method and its input/output.

## .run() Returns

<PropertiesTable
  content={[
    {
      name: "runId",
      type: "string",
      description: "The id of the run (optional).",
    },
    {
      name: "preprocessStepResult",
      type: "object",
      description:
        "Object with processed input and output: { processedInput: string, processedOutput: string }",
    },
    {
      name: "analyzeStepResult",
      type: "object",
      description: "Object with similarity: { similarity: number }",
    },
    {
      name: "score",
      type: "number",
      description:
        "Similarity score (0-1) where 1 indicates perfect similarity.",
    },
  ]}
/>

## Scoring Details

The scorer evaluates textual similarity through character-level matching and configurable text normalization.

### Scoring Process

1. Normalizes text:
   - Case normalization (if ignoreCase: true)
   - Whitespace normalization (if ignoreWhitespace: true)
2. Compares processed strings using string-similarity algorithm:
   - Analyzes character sequences
   - Aligns word boundaries
   - Considers relative positions
   - Accounts for length differences

Final score: `similarity_value * scale`

## Example

Evaluate textual similarity between expected and actual agent outputs:

```typescript title="src/example-content-similarity.ts"
import { runEvals } from "@mastra/core/evals";
import { createContentSimilarityScorer } from "@mastra/evals/scorers/prebuilt";
import { myAgent } from "./agent";

const scorer = createContentSimilarityScorer();

const result = await runEvals({
  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.id].score,
      groundTruth: scorerResults[scorer.id].groundTruth,
    });
  },
});

console.log(result.scores);
```

For more details on `runEvals`, see the [runEvals reference](/reference/v1/evals/run-evals).

To add this scorer to an agent, see the [Scorers overview](/docs/v1/evals/overview#adding-scorers-to-agents) guide.

### Score interpretation

A similarity score between 0 and 1:

- **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.

## Related

- [Completeness Scorer](./completeness)
- [Textual Difference Scorer](./textual-difference)
- [Answer Relevancy Scorer](./answer-relevancy)
- [Keyword Coverage Scorer](./keyword-coverage)
