agentdebugx 0.2.2__tar.gz → 0.2.3__tar.gz

{agentdebugx-0.2.2 → agentdebugx-0.2.3}/PKG-INFO

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

{agentdebugx-0.2.2 → agentdebugx-0.2.3}/docs/23_status_v0_2.md

@@ -1,4 +1,4 @@
-# 23 — Capability + Test Coverage Status (v0.2.2)
+# 23 — Capability + Test Coverage Status (v0.2.3)
 
 A live audit of what's implemented, what's tested, and what's specced but
 not yet built. Pair this with [docs/15_roadmap.md](./15_roadmap.md), which is
@@ -20,7 +20,9 @@ the forward-looking plan; this doc is the rear-view mirror.
 | Attribution | `agentdebug.attribution.HeuristicAttributor` | ✅ stable | first-finding + tiebreak |
 | Attribution | `agentdebug.attribution.AllAtOnceAttributor` | ✅ stable | mocked LLM + fallback |
 | Attribution | `agentdebug.attribution.StepByStepAttributor` | ✅ **new 0.2.2** | scripted-LLM + fallback |
+| Attribution | `agentdebug.attribution.BinarySearchAttributor` | ✅ **new 0.2.3** | oracle-LLM logarithmic convergence + fallback + render elision |
 | 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 |
 | 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 |
@@ -45,13 +47,11 @@ across 32 source files.
 | [06_detectors.md](./06_detectors.md) | `trajectory_perplexity` (TrajAD) | needs token-level LM perplexity API or embedding model + baseline calibration | v0.3 |
 | [06_detectors.md](./06_detectors.md) | `topic_drift` (embedding cosine) | needs embedding client; consider reusing `OpenAICompatClient` `/embeddings` | v0.3 |
 | [06_detectors.md](./06_detectors.md) | LTL spec monitors | requires user-supplied spec or LLM-synthesized monitors; gated on RV research | v1.2 |
-| [07_attribution.md](./07_attribution.md) | `BinarySearchAttributor` (ddmin) | requires replayable environment; few frameworks expose it | v0.3 |
-| [07_attribution.md](./07_attribution.md) | `CounterfactualAttributor` | requires re-rolling agent actions; same replay constraint | v0.3 |
+| [07_attribution.md](./07_attribution.md) | `CounterfactualAttributor` | requires re-rolling agent actions; framework-replay dependent | v0.3 |
 | [07_attribution.md](./07_attribution.md) | `SBFLAttributor` (Tarantula/Ochiai) | needs corpus of passing + failing traces of same task; gated on Hub adoption | v0.4 |
 | [07_attribution.md](./07_attribution.md) | `DeltaDebugAttributor` (Zeller) | same replay constraint | v0.3 |
-| [07_attribution.md](./07_attribution.md) | `EnsembleAttributor` | trivial once 2+ heavy backends ship; awaits BinarySearch/Counterfactual | 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) | `CriticRecoverer` | needs a verifier registry (search, code-exec, type-check) | 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 |
@@ -97,10 +97,17 @@ remaining gaps are deliberate:
 
 Before v0.3 ships, this doc should record green checkmarks for:
 
-- [ ] One replayable counterfactual attributor (`BinarySearchAttributor` is
-      the cheapest entry).
-- [ ] One tool-grounded recovery strategy (`CriticRecoverer`) wired against
-      a `Verifier` Protocol.
+- [x] **Logarithmic-cost attributor** (`BinarySearchAttributor`) shipped in
+      0.2.3 — Who&When method 3, O(log N) LLM calls, bisects the trajectory
+      via prefix evaluation. **Note:** this is not yet a "replayable
+      counterfactual" attributor; it predicts whether the failure has
+      already occurred from the prefix without re-rolling the agent. True
+      counterfactual replay is still v0.3.
+- [x] **Tool-grounded recovery strategy** (`CriticRecoverer` + `VerifierSpec`
+      registry) shipped in 0.2.3 — pattern-matches failure modes against 5
+      default verifier templates (JSON-schema guard, final-state check,
+      tool-result type-check, handoff contract, loop-detector guard) and
+      emits per-finding `FixProposal` with rationale + suggested code.
 - [ ] One additional framework adapter that goes through the full conformance
       suite (CrewAI is the most-requested).
 - [ ] HuggingFace Hub round-trip live test (gated on `HF_TOKEN`).

{agentdebugx-0.2.2 → agentdebugx-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentdebugx"
-version = "0.2.2"
+version = "0.2.3"
 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.2 → agentdebugx-0.2.3}/src/agentdebug/__init__.py

@@ -13,6 +13,7 @@ from agentdebug.attribution import (
     AllAtOnceAttributor,
     AttributionResult,
     Attributor,
+    BinarySearchAttributor,
     Blame,
     HeuristicAttributor,
     StepByStepAttributor,
@@ -38,7 +39,14 @@ from agentdebug.models import (
     Modality,
 )
 from agentdebug.recorder import AgentDebug, TraceSession
-from agentdebug.recovery import FixProposal, Recoverer, ReflexionSuggestion
+from agentdebug.recovery import (
+    DEFAULT_VERIFIERS,
+    CriticRecoverer,
+    FixProposal,
+    Recoverer,
+    ReflexionSuggestion,
+    VerifierSpec,
+)
 from agentdebug.traceback import CascadeFrame, build_cascade, format_traceback
 from agentdebug.storage import JsonlTraceStore, SQLiteTraceStore
 from agentdebug.taxonomy import SEED_FAILURE_MODES, get_failure_mode
@@ -53,13 +61,17 @@ __all__ = [
     'Attributor',
     'Blame',
     'BusEvent',
+    'BinarySearchAttributor',
     'CascadeFrame',
+    'CriticRecoverer',
+    'DEFAULT_VERIFIERS',
     'Detector',
     'DetectorConfig',
     'RepeatedStateDetector',
     'RepeatedToolCallDetector',
     'StepByStepAttributor',
     'StepCountLimitDetector',
+    'VerifierSpec',
     'build_cascade',
     'default_detectors',
     'format_traceback',
@@ -84,4 +96,4 @@ __all__ = [
     'get_failure_mode',
 ]
 
-__version__ = '0.2.2'
+__version__ = '0.2.3'

{agentdebugx-0.2.2 → agentdebugx-0.2.3}/src/agentdebug/attribution.py

@@ -21,6 +21,10 @@ import logging
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Protocol, cast
 
+
+# Forward decl so BinarySearchAttributor.attribute can reference _EllipsisEvent
+# from the helper render path; defined later in the module.
+
 from agentdebug.llm import LLMClient, extract_json_block
 from agentdebug.models import AgentEvent, AgentTrajectory, FailureFinding, new_id
 
@@ -227,6 +231,27 @@ class AllAtOnceAttributor:
         return [str(value)]
 
 
+_BISECT_SYSTEM_PROMPT = """You are AgentDebugX-Attributor running the
+Who&When "Binary-Search" attribution method (arXiv:2505.00212). You will be
+shown a PREFIX of a failed agent trajectory truncated to its first N events.
+
+Decide whether the failure has ALREADY occurred within this prefix, i.e.,
+whether the trajectory is unrecoverable as of the last event shown.
+
+Respond ONLY with a JSON object (no prose, no markdown):
+
+{
+  "failure_already_happened": true | false,
+  "confidence": <float in [0,1]>,
+  "rationale": "<one or two sentences>",
+  "decisive_event_id": "<event_id or null>"
+}
+
+Be conservative: only return true when you can point to evidence in the
+prefix that the agent has already taken (or omitted) the decisive step.
+"""
+
+
 _STEP_SYSTEM_PROMPT = """You are AgentDebugX-Attributor, scanning a failed
 agent trajectory one step at a time (the Who&When "Step-by-Step" method,
 arXiv:2505.00212).
@@ -393,7 +418,153 @@ class StepByStepAttributor:
         return [str(value)]
 
 
+class BinarySearchAttributor:
+    """LLM-based attributor implementing Who&When's Binary-Search method.
+
+    Bisects the trajectory and asks the LLM whether the failure has already
+    occurred in each prefix. Costs O(log N) LLM calls vs StepByStep's O(N).
+
+    The contract:
+
+    * Pre-condition: the trajectory is known to have failed overall.
+    * Loop invariant: ``failure_already_happened`` is False at ``lo`` and
+      True at ``hi``. The decisive step lives in ``(lo, hi]``.
+    * Termination: ``hi - lo == 1``; ``hi - 1`` is the decisive index.
+
+    Returns the event at the decisive index as the primary Blame hypothesis.
+    Falls back to the configured ``fallback`` attributor when the trajectory
+    is empty or the LLM responses are uninterpretable.
+    """
+
+    id = 'binary_search'
+
+    def __init__(
+        self,
+        llm: LLMClient,
+        *,
+        fallback: Optional[Attributor] = None,
+        max_tokens: int = 1024,
+        context_window: int = 6,
+    ) -> None:
+        self.llm = llm
+        self.fallback: Attributor = fallback or HeuristicAttributor()
+        self.max_tokens = max_tokens
+        # When formatting a prefix into the LLM prompt we only keep this many
+        # events at the head + this many at the tail; the middle is elided.
+        # Keeps cost bounded for very long trajectories.
+        self.context_window = context_window
+
+    def attribute(
+        self,
+        trajectory: AgentTrajectory,
+        findings: List[FailureFinding],
+    ) -> AttributionResult:
+        n = len(trajectory.events)
+        if n == 0:
+            return self.fallback.attribute(trajectory, findings)
+        lo, hi = 0, n
+        probe_count = 0
+        # Sanity: cap probes at ceil(log2(n)) + 2 to bound cost in pathological cases.
+        import math
+        max_probes = max(1, int(math.ceil(math.log2(max(n, 2)))) + 2)
+        while hi - lo > 1 and probe_count < max_probes:
+            mid = (lo + hi) // 2
+            probe_count += 1
+            verdict = self._probe(trajectory, mid)
+            if verdict is None:
+                # Uninterpretable response: fall back rather than guess.
+                return self.fallback.attribute(trajectory, findings)
+            already = bool(verdict.get('failure_already_happened'))
+            if already:
+                hi = mid
+            else:
+                lo = mid
+        decisive_index = hi - 1
+        decisive = trajectory.events[decisive_index]
+        return AttributionResult(
+            method=self.id,
+            hypotheses=[Blame(
+                span_id=decisive.event_id,
+                step_index=decisive.step_index,
+                agent_name=decisive.agent_name,
+                confidence=0.6 + 0.1 * min(probe_count, 4),
+                rationale=(
+                    f'Binary search located the decisive step within '
+                    f'{probe_count} probes over {n} events.'
+                ),
+                evidence=[
+                    f'event_id={decisive.event_id}',
+                    f'step={decisive.step_index}',
+                ],
+                sources=[self.id],
+            )],
+            raw={'probe_count': probe_count, 'trajectory_len': n},
+        )
+
+    def _probe(
+        self, trajectory: AgentTrajectory, prefix_len: int
+    ) -> Optional[Dict[str, Any]]:
+        prefix = trajectory.prefix(prefix_len)
+        # Render prefix with head + tail elision so long prefixes stay cheap.
+        events_doc = self._render_prefix(prefix)
+        user = (
+            f'GOAL: {trajectory.goal!r}\n'
+            f'FRAMEWORK: {trajectory.framework!r}\n\n'
+            f'PREFIX (events 1..{prefix_len} of {len(trajectory.events)}):\n'
+            f'{events_doc}'
+        )
+        try:
+            result = self.llm.complete(
+                messages=[
+                    {'role': 'system', 'content': _BISECT_SYSTEM_PROMPT},
+                    {'role': 'user', 'content': user},
+                ],
+                max_tokens=self.max_tokens,
+            )
+        except Exception as exc:  # pragma: no cover
+            LOG.warning('binary_search probe at prefix_len=%s failed: %s',
+                        prefix_len, exc)
+            return None
+        parsed = extract_json_block(result.text)
+        if parsed is None:
+            return None
+        return cast(Dict[str, Any], parsed)
+
+    def _render_prefix(self, prefix: AgentTrajectory) -> str:
+        events = prefix.events
+        if len(events) <= 2 * self.context_window:
+            view = events
+        else:
+            head = events[: self.context_window]
+            tail = events[-self.context_window:]
+            elided = len(events) - 2 * self.context_window
+            view = head + [_EVENT_ELLIPSIS(elided)] + tail
+        return '\n'.join(self._render_event(e) for e in view)
+
+    @staticmethod
+    def _render_event(event: Any) -> str:
+        if isinstance(event, _EllipsisEvent):
+            return f'... ({event.count} events elided) ...'
+        return (
+            f'event_id={event.event_id} step={event.step_index} '
+            f'agent={event.agent_name} '
+            f'type={getattr(event.event_type, "value", event.event_type)} '
+            f'output={str(event.output)[:200]} '
+            f'error={str(event.error)[:200]}'
+        )
+
+
+@dataclass
+class _EllipsisEvent:
+    count: int
+
+
+def _EVENT_ELLIPSIS(count: int) -> _EllipsisEvent:
+    return _EllipsisEvent(count=count)
+
+
 __all__ = [
     'Attributor', 'Blame', 'AttributionResult',
     'HeuristicAttributor', 'AllAtOnceAttributor', 'StepByStepAttributor',
+    'BinarySearchAttributor',
 ]

{agentdebugx-0.2.2 → agentdebugx-0.2.3}/src/agentdebug/models.py

@@ -102,6 +102,18 @@ class AgentTrajectory(BaseModel):
         self.events.append(event)
         return event
 
+    def prefix(self, n: int) -> 'AgentTrajectory':
+        """Return a copy keeping only the first ``n`` events.
+
+        Used by replay/attribution backends (Binary-Search, Delta-Debugging)
+        that need to ask "would the trajectory still fail if it had stopped
+        at step k?" The returned object is a SHALLOW copy of the events list
+        but a fresh AgentTrajectory; mutating it does not touch the original.
+        """
+        truncated = self.model_copy(deep=False) if hasattr(self, 'model_copy') else self.copy(deep=False)
+        truncated.events = list(self.events[:max(0, n)])
+        return truncated
+
 
 class FailureMode(BaseModel):
     """A seed or generated taxonomy node."""

agentdebugx-0.2.3/src/agentdebug/recovery.py

@@ -0,0 +1,314 @@
+"""Lightweight recovery suggestions.
+
+v0.1 ships ``ReflexionSuggestion`` — a *suggest-only* recovery generator that
+produces a structured retry-prompt artifact based on Reflexion (Shinn et al.,
+NeurIPS 2023, arXiv:2303.11366). Heavier strategies (Self-Refine loop, CRITIC,
+Saga rollback, MCTS) are deferred per the roadmap and will land behind the same
+:class:`Recoverer` protocol.
+
+By design, **nothing here re-executes the agent** — recovery proposals are
+artifacts to be surfaced (CLI/UI/PR comment) or fed back into the next run.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Protocol, Tuple
+
+from agentdebug.models import (
+    AgentTrajectory,
+    DiagnosticReport,
+    FailureFinding,
+    new_id,
+)
+
+
+@dataclass
+class FixProposal:
+    proposal_id: str
+    recoverer_id: str
+    target_event_id: Optional[str]
+    summary: str
+    rationale: str
+    confidence: float
+    suggestion_text: str
+    side_effects: List[str] = field(default_factory=list)
+    requires_human_approval: bool = False
+
+
+class Recoverer(Protocol):
+    id: str
+
+    def suggest(
+        self,
+        trajectory: AgentTrajectory,
+        report: DiagnosticReport,
+    ) -> List[FixProposal]:
+        ...
+
+
+class ReflexionSuggestion:
+    """Emit a Reflexion-style retry reflection per finding.
+
+    The output is purely textual — it can be appended to the agent's next
+    system prompt, written to a project ``MANUAL.md``, or surfaced in the
+    Console. There is no auto-apply.
+    """
+
+    id = 'reflexion'
+
+    def suggest(
+        self,
+        trajectory: AgentTrajectory,
+        report: DiagnosticReport,
+    ) -> List[FixProposal]:
+        if not report.findings:
+            return []
+        proposals: List[FixProposal] = []
+        for finding in report.findings:
+            proposals.append(self._build_proposal(trajectory, finding))
+        return proposals
+
+    def _build_proposal(
+        self, trajectory: AgentTrajectory, finding: FailureFinding
+    ) -> FixProposal:
+        goal = trajectory.goal or '(no goal recorded)'
+        framework = trajectory.framework or '(framework not declared)'
+        evidence_block = '\n'.join(f'  - {e}' for e in finding.evidence) or '  (none)'
+        suggestion_template = (
+            finding.suggestion
+            or (finding.failure_mode.suggestion_templates[0]
+                if finding.failure_mode.suggestion_templates
+                else 'Inspect the offending step and constrain the agent at that point.')
+        )
+        reflection = (
+            f'Task: {goal}\n'
+            f'Framework: {framework}\n'
+            f'Observed failure mode: {finding.failure_mode.mode_id} '
+            f'({finding.failure_mode.name})\n'
+            f'Located at agent={finding.agent_name}, step={finding.step_index}, '
+            f'event_id={finding.event_id}\n'
+            f'Evidence:\n{evidence_block}\n'
+            f'Next time, do the following:\n  {suggestion_template}\n'
+        )
+        return FixProposal(
+            proposal_id=new_id('fix'),
+            recoverer_id=self.id,
+            target_event_id=finding.event_id,
+            summary=(
+                f'Reflexion retry hint for {finding.failure_mode.mode_id} '
+                f'at step {finding.step_index}'
+            ),
+            rationale=(
+                'Reflexion (Shinn et al., NeurIPS 2023) converts a failure '
+                'into a verbal hint appended to next attempt.'
+            ),
+            confidence=min(0.9, max(0.1, finding.confidence)),
+            suggestion_text=reflection,
+            side_effects=['memory.write'],
+            requires_human_approval=False,
+        )
+
+
+@dataclass(frozen=True)
+class VerifierSpec:
+    """A pattern describing a tool-grounded verifier that could have caught
+    a particular family of failures.
+
+    Used by :class:`CriticRecoverer` to recommend (not run) the addition of
+    a verifier between the failing step and the next side-effect.
+    """
+
+    id: str
+    description: str
+    matches_families: tuple[str, ...]      # e.g. ('action',)
+    matches_mode_prefixes: tuple[str, ...]  # e.g. ('action.format_error', 'action.parameter_error')
+    suggested_code: str                      # short snippet showing how to add the guard
+    rationale: str
+
+    def matches(self, finding: 'FailureFinding') -> bool:
+        if finding.failure_mode.family in self.matches_families:
+            return True
+        return any(
+            finding.failure_mode.mode_id.startswith(p)
+            for p in self.matches_mode_prefixes
+        )
+
+
+DEFAULT_VERIFIERS: List[VerifierSpec] = [
+    VerifierSpec(
+        id='json_schema_guard',
+        description='Validate tool arguments against the tool JSON schema before execution.',
+        matches_families=('action',),
+        matches_mode_prefixes=('action.format_error', 'action.parameter_error'),
+        suggested_code=(
+            'from jsonschema import validate, ValidationError\n'
+            'try:\n'
+            '    validate(instance=tool_args, schema=tool.schema)\n'
+            'except ValidationError as exc:\n'
+            '    return handle_arg_error(exc, tool=tool, args=tool_args)\n'
+        ),
+        rationale=(
+            'CRITIC (Gou et al., ICLR 2024): a tool-interactive verifier '
+            'catches malformed/missing-argument failures before they hit '
+            'the downstream API.'
+        ),
+    ),
+    VerifierSpec(
+        id='final_state_check',
+        description='Independent final-state verifier confirms the task is satisfied before terminating.',
+        matches_families=('verification', 'reflection'),
+        matches_mode_prefixes=('verification.', 'reflection.progress_misjudge'),
+        suggested_code=(
+            'def verify_task_complete(goal: str, final_state: dict) -> bool:\n'
+            '    # Check every explicit success criterion; do NOT trust the\n'
+            '    # acting agent\'s self-report.\n'
+            '    return all(criterion(final_state) for criterion in success_criteria(goal))\n'
+            '\n'
+            'if not verify_task_complete(goal, state):\n'
+            '    trigger_recovery_planning(reason="task not verified complete")\n'
+        ),
+        rationale=(
+            'MAST (Cemri et al., 2025) shows premature termination + missing '
+            'task validation are dominant multi-agent failure modes. A '
+            'verifier that does not trust the acting agent is the standard '
+            'fix.'
+        ),
+    ),
+    VerifierSpec(
+        id='tool_result_typecheck',
+        description='Type-check the tool result and require explicit handling of None / empty.',
+        matches_families=('action', 'system'),
+        matches_mode_prefixes=('action.wrong_tool', 'system.tool_execution_error'),
+        suggested_code=(
+            'result = tool.run(args)\n'
+            'if result is None or result == {}:\n'
+            '    return handle_empty_result(tool=tool, args=args)\n'
+            'if not isinstance(result, tool.expected_return_type):\n'
+            '    return handle_unexpected_type(result, tool=tool)\n'
+        ),
+        rationale=(
+            'Tool outputs that the agent does not branch on (None, empty '
+            'list, unexpected type) propagate as "agent hallucinated a '
+            'fact" downstream. Force the agent to handle them at the call '
+            'site.'
+        ),
+    ),
+    VerifierSpec(
+        id='handoff_context_contract',
+        description='Require the receiving agent to restate critical constraints before proceeding.',
+        matches_families=('multiagent',),
+        matches_mode_prefixes=('multiagent.handoff_loss',),
+        suggested_code=(
+            'def handoff(payload: HandoffPayload, to_agent: Agent) -> None:\n'
+            '    received = to_agent.read(payload)\n'
+            '    if not received.restates(payload.constraints):\n'
+            '        raise HandoffContractError(\n'
+            '            "receiver did not restate constraints"\n'
+            '        )\n'
+        ),
+        rationale=(
+            'Who&When (Zhang et al., 2025): handoff context loss is the '
+            'most common decisive multi-agent failure step. Typed handoff '
+            'payloads + receiver restating prevent silent dropping.'
+        ),
+    ),
+    VerifierSpec(
+        id='loop_detector_guard',
+        description='Detect repeated tool calls / no-progress windows and trigger replan.',
+        matches_families=('planning',),
+        matches_mode_prefixes=('planning.inefficient_plan',),
+        suggested_code=(
+            'from agentdebug.detectors import RepeatedToolCallDetector\n'
+            'detector = RepeatedToolCallDetector(threshold=3)\n'
+            'if detector.detect(current_trajectory):\n'
+            '    return replan(reason="loop detected")\n'
+        ),
+        rationale=(
+            'Loops are the canonical inefficient-plan failure. AgentDebugX '
+            'ships an in-process detector you can call between steps.'
+        ),
+    ),
+]
+
+
+class CriticRecoverer:
+    """Tool-grounded recovery suggestions modeled on CRITIC (arXiv:2305.11738).
+
+    Unlike the paper's CRITIC loop (which re-runs the agent against a
+    verifier until pass), this recoverer is suggest-only: for each finding
+    it matches the failure mode against a registry of :class:`VerifierSpec`
+    templates and emits a :class:`FixProposal` with the suggested verifier
+    code + rationale. The user decides whether to add the verifier.
+
+    Pair with :class:`ReflexionSuggestion` for full coverage: Reflexion
+    tells the agent what went wrong; CriticRecoverer tells the developer
+    what guard to add.
+    """
+
+    id = 'critic'
+
+    def __init__(
+        self,
+        verifiers: Optional[List[VerifierSpec]] = None,
+    ) -> None:
+        self.verifiers = list(verifiers) if verifiers is not None else list(DEFAULT_VERIFIERS)
+
+    def suggest(
+        self,
+        trajectory: AgentTrajectory,
+        report: DiagnosticReport,
+    ) -> List[FixProposal]:
+        if not report.findings:
+            return []
+        proposals: List[FixProposal] = []
+        seen: set[tuple[str, str]] = set()  # (event_id, verifier_id)
+        for finding in report.findings:
+            for verifier in self.verifiers:
+                if not verifier.matches(finding):
+                    continue
+                key = (finding.event_id or '', verifier.id)
+                if key in seen:
+                    continue
+                seen.add(key)
+                proposals.append(self._build(finding, verifier))
+        return proposals
+
+    def _build(
+        self, finding: FailureFinding, verifier: VerifierSpec,
+    ) -> FixProposal:
+        summary = (
+            f'Add {verifier.id} before {finding.failure_mode.mode_id} '
+            f'(step {finding.step_index}, agent {finding.agent_name})'
+        )
+        text = (
+            f'Failure: {finding.failure_mode.mode_id} '
+            f'({finding.failure_mode.name})\n'
+            f'Located at agent={finding.agent_name}, step={finding.step_index}, '
+            f'event_id={finding.event_id}\n\n'
+            f'Recommended verifier: {verifier.id}\n'
+            f'Rationale: {verifier.rationale}\n\n'
+            f'Suggested code:\n'
+            f'```python\n{verifier.suggested_code}\n```\n'
+        )
+        return FixProposal(
+            proposal_id=new_id('fix'),
+            recoverer_id=self.id,
+            target_event_id=finding.event_id,
+            summary=summary,
+            rationale=verifier.rationale,
+            confidence=max(0.3, min(0.85, finding.confidence)),
+            suggestion_text=text,
+            side_effects=[],
+            requires_human_approval=False,
+        )
+
+
+__all__ = [
+    'CriticRecoverer',
+    'DEFAULT_VERIFIERS',
+    'FixProposal',
+    'Recoverer',
+    'ReflexionSuggestion',
+    'VerifierSpec',
+]

agentdebugx-0.2.2/src/agentdebug/recovery.py

@@ -1,113 +0,0 @@
-"""Lightweight recovery suggestions.
-
-v0.1 ships ``ReflexionSuggestion`` — a *suggest-only* recovery generator that
-produces a structured retry-prompt artifact based on Reflexion (Shinn et al.,
-NeurIPS 2023, arXiv:2303.11366). Heavier strategies (Self-Refine loop, CRITIC,
-Saga rollback, MCTS) are deferred per the roadmap and will land behind the same
-:class:`Recoverer` protocol.
-
-By design, **nothing here re-executes the agent** — recovery proposals are
-artifacts to be surfaced (CLI/UI/PR comment) or fed back into the next run.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import List, Optional, Protocol
-
-from agentdebug.models import (
-    AgentTrajectory,
-    DiagnosticReport,
-    FailureFinding,
-    new_id,
-)
-
-
-@dataclass
-class FixProposal:
-    proposal_id: str
-    recoverer_id: str
-    target_event_id: Optional[str]
-    summary: str
-    rationale: str
-    confidence: float
-    suggestion_text: str
-    side_effects: List[str] = field(default_factory=list)
-    requires_human_approval: bool = False
-
-
-class Recoverer(Protocol):
-    id: str
-
-    def suggest(
-        self,
-        trajectory: AgentTrajectory,
-        report: DiagnosticReport,
-    ) -> List[FixProposal]:
-        ...
-
-
-class ReflexionSuggestion:
-    """Emit a Reflexion-style retry reflection per finding.
-
-    The output is purely textual — it can be appended to the agent's next
-    system prompt, written to a project ``MANUAL.md``, or surfaced in the
-    Console. There is no auto-apply.
-    """
-
-    id = 'reflexion'
-
-    def suggest(
-        self,
-        trajectory: AgentTrajectory,
-        report: DiagnosticReport,
-    ) -> List[FixProposal]:
-        if not report.findings:
-            return []
-        proposals: List[FixProposal] = []
-        for finding in report.findings:
-            proposals.append(self._build_proposal(trajectory, finding))
-        return proposals
-
-    def _build_proposal(
-        self, trajectory: AgentTrajectory, finding: FailureFinding
-    ) -> FixProposal:
-        goal = trajectory.goal or '(no goal recorded)'
-        framework = trajectory.framework or '(framework not declared)'
-        evidence_block = '\n'.join(f'  - {e}' for e in finding.evidence) or '  (none)'
-        suggestion_template = (
-            finding.suggestion
-            or (finding.failure_mode.suggestion_templates[0]
-                if finding.failure_mode.suggestion_templates
-                else 'Inspect the offending step and constrain the agent at that point.')
-        )
-        reflection = (
-            f'Task: {goal}\n'
-            f'Framework: {framework}\n'
-            f'Observed failure mode: {finding.failure_mode.mode_id} '
-            f'({finding.failure_mode.name})\n'
-            f'Located at agent={finding.agent_name}, step={finding.step_index}, '
-            f'event_id={finding.event_id}\n'
-            f'Evidence:\n{evidence_block}\n'
-            f'Next time, do the following:\n  {suggestion_template}\n'
-        )
-        return FixProposal(
-            proposal_id=new_id('fix'),
-            recoverer_id=self.id,
-            target_event_id=finding.event_id,
-            summary=(
-                f'Reflexion retry hint for {finding.failure_mode.mode_id} '
-                f'at step {finding.step_index}'
-            ),
-            rationale=(
-                'Reflexion (Shinn et al., NeurIPS 2023) converts a failure '
-                'into a verbal hint appended to next attempt.'
-            ),
-            confidence=min(0.9, max(0.1, finding.confidence)),
-            suggestion_text=reflection,
-            side_effects=['memory.write'],
-            requires_human_approval=False,
-        )
-
-
-__all__ = ['Recoverer', 'FixProposal', 'ReflexionSuggestion']