etaoi 0.0.2__tar.gz

etaoi-0.0.2/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.3
+Name: etaoi
+Version: 0.0.2
+Summary: Agent-native trace SDK for LangChain / LangGraph / deepagents (skeleton)
+Keywords: langchain,langgraph,deepagents,tracing,observability,agents
+Author: AAIRA / VIZ contributors
+License: MIT
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: etaoi-schema>=0.3,<1
+Requires-Dist: langchain-core>=1.0,<2
+Requires-Dist: anyio>=4
+Requires-Dist: msgpack>=1.1.2
+Requires-Dist: tenacity>=9
+Requires-Dist: websockets>=13,<17
+Requires-Dist: livekit-agents>=1.2,<2 ; extra == 'livekit'
+Requires-Dist: deepagents>=0.6.1,<0.7 ; extra == 'test'
+Requires-Dist: langgraph>=1.1.0,<2 ; extra == 'test'
+Requires-Dist: pytest>=8 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24 ; extra == 'test'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/etaoi/etaoi
+Project-URL: Repository, https://github.com/etaoi/etaoi
+Provides-Extra: livekit
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# etaoi
+
+Python SDK for [VIZ](../../README.md) — an agent-native trace visualizer for the LangChain
+ecosystem and LiveKit voice agents.
+
+> **Status:** Skeleton. This package exists so CI is green from day one; the real
+> implementation (LangChain `BaseCallbackHandler` adapter, WebSocket transport,
+> MessagePack serialization, background flush) lands in Phase 2 of the
+> [delivery roadmap](../../.planning/ROADMAP.md).
+
+When complete, a developer will be able to:
+
+```python
+import etaoi
+
+etaoi.attach(my_agent)  # streams telemetry to a local VIZ server
+```
+
+For the wire schema this package depends on, see
+[`etaoi-schema`](../etaoi-schema/python/README.md).

etaoi-0.0.2/README.md

@@ -0,0 +1,20 @@
+# etaoi
+
+Python SDK for [VIZ](../../README.md) — an agent-native trace visualizer for the LangChain
+ecosystem and LiveKit voice agents.
+
+> **Status:** Skeleton. This package exists so CI is green from day one; the real
+> implementation (LangChain `BaseCallbackHandler` adapter, WebSocket transport,
+> MessagePack serialization, background flush) lands in Phase 2 of the
+> [delivery roadmap](../../.planning/ROADMAP.md).
+
+When complete, a developer will be able to:
+
+```python
+import etaoi
+
+etaoi.attach(my_agent)  # streams telemetry to a local VIZ server
+```
+
+For the wire schema this package depends on, see
+[`etaoi-schema`](../etaoi-schema/python/README.md).

etaoi-0.0.2/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["uv_build>=0.4,<0.11"]
+build-backend = "uv_build"
+
+[project]
+name = "etaoi"
+version = "0.0.2"
+description = "Agent-native trace SDK for LangChain / LangGraph / deepagents (skeleton)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "AAIRA / VIZ contributors" }]
+keywords = ["langchain", "langgraph", "deepagents", "tracing", "observability", "agents"]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "etaoi-schema>=0.3,<1",
+    "langchain-core>=1.0,<2",
+    "anyio>=4",
+    "msgpack>=1.1.2",
+    "tenacity>=9",
+    "websockets>=13,<17",
+]
+
+[project.optional-dependencies]
+livekit = [
+    "livekit-agents>=1.2,<2",
+]
+test = [
+    "deepagents>=0.6.1,<0.7",
+    "langgraph>=1.1.0,<2",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/etaoi/etaoi"
+Repository = "https://github.com/etaoi/etaoi"
+
+[project.scripts]
+etaoi = "etaoi.cli:main"
+
+[tool.uv.sources]
+etaoi-schema = { workspace = true }
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+packages = ["etaoi"]
+
+[[tool.mypy.overrides]]
+module = ["msgpack", "msgpack.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "benchmark: opt-in SDK overhead benchmark (Plan 02-08); run via `pytest -m benchmark`",
+]

etaoi-0.0.2/src/etaoi/_LIVEKIT_WIRING.md

@@ -0,0 +1,45 @@
+# LiveKit livekit/handler.py — agent_context wiring (deferred from Phase 06)
+
+After merging this branch into main, paste the emit call into the
+`LiveKitVoiceHandler.bootstrap()` (or equivalent entry-point invoked from
+`Agent.on_enter`). The exact insertion point is the handler method that
+runs once per attach, before any voice_session events go out.
+
+## Diff to apply
+
+```python
+# At the top of packages/etaoi/src/etaoi/livekit/handler.py
+from etaoi.livekit_context import build_voice_agent_context
+
+# Inside the bootstrap path (Agent.on_enter or LiveKitVoiceHandler.bind/attach):
+def _bootstrap_agent_context(self, agent: Any, session: Any) -> None:
+    """Emit one agent_context span and cache its id for trace linkage."""
+    try:
+        ctx = build_voice_agent_context(agent, session)
+        self.emit_agent_context(ctx)
+    except Exception:
+        # Bootstrap failure must never block the voice pipeline.
+        return
+```
+
+`emit_agent_context` already exists on `AgentVizHandler` (the LangChain
+handler base) — if `LiveKitVoiceHandler` doesn't inherit from it, copy the
+method or thread a reference. The contract: cache the bootstrap span_id
+and stamp `metadata[AGENT_CONTEXT_ID]` on every subsequent voice_session /
+voice_turn / llm span.
+
+## Hook location
+
+In livekit-agents 1.5, the right place is the `Agent.on_enter` lifecycle
+hook — fires once when the agent enters its session. Either:
+- Subclass `Agent` and override `on_enter` (user-side), then call our
+  `_bootstrap_agent_context` from there, or
+- Patch the handler to attach an `on_enter` listener at bind time.
+
+## Test plan
+
+The existing `test_livekit_context.py` covers the snapshot shape. After
+wiring, add one test in `test_livekit_handler.py` that asserts:
+1. Exactly one `agent_context` span is emitted per attach.
+2. Subsequent voice_session events carry `metadata[AGENT_CONTEXT_ID]`
+   equal to the bootstrap span_id.

etaoi-0.0.2/src/etaoi/__init__.py

@@ -0,0 +1,25 @@
+"""etaoi - Python SDK for VIZ."""
+
+from etaoi._version import __version__
+from etaoi.attach import AttachedHandle, attach
+from etaoi.handler import AgentVizHandler
+from etaoi.probe import instrument
+
+# LiveKit voice integration is gated by the optional ``[livekit]`` extra.
+# Re-exported lazily so users without livekit-agents installed can still
+# ``from etaoi import attach`` without paying an ImportError.
+try:
+    from etaoi.livekit.attach import AttachedSessionHandle, attach_session
+
+    _livekit_exports: tuple[str, ...] = ("AttachedSessionHandle", "attach_session")
+except Exception:  # pragma: no cover — only triggers when livekit subpackage breaks
+    _livekit_exports = ()
+
+__all__ = [
+    "AgentVizHandler",
+    "AttachedHandle",
+    "__version__",
+    "attach",
+    "instrument",
+    *_livekit_exports,
+]

etaoi-0.0.2/src/etaoi/__main__.py

@@ -0,0 +1,11 @@
+"""Allow ``python -m etaoi <subcommand>`` as an alternative to the
+console_script. Useful in containers and CI where the entry-point script
+may not be on PATH but the package is importable.
+"""
+
+from __future__ import annotations
+
+from etaoi.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

etaoi-0.0.2/src/etaoi/_active.py

@@ -0,0 +1,40 @@
+"""Process-global access to the currently-attached ``AgentVizHandler``.
+
+LangChain v1 does not fire callbacks for ``AgentMiddleware.wrap_model_call``
+methods — they're invoked as plain Python function calls inside the model
+node. The probe wrappers in :mod:`etaoi.probe` need to find the live
+handler to emit per-middleware snapshot spans; we keep that pointer in a
+``ContextVar`` so it works correctly under asyncio + threadpool execution.
+
+Set by :meth:`AgentVizHandler.__init__` and cleared by the handler when the
+top-level run closes. Probes call :func:`active_handler` and emit if a
+handler is bound, otherwise pass through with no overhead.
+
+Also exposes a per-call "current run id" — the most recently-opened
+LangChain span. Probes use it to parent their synthetic spans correctly.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from etaoi.handler import AgentVizHandler
+
+ACTIVE_HANDLER: ContextVar["AgentVizHandler | None"] = ContextVar(
+    "agentviz_active_handler", default=None
+)
+
+ACTIVE_RUN_ID: ContextVar[UUID | None] = ContextVar(
+    "agentviz_active_run_id", default=None
+)
+
+
+def active_handler() -> "AgentVizHandler | None":
+    return ACTIVE_HANDLER.get()
+
+
+def active_run_id() -> UUID | None:
+    return ACTIVE_RUN_ID.get()

etaoi-0.0.2/src/etaoi/_disabled.py

@@ -0,0 +1,52 @@
+"""``AGENTVIZ_DISABLED=1`` short-circuit (SDK-08).
+
+When the env var is set, constructing :class:`etaoi.handler.AgentVizHandler`
+returns a module-level :class:`NoopHandler` singleton instead of building a
+real handler — zero allocation beyond the singleton itself, every callback is
+a no-op. This is the SDK's escape hatch for operators who want to keep the
+``attach()`` call in their code path but suppress all instrumentation at run
+time (CI, profile-of-prod parity runs, debugging).
+
+Accepted truthy values (case-insensitive): ``"1"``, ``"true"``, ``"yes"``.
+Anything else (empty string, ``"0"``, ``"false"``) leaves instrumentation on.
+"""
+
+from __future__ import annotations
+
+import os
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+_TRUTHY = frozenset({"1", "true", "yes"})
+
+
+def is_disabled() -> bool:
+    """Return ``True`` iff ``AGENTVIZ_DISABLED`` is set to a truthy value.
+
+    The env var is read on every call (no caching) so tests can flip it
+    between cases without juggling module state.
+    """
+    return os.environ.get("AGENTVIZ_DISABLED", "").strip().lower() in _TRUTHY
+
+
+class NoopHandler(BaseCallbackHandler):
+    """Callback handler that does nothing.
+
+    Subclasses :class:`BaseCallbackHandler` so it satisfies type checks at
+    the ``langchain`` boundary (``config={"callbacks": [...]}``) without
+    overriding any methods — every ``on_*`` falls through to the base
+    class's no-op implementation.
+    """
+
+    __slots__ = ()
+
+
+_NOOP_HANDLER = NoopHandler()
+
+
+def noop_singleton() -> NoopHandler:
+    """Return the process-wide :class:`NoopHandler` instance."""
+    return _NOOP_HANDLER
+
+
+__all__ = ["NoopHandler", "is_disabled", "noop_singleton"]

etaoi-0.0.2/src/etaoi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.2"

etaoi-0.0.2/src/etaoi/_voice_context.py

@@ -0,0 +1,67 @@
+"""Cross-handler contextvar bridge for stitching LangChain spans to a LiveKit
+voice turn.
+
+When a LiveKit voice turn opens, the LiveKitVoiceHandler binds the active
+``speech_id`` (and optional ``agent_id`` / ``agent_label``) here. If the
+session's LLM is a ``livekit-plugins-langchain`` ``LLMAdapter`` wrapping a
+LangGraph / deepagents / ``create_agent`` graph, every LangChain callback the
+internal graph fires runs on the same task — so the AgentVizHandler
+(LangChain) can read ``current_voice_context()`` and tag its spans with the
+LK speech_id, producing a single stitched trace across both handlers.
+
+This module is import-light on purpose: pure stdlib, zero dependencies, so
+the LiveKit and LangChain SDK extras can both pull it in without leaking
+their own deps on each other.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class VoiceContext:
+    """Snapshot of the currently-active LiveKit voice turn for stitching.
+
+    All fields are optional individually so partial activation (turn open
+    before agent identity is known, agent active outside a turn) is
+    representable.
+    """
+
+    speech_id: str | None = None
+    agent_id: str | None = None
+    agent_label: str | None = None
+    session_id: str | None = None
+
+
+_CURRENT: ContextVar[VoiceContext | None] = ContextVar(
+    "agentviz_voice_context", default=None
+)
+
+
+def current_voice_context() -> VoiceContext | None:
+    """Return the active VoiceContext, or None if no LK turn is in flight."""
+    return _CURRENT.get()
+
+
+def set_voice_context(ctx: VoiceContext | None) -> object:
+    """Bind ``ctx`` as the active context. Returns a token for ``reset()``."""
+    return _CURRENT.set(ctx)
+
+
+def reset_voice_context(token: object) -> None:
+    """Restore the previous context. Safe to call with a stale token."""
+    try:
+        _CURRENT.reset(token)  # type: ignore[arg-type]
+    except (ValueError, LookupError):
+        # Stale token (different task / already reset). Best-effort clear.
+        _CURRENT.set(None)
+
+
+__all__ = [
+    "VoiceContext",
+    "current_voice_context",
+    "reset_voice_context",
+    "set_voice_context",
+]

etaoi-0.0.2/src/etaoi/attach.py

@@ -0,0 +1,249 @@
+"""Public ``attach()`` entry point — one-line agent instrumentation (Plan 02-05).
+
+``from etaoi import attach``
+``handle = attach(my_agent)`` — returns AttachedHandle with ``.detach()`` and ``.handler`` attrs.
+
+Honors ``AGENTVIZ_DISABLED=1`` short-circuit: returns a noop handle with no Sender allocated.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import contextlib
+import logging
+import threading
+from typing import Any
+from uuid import UUID
+
+import anyio
+
+from etaoi._disabled import is_disabled
+from etaoi.context import build_agent_context
+from etaoi.handler import AgentVizHandler
+from etaoi.sinks import MsgpackDropSink, NoopSink, Sink, WebSocketSink
+from etaoi.transport.sender import Sender
+
+logger = logging.getLogger(__name__)
+
+
+class AttachedHandle:
+    """Returned by ``attach()``. Provides ``.detach()`` and ``.handler``."""
+
+    def __init__(
+        self,
+        handler: AgentVizHandler,
+        sender: Sender | None,
+        thread: threading.Thread | None,
+        cancel_scope: anyio.CancelScope | None,
+        agent: Any = None,
+        loop: asyncio.AbstractEventLoop | None = None,
+    ) -> None:
+        self.handler = handler
+        self._sender = sender
+        self._thread = thread
+        self._cancel_scope = cancel_scope
+        self._loop = loop
+        self._agent = agent
+        self._installed_on_config = False
+        self._detached = False
+        atexit.register(self._safe_detach)
+
+    @property
+    def user_id(self) -> str | None:
+        """The user_id pinned on the underlying handler (or ``None``)."""
+        return getattr(self.handler, "_user_id", None)
+
+    @property
+    def session_id(self) -> UUID | None:
+        """The session_id pinned on the underlying handler (or ``None``)."""
+        return getattr(self.handler, "_session_id", None)
+
+    def detach(self) -> None:
+        if self._detached:
+            return
+        self._detached = True
+        # Remove the handler from the agent config if we installed it.
+        if self._installed_on_config and self._agent is not None:
+            with contextlib.suppress(Exception):
+                cfg = getattr(self._agent, "config", None)
+                if isinstance(cfg, dict):
+                    callbacks = cfg.get("callbacks")
+                    if isinstance(callbacks, list) and self.handler in callbacks:
+                        callbacks.remove(self.handler)
+        # Synthesize span_ends for runs that LangChain/deepagents never closed
+        # (terminal callbacks skipped on short flows → "empty card" in UI).
+        with contextlib.suppress(Exception):
+            self.handler.flush_open_spans()
+        # Graceful shutdown: schedule aclose() on the sender's background loop
+        # so the 75 ms batch buffer drains BEFORE we tear the task down.
+        # Hard-cancelling the scope (the original behavior) discarded any
+        # envelopes still sitting in the batch window — that's how short
+        # agent runs lost their final LLM `span_end`.
+        if self._sender is not None and self._loop is not None and not self._loop.is_closed():
+            with contextlib.suppress(Exception):
+                fut = asyncio.run_coroutine_threadsafe(self._sender.aclose(), self._loop)
+                with contextlib.suppress(Exception):
+                    fut.result(timeout=2.5)
+        if self._cancel_scope is not None:
+            with contextlib.suppress(Exception):
+                self._cancel_scope.cancel()
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=2.0)
+
+    def _safe_detach(self) -> None:
+        with contextlib.suppress(Exception):
+            self.detach()
+
+
+class _DisabledHandle:
+    """No-op handle returned when AGENTVIZ_DISABLED=1."""
+
+    def __init__(self) -> None:
+        self.handler = AgentVizHandler(sink=NoopSink())
+
+    @property
+    def user_id(self) -> str | None:
+        return None
+
+    @property
+    def session_id(self) -> UUID | None:
+        return None
+
+    def detach(self) -> None:
+        return
+
+
+def _resolve_sink(sink: str | Sink | None, server_url: str) -> tuple[Sink, Sender | None]:
+    if sink is None or sink == "ws":
+        sender = Sender(server_url)
+        return WebSocketSink(sender), sender
+    if sink == "noop":
+        return NoopSink(), None
+    if sink == "msgpack-drop":
+        return MsgpackDropSink(), None
+    if isinstance(sink, str):
+        raise ValueError(f"unknown sink mode: {sink!r}")
+    return sink, None
+
+
+def _install_handler_on_agent(agent: Any, handler: AgentVizHandler) -> bool:
+    """Best-effort install the handler into ``agent.config['callbacks']``.
+
+    Returns True iff the handler was successfully appended (so ``detach``
+    knows to remove it). Failures are silent — ``attach()`` MUST NOT raise
+    on a malformed agent argument; the returned handle still carries the
+    handler so callers can wire it manually via ``config={"callbacks": ...}``.
+
+    LangGraph's ``CompiledStateGraph`` exposes a mutable ``config`` dict that
+    flows through ``invoke()`` / ``ainvoke()``. Appending to its
+    ``"callbacks"`` list is the lowest-friction wiring: the agent picks
+    the handler up on every subsequent invocation without the caller
+    having to thread it through manually. Plan 02-08's overhead benchmark
+    relies on this so the test body can call ``agent.invoke(...)`` without
+    re-passing the handler each turn.
+    """
+    cfg = getattr(agent, "config", None)
+    if not isinstance(cfg, dict):
+        return False
+    callbacks = cfg.get("callbacks")
+    if callbacks is None:
+        cfg["callbacks"] = [handler]
+        return True
+    if isinstance(callbacks, list):
+        callbacks.append(handler)
+        return True
+    # Some LangChain primitives accept a BaseCallbackManager here; we don't
+    # want to swap it out from under the user. Fall back to manual wiring.
+    return False
+
+
+def attach(
+    agent: Any,
+    *,
+    server_url: str = "ws://127.0.0.1:8787/ingest",
+    sink: str | Sink | None = None,
+    user_id: str | None = None,
+    session_id: str | UUID | None = None,
+) -> AttachedHandle | _DisabledHandle:
+    """Attach AgentViz to an agent.
+
+    Args:
+        agent: The agent object (LangChain Runnable / LangGraph compiled
+            graph / deepagent). The handler is best-effort appended to
+            ``agent.config['callbacks']`` so subsequent ``invoke()`` calls
+            pick it up automatically.
+        server_url: WS ingest URL (only consulted when ``sink`` defaults to
+            ``"ws"``).
+        sink: ``"ws"`` (default), ``"noop"``, ``"msgpack-drop"``, or a
+            custom :class:`Sink` instance.
+        user_id: Optional user identifier stamped on every event emitted by
+            this handle. Omitted → server buckets as anonymous.
+        session_id: Optional session id (UUID or string). Omitted → uuid4.
+            Strings that don't parse as UUIDs are coerced via uuid5 so the
+            same string maps to the same session across attach() calls.
+
+    Top-level ``invoke()`` calls under this handle each get a fresh
+    auto-allocated ``trace_id``, so one ``attach(...)`` can cover many
+    invocations within a single session.
+    """
+    if is_disabled():
+        return _DisabledHandle()
+
+    resolved_sink, sender = _resolve_sink(sink, server_url)
+    handler = AgentVizHandler(
+        sink=resolved_sink,
+        user_id=user_id,
+        session_id=session_id,
+    )
+
+    cancel_scope: anyio.CancelScope | None = None
+    thread: threading.Thread | None = None
+
+    if sender is not None:
+        # Run the Sender on its own event loop in a background thread so the user's
+        # agent (which may be sync or async) does not need to know about it.
+        ready = threading.Event()
+        loop_holder: dict[str, Any] = {}
+        bg_sender = sender
+
+        def _run() -> None:
+            async def _main() -> None:
+                nonlocal_scope = anyio.CancelScope()
+                loop_holder["scope"] = nonlocal_scope
+                with contextlib.suppress(RuntimeError):
+                    loop_holder["loop"] = asyncio.get_running_loop()
+                ready.set()
+                with nonlocal_scope:
+                    try:
+                        await bg_sender.run()
+                    except Exception as e:
+                        logger.warning("etaoi sender exited: %r", e)
+
+            with contextlib.suppress(Exception):
+                anyio.run(_main)
+
+        thread = threading.Thread(target=_run, name="etaoi-sender", daemon=True)
+        thread.start()
+        ready.wait(timeout=2.0)
+        cancel_scope = loop_holder.get("scope")
+        bg_loop = loop_holder.get("loop")
+    else:
+        bg_loop = None
+
+    installed = False
+    with contextlib.suppress(Exception):
+        installed = _install_handler_on_agent(agent, handler)
+
+    # Bootstrap-once agent_context span. Best-effort: introspection failure
+    # must never block attach (the host agent always wins).
+    with contextlib.suppress(Exception):
+        ctx = build_agent_context(agent)
+        handler.emit_agent_context(ctx)
+
+    h = AttachedHandle(handler, sender, thread, cancel_scope, agent=agent, loop=bg_loop)
+    h._installed_on_config = installed
+    return h
+
+
+__all__ = ["AttachedHandle", "attach"]