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:

Analyze Behavior: Evaluates the baseline scenario to understand its current traits.
Plan Mutations: Selects which dimensions to apply to maximize diversity without breaking the scenario logic.
Generate Mutations: The LLM executes the planned mutations to produce new scenarios.
Quality Review: Ensures the generated scenarios meet quality and coherence standards.
Deduplicate: Removes redundant scenarios that don't add behavioral diversity.
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!
)

3. Saving & Using the Dataset

When a mutation is applied, the output is represented as a list of MutationCase objects inside the dataset. You can save these easily.

Method	Description
`dataset.save("file.json")`	Saves the output in a structured JSON format.

# A MutationCase contains the exact change and rationale.
# Simply save the dataset to a JSON file.
dataset.save("mutations.json")
print("✅ Dataset generated and saved successfully!")

$ python augment_script.py
[Mutant] Augmenting scenarios...
[Mutant] Generation complete in 4.2s.
✅ Dataset generated and saved successfully!