agentdebugx 0.1.0__py3-none-any.whl

agentdebug/__init__.py

@@ -0,0 +1,65 @@
+"""AgentDebugX public API.
+
+The package is intentionally imported as ``agentdebug`` so existing and future
+agent systems can add debugging with a small surface area. The PyPI
+distribution is named ``agentdebugx``.
+
+See ``docs/14_api_reference.md`` for the full public surface and
+``docs/18_comparison_codex_vs_design.md`` for the merged v0.1 scope.
+"""
+
+from agentdebug.analyzers import HeuristicAnalyzer
+from agentdebug.attribution import (
+    AllAtOnceAttributor,
+    AttributionResult,
+    Attributor,
+    Blame,
+    HeuristicAttributor,
+)
+from agentdebug.events import DEFAULT_BUS, BusEvent, EventBus, EventSubscription
+from agentdebug.models import (
+    AgentEvent,
+    AgentTrajectory,
+    Artifact,
+    DiagnosticReport,
+    EventType,
+    FailureFinding,
+    FailureMode,
+    Modality,
+)
+from agentdebug.recorder import AgentDebug, TraceSession
+from agentdebug.recovery import FixProposal, Recoverer, ReflexionSuggestion
+from agentdebug.storage import JsonlTraceStore, SQLiteTraceStore
+from agentdebug.taxonomy import SEED_FAILURE_MODES, get_failure_mode
+
+__all__ = [
+    'AgentDebug',
+    'AgentEvent',
+    'AgentTrajectory',
+    'AllAtOnceAttributor',
+    'Artifact',
+    'AttributionResult',
+    'Attributor',
+    'Blame',
+    'BusEvent',
+    'DEFAULT_BUS',
+    'DiagnosticReport',
+    'EventBus',
+    'EventSubscription',
+    'EventType',
+    'FailureFinding',
+    'FailureMode',
+    'FixProposal',
+    'HeuristicAnalyzer',
+    'HeuristicAttributor',
+    'JsonlTraceStore',
+    'Modality',
+    'Recoverer',
+    'ReflexionSuggestion',
+    'SEED_FAILURE_MODES',
+    'SQLiteTraceStore',
+    'TraceSession',
+    'get_failure_mode',
+]
+
+__version__ = '0.1.0'

agentdebug/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""Framework adapters.
+
+The base Protocol and status dataclass are always available. Concrete
+adapters live in sibling modules and are imported lazily by name so that
+``import agentdebug.adapters`` never pulls in optional framework deps.
+"""
+
+from agentdebug.adapters.base import AdapterStatus, FrameworkAdapter
+
+__all__ = ['AdapterStatus', 'FrameworkAdapter']

agentdebug/adapters/base.py

@@ -0,0 +1,22 @@
+"""Adapter interfaces for agent frameworks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from agentdebug.recorder import AgentDebug
+
+
+@dataclass(frozen=True)
+class AdapterStatus:
+    framework: str
+    implemented: bool
+    notes: str
+
+
+class FrameworkAdapter(Protocol):
+    framework: str
+
+    def instrument(self, debugger: AgentDebug) -> AdapterStatus:
+        ...

agentdebug/adapters/langgraph.py

@@ -0,0 +1,261 @@
+"""LangChain / LangGraph adapter.
+
+Provides ``LangChainCallbackAdapter``, a ``BaseCallbackHandler`` subclass that
+records LangChain/LangGraph events into an AgentDebugX trajectory.
+
+We *defer* the import of ``langchain_core`` so importing this module never fails
+when LangChain is not installed. Users see a clear error only if they actually
+construct the adapter without LangChain installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, cast
+
+from agentdebug.adapters.base import AdapterStatus, FrameworkAdapter
+from agentdebug.models import AgentTrajectory, EventType
+from agentdebug.recorder import AgentDebug
+
+
+def _load_base_callback_handler() -> type:
+    try:
+        from langchain_core.callbacks import BaseCallbackHandler
+    except ImportError as exc:  # pragma: no cover - exercised in docs
+        raise ImportError(
+            'LangChainCallbackAdapter requires `langchain_core`. '
+            'Install with `pip install langchain-core`.'
+        ) from exc
+    return cast(type, BaseCallbackHandler)
+
+
+class LangChainCallbackAdapter:
+    """Bridge LangChain/LangGraph callbacks into an AgentDebugX trajectory.
+
+    Usage:
+
+    >>> from agentdebug import AgentDebug
+    >>> from agentdebug.adapters.langgraph import LangChainCallbackAdapter
+    >>> debugger = AgentDebug()
+    >>> trajectory = debugger.start_trace(goal='...', framework='langgraph')
+    >>> handler = LangChainCallbackAdapter(debugger, trajectory)
+    >>> graph.invoke(state, config={'callbacks': [handler]})
+    >>> debugger.finish_trace(trajectory, success=True)
+    """
+
+    framework = 'langgraph'
+
+    def __new__(cls, debugger: AgentDebug, trajectory: AgentTrajectory) -> Any:
+        base = _load_base_callback_handler()
+        # Dynamically build a subclass of BaseCallbackHandler whose hooks call
+        # our recording functions. We keep the implementation here to avoid a
+        # module-level dependency on langchain_core.
+        impl = type(
+            '_LangChainAdapterImpl',
+            (base,),
+            {
+                'on_chain_start': cls._on_chain_start,
+                'on_chain_end': cls._on_chain_end,
+                'on_chain_error': cls._on_chain_error,
+                'on_tool_start': cls._on_tool_start,
+                'on_tool_end': cls._on_tool_end,
+                'on_tool_error': cls._on_tool_error,
+                'on_llm_start': cls._on_llm_start,
+                'on_llm_end': cls._on_llm_end,
+                'on_llm_error': cls._on_llm_error,
+                'on_agent_action': cls._on_agent_action,
+                'on_agent_finish': cls._on_agent_finish,
+                '_step_counter': 0,
+            },
+        )
+        inst = impl()
+        inst._debugger = debugger
+        inst._trajectory = trajectory
+        return inst
+
+    # ------------- hook implementations -------------
+
+    @staticmethod
+    def _next_step(handler: Any) -> int:
+        handler._step_counter += 1
+        return int(handler._step_counter)
+
+    @staticmethod
+    def _record(
+        handler: Any,
+        *,
+        event_type: EventType,
+        agent_name: str,
+        module: Optional[str],
+        input: Any = None,
+        output: Any = None,
+        error: Optional[str] = None,
+        parent_event_id: Optional[str] = None,
+        run_id: Optional[Any] = None,
+        **metadata: Any,
+    ) -> None:
+        meta: Dict[str, Any] = dict(metadata)
+        if run_id is not None:
+            meta['run_id'] = str(run_id)
+        handler._debugger.record_event(
+            handler._trajectory,
+            event_type=event_type,
+            agent_name=agent_name,
+            module=module,
+            step_index=LangChainCallbackAdapter._next_step(handler),
+            input=input,
+            output=output,
+            error=error,
+            parent_event_id=parent_event_id,
+            **meta,
+        )
+
+    # The keyword arguments accepted by these methods match the signature of
+    # BaseCallbackHandler; we use **kwargs for compatibility across LangChain
+    # versions which add or rename fields.
+
+    def _on_chain_start(  # type: ignore[no-untyped-def]
+        self, serialized, inputs, *, run_id, parent_run_id=None, **kwargs
+    ):
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.AGENT_STEP,
+            agent_name=str(((serialized or {}).get('name')) or 'chain'),
+            module='planning',
+            input=inputs,
+            run_id=run_id,
+            parent_run_id=str(parent_run_id) if parent_run_id else None,
+        )
+
+    def _on_chain_end(self, outputs, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.OBSERVATION,
+            agent_name='chain',
+            module='planning',
+            output=outputs,
+            run_id=run_id,
+        )
+
+    def _on_chain_error(self, error, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.ERROR,
+            agent_name='chain',
+            module='system',
+            error=str(error),
+            run_id=run_id,
+        )
+
+    def _on_tool_start(  # type: ignore[no-untyped-def]
+        self, serialized, input_str, *, run_id, **kwargs
+    ):
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.TOOL_CALL,
+            agent_name=str(((serialized or {}).get('name')) or 'tool'),
+            module='action',
+            input=input_str,
+            run_id=run_id,
+        )
+
+    def _on_tool_end(self, output, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.TOOL_RESULT,
+            agent_name='tool',
+            module='action',
+            output=output,
+            run_id=run_id,
+        )
+
+    def _on_tool_error(self, error, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.TOOL_RESULT,
+            agent_name='tool',
+            module='action',
+            error=str(error),
+            run_id=run_id,
+        )
+
+    def _on_llm_start(  # type: ignore[no-untyped-def]
+        self, serialized, prompts, *, run_id, **kwargs
+    ):
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.LLM_CALL,
+            agent_name=str(((serialized or {}).get('name')) or 'llm'),
+            module='planning',
+            input=prompts,
+            run_id=run_id,
+        )
+
+    def _on_llm_end(self, response, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.LLM_RESPONSE,
+            agent_name='llm',
+            module='planning',
+            output=str(response)[:1000],
+            run_id=run_id,
+        )
+
+    def _on_llm_error(self, error, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.ERROR,
+            agent_name='llm',
+            module='system',
+            error=str(error),
+            run_id=run_id,
+        )
+
+    def _on_agent_action(self, action, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.PLAN,
+            agent_name='agent',
+            module='planning',
+            output=str(action)[:1000],
+            run_id=run_id,
+        )
+
+    def _on_agent_finish(self, finish, *, run_id, **kwargs):  # type: ignore[no-untyped-def]
+        LangChainCallbackAdapter._record(
+            self,
+            event_type=EventType.OBSERVATION,
+            agent_name='agent',
+            module='planning',
+            output=str(finish)[:1000],
+            run_id=run_id,
+        )
+
+
+class LangGraphAdapter:
+    """LangGraph adapter, structural :class:`FrameworkAdapter` (Protocol)."""
+
+    framework = 'langgraph'
+
+    def instrument(self, debugger: AgentDebug) -> AdapterStatus:  # noqa: D401
+        try:
+            _load_base_callback_handler()
+        except ImportError as exc:
+            return AdapterStatus(
+                framework=self.framework,
+                implemented=False,
+                notes=str(exc),
+            )
+        return AdapterStatus(
+            framework=self.framework,
+            implemented=True,
+            notes=(
+                'Create a trajectory, then pass '
+                '`LangChainCallbackAdapter(debugger, trajectory)` in '
+                "config={'callbacks': [handler]} when invoking your graph."
+            ),
+        )
+
+
+_: FrameworkAdapter = LangGraphAdapter()  # static structural check
+
+__all__ = ['LangChainCallbackAdapter', 'LangGraphAdapter']

agentdebug/adapters/otel.py

@@ -0,0 +1,151 @@
+"""Optional OpenTelemetry GenAI export shim.
+
+Translates an :class:`AgentTrajectory` into OTel spans following the GenAI
+semantic conventions (``gen_ai.*`` attributes). Best-effort: the entire module
+is a no-op when ``opentelemetry-api`` is not installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from agentdebug.adapters.base import AdapterStatus, FrameworkAdapter
+from agentdebug.models import AgentEvent, AgentTrajectory, EventType
+from agentdebug.recorder import AgentDebug
+
+
+def _otel_available() -> bool:
+    try:
+        import opentelemetry  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+_EVENT_TO_OP: Dict[EventType, str] = {
+    EventType.LLM_CALL: 'chat',
+    EventType.LLM_RESPONSE: 'chat',
+    EventType.TOOL_CALL: 'execute_tool',
+    EventType.TOOL_RESULT: 'execute_tool',
+    EventType.AGENT_STEP: 'invoke_agent',
+    EventType.PLAN: 'invoke_agent',
+    EventType.REFLECTION: 'invoke_agent',
+    EventType.HANDOFF: 'handoff',
+    EventType.MEMORY_READ: 'retrieve_context',
+    EventType.MEMORY_WRITE: 'retrieve_context',
+    EventType.RUN_START: 'invoke_workflow',
+    EventType.RUN_END: 'invoke_workflow',
+    EventType.OBSERVATION: 'invoke_agent',
+    EventType.ERROR: 'invoke_agent',
+    EventType.GUARDRAIL: 'invoke_agent',
+    EventType.HUMAN_FEEDBACK: 'invoke_agent',
+}
+
+
+def export_trajectory(
+    trajectory: AgentTrajectory,
+    *,
+    tracer_name: str = 'agentdebug',
+    tracer_provider: Optional[Any] = None,
+) -> int:
+    """Emit OTel spans for a finished trajectory. Returns the number of spans emitted.
+
+    Returns 0 (and emits nothing) when OpenTelemetry is not installed.
+    """
+    if not _otel_available():
+        return 0
+    from opentelemetry import trace as ot_trace
+
+    tracer = (tracer_provider or ot_trace.get_tracer_provider()).get_tracer(tracer_name)
+    emitted = 0
+    with tracer.start_as_current_span(
+        f'agentdebug.run/{trajectory.framework or "unknown"}',
+        attributes=_root_attributes(trajectory),
+    ) as root:
+        _set_attr(root, 'agentdebug.trace_id', trajectory.trace_id)
+        for event in trajectory.events:
+            _emit_event_span(tracer, event)
+            emitted += 1
+    return emitted
+
+
+def _emit_event_span(tracer: Any, event: AgentEvent) -> None:
+    op = _EVENT_TO_OP.get(event.event_type, 'invoke_agent')
+    with tracer.start_as_current_span(
+        f'agentdebug.event/{_event_type_value(event.event_type)}',
+        attributes=_event_attributes(event, op),
+    ) as span:
+        if event.error:
+            _set_attr(span, 'error.message', str(event.error))
+
+
+def _root_attributes(trajectory: AgentTrajectory) -> Dict[str, Any]:
+    attrs: Dict[str, Any] = {
+        'gen_ai.operation.name': 'invoke_workflow',
+        'agentdebug.trace_id': trajectory.trace_id,
+        'agentdebug.framework': trajectory.framework or '',
+    }
+    if trajectory.goal:
+        attrs['agentdebug.goal'] = trajectory.goal
+    if trajectory.task_id:
+        attrs['agentdebug.task_id'] = trajectory.task_id
+    return attrs
+
+
+def _event_attributes(event: AgentEvent, op: str) -> Dict[str, Any]:
+    attrs: Dict[str, Any] = {
+        'gen_ai.operation.name': op,
+        'agentdebug.event_id': event.event_id,
+        'agentdebug.event_type': _event_type_value(event.event_type),
+        'agentdebug.agent.name': event.agent_name,
+    }
+    if event.module is not None:
+        attrs['agentdebug.module'] = event.module
+    if event.step_index is not None:
+        attrs['agentdebug.step_index'] = event.step_index
+    if event.duration_ms is not None:
+        attrs['agentdebug.duration_ms'] = event.duration_ms
+    if event.error:
+        attrs['error.type'] = 'AgentEventError'
+    return attrs
+
+
+def _set_attr(span: Any, key: str, value: Any) -> None:
+    setter = getattr(span, 'set_attribute', None)
+    if callable(setter):
+        setter(key, value)
+
+
+def _event_type_value(event_type: EventType) -> str:
+    value = getattr(event_type, 'value', event_type)
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+class OTelExportAdapter:
+    """OTel export adapter, structural :class:`FrameworkAdapter` (not subclassed)."""
+
+    framework = 'otel'
+
+    def instrument(self, debugger: AgentDebug) -> AdapterStatus:  # noqa: D401
+        if _otel_available():
+            return AdapterStatus(
+                framework=self.framework,
+                implemented=True,
+                notes=(
+                    'OpenTelemetry detected. Call '
+                    'agentdebug.adapters.otel.export_trajectory(trajectory) '
+                    'to emit gen_ai.* spans.'
+                ),
+            )
+        return AdapterStatus(
+            framework=self.framework,
+            implemented=False,
+            notes='Install `opentelemetry-api` and `opentelemetry-sdk` to enable.',
+        )
+
+
+_: FrameworkAdapter = OTelExportAdapter()  # static structural check
+
+__all__ = ['OTelExportAdapter', 'export_trajectory']

agentdebug/adapters/raw.py

@@ -0,0 +1,134 @@
+"""Adapter for raw / vanilla ReAct loops.
+
+For users who write a ``while not done: ...`` loop against the OpenAI or
+Anthropic SDK directly (no framework), this adapter exposes:
+
+* :func:`trace_loop` — decorator that wraps a function in a :class:`TraceSession`
+  and exposes the active session via :func:`current_session`.
+* :func:`mark_step` — record a step boundary inside the wrapped function.
+
+This is the lowest-overhead integration path: no framework dependency, no
+monkey-patching.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import time
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar, cast
+
+from agentdebug.adapters.base import AdapterStatus, FrameworkAdapter
+from agentdebug.models import EventType
+from agentdebug.recorder import AgentDebug, TraceSession
+
+_current_session: contextvars.ContextVar[Optional[TraceSession]] = contextvars.ContextVar(
+    'agentdebug_current_session', default=None
+)
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def current_session() -> Optional[TraceSession]:
+    """Return the active TraceSession in this context, if any."""
+    return _current_session.get()
+
+
+def trace_loop(
+    debugger: AgentDebug,
+    *,
+    goal: Optional[str] = None,
+    framework: str = 'raw',
+    task_id: Optional[str] = None,
+    success_on_return: bool = True,
+) -> Callable[[F], F]:
+    """Wrap a function so its execution becomes one trajectory.
+
+    Inside the wrapped function, use :func:`current_session` to grab the active
+    :class:`TraceSession` for direct ``trace.record(...)`` calls, or use
+    :func:`mark_step` for the common case.
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            run_goal = goal or func.__name__
+            session = debugger.trace(goal=run_goal, framework=framework, task_id=task_id)
+            token = _current_session.set(session)
+            with session:
+                try:
+                    result = func(*args, **kwargs)
+                except Exception:
+                    raise
+                finally:
+                    _current_session.reset(token)
+            # If the function returned normally, session.__exit__ already marked success.
+            return result
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
+def mark_step(
+    *,
+    event_type: EventType = EventType.AGENT_STEP,
+    agent_name: str = 'agent',
+    step_index: Optional[int] = None,
+    module: Optional[str] = None,
+    input: Any = None,
+    output: Any = None,
+    error: Optional[str] = None,
+    duration_ms: Optional[float] = None,
+    **metadata: Any,
+) -> None:
+    """Record a step boundary on the current session (no-op if none active)."""
+    session = current_session()
+    if session is None:
+        return
+    session.record(
+        event_type=event_type,
+        agent_name=agent_name,
+        step_index=step_index,
+        module=module,
+        input=input,
+        output=output,
+        error=error,
+        duration_ms=duration_ms,
+        **metadata,
+    )
+
+
+class RawLoopAdapter:
+    """Implements :class:`FrameworkAdapter` via duck-typing (not subclassed because
+    ``FrameworkAdapter`` is a ``Protocol``)."""
+
+    framework = 'raw'
+
+    def instrument(self, debugger: AgentDebug) -> AdapterStatus:  # noqa: D401
+        # Nothing to attach globally — users opt in by decorating their loop.
+        return AdapterStatus(
+            framework=self.framework,
+            implemented=True,
+            notes=(
+                'Apply @agentdebug.adapters.raw.trace_loop(debugger) to your '
+                'agent loop and call mark_step(...) inside it.'
+            ),
+        )
+
+
+_: FrameworkAdapter = RawLoopAdapter()  # static structural check
+
+
+def timed_block_ms(start: float) -> float:
+    """Helper for adapters: ms since a perf_counter start."""
+    return (time.perf_counter() - start) * 1000.0
+
+
+__all__ = [
+    'RawLoopAdapter',
+    'current_session',
+    'mark_step',
+    'timed_block_ms',
+    'trace_loop',
+]