docs/ARCHITECTURE.md

Architecture Notes

Core Components

• Attack Generator
• Attack Execution Engine
• Mitigation Layer
• Evaluation and Metrics
• Results Logging and Analysis

Design Principles

• Modular interfaces for attacks, mitigations, and models
• Reproducible experiment configuration
• Clear separation between execution and evaluation

Current MVP

The current MVP implements a small end-to-end evaluation pipeline:

1. Load normalized attack cases from data/normalized/attack_cases.jsonl
2. Select a small reproducible sample from config
3. Execute the sample through a model adapter
4. Score each case with a minimal attack-success evaluator
5. Save run artifacts under results/<run_id>/

The active runtime path is:

normalized attack cases -> model adapter -> evaluator -> run artifacts

Canonical Data Contract

The canonical normalized source of truth is:

• data/normalized/attack_cases.jsonl

The enriched derivative is:

• data/normalized/attack_cases.enriched.jsonl

The enriched file adds taxonomy and evaluation-support metadata, but it is not the primary source of truth. The normalized file remains the base corpus used by the framework contract.

Implemented Adapters

• mock Used for local pipeline verification without network calls or token costs.
• groq Used as the first real hosted inference backend for the MVP.

The model adapter boundary is intentionally provider-agnostic so later work can add ollama, transformers, or vllm without changing orchestration.

Run Artifacts

Each experiment run writes:

• manifest.json: config, model, dataset, and git metadata
• case_results.jsonl: one result per evaluated case
• summary.json: aggregate metrics and output paths

The manifest now records the config source path, dataset SHA-256, selected case IDs, and filter/selection settings so a run can be replayed from the same contract with deterministic case selection.

The full schema contract for normalized cases, enriched cases, configs, and run artifacts is documented in:

• docs/SCHEMA_CONTRACT.md

Current Evaluation Scope

The MVP currently implements one minimal metric:

• attack_success A simple substring-based check using the case expected_target

This is intentionally narrow so the team can validate the full execution path before adding category-specific success logic, richer leakage checks, and mitigation-aware scoring.

The runner now also records heuristic evaluation support fields:

• refusal
• prompt_leakage
• manual_review
• matched_rule

These are not final research metrics, but they make the MVP more useful for debugging, output review, and richer analysis while taxonomy work continues.

Near-Term Scaling Path

The next steps after the MVP are:

• improve category-specific evaluation logic
• expand focused attack subset configs for stronger attack pressure
• use focused active-corpus slices such as HackAPrompt override/leakage and TensorTrust hijacking/extraction
• compare prompt execution modes such as plain, context_first, and attack_then_task
• add mitigation plugin hooks
• add more hosted or local model backends
• expand experiment configs beyond the MVP smoke and 20-case Groq runs