adversarial-debate

[!NOTE] Status: v0.2.2 shipped Aug 2026. Measurement infrastructure release adding statistical rigor to every published metric. Key finding: LLM judge validated (87.4% match rate, 77.8 sigma above vocabulary floor). Convergence noise floor measured at ±0.020. Core improvement: Every published metric now has a known confidence interval. Causal mechanism for Mistral effect formally documented. The core isolation rule is mechanically enforced: reviewer B cannot see reviewer A's answer until it has fully committed its own.

---

Why

Most AI "second opinions" are fake. The usual pattern is one model proposes an answer and a second model is asked to double-check — after being shown the first model's framing, assumptions, and conclusion. That setup almost guarantees convergence, even when convergence should not happen. It looks careful. It is actually agreement with extra steps.

The most expensive agent failures are rarely about missing information. They are about prematurely accepted reasoning: a pull request that feels "probably safe," an architecture change that seems "good enough," an incident hypothesis that sounds plausible in the first ten minutes. These are exactly the decisions where human teams rely on independent review and constructive conflict.

AdversarialDebate productizes that discipline for LLM systems:

• Independent passes — agents analyze the same input in strict isolation.
• Delayed revelation — conclusions are revealed only after both sides commit.
• Structured challenge — each agent must respond point by point: assumptions, evidence quality, edge cases, risk exposure.
• Dissent preservation — if disagreement survives the debate, the system ships a structured disagreement report instead of pretending consensus exists.

The outcome is not always consensus. Sometimes the most valuable result is a sharply defined disagreement showing exactly where uncertainty lives.

Quickstart

pip install adversarial-debate

# Scaffold config
advdeb init

# Edit in your API keys
# $EDITOR advdeb.toml

# Review a PR
advdeb review --pr https://github.com/kubernetes/kubernetes/pull/140860 --domain pr_review

# View the report
advdeb report <run_id>

# Export the transcript
advdeb transcript <run_id> --export jsonl

See docs/reference/quickstart.md for the full walkthrough.

What It Is

The Independent Pass → Debate → Decide Loop

                    ┌────────────────────────────┐
        input ────► │  Input Normalizer          │  PR diff / ADR / incident / plan
                    └──────────┬─────────────────┘
                               │  same artifact, isolated contexts
                 ┌─────────────┴─────────────┐
                 ▼                           ▼
           ┌──────────┐                ┌──────────┐
           │ Agent A  │   no peeking   │ Agent B  │
           └────┬─────┘                └────┬─────┘
                │ commit review             │ commit review
                └────────────┬──────────────┘
                             ▼  revelation gate opens
                    ┌─────────────────┐
                    │ Debate Controller│  bounded rounds, point-by-point
                    └────────┬─────────┘
                             ▼
              converged? ─── yes ──► Joint Verdict (strongest surviving arguments)
                  │
                  no
                  ▼
       Disagreement Report (unresolved points + what would resolve them)

Key Properties

Architecture (v0.2.2)

Current stack: Python · Pydantic schemas · SQLite · PydanticAI / LangGraph / raw-API adapters · CLI and field-test scripts.

Planned additions: FastAPI service · React side-by-side review UI · broader adapter coverage.

Example Output

verdict: DISPUTED            # 6 of 9 points converged
resolved:
  - claim: "Rate-limit bump is safe under current traffic"
    status: agreed_by_both
unresolved:
  - claim: "Expand/contract migration is safe for pr-482"
    agent_a: sufficient as written
    agent_b: needs lock-timeout analysis on orders table (~40GB)
    would_resolve_if: load test at production row count
audit: transcripts/2026-08-pr482.jsonl

Use Cases

• Code review — two reviewers, one risky diff, zero shared bias
• Architecture tradeoff evaluation under uncertainty
• Change risk assessment before rollout
• Incident hypothesis review — competing root causes, argued out
• Migration plan audit

Roadmap

Field Test Reports & Release Docs

v0.2.2 (current)

• Full Field Test Report — noise-floor CIs, permutation control, shared RLHF priors
• Release Notes — what changed, model selection guidance, upgrade notes
• Field Test Plan — experimental methodology
• Learnings — findings and causal mechanism documentation

v0.2.1

• Full Corpus Report — Mistral effect confirmed, 367 debates, pipeline integrity, false-negative measurement
• Release Notes
• Field Test Plan
• Findings & Learnings

v0.2.0

• Full Corpus Report — 150 artifacts, 4 domains, 217 debates
• Field Test Plan

v0.1.0

• Full Corpus Report — 70 PRs, 6 pairs, 411 debates
• Field Test Plan

CHANGELOG — full version history

v0.2.2 Key Results

v0.2.2 Artifacts

• Noise-floor report: results/field-test/v0.2.2/noise-floor-report.json
• Permutation control: results/field-test/v0.2.2/permutation-control-report.json
• Field test scripts: scripts/README.md (see steps 8-9)

Non-Goals

• Replacing human reviewers for irreversible high-risk decisions
• Forcing consensus when disagreement is more informative
• Optimizing speed over reasoning quality
• Being a generic chat wrapper around multiple models

Honest Limitation

Debate does not guarantee truth. Two strong debaters can still miss the same blind spot, and poorly designed personas can turn useful disagreement into performance theater. The design answer: measure whether debate changed anything, and preserve dissent rather than flattening it.

License

MIT © 2026 Debashish Ghosal