debugerai 0.2.0__py3-none-any.whl

debugai/__init__.py

@@ -0,0 +1,51 @@
+"""DebugAI — AI Observability & Debugging Platform.
+
+A 3-layer root-cause engine for LLM application failures:
+
+  Layer 1 (deterministic)  — Signal extraction: 8 metrics per request.
+  Layer 2 (deterministic)  — Rule engine: 5 failure detectors, primary + secondary.
+  Layer 3 (probabilistic)  — LLM explainer: human-readable explanation + fix.
+
+Public API (Level 1 integration):
+
+    from debugai import analyze
+    result = analyze(prompt, output, chunks=..., similarity_scores=...)
+"""
+
+from debugai.schema import CaptureRecord
+from debugai.analyze import analyze
+from debugai.config import DebugAIConfig
+from debugai.metrics import metrics
+from debugai.sdk import (
+    wrap_llm, awrap_llm, retrieval_context, session, http_trace_sink,
+    completion, acompletion, CompletionResponse,
+    register_provider, register_adapter, set_default_config,
+    compare, ComparisonResult, BudgetExceededError,
+    _GenericOpenAICompatAdapter,
+)
+from debugai.tracing import Trace, Span, Tracer, Score
+
+__all__ = [
+    # Core
+    "analyze", "CaptureRecord",
+    # Config & metrics
+    "DebugAIConfig", "metrics",
+    # SDK wrappers
+    "wrap_llm", "awrap_llm",
+    # Universal completion API
+    "completion", "acompletion", "CompletionResponse",
+    # Registration
+    "register_provider", "register_adapter", "set_default_config",
+    # Context managers
+    "retrieval_context", "session",
+    # Observability
+    "Trace", "Span", "Tracer", "Score",
+    # Sinks
+    "http_trace_sink",
+    # Adapters
+    "_GenericOpenAICompatAdapter",
+    # Compare + budget
+    "compare", "ComparisonResult", "BudgetExceededError",
+]
+__version__ = "0.2.0"
+__all__ += ["__version__"]

debugai/agents/__init__.py

@@ -0,0 +1,43 @@
+"""Fix Agent Framework (Architecture §8) — diagnose → fix → verify → review."""
+
+from __future__ import annotations
+
+from debugai.agents.base import FixAgent
+from debugai.agents.builtin import (
+    ConstraintAgent, ContextOptimizerAgent, DocumentPatchAgent,
+    KnowledgeBaseAgent, PromptRuleAgent, SocraticTutorAgent,
+)
+from debugai.agents.registry import FixAgentRegistry
+from debugai.agents.types import (
+    ESCALATED, FAILED, MITIGATED, PENDING_RERUN, VERIFIED,
+    FixCandidate, FixReport, TestCase, TestResult,
+)
+from debugai.schema import CaptureRecord
+
+# A process-wide default registry with the five built-ins.
+DEFAULT_REGISTRY = FixAgentRegistry()
+
+
+def propose_fix(diagnosis: dict, record: CaptureRecord, rerun=None,
+                registry: FixAgentRegistry | None = None) -> FixReport | None:
+    """Select the right agent for a diagnosis and run the fix-verify loop.
+
+    Returns a FixReport, or None if no agent handles the failure (or the
+    request is healthy).
+    """
+    if not diagnosis or diagnosis.get("healthy"):
+        return None
+    reg = registry or DEFAULT_REGISTRY
+    agent = reg.find_agent(diagnosis)
+    if agent is None:
+        return None
+    return agent.run(diagnosis, record, rerun=rerun)
+
+
+__all__ = [
+    "FixAgent", "FixAgentRegistry", "DEFAULT_REGISTRY", "propose_fix",
+    "FixCandidate", "FixReport", "TestCase", "TestResult",
+    "PromptRuleAgent", "KnowledgeBaseAgent", "ConstraintAgent",
+    "ContextOptimizerAgent", "DocumentPatchAgent", "SocraticTutorAgent",
+    "VERIFIED", "MITIGATED", "FAILED", "PENDING_RERUN", "ESCALATED",
+]

debugai/agents/base.py

@@ -0,0 +1,192 @@
+"""Abstract FixAgent + the universal diagnose-fix-verify loop (Architecture §8.1).
+
+    1. Diagnose        (deterministic — already done; passed in)
+    2. Generate fix    (agent — generate_fix)
+    3. Build tests     (agent — build_test_cases)
+    4. Run regression  (deterministic — _run_test)
+    5. Re-diagnose     (deterministic — Layer 1+2 on the re-run output)
+    6. Developer review (human — consumes the FixReport)
+
+The agent (steps 2-3) is the only probabilistic part, and it is sandwiched
+between deterministic verification. Re-running the model is injected as a
+`rerun` callable so the framework has no hard dependency on any LLM:
+
+    rerun(system_prompt, user_prompt, chunks, temperature) -> output_text
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Callable
+
+from debugai.agents.types import (
+    ESCALATED, FAILED, MITIGATED, PENDING_RERUN, VERIFIED,
+    FixCandidate, FixReport, TestCase, TestResult,
+)
+from debugai.analyze import analyze
+from debugai.schema import CaptureRecord
+from debugai.signals import _extract_entities
+
+log = logging.getLogger("debugai.agents")
+
+Rerun = Callable[[str, str, list, "float | None"], str]
+
+
+@dataclass
+class _Applied:
+    system_prompt: str
+    chunks: list[str]
+    similarity_scores: list[float]
+    temperature: float | None
+
+
+class FixAgent(ABC):
+    name: str = "fix-agent"
+    handles: str = ""  # failure id this agent targets
+    # When False, the fix lives in the pipeline (e.g. re-chunking) and a prompt-only
+    # rerun can't structurally clear the failure — tests verify an interim guard,
+    # and a clean test pass yields a MITIGATED (not VERIFIED) verdict.
+    verifiable_by_rerun: bool = True
+
+    # --- selection ---------------------------------------------------------
+    def can_handle(self, diagnosis: dict) -> bool:
+        primary = (diagnosis or {}).get("primary") or {}
+        return primary.get("failure") == self.handles
+
+    # --- agent-specific (subclasses implement) -----------------------------
+    @abstractmethod
+    def generate_fix(self, diagnosis: dict, record: CaptureRecord) -> FixCandidate: ...
+
+    @abstractmethod
+    def build_test_cases(self, diagnosis: dict, record: CaptureRecord) -> list[TestCase]: ...
+
+    # --- the inherited loop ------------------------------------------------
+    def run(self, diagnosis: dict, record: CaptureRecord, rerun: Rerun | None = None) -> FixReport:
+        candidate = self.generate_fix(diagnosis, record)
+        before_conf = ((diagnosis.get("primary") or {}).get("confidence"))
+
+        if candidate.escalate:
+            return FixReport(
+                agent=self.name, failure=self.handles, verdict=ESCALATED,
+                candidate=candidate, diff=self._diff(candidate, record),
+                before_confidence=before_conf,
+            )
+
+        tests = self.build_test_cases(diagnosis, record)
+        report = FixReport(
+            agent=self.name, failure=self.handles, verdict=PENDING_RERUN,
+            candidate=candidate, diff=self._diff(candidate, record),
+            tests_total=len(tests), before_confidence=before_conf,
+        )
+        if rerun is None:
+            # Candidate + tests produced, but nothing to execute them against.
+            report.test_results = [TestResult(case=t, passed=False,
+                                              failures=["not run (no model)"]) for t in tests]
+            return report
+
+        applied = self._apply(candidate, record)
+
+        # Step 4 — deterministic regression tests.
+        results = [self._run_test(t, applied, rerun) for t in tests]
+        report.test_results = results
+        report.tests_passed = sum(1 for r in results if r.passed)
+
+        # Step 5 — re-diagnose the original failing request with the fix applied.
+        after, after_output = self._rediagnose(record, applied, rerun)
+        report.reverified = True
+        report.after_diagnosis = after
+        report.after_output = after_output
+        cleared = after.get("healthy") or (
+            (after.get("primary") or {}).get("failure") != self.handles
+        )
+        report.reverified_cleared = bool(cleared)
+
+        all_pass = report.tests_passed == report.tests_total
+        if not self.verifiable_by_rerun:
+            # Pipeline fix: interim guard tests verify, but Layer 1+2 still sees the
+            # structural failure until the pipeline change lands.
+            report.verdict = MITIGATED if all_pass else FAILED
+        else:
+            report.verdict = VERIFIED if (all_pass and cleared) else FAILED
+        return report
+
+    # --- deterministic helpers --------------------------------------------
+    def _apply(self, c: FixCandidate, record: CaptureRecord) -> _Applied:
+        system = record.system_prompt
+        if c.system_prompt_additions:
+            system = (system + "\n\n" + c.system_prompt_additions).strip()
+        chunks, scores = list(record.retrieved_chunks), list(record.similarity_scores)
+        if c.max_chunks is not None:
+            if scores and len(scores) == len(chunks):
+                order = sorted(range(len(chunks)), key=lambda i: scores[i], reverse=True)
+                keep = sorted(order[: c.max_chunks])
+                chunks = [chunks[i] for i in keep]
+                scores = [scores[i] for i in keep]
+            else:
+                chunks = chunks[: c.max_chunks]
+                scores = scores[: c.max_chunks]
+        if c.chunk_char_budget is not None:
+            # Stand-in for summarization: cap each kept chunk to the budget.
+            chunks = [ch[: c.chunk_char_budget] for ch in chunks]
+        temp = c.new_temperature if c.new_temperature is not None else record.temperature
+        return _Applied(system_prompt=system, chunks=chunks, similarity_scores=scores, temperature=temp)
+
+    def _run_test(self, t: TestCase, applied: _Applied, rerun: Rerun) -> TestResult:
+        outputs, failures = [], []
+        for _ in range(max(1, t.runs)):
+            out = rerun(applied.system_prompt, t.input, applied.chunks, applied.temperature) or ""
+            outputs.append(out)
+            low = out.lower()
+            for kw in t.must_contain:
+                if kw.lower() not in low:
+                    failures.append(f"missing '{kw}'")
+            for kw in t.must_not_contain:
+                if kw.lower() in low:
+                    failures.append(f"contains '{kw}'")
+        return TestResult(case=t, passed=not failures, outputs=outputs, failures=failures)
+
+    def _rediagnose(self, record: CaptureRecord, applied: _Applied, rerun: Rerun) -> tuple[dict, str]:
+        new_output = rerun(applied.system_prompt, record.user_prompt, applied.chunks, applied.temperature) or ""
+        result = analyze(
+            prompt=record.user_prompt,
+            output=new_output,
+            system_prompt=applied.system_prompt,
+            chunks=applied.chunks,
+            similarity_scores=applied.similarity_scores,
+            temperature=applied.temperature,
+            context_window=record.context_window,
+            explain_with_llm=False,
+        )
+        return result, new_output
+
+    def _diff(self, c: FixCandidate, record: CaptureRecord) -> str:
+        lines: list[str] = []
+        if c.system_prompt_additions:
+            lines.append("--- system_prompt (appended)")
+            for ln in c.system_prompt_additions.splitlines():
+                lines.append("+ " + ln)
+        if c.new_temperature is not None:
+            lines.append(f"~ temperature: {record.temperature} -> {c.new_temperature}")
+        if c.max_chunks is not None:
+            lines.append(f"~ retrieved_chunks: {len(record.retrieved_chunks)} -> top {c.max_chunks} by similarity")
+        for ex in c.few_shot_examples:
+            lines.append(f"+ few-shot: {ex.get('input','')[:48]} -> {ex.get('output','')[:48]}")
+        if c.notes:
+            lines.append(f"# note: {c.notes}")
+        return "\n".join(lines)
+
+    # --- shared NER helper for test generation -----------------------------
+    @staticmethod
+    def _fabricated_entities(record: CaptureRecord) -> list[str]:
+        """Entities in the output that are absent from the retrieved context."""
+        out_ents = _extract_entities(record.llm_output)
+        ctx = record.context_text.lower()
+        return sorted(e for e in out_ents if e not in ctx)
+
+    @staticmethod
+    def _grounded_entities(record: CaptureRecord) -> list[str]:
+        out_ents = _extract_entities(record.llm_output)
+        ctx = record.context_text.lower()
+        return sorted(e for e in out_ents if e in ctx)

debugai/agents/builtin.py

@@ -0,0 +1,246 @@
+"""The five built-in fix agents (Architecture §8.3).
+
+Each targets one failure type and ships a deterministic fix template. (Fix text
+can be LLM-drafted when a key is present, but the templates make the framework
+work — and verify — offline.) Generation is the only probabilistic step; the
+loop in ``base.FixAgent.run`` verifies every fix deterministically.
+"""
+
+from __future__ import annotations
+
+from debugai.agents.base import FixAgent
+from debugai.agents.types import (
+    FAILED, PENDING_RERUN, VERIFIED, FixCandidate, FixReport, TestCase,
+)
+from debugai.detectors import (
+    CONTEXT_OVERFLOW, ENTITY_GAP, HALLUCINATION, PROMPT_BRITTLENESS, RETRIEVAL_FAILURE,
+)
+from debugai.judge import INSTRUCTION_VIOLATION, judge_instructions
+from debugai.schema import CaptureRecord
+
+
+def _first(xs: list[str], n: int) -> list[str]:
+    return [x for x in xs[:n] if x]
+
+
+# --------------------------------------------------------------------------- #
+# 1. Prompt Rule Agent — hallucination
+# --------------------------------------------------------------------------- #
+class PromptRuleAgent(FixAgent):
+    name = "Prompt Rule Agent"
+    handles = HALLUCINATION
+
+    GROUNDING = (
+        "Answer ONLY using the provided context. If the context does not contain "
+        "the answer, reply exactly: \"I don't have that information.\" Never invent "
+        "names, numbers, dates, clauses, or citations. For every specific claim, the "
+        "supporting text must appear in the context."
+    )
+
+    def generate_fix(self, diagnosis, record):
+        return FixCandidate(
+            agent=self.name, failure=self.handles,
+            strategy="Add grounding constraints + an out-of-context fallback to the system prompt.",
+            rationale="Retrieval succeeded but the output is ungrounded — constrain "
+                      "generation to the supplied context.",
+            system_prompt_additions=self.GROUNDING,
+        )
+
+    def build_test_cases(self, diagnosis, record):
+        fab = self._fabricated_entities(record)
+        grounded = self._grounded_entities(record)
+        tests = [
+            TestCase(input=record.user_prompt, must_not_contain=_first(fab, 4),
+                     category="original"),
+            TestCase(input=record.user_prompt, must_not_contain=_first(fab, 4),
+                     category="variance", runs=3),
+        ]
+        if grounded:
+            tests.append(TestCase(input=record.user_prompt,
+                                  must_contain=_first(grounded, 1), category="regression"))
+        return tests
+
+
+# --------------------------------------------------------------------------- #
+# 2. Knowledge Base Agent — retrieval failure
+# --------------------------------------------------------------------------- #
+class KnowledgeBaseAgent(FixAgent):
+    name = "Knowledge Base Agent"
+    handles = RETRIEVAL_FAILURE
+    verifiable_by_rerun = False  # real fix is re-chunking/re-embedding the corpus
+
+    GUARD = (
+        "If the retrieved context does not address the question, reply exactly: "
+        "\"The knowledge base does not contain this information.\" Do not answer "
+        "from prior knowledge."
+    )
+
+    def generate_fix(self, diagnosis, record):
+        sim = ((diagnosis.get("signals") or {}).get("similarity"))
+        return FixCandidate(
+            agent=self.name, failure=self.handles,
+            strategy="Re-chunk source docs entity-aware + add an interim 'not in KB' guard.",
+            rationale=f"Mean retrieval similarity {sim} is below threshold — the "
+                      "retriever returned irrelevant chunks.",
+            system_prompt_additions=self.GUARD,
+            notes="Re-chunk the source corpus with an entity-aware strategy and "
+                  "re-embed; verify the target document is actually indexed.",
+        )
+
+    def build_test_cases(self, diagnosis, record):
+        fab = self._fabricated_entities(record)
+        return [
+            TestCase(input=record.user_prompt, must_not_contain=_first(fab, 4),
+                     category="original"),
+            TestCase(input=record.user_prompt, must_not_contain=_first(fab, 4),
+                     category="variance", runs=3),
+        ]
+
+
+# --------------------------------------------------------------------------- #
+# 3. Constraint Agent — prompt brittleness
+# --------------------------------------------------------------------------- #
+class ConstraintAgent(FixAgent):
+    name = "Constraint Agent"
+    handles = PROMPT_BRITTLENESS
+
+    TEMPLATE = (
+        "Be deterministic and consistent across runs. Follow a fixed output format "
+        "and do not vary phrasing, ordering, or structure between identical inputs."
+    )
+
+    def generate_fix(self, diagnosis, record):
+        return FixCandidate(
+            agent=self.name, failure=self.handles,
+            strategy="Lower temperature, add an output-format template, and pin behavior with a few-shot example.",
+            rationale="Grounding signals are healthy but output variance is high — "
+                      "constrain sampling and format.",
+            new_temperature=0.2,
+            system_prompt_additions=self.TEMPLATE,
+            few_shot_examples=[{"input": record.user_prompt, "output": record.llm_output}],
+        )
+
+    def build_test_cases(self, diagnosis, record):
+        grounded = self._grounded_entities(record)
+        mc = _first(grounded, 1)
+        return [
+            TestCase(input=record.user_prompt, must_contain=mc, category="regression"),
+            TestCase(input=record.user_prompt, must_contain=mc, category="variance", runs=3),
+        ]
+
+
+# --------------------------------------------------------------------------- #
+# 4. Context Optimizer Agent — context overflow
+# --------------------------------------------------------------------------- #
+class ContextOptimizerAgent(FixAgent):
+    name = "Context Optimizer Agent"
+    handles = CONTEXT_OVERFLOW
+
+    def generate_fix(self, diagnosis, record):
+        return FixCandidate(
+            agent=self.name, failure=self.handles,
+            strategy="Reduce to the top-N most relevant chunks and summarize each to fit the window.",
+            rationale="The prompt overflows the context window; trim and compress "
+                      "the retrieved context.",
+            max_chunks=8,
+            chunk_char_budget=240,
+            notes="Summarize prior conversation history; consider a larger-context model.",
+        )
+
+    def build_test_cases(self, diagnosis, record):
+        grounded = self._grounded_entities(record)
+        return [
+            TestCase(input=record.user_prompt, must_contain=_first(grounded, 1),
+                     category="regression"),
+        ]
+
+
+# --------------------------------------------------------------------------- #
+# 5. Document Patch Agent — entity gap (escalates)
+# --------------------------------------------------------------------------- #
+class DocumentPatchAgent(FixAgent):
+    name = "Document Patch Agent"
+    handles = ENTITY_GAP
+
+    def generate_fix(self, diagnosis, record):
+        missing = self._fabricated_entities(record)  # entities not in the corpus
+        names = ", ".join(_first(missing, 6)) or "the requested entities"
+        return FixCandidate(
+            agent=self.name, failure=self.handles,
+            strategy="Identify missing entities and flag the knowledge-base gap for human review.",
+            rationale="Retrieval is healthy but the corpus lacks coverage for these "
+                      "entities — content cannot be safely auto-generated.",
+            notes=f"Knowledge base needs articles covering: {names}.",
+            escalate=True,
+        )
+
+    def build_test_cases(self, diagnosis, record):
+        return []  # escalated before tests run
+
+
+# --------------------------------------------------------------------------- #
+# 6. Socratic Tutor Agent — instruction_violation (behavioural / pedagogy)
+# --------------------------------------------------------------------------- #
+class SocraticTutorAgent(FixAgent):
+    name = "Socratic Tutor Agent"
+    handles = INSTRUCTION_VIOLATION
+
+    RULES = (
+        "STRICT Socratic correction — these override any conflicting guidance above:\n"
+        "- Do NOT explain the concept or state the answer. Give at most ONE short "
+        "clue (one sentence maximum), and only if the student is stuck.\n"
+        "- Lead with the question: the turn must centre on exactly ONE short leading "
+        "question (exactly one '?') that moves the student one step forward, and must "
+        "never restate or reword a question already asked.\n"
+        "- Do not open by paraphrasing the student's message.\n"
+        "- Keep the whole turn to 1-2 sentences. When unsure, ask rather than explain."
+    )
+
+    def generate_fix(self, diagnosis, record):
+        ev = ((diagnosis.get("primary") or {}).get("evidence") or {})
+        viols = ev.get("violations") or []
+        names = "; ".join(v.get("rule", "") for v in viols[:4]) or "Socratic-method rules"
+        return FixCandidate(
+            agent=self.name, failure=self.handles,
+            strategy="Rewrite the system prompt to enforce the violated Socratic rules.",
+            rationale=f"The response broke pedagogy rules ({names}); tighten the "
+                      "system prompt so the tutor guides instead of answering.",
+            system_prompt_additions=self.RULES,
+        )
+
+    def build_test_cases(self, diagnosis, record):
+        return []  # verified by re-judging (below), not by must_contain checks
+
+    def run(self, diagnosis, record, rerun=None):
+        """Judge-based verify loop: rewrite prompt → regenerate → re-judge."""
+        candidate = self.generate_fix(diagnosis, record)
+        before = (diagnosis.get("primary") or {}).get("confidence")
+        report = FixReport(agent=self.name, failure=self.handles, verdict=PENDING_RERUN,
+                           candidate=candidate, diff=self._diff(candidate, record),
+                           before_confidence=before)
+        if rerun is None:
+            return report
+        applied = self._apply(candidate, record)
+        new_output = rerun(applied.system_prompt, record.user_prompt,
+                           applied.chunks, applied.temperature) or ""
+        jd = judge_instructions(applied.system_prompt, record.user_prompt, new_output)
+        report.reverified = True
+        report.after_output = new_output
+        report.reverified_cleared = jd.healthy
+        report.after_diagnosis = {
+            "healthy": jd.healthy,
+            "primary": None if jd.healthy else {
+                "failure": INSTRUCTION_VIOLATION, "confidence": jd.confidence},
+        }
+        report.verdict = VERIFIED if jd.healthy else FAILED
+        return report
+
+
+BUILTIN_AGENTS = [
+    PromptRuleAgent,
+    KnowledgeBaseAgent,
+    ConstraintAgent,
+    ContextOptimizerAgent,
+    DocumentPatchAgent,
+    SocraticTutorAgent,
+]

debugai/agents/registry.py

@@ -0,0 +1,31 @@
+"""Fix agent registry + plugin architecture (Architecture §8.5).
+
+Custom agents register at the front, so they take priority over the built-ins
+and inherit the full diagnose-fix-verify loop.
+
+    registry = FixAgentRegistry()
+    registry.register(SyllabusAgent("class10_cbse.pdf"))   # custom, checked first
+    agent = registry.find_agent(diagnosis)
+"""
+
+from __future__ import annotations
+
+from debugai.agents.base import FixAgent
+from debugai.agents.builtin import BUILTIN_AGENTS
+
+
+class FixAgentRegistry:
+    def __init__(self, include_builtins: bool = True):
+        self.agents: list[FixAgent] = (
+            [cls() for cls in BUILTIN_AGENTS] if include_builtins else []
+        )
+
+    def register(self, agent: FixAgent) -> None:
+        """Register a custom agent — inserted first so it wins over built-ins."""
+        self.agents.insert(0, agent)
+
+    def find_agent(self, diagnosis: dict) -> FixAgent | None:
+        for agent in self.agents:
+            if agent.can_handle(diagnosis):
+                return agent
+        return None

debugai/agents/types.py

@@ -0,0 +1,108 @@
+"""Data types for the Fix Agent Framework (Architecture §8)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+# Verdicts for a fix attempt.
+VERIFIED = "verified"          # tests pass AND re-diagnosis clears the failure
+MITIGATED = "mitigated"        # interim guard verified, but full fix needs a pipeline change
+FAILED = "failed"             # fix did not clear the failure / tests failed
+PENDING_RERUN = "pending_rerun"  # candidate + tests produced, but no model to verify
+ESCALATED = "escalated"        # agent declined to auto-fix; flagged for a human
+
+
+@dataclass
+class FixCandidate:
+    """A candidate fix produced by an agent. The modifications are applied
+    deterministically by the loop before re-running the model."""
+
+    agent: str
+    failure: str
+    strategy: str
+    rationale: str = ""
+    # Modifications (any subset applies):
+    system_prompt_additions: str = ""
+    new_temperature: float | None = None
+    max_chunks: int | None = None
+    chunk_char_budget: int | None = None   # summarize/truncate each kept chunk
+    few_shot_examples: list[dict] = field(default_factory=list)
+    # Advisory output (not auto-applied):
+    notes: str = ""
+    escalate: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class TestCase:
+    """One deterministic regression check (§8.4)."""
+
+    __test__ = False  # not a pytest test class
+
+    input: str
+    must_contain: list[str] = field(default_factory=list)
+    must_not_contain: list[str] = field(default_factory=list)
+    category: str = "regression"   # original | edge | regression | variance
+    runs: int = 1                  # variance checks run 3x
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class TestResult:
+    __test__ = False  # not a pytest test class
+
+    case: TestCase
+    passed: bool
+    outputs: list[str] = field(default_factory=list)
+    failures: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "input": self.case.input,
+            "category": self.case.category,
+            "runs": self.case.runs,
+            "passed": self.passed,
+            "failures": self.failures,
+            "must_contain": self.case.must_contain,
+            "must_not_contain": self.case.must_not_contain,
+        }
+
+
+@dataclass
+class FixReport:
+    """The full diagnose-fix-verify report presented for developer review (§8.1)."""
+
+    agent: str
+    failure: str
+    verdict: str
+    candidate: FixCandidate
+    diff: str = ""
+    test_results: list[TestResult] = field(default_factory=list)
+    tests_passed: int = 0
+    tests_total: int = 0
+    reverified: bool = False
+    reverified_cleared: bool | None = None
+    before_confidence: float | None = None
+    after_diagnosis: dict | None = None
+    after_output: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "agent": self.agent,
+            "failure": self.failure,
+            "verdict": self.verdict,
+            "candidate": self.candidate.to_dict(),
+            "diff": self.diff,
+            "tests_passed": self.tests_passed,
+            "tests_total": self.tests_total,
+            "test_results": [t.to_dict() for t in self.test_results],
+            "reverified": self.reverified,
+            "reverified_cleared": self.reverified_cleared,
+            "before_confidence": self.before_confidence,
+            "after_diagnosis": self.after_diagnosis,
+            "after_output": self.after_output,
+        }