agobs 1.0__py3-none-any.whl

agentlens/__init__.py

@@ -0,0 +1,48 @@
+"""AgentLens — local-first diagnostics & observability for AI agents.
+
+Answers one question: *"Why did my agent behave this way?"*
+
+Zero-config quickstart::
+
+    from agentlens import monitor
+    monitor.start()                      # auto-patches installed LLM SDKs
+    # ... run your agent ...
+
+Manual instrumentation (framework-agnostic)::
+
+    import agentlens
+    agentlens.init(project="research-bot")
+    with agentlens.trace_agent("planner"):
+        agentlens.log_tool("web_search", args={"q": "..."}, result=[...], retry_count=1)
+        agentlens.log_memory("read", "user_prefs", hit=True)
+        agentlens.log_llm(model="gpt-4o", input_tokens=1200, output_tokens=400)
+
+Then ``agentlens ui`` to explore the dashboard (default http://127.0.0.1:7180).
+"""
+from . import monitor
+from .client import flush, get_client, init
+from .events import Span, SpanKind
+from .tracing import (
+    current_session_id,
+    current_trace_id,
+    log_decision,
+    log_error,
+    log_llm,
+    log_memory,
+    log_retrieval,
+    log_tool,
+    trace,
+    trace_agent,
+    trace_session,
+    trace_workflow,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "init", "flush", "get_client", "monitor",
+    "trace", "trace_session", "trace_workflow", "trace_agent",
+    "current_trace_id", "current_session_id",
+    "log_llm", "log_tool", "log_memory", "log_decision", "log_retrieval", "log_error",
+    "Span", "SpanKind", "__version__",
+]

agentlens/_diag.py

@@ -0,0 +1,32 @@
+"""Diagnostics for the framework adapters and auto-patchers.
+
+Adapters hook into framework internals (callback signatures, method names) that
+move between versions. When they drift the failure is silent — a span just stops
+being captured. These helpers turn that silence into a visible
+``AgentLensWarning`` so version drift is noticed instead of producing empty
+dashboards.
+"""
+from __future__ import annotations
+
+import warnings
+from typing import Iterable
+
+
+class AgentLensWarning(UserWarning):
+    """Emitted when an adapter/patcher can't hook something it expected to."""
+
+
+def warn(message: str) -> None:
+    warnings.warn(f"[agentlens] {message}", AgentLensWarning, stacklevel=3)
+
+
+def require_methods(obj: object, methods: Iterable[str], what: str) -> None:
+    """Warn if ``obj`` is missing every one of ``methods`` (so the wrapper would
+    silently capture nothing). ``methods`` is treated as "at least one must
+    exist"."""
+    present = [m for m in methods if callable(getattr(obj, m, None))]
+    if not present:
+        warn(
+            f"{what}: {type(obj).__name__} has none of {list(methods)} — "
+            f"that will not be captured (framework version drift?)"
+        )

agentlens/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Framework adapters.
+
+Auto-patching (``monitor.start()``) covers the raw LLM SDKs. Agent frameworks
+expose their own callback/hook systems that carry far richer structure (agent
+boundaries, tool calls, decisions), so each framework gets a dedicated adapter
+here. Every adapter is import-time safe: importing this package never requires
+any framework to be installed.
+
+Common, framework-agnostic helpers live in ``common`` (``wrap_tool``,
+``traced_tool``) and work everywhere.
+"""
+from __future__ import annotations
+
+from .common import traced_tool, wrap_tool
+
+__all__ = ["traced_tool", "wrap_tool"]

agentlens/adapters/anthropic_agents.py

@@ -0,0 +1,52 @@
+"""Anthropic Agent SDK (``claude-agent-sdk``) adapter.
+
+The Claude Agent SDK runs tools you define and streams messages. The most
+reliable, version-stable instrumentation point is the tools themselves: wrap
+each tool callable so its invocation logs a tool span (args, result, errors).
+Raw Claude API calls the SDK makes are additionally captured by
+``monitor.start()`` auto-patching the underlying ``anthropic`` client.
+
+Example::
+
+    from agentlens.adapters.anthropic_agents import traced_tool
+
+    @traced_tool("get_weather")
+    async def get_weather(args): ...
+"""
+from __future__ import annotations
+
+import functools
+import time
+from typing import Any, Callable, Optional
+
+from .common import traced_tool, wrap_tool
+
+instrument_tool = wrap_tool
+
+
+def traced_async_tool(name: Optional[str] = None):
+    """Async variant of :func:`traced_tool` for ``async def`` tool handlers."""
+    def deco(fn: Callable) -> Callable:
+        tool_name = name or getattr(fn, "__name__", "tool")
+
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            from ..tracing import log_tool
+
+            t0 = time.time()
+            try:
+                result = await fn(*args, **kwargs)
+            except Exception as e:
+                log_tool(tool_name, args={"args": args, "kwargs": kwargs}, error=e,
+                         duration_ms=(time.time() - t0) * 1000.0)
+                raise
+            log_tool(tool_name, args={"args": args, "kwargs": kwargs}, result=result,
+                     duration_ms=(time.time() - t0) * 1000.0)
+            return result
+
+        return wrapper
+
+    return deco
+
+
+__all__ = ["traced_tool", "traced_async_tool", "wrap_tool", "instrument_tool"]

agentlens/adapters/autogen.py

@@ -0,0 +1,61 @@
+"""AutoGen (AG2 / pyautogen) adapter.
+
+AutoGen conversable agents support registered reply/hook functions. This adapter
+instruments an agent so each generated reply logs an agent span, and provides a
+tool wrapper for function-calling tools.
+
+Example::
+
+    from agentlens.adapters.autogen import instrument_agent
+    instrument_agent(assistant)
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .. import client as _client
+from ..events import Span, SpanKind, jsonable
+from .common import wrap_tool
+
+instrument_tool = wrap_tool
+
+
+def instrument_agent(agent: Any) -> Any:
+    """Hook an AutoGen agent so its replies log agent spans. Uses
+    ``register_hook('process_message_before_send')`` when available, else wraps
+    ``generate_reply``."""
+    name = getattr(agent, "name", None) or type(agent).__name__
+
+    def _log(content: Any) -> None:
+        try:
+            ev = Span(project=_client.get_project(), kind=SpanKind.AGENT.value, name=name,
+                      attributes={"agent_name": name, "output": jsonable(content)})
+            _client.get_client().log_event(ev.finish().model_dump())
+        except Exception:
+            pass
+
+    if hasattr(agent, "register_hook"):
+        def hook(sender=None, message=None, recipient=None, silent=None, **kw):
+            _log(message)
+            return message
+        try:
+            agent.register_hook("process_message_before_send", hook)
+            return agent
+        except Exception:
+            pass
+
+    # fallback: wrap generate_reply
+    original = getattr(agent, "generate_reply", None)
+    if callable(original):
+        import functools
+
+        @functools.wraps(original)
+        def wrapper(*a, **k):
+            reply = original(*a, **k)
+            _log(reply)
+            return reply
+        try:
+            agent.generate_reply = wrapper
+        except Exception:
+            pass
+    return agent

agentlens/adapters/common.py

@@ -0,0 +1,46 @@
+"""Framework-agnostic instrumentation helpers.
+
+These work with any agent framework (or none): wrap a plain callable as a tool
+so each invocation logs a ``tool`` span — including its arguments, result,
+duration, and any exception (which automatically feeds the Failure Explorer).
+"""
+from __future__ import annotations
+
+import functools
+import time
+from typing import Any, Callable, Optional
+
+
+def wrap_tool(fn: Callable, name: Optional[str] = None) -> Callable:
+    """Return a wrapped callable that logs a ``tool`` span per call. Re-raises
+    the original exception after recording it, so behavior is unchanged."""
+    tool_name = name or getattr(fn, "__name__", None) or "tool"
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        from ..tracing import log_tool
+
+        t0 = time.time()
+        try:
+            result = fn(*args, **kwargs)
+        except Exception as e:
+            log_tool(tool_name, args={"args": args, "kwargs": kwargs}, error=e,
+                     duration_ms=(time.time() - t0) * 1000.0)
+            raise
+        log_tool(tool_name, args={"args": args, "kwargs": kwargs}, result=result,
+                 duration_ms=(time.time() - t0) * 1000.0)
+        return result
+
+    return wrapper
+
+
+def traced_tool(name: Optional[str] = None):
+    """Decorator form of :func:`wrap_tool`.
+
+        @traced_tool()
+        def web_search(q): ...
+    """
+    def deco(fn: Callable) -> Callable:
+        return wrap_tool(fn, name)
+
+    return deco

agentlens/adapters/crewai.py

@@ -0,0 +1,66 @@
+"""CrewAI adapter.
+
+CrewAI agents/crews accept ``step_callback`` and ``task_callback`` hooks, and
+their tools are plain callables. This adapter provides:
+
+  * ``step_callback`` / ``task_callback`` — pass to ``Agent(...)`` / ``Crew(...)``
+    to log agent-step and task spans,
+  * ``instrument_tools(tools)`` — wrap a list of tools so each invocation logs a
+    tool span (uses the framework-agnostic ``wrap_tool``).
+
+Example::
+
+    from agentlens.adapters.crewai import step_callback, instrument_tools
+    agent = Agent(..., tools=instrument_tools(tools), step_callback=step_callback)
+"""
+from __future__ import annotations
+
+from typing import Any, List
+
+from ..events import SpanKind, jsonable
+from ..tracing import _log
+from .common import wrap_tool
+
+
+def step_callback(step: Any) -> None:
+    """Log a CrewAI agent step as an agent span (best-effort field extraction).
+
+    Uses the contextvar-aware logger so the span nests under whatever trace is
+    active — wrap the crew kickoff in ``agentlens.trace_workflow(...)`` to keep a
+    crew's steps in one run instead of scattering them into top-level rows."""
+    try:
+        _log(SpanKind.AGENT.value, "crewai.step",
+             {"agent_name": getattr(step, "agent", None) and str(getattr(step, "agent")),
+              "output": jsonable(getattr(step, "output", None) or step)})
+    except Exception:
+        pass
+
+
+def task_callback(task_output: Any) -> None:
+    """Log a CrewAI task result as a workflow span (nested under the active trace)."""
+    try:
+        _log(SpanKind.WORKFLOW.value, "crewai.task",
+             {"output": jsonable(getattr(task_output, "raw", None) or task_output)})
+    except Exception:
+        pass
+
+
+def instrument_tools(tools: List[Any]) -> List[Any]:
+    """Wrap each tool's underlying callable so calls log tool spans. Works for
+    CrewAI ``BaseTool`` instances (wraps ``_run``/``run``) and plain functions."""
+    out = []
+    for t in tools or []:
+        for attr in ("_run", "run", "func"):
+            fn = getattr(t, attr, None)
+            if callable(fn):
+                name = getattr(t, "name", None) or getattr(fn, "__name__", "tool")
+                try:
+                    setattr(t, attr, wrap_tool(fn, name))
+                except Exception:
+                    pass
+                break
+        else:
+            if callable(t):
+                t = wrap_tool(t)
+        out.append(t)
+    return out

agentlens/adapters/fastmcp.py

@@ -0,0 +1,56 @@
+"""FastMCP adapter.
+
+FastMCP keeps registered tools in a tool manager; this adapter wraps each tool's
+underlying function so calls log tool spans. Call ``instrument_server(mcp)``
+after your tools are registered.
+
+Example::
+
+    from fastmcp import FastMCP
+    from agentlens.adapters.fastmcp import instrument_server
+
+    mcp = FastMCP("demo")
+
+    @mcp.tool()
+    def add(a: int, b: int) -> int: return a + b
+
+    instrument_server(mcp)
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .anthropic_agents import traced_async_tool
+from .common import traced_tool, wrap_tool
+
+instrument_tool = wrap_tool
+
+
+def instrument_server(mcp: Any) -> Any:
+    """Wrap each registered FastMCP tool's function with a tool-span logger."""
+    manager = getattr(mcp, "_tool_manager", None) or getattr(mcp, "tool_manager", None)
+    tools = None
+    if manager is not None:
+        tools = getattr(manager, "_tools", None) or getattr(manager, "tools", None)
+    tools = tools if tools is not None else getattr(mcp, "_tools", None)
+
+    items = []
+    if isinstance(tools, dict):
+        items = list(tools.items())
+    elif isinstance(tools, (list, tuple)):
+        items = [(getattr(t, "name", i), t) for i, t in enumerate(tools)]
+
+    for key, tool in items:
+        for attr in ("fn", "func", "handler", "callback"):
+            fn = getattr(tool, attr, None)
+            if callable(fn) and not getattr(fn, "__agentlens_patched__", False):
+                name = getattr(tool, "name", None) or str(key)
+                try:
+                    setattr(tool, attr, wrap_tool(fn, name))
+                except Exception:
+                    pass
+                break
+    return mcp
+
+
+__all__ = ["traced_tool", "traced_async_tool", "wrap_tool", "instrument_tool", "instrument_server"]

agentlens/adapters/langchain.py

@@ -0,0 +1,183 @@
+"""LangChain adapter: a callback handler that converts LangChain run events
+into AgentLens spans.
+
+Usage::
+
+    from agentlens.adapters.langchain import AgentLensCallbackHandler
+    chain.invoke(question, config={"callbacks": [AgentLensCallbackHandler()]})
+
+LangGraph runs through the same LangChain callback system, so this handler works
+for LangGraph graphs too (see ``adapters/langgraph.py``).
+
+The pure mapping helpers below (dict in -> span dict out) are testable without
+LangChain installed.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+from .. import client as _client
+from ..events import Span, SpanKind, estimate_tokens, jsonable, normalize_result
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler  # type: ignore
+except ImportError:  # pragma: no cover
+    BaseCallbackHandler = object
+
+
+# --------------------------------------------------------------- pure mapping
+
+def llm_span(prompts: List[str], response_text: str, model: Optional[str],
+             trace_id: str, parent_span_id: Optional[str], project: str,
+             start_time: float, token_usage: Optional[Dict[str, Any]] = None,
+             status: str = "ok") -> Dict[str, Any]:
+    usage = token_usage or {}
+    ev = Span(
+        trace_id=trace_id, parent_span_id=parent_span_id, project=project,
+        kind=SpanKind.LLM.value, name=model or "langchain.llm", start_time=start_time,
+        attributes={"model": model, "provider": "langchain", "prompt": "\n\n".join(prompts),
+                    "response": response_text, "input_tokens": usage.get("prompt_tokens"),
+                    "output_tokens": usage.get("completion_tokens")},
+    )
+    return ev.finish(status).model_dump()
+
+
+def tool_span(tool_name: str, args: Any, result: Any, trace_id: str,
+              parent_span_id: Optional[str], project: str, start_time: float,
+              error: Any = None) -> Dict[str, Any]:
+    j_args, j_result = jsonable(args), jsonable(result)
+    attrs: Dict[str, Any] = {"tool_name": tool_name, "input": j_args, "output": j_result,
+                             "args": j_args, "result": j_result}
+    status = "ok"
+    if error is not None:
+        status = "error"
+        attrs["error"] = repr(error)
+        attrs["exception"] = type(error).__name__ if isinstance(error, BaseException) else None
+    ev = Span(trace_id=trace_id, parent_span_id=parent_span_id, project=project,
+              kind=SpanKind.TOOL.value, name=tool_name, start_time=start_time, attributes=attrs)
+    return ev.finish(status).model_dump()
+
+
+# ------------------------------------------------------------------- handler
+
+class AgentLensCallbackHandler(BaseCallbackHandler):
+    """Maps on_chain_* to the run/agent boundary, on_tool_* to tool spans,
+    on_retriever_* to retrieval spans and on_llm_* to llm spans."""
+
+    def __init__(self, project: Optional[str] = None):
+        if BaseCallbackHandler is object:
+            raise ImportError("LangChain is not installed. Run: pip install agentlens[langchain]")
+        self.project = project or _client.get_project()
+        self._trace_id: Optional[str] = None
+        self._root_run: Optional[str] = None
+        self._starts: Dict[str, float] = {}
+        self._names: Dict[str, str] = {}
+        self._trace_start: Optional[float] = None
+        self._name: Optional[str] = None
+
+    def _ensure_trace(self) -> str:
+        if self._trace_id is None:
+            self._trace_id = Span().trace_id
+        return self._trace_id
+
+    def _emit(self, ev: Dict[str, Any]) -> None:
+        _client.get_client().log_event(ev)
+
+    # -- chain = run/agent boundary --------------------------------------
+    def on_chain_start(self, serialized, inputs, *, run_id, parent_run_id=None, **kw):
+        if parent_run_id is None and self._root_run is None:
+            self._root_run = str(run_id)
+            self._trace_id = Span().trace_id
+            self._trace_start = time.time()
+            self._name = (serialized or {}).get("name") if isinstance(serialized, dict) else None
+
+    def on_chain_end(self, outputs, *, run_id, parent_run_id=None, **kw):
+        if str(run_id) == self._root_run:
+            ev = Span(trace_id=self._trace_id, project=self.project, kind=SpanKind.WORKFLOW.value,
+                      name=self._name or "langchain.chain", start_time=self._trace_start or time.time(),
+                      attributes={"name": self._name})
+            self._emit(ev.finish().model_dump())
+            self._root_run = None
+
+    def on_chain_error(self, error, *, run_id, parent_run_id=None, **kw):
+        if str(run_id) == self._root_run:
+            ev = Span(trace_id=self._trace_id, project=self.project, kind=SpanKind.WORKFLOW.value,
+                      name=self._name or "langchain.chain", start_time=self._trace_start or time.time(),
+                      attributes={"error": repr(error), "exception": type(error).__name__})
+            self._emit(ev.finish("error").model_dump())
+            self._root_run = None
+
+    # -- tools -----------------------------------------------------------
+    def on_tool_start(self, serialized, input_str, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        self._starts[rid] = time.time()
+        self._names[rid] = (serialized or {}).get("name", "tool") if isinstance(serialized, dict) else "tool"
+        self._names[rid + ":in"] = input_str
+
+    def on_tool_end(self, output, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        self._emit(tool_span(self._names.pop(rid, "tool"), self._names.pop(rid + ":in", None),
+                             output, self._ensure_trace(), None, self.project,
+                             self._starts.pop(rid, time.time())))
+
+    def on_tool_error(self, error, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        self._emit(tool_span(self._names.pop(rid, "tool"), self._names.pop(rid + ":in", None),
+                             None, self._ensure_trace(), None, self.project,
+                             self._starts.pop(rid, time.time()), error=error))
+
+    # -- retriever -------------------------------------------------------
+    def on_retriever_start(self, serialized, query, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        self._starts[rid] = time.time()
+        self._names[rid] = query
+
+    def on_retriever_end(self, documents, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        results = [normalize_result(d) for d in (documents or [])]
+        ev = Span(trace_id=self._ensure_trace(), project=self.project, kind=SpanKind.RETRIEVAL.value,
+                  name="langchain.retriever", start_time=self._starts.pop(rid, time.time()),
+                  attributes={"query": self._names.pop(rid, ""), "results": results, "top_k": len(results)})
+        self._emit(ev.finish().model_dump())
+
+    # -- llm -------------------------------------------------------------
+    def on_llm_start(self, serialized, prompts, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        self._starts[rid] = time.time()
+        self._names[rid] = "\n\n".join(prompts)
+
+    def on_chat_model_start(self, serialized, messages, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        self._starts[rid] = time.time()
+        flat = []
+        for batch in messages:
+            for m in batch:
+                flat.append(f"{getattr(m, 'type', 'msg')}: {getattr(m, 'content', m)}")
+        self._names[rid] = "\n".join(flat)
+
+    def on_llm_end(self, response, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        text, model, usage = "", None, None
+        try:
+            out = getattr(response, "llm_output", None) or {}
+            model = out.get("model_name") or out.get("model")
+            usage = out.get("token_usage") or out.get("usage")
+            gen = response.generations[0][0]
+            msg = getattr(gen, "message", None)
+            text = getattr(gen, "text", "") or getattr(msg, "content", "")
+            meta = getattr(msg, "response_metadata", None) or {}
+            model = model or meta.get("model_name") or meta.get("model")
+            usage = usage or meta.get("token_usage")
+            um = getattr(msg, "usage_metadata", None)
+            if not usage and um:
+                usage = {"prompt_tokens": um.get("input_tokens"), "completion_tokens": um.get("output_tokens")}
+        except (AttributeError, IndexError):
+            pass
+        self._emit(llm_span([self._names.pop(rid, "")], text, model, self._ensure_trace(),
+                            None, self.project, self._starts.pop(rid, time.time()), usage))
+
+    def on_llm_error(self, error, *, run_id, parent_run_id=None, **kw):
+        rid = str(run_id)
+        self._emit(llm_span([self._names.pop(rid, "")], repr(error), None, self._ensure_trace(),
+                            None, self.project, self._starts.pop(rid, time.time()), status="error"))

agentlens/adapters/langgraph.py

@@ -0,0 +1,17 @@
+"""LangGraph adapter.
+
+LangGraph executes nodes through the LangChain callback system, so the
+``AgentLensCallbackHandler`` from the LangChain adapter captures graph node
+LLM/tool/retrieval activity directly. Pass it in the run config::
+
+    from agentlens.adapters.langgraph import AgentLensCallbackHandler
+    graph.invoke(state, config={"callbacks": [AgentLensCallbackHandler()]})
+
+Each graph node fires chain start/end events; tool nodes fire tool events; the
+parent/child span tree reconstructs the workflow path in the Run detail view.
+"""
+from __future__ import annotations
+
+from .langchain import AgentLensCallbackHandler
+
+__all__ = ["AgentLensCallbackHandler"]

agentlens/adapters/llamaindex.py

@@ -0,0 +1,73 @@
+"""LlamaIndex adapter: a callback handler mapping LlamaIndex events to spans.
+
+Usage::
+
+    from llama_index.core import Settings
+    from llama_index.core.callbacks import CallbackManager
+    from agentlens.adapters.llamaindex import AgentLensLlamaHandler
+
+    Settings.callback_manager = CallbackManager([AgentLensLlamaHandler()])
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+from .. import client as _client
+from ..events import Span, SpanKind, jsonable, normalize_result
+
+try:
+    from llama_index.core.callbacks.base_handler import BaseCallbackHandler  # type: ignore
+    from llama_index.core.callbacks.schema import CBEventType  # type: ignore
+    _OK = True
+except ImportError:  # pragma: no cover
+    BaseCallbackHandler = object
+    CBEventType = None
+    _OK = False
+
+
+class AgentLensLlamaHandler(BaseCallbackHandler):
+    """Maps LLM / FUNCTION_CALL / AGENT_STEP / RETRIEVE events to AgentLens spans."""
+
+    def __init__(self, project: Optional[str] = None):
+        if not _OK:
+            raise ImportError("LlamaIndex is not installed. Run: pip install agentlens[llamaindex]")
+        super().__init__(event_starts_to_ignore=[], event_ends_to_ignore=[])
+        self.project = project or _client.get_project()
+        self._trace_id = Span().trace_id
+        self._starts: Dict[str, float] = {}
+        self._payloads: Dict[str, Any] = {}
+
+    def start_trace(self, trace_id: Optional[str] = None) -> None:
+        self._trace_id = Span().trace_id
+
+    def end_trace(self, trace_id: Optional[str] = None, trace_map=None) -> None:
+        pass
+
+    def on_event_start(self, event_type, payload=None, event_id="", parent_id="", **kw) -> str:
+        self._starts[event_id] = time.time()
+        self._payloads[event_id] = payload or {}
+        return event_id
+
+    def on_event_end(self, event_type, payload=None, event_id="", **kw) -> None:
+        t0 = self._starts.pop(event_id, time.time())
+        payload = payload or self._payloads.pop(event_id, {})
+        name = str(getattr(event_type, "value", event_type))
+        kind, attrs = self._map(event_type, payload)
+        ev = Span(trace_id=self._trace_id, project=self.project, kind=kind,
+                  name=name, start_time=t0, attributes=attrs)
+        _client.get_client().log_event(ev.finish().model_dump())
+
+    def _map(self, event_type, payload) -> tuple:
+        et = str(getattr(event_type, "value", event_type)).lower()
+        if "llm" in et:
+            return SpanKind.LLM.value, {"model": jsonable(payload.get("serialized", {})),
+                                        "response": jsonable(payload.get("response"))}
+        if "retrieve" in et:
+            nodes = payload.get("nodes") or []
+            return SpanKind.RETRIEVAL.value, {"query": jsonable(payload.get("query_str")),
+                                              "results": [normalize_result(n) for n in nodes]}
+        if "function" in et or "tool" in et or "agent" in et:
+            jp = jsonable(payload)
+            return SpanKind.TOOL.value, {"tool_name": et, "input": jp, "args": jp}
+        return SpanKind.OTHER.value, {"payload": jsonable(payload)}