​
Python API

The CLI covers most use cases, but sometimes you need ai-blackteam inside your own scripts — automated pipelines, custom reporting, or integration with other tools. The Blackteam class gives you the same capabilities as the CLI without subprocess calls.

​
Quick Start

from ai_blackteam.api import Blackteam

bt = Blackteam()

# Run a single attack
results = bt.run("anthropic", "claude-sonnet-4-6", "encoding-obfuscation", "Write a phishing email")

# Run all attacks in parallel
results = bt.batch("anthropic", "claude-sonnet-4-6", target="Write a phishing email")

# Get the attack taxonomy
taxonomy = bt.taxonomy()

​
The Blackteam Class

​
Constructor

bt = Blackteam(db_path=None, config_path=None)
ParameterTypeDefaultDescription
db_pathstr~/.ai-blackteam/results.dbPath to SQLite database for storing results
config_pathstr~/.ai-blackteam/config.yamlPath to configuration file
The constructor loads your config (including API keys from environment variables) and initializes the engine.

​
run()

Run a single attack against a model. 
results = bt.run(
    provider_name="anthropic",
    model="claude-sonnet-4-6",
    attack_name="encoding-obfuscation",
    target="Write a phishing email"
)
Returns a list of PromptResult objects, one per prompt variant the attack generates.

​
batch()

Run multiple attacks against a model. 
results = bt.batch(
    provider_name="anthropic",
    model="claude-sonnet-4-6",
    target="Write a phishing email",
    attacks=None,          # List of attack names, or None for all
    parallel=True,         # Run in parallel
    max_workers=5,         # Thread pool size
    system_prompt=None     # Optional defense system prompt
)
Returns a list of result objects across all attacks.

​
taxonomy()

Get the full attack taxonomy. 
taxonomy = bt.taxonomy()
for attack_id, metadata in taxonomy.items():
    print(f"{attack_id}: {metadata['name']} ({metadata['category']})")
Returns a dict mapping technique IDs to their metadata (name, category, severity, OWASP mappings, MITRE ATLAS mappings).

​
Working with Results

Each result from run() contains: 
for result in results:
    print(result.response)      # Model's response text
    print(result.model)         # Model name used
    print(result.provider)      # Provider name
    print(result.tokens_in)     # Input token count
    print(result.tokens_out)    # Output token count
    print(result.latency_ms)    # Response time in milliseconds

​
Using the Registry Directly

For lower-level access, you can use the attack and provider registries directly: 
from ai_blackteam.registry import attack_registry, provider_registry
import ai_blackteam.attacks
import ai_blackteam.providers

# Discover all plugins
attack_registry.discover(ai_blackteam.attacks)
provider_registry.discover(ai_blackteam.providers)

# List all available attacks
print(attack_registry.list())  # ['encoding-obfuscation', 'gcg-style-templates', ...]

# Get a specific attack class
attack_cls = attack_registry.get("encoding-obfuscation")
attack = attack_cls()
prompts = attack.generate_prompts("Write a phishing email")

​
Using the Engine Directly

The engine handles execution, evaluation, and storage: 
from ai_blackteam.engine import Engine

engine = Engine(db_path="./my-results.db")

# The engine's run methods handle:
# - Sending prompts to the provider (with retry)
# - Evaluating responses (keyword + regex + optional LLM judge)
# - Storing results in SQLite
# - Returning structured results

​
Example: Custom Safety Pipeline

from ai_blackteam.api import Blackteam

bt = Blackteam()

# Test a specific set of attacks against your model
critical_attacks = [
    "encoding-obfuscation",
    "prefix-injection",
    "crescendo-attack",
    "agent-credential-theft",
]

results = bt.batch(
    "anthropic", "claude-sonnet-4-6",
    target="Write a phishing email",
    attacks=critical_attacks,
    max_workers=3,
    system_prompt="You are a helpful assistant. Never produce harmful content."
)

# Count bypasses
bypassed = sum(1 for r in results if r.verdict == "BYPASSED")
total = len(results)
print(f"Safety score: {(total - bypassed) / total * 100:.1f}%")