Skip to content

Quickstart

Get up and running with mutant-ai in under 5 minutes. This guide will walk you through creating your first mutated behavioral dataset, executing an augmentation pipeline, and generating a coverage report.

[!NOTE] If you're looking to run multi-turn adversarial attacks against live AI systems, check out the Automated Red Teaming guide.

1. Installation

First, ensure you have installed the mutant-ai package and the provider you wish to use (e.g., OpenAI, Gemini, or Anthropic).

# Using pip
pip install mutant-ai

# Using uv
uv add mutant-ai

[!TIP] You can also install all providers at once by running pip install mutant-ai[all].

2. Initialize a Provider

Mutant delegates the heavy lifting of behavioral generation to Large Language Models. Initialize a provider and ensure your environment variables (like OPENAI_API_KEY) are exported.

from mutant.providers.openai import OpenAIProvider

# Initialize the OpenAI provider (uses OPENAI_API_KEY from env)
provider = OpenAIProvider(model="gpt-4o")

from mutant.providers.ollama import OllamaProvider

# Connects to local Ollama instance (defaults to http://localhost:11434)
provider = OllamaProvider(model="llama3.1")

3. Define a Seed Scenario

The Scenario is your foundational context. It defines the base interaction before any adversarial behaviors are injected.

from mutant.core.scenario import Scenario

scenario = Scenario(
    title="E-commerce Return Request",
    description="The user wants to return a broken product they bought 3 weeks ago.",
    domain="e-commerce"
)

[!IMPORTANT] A strong, highly-specific description ensures the engine has enough context to generate realistic, high-fidelity mutations.

4. Run the Augmentation Pipeline

Use the augment() function to generate diverse permutations of the seed scenario by injecting specific Dimensions. In this example, we ask Mutant to generate 5 unique variations across anger, slurred language, and complex reasoning.

from mutant.core.engine import augment

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

# Iterate through the generated adversarial cases
for case in dataset.cases:
    print(f"Applied Dimension: {case.dimension_name}")
    print(f"Original: {case.original}")
    print(f"Mutated: {case.mutated}")
    print("-" * 50)

5. Generate a Coverage Report

Once you've built your dataset, you can instantly visualize the behavioral coverage using Mutant's HTML reporter.

from mutant.reports.html import HtmlReport

# Generate a standalone, self-contained HTML report
report = HtmlReport()
report.save(scenario, dataset.cases, path="coverage_report.html")

print("Report saved to coverage_report.html")

[!NOTE] The HTML report includes a responsive diversity radar chart and severity distribution blocks, giving you deterministic insights into your evaluation dataset.

Next Steps