Scenarios

A Scenario is the fundamental unit of state in the Mutant ecosystem. It defines the context, actors, and specific objectives of a simulated test case.

Overview

When evaluating an LLM or an AI Agent, you need a deterministic starting point—a seed. A Scenario serves as this seed. It encapsulates the "who," "where," and "what," providing the necessary scaffolding for the LLM to understand the situation before any behavioral mutations are applied.

Minimal Example

Here is a dead-simple example of creating a Scenario:

from mutant.core.scenario import Scenario

scenario = Scenario(
    title="Refund Request",
    description="The user wants a refund for a broken laptop.",
)

Architecture

A Scenario is a Pydantic model that strictly enforces structure. It contains:

Parameter	Type	Required	Description
`title`	`str`	Yes	Short identifier (e.g., "Refund Request").
`description`	`str`	Yes	A deeper explanation of the scenario. This is what gets mutated.
`domain`	`str`	No	Optional domain constraint (e.g. "finance", "healthcare").
`context`	`dict`	No	Structured background details (organization, rules).
`tags`	`list[str]`	No	Labels for filtering during reporting.

Advanced Example

You can pass structured dictionaries into context to ground the mutation engine in reality:

from mutant.core.scenario import Scenario

scenario = Scenario(
    title="Flight Cancellation",
    description="A user's flight was cancelled due to weather and they are seeking alternatives.",
    domain="travel",
    context={
        "user_tier": "premium",
        "current_location": "Airport Terminal 3",
        "policy": "Weather cancellations only allow rebooking for next 24 hours."
    },
    tags=["customer-support", "high-priority"]
)

How It Works in the Pipeline

Ingestion: The MutationEngine receives the seed Scenario.
Analysis: During the Analyze Behavior stage, Mutant evaluates the Scenario's core behavioral traits.
Planning: The engine plans how to realistically alter the Scenario based on requested Dimensions.
Execution: The Scenario is mutated into a MutationCase, containing both the original parameters and the newly injected behaviors.