Augment (Engine)

Augment is the core execution engine of Mutant. It is responsible for orchestrating the transformation of simple baseline scenarios into complex, challenging behavioral datasets.

The Concept

Instead of just asking an LLM to "generate diverse data," the augment() pipeline systematically applies specific types of cognitive or structural changes (Dimensions) to the input Scenario.

The Augmentation Pipeline

Mutant orchestrates these changes through a robust 6-stage pipeline:

1. Analyze Behavior: Evaluates the baseline scenario to understand its current traits.
2. Plan Mutations: Selects which dimensions to apply to maximize diversity without breaking the scenario logic.
3. Generate Mutations: The LLM executes the planned mutations to produce new scenarios.
4. Quality Review: Ensures the generated scenarios meet quality and coherence standards.
5. Deduplicate: Removes redundant scenarios that don't add behavioral diversity.
6. Analyze Coverage: Generates reports on the dataset's overall diversity landscape.

Defining and Loading Data

The augment() function takes a dataset parameter, which expects a list of Scenario objects. You can define these scenarios manually, or load them from external files like JSON or CSV.

1. Defining Scenarios Manually

You can instantiate multiple scenarios directly in your code and pass them as a list to the augment() engine:

from mutant.core.scenario import Scenario
from mutant.core.engine import augment
from mutant.providers.ollama import OllamaProvider

provider = OllamaProvider(model="llama3.1")

# Define multiple scenarios individually
scenarios = [
    Scenario(
        title="Refund Request",
        description="The user wants a refund for a broken laptop."
    ),
    Scenario(
        title="Account Locked",
        description="A user's account was locked due to suspicious activity. They are contacting support to unlock it."
    ),
    Scenario(
        title="Late Delivery",
        description="The customer's package is 3 days late and they want an update."
    )
]

# Pass the list of scenarios to augment
dataset = await augment(
    dataset=scenarios,
    provider=provider,
    mutations_per_case=5 # <-- Generates 5 variations for each input scenario!
)

2. Loading Scenarios from JSON or CSV

Since Scenario is a Pydantic model, it's easy to load a list of scenarios from structured data like JSON or CSV.

import json
from mutant.core.scenario import Scenario
from mutant.core.engine import augment

# Load scenario data from a JSON file
with open("baseline_scenarios.json", "r") as f:
    raw_data = json.load(f)

# Convert raw dictionaries into Scenario objects
scenarios = [Scenario(**data) for data in raw_data]

dataset = await augment(
    dataset=scenarios,
    provider=provider,
    mutations_per_case=5 # <-- Generates 5 variations for each input scenario!
)

Example: The Output

When a mutation is applied, the scenario transforms. For instance, an "Urgency" mutation might change a standard support request into a high-stakes, time-sensitive crisis.

The output is represented as a MutationCase:

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

# A MutationCase contains the exact change and rationale
# Let's say we generated 6 mutations
print(f"Generated {len(dataset.cases)} mutations!")
# Output: "Generated 6 mutations!"

case = dataset.cases[0]

print(f"Dimension: {case.dimension_name}")
# Output: "emotion.angry"

print(f"Original: {case.original_description}")
# Output: "I would like a refund."

print(f"Mutated: {case.mutated_description}")
# Output: "I am absolutely furious! I need my money back immediately!"

# You can iterate through all generated mutations
for i, case in enumerate(dataset.cases):
    print(f"Mutation {i+1}: [{case.dimension_name}] {case.mutated_description}")

$ python augment_script.py
Generated 6 mutations!
Mutation 1: [emotion.angry] I am absolutely furious! I need my money back immediately!
Mutation 2: [language.slang] Yo, I need a refund for this right now, it's totally busted.
Mutation 3: [emotion.angry] This is a complete scam! Give me my refund now!
Mutation 4: [language.slang] This thing is wack, hook me up with a refund ASAP.
Mutation 5: [emotion.angry] Unacceptable! I demand a full refund this instant!
Mutation 6: [language.slang] Bruh, this is trash. I want my cash back.