agentdebugx 0.2.8__tar.gz → 0.2.10__tar.gz

{agentdebugx-0.2.8 → agentdebugx-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentdebugx
-Version: 0.2.8
+Version: 0.2.10
 Summary: Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`.
 License: MIT
 License-File: LICENSE

{agentdebugx-0.2.8 → agentdebugx-0.2.10}/docs/23_status_v0_2.md

@@ -23,8 +23,11 @@ the forward-looking plan; this doc is the rear-view mirror.
 | Attribution | `agentdebug.attribution.BinarySearchAttributor` | ✅ **new 0.2.3** | oracle-LLM logarithmic convergence + fallback + render elision |
 | Attribution | `agentdebug.attribution.CounterfactualAttributor` | ✅ **new 0.2.7** | scripted-rescue-prob ranking + candidate selection priority (findings → errors → tail) + dual fallback (no candidates / silent LLM) |
 | Attribution | `agentdebug.attribution.SBFLAttributor` (Tarantula / Ochiai / DStar) | ✅ **new 0.2.8** | signature design + ranking on synthetic corpus + 3 formulas + dual fallback + edge cases. Model-free: zero LLM cost at inference. |
+| Attribution | `agentdebug.attribution.EnsembleAttributor` (+ `AttributionBudget`) | ✅ **new 0.2.10** | Borda + Bayesian merge, weighted backends, walltime/backend-count budget, swallows backend exceptions, falls back when all empty, honest per-source provenance |
 | Recovery | `agentdebug.recovery.ReflexionSuggestion` | ✅ stable | per-finding + empty |
 | Recovery | `agentdebug.recovery.CriticRecoverer` + `VerifierSpec` registry | ✅ **new 0.2.3** | 5 family-matched verifier templates; dedup + custom-override |
+| Recovery | `agentdebug.recovery.SelfRefineLoop` | ✅ **new 0.2.9** | scripted-LLM happy + silent-LLM safe + multi-iter; per-finding generator→critic→refiner |
+| Recovery | `agentdebug.recovery.AutoManualRules` (+ `apply()`) | ✅ **new 0.2.9** | no-LLM fallback + LLM rule-distill + idempotent apply + multi-rule append |
 | DeepDebug | `agentdebug.deep.DeepDebugAnalyzer` | ✅ stable | full loop + silent LLM |
 | Cascade view | `agentdebug.traceback.format_traceback` | ✅ stable | cascade + step-order + ANSI + empty |
 | Detectors | `agentdebug.detectors.RepeatedToolCall / RepeatedState / StepCountLimit` | ✅ **new 0.2.2** | threshold + window + budget |
@@ -52,9 +55,6 @@ across 32 source files.
 | [07_attribution.md](./07_attribution.md) | `CounterfactualAttributor` — *real* replay variant | true re-rollout requires framework-specific replay surface; the v0.2.7 LLM-simulated variant ships now, the real-replay variant is gated on adapter support (LangGraph checkpointer / OpenHands rewind) | v0.4 |
 | [07_attribution.md](./07_attribution.md) | `SBFLAttributor` — *corpus* | shipped in 0.2.8 (`tarantula`/`ochiai`/`dstar`); awaiting paired-trace adoption to gather a useful corpus in production | corpus tooling deferred to v0.4 |
 | [07_attribution.md](./07_attribution.md) | `DeltaDebugAttributor` (Zeller) | same replay constraint | v0.3 |
-| [07_attribution.md](./07_attribution.md) | `EnsembleAttributor` | trivial once Counterfactual lands; awaits Counterfactual | v0.3 |
-| [08_recovery.md](./08_recovery.md) | `SelfRefineLoop` | small but needs a generator-critic-refiner orchestration | v0.3 |
-| [08_recovery.md](./08_recovery.md) | `AutoManualRules` | needs persistent project manual + injection into next-run prompts | v0.3 |
 | [08_recovery.md](./08_recovery.md) | `LangGraphRewind` | depends on LangGraph checkpointer; ships when we have a real LangGraph user | v0.3 |
 | [08_recovery.md](./08_recovery.md) | `SagaRollback` | needs compensation registry on tool definitions; new schema | v0.3 |
 | [08_recovery.md](./08_recovery.md) | `MCTSBranchExploration` (LATS) | heavy; v2 feature | v2.0 |

{agentdebugx-0.2.8 → agentdebugx-0.2.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentdebugx"
-version = "0.2.8"
+version = "0.2.10"
 description = "Portable error analysis, tracing, and recovery framework for agentic AI systems. Import as `agentdebug`."
 authors = ["ULab @ UIUC <ulab@illinois.edu>"]
 license = "MIT"

{agentdebugx-0.2.8 → agentdebugx-0.2.10}/src/agentdebug/__init__.py

@@ -11,11 +11,13 @@ See ``docs/14_api_reference.md`` for the full public surface and
 from agentdebug.analyzers import HeuristicAnalyzer
 from agentdebug.attribution import (
     AllAtOnceAttributor,
+    AttributionBudget,
     AttributionResult,
     Attributor,
     BinarySearchAttributor,
     Blame,
     CounterfactualAttributor,
+    EnsembleAttributor,
     HeuristicAttributor,
     SBFLAttributor,
     StepByStepAttributor,
@@ -43,10 +45,12 @@ from agentdebug.models import (
 from agentdebug.recorder import AgentDebug, TraceSession
 from agentdebug.recovery import (
     DEFAULT_VERIFIERS,
+    AutoManualRules,
     CriticRecoverer,
     FixProposal,
     Recoverer,
     ReflexionSuggestion,
+    SelfRefineLoop,
     VerifierSpec,
 )
 from agentdebug.traceback import CascadeFrame, build_cascade, format_traceback
@@ -63,6 +67,8 @@ __all__ = [
     'Attributor',
     'Blame',
     'BusEvent',
+    'AttributionBudget',
+    'AutoManualRules',
     'BinarySearchAttributor',
     'CascadeFrame',
     'CounterfactualAttributor',
@@ -70,9 +76,11 @@ __all__ = [
     'DEFAULT_VERIFIERS',
     'Detector',
     'DetectorConfig',
+    'EnsembleAttributor',
     'RepeatedStateDetector',
     'RepeatedToolCallDetector',
     'SBFLAttributor',
+    'SelfRefineLoop',
     'StepByStepAttributor',
     'StepCountLimitDetector',
     'VerifierSpec',
@@ -100,4 +108,4 @@ __all__ = [
     'get_failure_mode',
 ]
 
-__version__ = '0.2.8'
+__version__ = '0.2.10'

{agentdebugx-0.2.8 → agentdebugx-0.2.10}/src/agentdebug/attribution.py

@@ -19,7 +19,7 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, Protocol, cast
+from typing import Any, Dict, List, Optional, Protocol, Tuple, cast
 
 
 # Forward decl so BinarySearchAttributor.attribute can reference _EllipsisEvent
@@ -936,8 +936,217 @@ def _suspiciousness(
     return float((ef ** dstar_exponent) / denom)
 
 
+@dataclass
+class AttributionBudget:
+    """Optional cap on ensemble cost."""
+
+    max_backends: Optional[int] = None     # short-circuit after N successful backends
+    max_seconds: Optional[float] = None    # walltime cap; remaining backends skipped
+
+    def exceeded(
+        self, *, completed: int, elapsed_s: float,
+    ) -> bool:
+        if self.max_backends is not None and completed >= self.max_backends:
+            return True
+        if self.max_seconds is not None and elapsed_s >= self.max_seconds:
+            return True
+        return False
+
+
+class EnsembleAttributor:
+    """Compose any subset of attributors into a single ranked result.
+
+    Two merge strategies:
+
+      * ``"borda"`` (default) — each backend's ranked list contributes
+        Borda points (top hypothesis = N, next = N-1, …). Steps are
+        ranked by total points × backend weight; ties broken by primary
+        confidence × weight.
+      * ``"bayesian"`` — combine confidences as 1 - ∏(1 - w_i × c_i)
+        across backends that nominated the same (event_id, step_index).
+        Treats each backend as an independent noisy classifier; good when
+        backends are heterogeneous and confidences are well-calibrated.
+
+    Provenance is HONEST: every output ``Blame.sources`` lists every
+    backend that contributed; the rationale aggregates source-by-source
+    so the UI can show which backends agreed.
+
+    Pair with ``AttributionBudget`` to cap wall-clock or backend count
+    when running expensive backends (e.g., BinarySearch + Counterfactual)
+    alongside cheap ones (Heuristic + SBFL).
+    """
+
+    id = 'ensemble'
+
+    def __init__(
+        self,
+        backends: List[Attributor],
+        *,
+        weights: Optional[Dict[str, float]] = None,
+        merge: str = 'borda',
+        top_k: int = 5,
+        budget: Optional[AttributionBudget] = None,
+        fallback: Optional[Attributor] = None,
+    ) -> None:
+        if not backends:
+            raise ValueError('EnsembleAttributor requires at least one backend')
+        if merge not in {'borda', 'bayesian'}:
+            raise ValueError(
+                f"Unknown merge strategy {merge!r}; use 'borda' or 'bayesian'"
+            )
+        self.backends = list(backends)
+        self.weights = weights or {b.id: 1.0 for b in backends}
+        self.merge = merge
+        self.top_k = top_k
+        self.budget = budget
+        self.fallback: Attributor = fallback or HeuristicAttributor()
+
+    def attribute(
+        self,
+        trajectory: AgentTrajectory,
+        findings: List[FailureFinding],
+    ) -> AttributionResult:
+        import time as _time
+
+        per_backend: List[Tuple[str, AttributionResult]] = []
+        started = _time.perf_counter()
+        for backend in self.backends:
+            if self.budget and self.budget.exceeded(
+                completed=len(per_backend),
+                elapsed_s=_time.perf_counter() - started,
+            ):
+                LOG.debug('ensemble budget hit; stopping early')
+                break
+            try:
+                result = backend.attribute(trajectory, findings)
+            except Exception as exc:  # pragma: no cover - defensive
+                LOG.warning('ensemble backend %s raised: %s', backend.id, exc)
+                continue
+            per_backend.append((backend.id, result))
+
+        # Any backend produced hypotheses? Otherwise fall back.
+        if not any(r.hypotheses for _id, r in per_backend):
+            return self.fallback.attribute(trajectory, findings)
+
+        if self.merge == 'borda':
+            merged = self._merge_borda(per_backend)
+        else:
+            merged = self._merge_bayesian(per_backend)
+
+        merged = merged[: self.top_k]
+        elapsed_ms = int((_time.perf_counter() - started) * 1000)
+        return AttributionResult(
+            method=self.id,
+            hypotheses=merged,
+            elapsed_ms=elapsed_ms,
+            raw={
+                'merge': self.merge,
+                'backends_run': [bid for bid, _ in per_backend],
+                'weights': dict(self.weights),
+                'budget_exceeded': bool(
+                    self.budget
+                    and self.budget.exceeded(
+                        completed=len(per_backend),
+                        elapsed_s=_time.perf_counter() - started,
+                    )
+                ),
+            },
+        )
+
+    # ---- merge strategies ----
+
+    def _merge_borda(
+        self, per_backend: List[Tuple[str, AttributionResult]],
+    ) -> List[Blame]:
+        # Aggregator keyed by canonical step identity.
+        agg: Dict[Tuple[Optional[str], Optional[int]], _MergeRow] = {}
+        for backend_id, result in per_backend:
+            w = self.weights.get(backend_id, 1.0)
+            n = len(result.hypotheses)
+            for rank, h in enumerate(result.hypotheses):
+                key = (h.span_id, h.step_index)
+                row = agg.setdefault(key, _MergeRow(span_id=h.span_id,
+                                                   step_index=h.step_index))
+                # Borda points: top = N, next = N-1, … last = 1
+                row.borda_points += (n - rank) * w
+                row.weighted_conf_sum += w * h.confidence
+                row.weight_sum += w
+                row.sources.add(backend_id)
+                if h.agent_name and not row.agent_name:
+                    row.agent_name = h.agent_name
+                if h.rationale and backend_id not in row.rationales:
+                    row.rationales[backend_id] = h.rationale
+                row.evidence.extend(h.evidence)
+        ranked = sorted(
+            agg.values(),
+            key=lambda r: (-r.borda_points, -r.weighted_conf_sum),
+        )
+        return [self._row_to_blame(r) for r in ranked]
+
+    def _merge_bayesian(
+        self, per_backend: List[Tuple[str, AttributionResult]],
+    ) -> List[Blame]:
+        agg: Dict[Tuple[Optional[str], Optional[int]], _MergeRow] = {}
+        for backend_id, result in per_backend:
+            w = self.weights.get(backend_id, 1.0)
+            for h in result.hypotheses:
+                key = (h.span_id, h.step_index)
+                row = agg.setdefault(key, _MergeRow(span_id=h.span_id,
+                                                   step_index=h.step_index))
+                # P(no source supports) *= (1 - w*c)
+                effective = max(0.0, min(1.0, w * h.confidence))
+                row.bayesian_not_pos *= (1.0 - effective)
+                row.weighted_conf_sum += w * h.confidence
+                row.weight_sum += w
+                row.sources.add(backend_id)
+                if h.agent_name and not row.agent_name:
+                    row.agent_name = h.agent_name
+                if h.rationale and backend_id not in row.rationales:
+                    row.rationales[backend_id] = h.rationale
+                row.evidence.extend(h.evidence)
+        ranked = sorted(
+            agg.values(),
+            key=lambda r: (-(1.0 - r.bayesian_not_pos), -r.weighted_conf_sum),
+        )
+        return [self._row_to_blame(r) for r in ranked]
+
+    def _row_to_blame(self, row: '_MergeRow') -> Blame:
+        if self.merge == 'borda':
+            # Confidence = weighted average of backend confidences (cap at 1).
+            conf = min(1.0, row.weighted_conf_sum / max(row.weight_sum, 1e-9))
+        else:
+            conf = max(0.0, min(1.0, 1.0 - row.bayesian_not_pos))
+        rationale = '; '.join(
+            f'{bid}: {txt[:140]}' for bid, txt in row.rationales.items()
+        ) or 'ensemble agreement'
+        return Blame(
+            span_id=row.span_id,
+            step_index=row.step_index,
+            agent_name=row.agent_name,
+            confidence=conf,
+            rationale=rationale,
+            evidence=list(dict.fromkeys(row.evidence)),  # dedupe preserve order
+            sources=sorted(row.sources),
+        )
+
+
+@dataclass
+class _MergeRow:
+    span_id: Optional[str]
+    step_index: Optional[int]
+    agent_name: Optional[str] = None
+    borda_points: float = 0.0
+    bayesian_not_pos: float = 1.0
+    weighted_conf_sum: float = 0.0
+    weight_sum: float = 0.0
+    sources: set[str] = field(default_factory=set)
+    rationales: Dict[str, str] = field(default_factory=dict)
+    evidence: List[str] = field(default_factory=list)
+
+
 __all__ = [
-    'Attributor', 'Blame', 'AttributionResult',
-    'HeuristicAttributor', 'AllAtOnceAttributor', 'StepByStepAttributor',
-    'BinarySearchAttributor', 'CounterfactualAttributor', 'SBFLAttributor',
+    'AllAtOnceAttributor', 'AttributionBudget', 'AttributionResult',
+    'Attributor', 'BinarySearchAttributor', 'Blame',
+    'CounterfactualAttributor', 'EnsembleAttributor', 'HeuristicAttributor',
+    'SBFLAttributor', 'StepByStepAttributor',
 ]

{agentdebugx-0.2.8 → agentdebugx-0.2.10}/src/agentdebug/recovery.py

@@ -304,11 +304,292 @@ class CriticRecoverer:
         )
 
 
+_SELF_REFINE_CRITIC_PROMPT = """You are AgentDebugX-SelfRefine acting as the
+CRITIC. You will be shown the goal of a failed agent run and a single
+failure finding (mode + step + evidence).
+
+Your job: in 2-4 short sentences, explain WHAT went wrong at that step and
+WHY it caused the failure. Do not propose a fix yet — that's the next round.
+Be concrete; reference the evidence.
+
+Output plain text. No JSON, no markdown."""
+
+
+_SELF_REFINE_REFINER_PROMPT = """You are AgentDebugX-SelfRefine acting as the
+REFINER. You will be shown the goal of a failed agent run, a single failure
+finding, AND the CRITIC's analysis of what went wrong.
+
+Your job: produce a single concrete REFINED ACTION the agent should take
+NEXT TIME at that step. 2-4 short sentences. Plain text. Be operational —
+the agent will read this verbatim as guidance.
+
+If the failure is in tool args, give the exact corrected arg shape. If the
+failure is in planning, give the next plan step. If the failure is in
+reflection, give the next verification check.
+
+Output plain text. No JSON, no markdown."""
+
+
+class SelfRefineLoop:
+    """Self-Refine (Madaan et al., NeurIPS 2023, arXiv:2303.17651) recovery.
+
+    Suggest-only — we do NOT re-execute the agent. For each finding, run a
+    bounded generator-critic-refiner cycle: CRITIC explains what went
+    wrong, REFINER proposes a concrete next-attempt action. The cycle can
+    iterate ``max_iters`` times; each iteration costs 2 LLM calls.
+
+    Output is a :class:`FixProposal` whose ``suggestion_text`` contains
+    both the critic analysis and the refiner's concrete action. Pair with
+    :class:`ReflexionSuggestion` for short verbal hints and
+    :class:`CriticRecoverer` for verifier-template recommendations.
+    """
+
+    id = 'self_refine'
+
+    def __init__(
+        self,
+        llm: object,
+        *,
+        max_iters: int = 1,
+        max_tokens: int = 512,
+    ) -> None:
+        # llm is duck-typed to LLMClient (avoid circular import); it must have
+        # a `.complete(messages=..., max_tokens=...)` returning .text.
+        self.llm = llm
+        self.max_iters = max(1, max_iters)
+        self.max_tokens = max_tokens
+
+    def suggest(
+        self,
+        trajectory: AgentTrajectory,
+        report: DiagnosticReport,
+    ) -> List[FixProposal]:
+        if not report.findings:
+            return []
+        proposals: List[FixProposal] = []
+        for finding in report.findings:
+            proposal = self._refine_one(trajectory, finding)
+            if proposal is not None:
+                proposals.append(proposal)
+        return proposals
+
+    def _refine_one(
+        self,
+        trajectory: AgentTrajectory,
+        finding: FailureFinding,
+    ) -> Optional[FixProposal]:
+        evidence_block = '\n'.join(f'  - {e}' for e in finding.evidence) or '  (none)'
+        finding_block = (
+            f'GOAL: {trajectory.goal!r}\n'
+            f'FAILURE MODE: {finding.failure_mode.mode_id} '
+            f'({finding.failure_mode.name})\n'
+            f'AT: agent={finding.agent_name}, step={finding.step_index}\n'
+            f'EVIDENCE:\n{evidence_block}'
+        )
+        last_critic = ''
+        last_refined = ''
+        try:
+            for _ in range(self.max_iters):
+                critic_text = self._call(
+                    system=_SELF_REFINE_CRITIC_PROMPT,
+                    user=finding_block + (
+                        f'\n\nPRIOR REFINED ACTION (improve on this if needed):\n'
+                        f'{last_refined}' if last_refined else ''
+                    ),
+                )
+                if not critic_text:
+                    break
+                last_critic = critic_text
+                refined_text = self._call(
+                    system=_SELF_REFINE_REFINER_PROMPT,
+                    user=finding_block + f'\n\nCRITIC ANALYSIS:\n{critic_text}',
+                )
+                if not refined_text:
+                    break
+                last_refined = refined_text
+        except Exception:
+            # Defensive: never break the host pipeline on LLM hiccup.
+            pass
+        if not last_critic and not last_refined:
+            return None
+        suggestion_text = (
+            f'Self-Refine output (after {self.max_iters} iter(s)) for '
+            f'{finding.failure_mode.mode_id} at step {finding.step_index}:\n\n'
+            f'CRITIC:\n{last_critic or "(no critic output)"}\n\n'
+            f'REFINED ACTION:\n{last_refined or "(no refined action)"}'
+        )
+        return FixProposal(
+            proposal_id=new_id('fix'),
+            recoverer_id=self.id,
+            target_event_id=finding.event_id,
+            summary=(
+                f'Self-Refine action for {finding.failure_mode.mode_id} '
+                f'at step {finding.step_index}'
+            ),
+            rationale=(
+                'Self-Refine (Madaan et al., NeurIPS 2023): one LM acts as '
+                'critic, then refiner; output is a concrete next-attempt '
+                'action the agent reads verbatim.'
+            ),
+            confidence=max(0.3, min(0.9, finding.confidence)),
+            suggestion_text=suggestion_text,
+            side_effects=[],
+            requires_human_approval=False,
+        )
+
+    def _call(self, *, system: str, user: str) -> str:
+        messages = [
+            {'role': 'system', 'content': system},
+            {'role': 'user', 'content': user},
+        ]
+        # Direct attribute access — llm is duck-typed (see __init__ note).
+        result = self.llm.complete(  # type: ignore[attr-defined]
+            messages=messages, max_tokens=self.max_tokens
+        )
+        text = getattr(result, 'text', '') or ''
+        return str(text).strip()
+
+
+class AutoManualRules:
+    """AutoManual-style learned rule extraction (Chen et al., NeurIPS 2024,
+    arXiv:2405.16247).
+
+    Distills each failure finding into a one-line rule. ``suggest()`` returns
+    one :class:`FixProposal` per finding whose ``suggestion_text`` holds the
+    rule. ``apply()`` appends accepted rules to a per-project Markdown manual
+    (``~/.agentdebug/manuals/<project>.md`` by default) which downstream
+    runs can prepend to their agent's system prompt to avoid re-hitting the
+    same failure.
+
+    Unlike :class:`ReflexionSuggestion` (short verbal hint per attempt) and
+    :class:`SelfRefineLoop` (heavy generator-critic-refiner per finding),
+    this is the LONG-TERM memory: small, append-only, surviving across runs.
+    Apply is opt-in because it writes to the filesystem.
+    """
+
+    id = 'auto_manual'
+
+    DEFAULT_MANUAL_DIR = '~/.agentdebug/manuals'
+
+    def __init__(
+        self,
+        *,
+        llm: Optional[object] = None,
+        manual_dir: Optional[str] = None,
+        project: str = 'default',
+        max_tokens: int = 256,
+    ) -> None:
+        # llm is optional — if absent, we synthesize a rule from the finding's
+        # suggestion template rather than calling out.
+        self.llm = llm
+        self.manual_dir = manual_dir or self.DEFAULT_MANUAL_DIR
+        self.project = project
+        self.max_tokens = max_tokens
+
+    def suggest(
+        self,
+        trajectory: AgentTrajectory,
+        report: DiagnosticReport,
+    ) -> List[FixProposal]:
+        if not report.findings:
+            return []
+        proposals: List[FixProposal] = []
+        for finding in report.findings:
+            rule = self._rule_for(trajectory, finding)
+            if not rule:
+                continue
+            proposals.append(FixProposal(
+                proposal_id=new_id('fix'),
+                recoverer_id=self.id,
+                target_event_id=finding.event_id,
+                summary=(
+                    f'Add rule to {self.project} manual: '
+                    f'"{rule[:80]}{"…" if len(rule) > 80 else ""}"'
+                ),
+                rationale=(
+                    'AutoManual (Chen et al., NeurIPS 2024): distill the '
+                    'failure into a one-line rule the next run reads via its '
+                    'system prompt. Long-term memory complements per-attempt '
+                    'Reflexion and per-finding Self-Refine.'
+                ),
+                confidence=max(0.4, min(0.9, finding.confidence)),
+                suggestion_text=rule,
+                side_effects=['manual.write'],
+                requires_human_approval=False,
+            ))
+        return proposals
+
+    def apply(self, proposal: FixProposal) -> str:
+        """Append the proposal's rule to the project manual; return the path."""
+        from pathlib import Path
+
+        target = Path(self.manual_dir).expanduser() / f'{self.project}.md'
+        target.parent.mkdir(parents=True, exist_ok=True)
+        existing = target.read_text(encoding='utf-8') if target.exists() else ''
+        if not existing:
+            header = f'# AgentDebugX learned manual — {self.project}\n\n'
+            existing = header + '<!-- auto-generated; safe to edit. -->\n\n'
+        # Idempotent: skip if the rule is already present (case-insensitive).
+        rule = proposal.suggestion_text.strip()
+        if rule.lower() in existing.lower():
+            return str(target)
+        target.write_text(
+            existing + f'- {rule}\n',
+            encoding='utf-8',
+        )
+        return str(target)
+
+    def _rule_for(
+        self,
+        trajectory: AgentTrajectory,
+        finding: FailureFinding,
+    ) -> Optional[str]:
+        # If no LLM, fall back to the finding's suggestion template.
+        if self.llm is None:
+            if finding.suggestion:
+                return str(finding.suggestion)
+            if finding.failure_mode.suggestion_templates:
+                return str(finding.failure_mode.suggestion_templates[0])
+            return None
+        prompt_system = (
+            'You distill failure findings into ONE-LINE actionable rules for '
+            'an agent to follow next time. Output plain text — a single '
+            'sentence under 200 characters. No JSON, no markdown, no '
+            'preamble. Start with an imperative verb ("Validate ...", '
+            '"Always ...", "Before ..."). Be specific to the failure.'
+        )
+        evidence = '; '.join(finding.evidence) or '(no evidence)'
+        prompt_user = (
+            f'Goal: {trajectory.goal!r}\n'
+            f'Failure mode: {finding.failure_mode.mode_id} '
+            f'({finding.failure_mode.name})\n'
+            f'Agent: {finding.agent_name} at step {finding.step_index}\n'
+            f'Evidence: {evidence}'
+        )
+        try:
+            result = self.llm.complete(  # type: ignore[attr-defined]
+                messages=[
+                    {'role': 'system', 'content': prompt_system},
+                    {'role': 'user', 'content': prompt_user},
+                ],
+                max_tokens=self.max_tokens,
+            )
+        except Exception:
+            return str(finding.suggestion) if finding.suggestion else None
+        text = getattr(result, 'text', '') or ''
+        rule = str(text).strip().splitlines()[0] if text.strip() else ''
+        if not rule:
+            return str(finding.suggestion) if finding.suggestion else None
+        return rule
+
+
 __all__ = [
+    'AutoManualRules',
     'CriticRecoverer',
     'DEFAULT_VERIFIERS',
     'FixProposal',
     'Recoverer',
     'ReflexionSuggestion',
+    'SelfRefineLoop',
     'VerifierSpec',
 ]