Dimensions (Operators)

Dimensions (sometimes referred to as Operators) are predefined, targeted strategies that dictate how a scenario should be mutated. They serve as the structural DNA for generating diverse, adversarial behaviors.

---

Role of Dimensions

If a Mutation is the act of changing a scenario, the Dimension is the specific tool used to guide that change. Dimensions target distinct behavioral, linguistic, or cognitive attributes.

By layering multiple dimensions, you can generate incredibly complex edge cases. For example, combining an Emotion dimension with a Reasoning dimension can produce a scenario where a user is frustrated (Emotion) because they are trying to solve a multi-step logic puzzle (Reasoning).

Applying Dimensions

You apply dimensions simply by passing their string IDs into the augment or mutate functions.

pip install mutant-ai
# or
uv add mutant-ai

from mutant.core.engine import augment

dataset = await augment(
    dataset=[scenario],
    provider=provider,
    dimensions=["emotion.angry", "reasoning.multi_step"]
)

print(dataset.cases[0].dimension_name)
# Output: "Emotion.Angry"

---

How Dimensions Work

Dimensions are built using Python classes that inherit from MutationDimension. Each dimension contains metadata (like severity and category) and highly specific prompt instructions that the LLM engine uses to execute the rewrite.

Example Architecture

from mutant.dimensions.base import MutationDimension
from mutant.core.mutation import MutationCategory, MutationSeverity

class AngryCustomerDimension(MutationDimension):
    id = "emotion.angry"
    name = "Angry Customer"
    description = "Customer is genuinely furious and threatening escalation."
    category = MutationCategory.EMOTION
    severity = MutationSeverity.HIGH

    def get_mutation_instructions(self) -> str:
        return (
            "Rewrite the scenario from the perspective of a customer who is "
            "genuinely, deeply angry. The anger should feel earned and specific..."
        )

When you pass this dimension into the augment() pipeline, Mutant injects get_mutation_instructions() directly into the LLM prompt context to guarantee a high-fidelity behavioral shift.

Customizing Dimension Prompts

You can fully customize any dimension's prompt instructions by subclassing an existing dimension or creating a brand new one, then registering it with the registry.

Here is a copy-pasteable example of creating a custom dimension that enforces a specific tone:

from mutant.dimensions.base import MutationDimension
from mutant.core.mutation import MutationCategory, MutationSeverity
from mutant.core.registry import registry
from mutant.core.engine import augment

# 1. Define your custom dimension
class CustomSarcasticDimension(MutationDimension):
    id = "custom.sarcastic"
    name = "Sarcastic Customer"
    description = "The customer is highly sarcastic and passive-aggressive."
    category = MutationCategory.EMOTION
    severity = MutationSeverity.MEDIUM

    def get_mutation_instructions(self) -> str:
        return (
            "Rewrite the scenario from the perspective of a highly sarcastic, "
            "passive-aggressive customer. You must use dry humor, rhetorical "
            "questions, and exaggerated politeness that masks genuine annoyance. "
            "Keep the core request identical, just wrap it in thick sarcasm."
        )

# 2. Register it with the Mutant engine
registry.register(CustomSarcasticDimension())

# 3. Use it in your pipeline just like a built-in dimension!
dataset = await augment(
    dataset=[scenario],
    provider=provider,
    dimensions=["custom.sarcastic"]
)

---

Built-in Dimensions Reference

Mutant ships with dozens of built-in dimensions grouped into key categories:

Category	Description	Severity Impact
Context	Modifies the situational background and constraints.	Variable
Language	Alters dialect, tone, fluency, or linguistic complexity.	Low
Emotion	Injects specific sentiments (e.g., Panic, Frustration).	Medium-High
Memory	Tests the agent's ability to retain long-term context.	Medium
Time	Introduces temporal urgency or retrospective analysis.	High
Tool	Focuses on testing tool-use and API interaction boundaries.	High
Reasoning	Increases cognitive load and logic requirements.	Critical
Safety	Tests adversarial robustness and boundary adherence.	Critical

[!NOTE] You can easily define your own custom Dimensions and register them into the Mutant ecosystem using the Plugin System.

For exhaustive documentation on specific dimensions, explore the Dimensions Reference section in the sidebar.