traceagent 0.1.0__tar.gz

traceagent-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Database
+*.db
+
+# Node
+dashboard/node_modules/
+
+# Built dashboard (generated — don't commit)
+server/agentlens_server/static/
+
+# Env
+.env
+.env.local

traceagent-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: traceagent
+Version: 0.1.0
+Summary: Local-first observability for AI agents. Lightweight SDK — trace LangChain, LangGraph, and any Python code.
+Project-URL: Homepage, https://github.com/agentlens/agentlens
+Project-URL: Documentation, https://github.com/agentlens/agentlens#readme
+Project-URL: Repository, https://github.com/agentlens/agentlens
+Project-URL: Issues, https://github.com/agentlens/agentlens/issues
+Author: AgentLens Contributors
+License: MIT
+Keywords: agents,ai,debugging,langchain,langgraph,llm,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# AgentLens SDK
+
+**Local-first observability for AI agents.** Lightweight Python SDK — trace LangChain, LangGraph, and any Python code.
+
+## Install
+
+```bash
+pip install agentlens
+```
+
+## Quick Start
+
+### Option 1: Environment Variables (zero code changes, like LangSmith)
+
+```bash
+export AGENTLENS_ENABLED=true
+export AGENTLENS_ENDPOINT=http://localhost:6832   # your AgentLens server
+```
+
+```python
+import agentlens  # auto-traces all LangChain/LangGraph calls
+
+result = graph.invoke({"messages": [HumanMessage(content="Hello!")]})
+```
+
+### Option 2: Explicit Callback
+
+```python
+from agentlens import AgentLens
+
+lens = AgentLens(server_url="http://localhost:6832")
+
+result = graph.invoke(
+    {"messages": [HumanMessage(content="Hello!")]},
+    config={"callbacks": [lens.callback()]}
+)
+```
+
+### Option 3: Decorators & Context Managers
+
+```python
+from agentlens import AgentLens
+
+lens = AgentLens()
+
+@lens.observe(name="search", kind="tool")
+def search(query: str):
+    return results
+
+with lens.trace("My Pipeline") as t:
+    result = search("hello")
+    t.outputs = {"result": result}
+```
+
+## Configuration
+
+| Env Variable | Description | Default |
+|---|---|---|
+| `AGENTLENS_ENABLED` | Enable tracing | `false` |
+| `AGENTLENS_ENDPOINT` | Server URL | `http://localhost:6832` |
+| `AGENTLENS_PROJECT` | Project name | `default` |
+| `AGENTLENS_TAGS` | Comma-separated tags | |
+| `AGENTLENS_AUTO_TRACE` | Auto-attach to LangChain | `true` when enabled |
+
+## Server
+
+The SDK sends traces to an AgentLens server. See [agentlens-server](../server/) for setup.

traceagent-0.1.0/README.md

@@ -0,0 +1,67 @@
+# AgentLens SDK
+
+**Local-first observability for AI agents.** Lightweight Python SDK — trace LangChain, LangGraph, and any Python code.
+
+## Install
+
+```bash
+pip install agentlens
+```
+
+## Quick Start
+
+### Option 1: Environment Variables (zero code changes, like LangSmith)
+
+```bash
+export AGENTLENS_ENABLED=true
+export AGENTLENS_ENDPOINT=http://localhost:6832   # your AgentLens server
+```
+
+```python
+import agentlens  # auto-traces all LangChain/LangGraph calls
+
+result = graph.invoke({"messages": [HumanMessage(content="Hello!")]})
+```
+
+### Option 2: Explicit Callback
+
+```python
+from agentlens import AgentLens
+
+lens = AgentLens(server_url="http://localhost:6832")
+
+result = graph.invoke(
+    {"messages": [HumanMessage(content="Hello!")]},
+    config={"callbacks": [lens.callback()]}
+)
+```
+
+### Option 3: Decorators & Context Managers
+
+```python
+from agentlens import AgentLens
+
+lens = AgentLens()
+
+@lens.observe(name="search", kind="tool")
+def search(query: str):
+    return results
+
+with lens.trace("My Pipeline") as t:
+    result = search("hello")
+    t.outputs = {"result": result}
+```
+
+## Configuration
+
+| Env Variable | Description | Default |
+|---|---|---|
+| `AGENTLENS_ENABLED` | Enable tracing | `false` |
+| `AGENTLENS_ENDPOINT` | Server URL | `http://localhost:6832` |
+| `AGENTLENS_PROJECT` | Project name | `default` |
+| `AGENTLENS_TAGS` | Comma-separated tags | |
+| `AGENTLENS_AUTO_TRACE` | Auto-attach to LangChain | `true` when enabled |
+
+## Server
+
+The SDK sends traces to an AgentLens server. See [agentlens-server](../server/) for setup.

traceagent-0.1.0/agentlens/__init__.py

@@ -0,0 +1,47 @@
+"""
+AgentLens - Local-first observability for AI agents.
+
+See everything your agents do, locally.
+
+Option 1 — Environment Variables (like LangSmith, zero code changes):
+
+    export AGENTLENS_ENABLED=true
+    export AGENTLENS_ENDPOINT=http://localhost:6832  # optional
+
+    # Then just import agentlens anywhere and all LangChain/LangGraph
+    # calls are traced automatically:
+    import agentlens
+
+Option 2 — Programmatic (one-liner):
+
+    import agentlens
+    agentlens.configure(enabled=True, project="my-project")
+
+Option 3 — Explicit callback:
+
+    from agentlens import AgentLens
+    lens = AgentLens()
+    result = graph.invoke(input, config={"callbacks": [lens.callback()]})
+"""
+
+from agentlens.core import AgentLens
+from agentlens.auto import configure, disable_auto_trace
+from agentlens.config import config
+from agentlens.models import Span, SpanKind, SpanStatus, Trace, TraceStatus
+
+__version__ = "0.1.0"
+__all__ = [
+    "AgentLens",
+    "configure",
+    "disable_auto_trace",
+    "config",
+    "Trace",
+    "Span",
+    "TraceStatus",
+    "SpanStatus",
+    "SpanKind",
+]
+
+# ---- Auto-activate if env vars are set (like LangSmith) ----
+if config.is_active and config.auto_trace:
+    configure(enabled=True)

traceagent-0.1.0/agentlens/auto.py

@@ -0,0 +1,201 @@
+"""Auto-tracing module — registers AgentLens as a global LangChain callback.
+
+When AGENTLENS_ENABLED=true, this hooks into LangChain's callback system
+so ALL LLM/chain/tool calls are traced automatically — zero code changes needed.
+
+This mirrors how LangSmith works with LANGCHAIN_TRACING_V2=true.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agentlens.config import config
+
+logger = logging.getLogger("agentlens")
+
+_auto_trace_installed = False
+
+
+def configure(
+    enabled: bool | None = None,
+    endpoint: str | None = None,
+    project: str | None = None,
+    tags: list[str] | None = None,
+    auto_trace: bool | None = None,
+) -> None:
+    """
+    Configure AgentLens programmatically. Call this once at the top of your app.
+
+    This is the alternative to setting environment variables.
+
+    Usage:
+        import agentlens
+        agentlens.configure(enabled=True, project="my-project")
+
+        # Now all LangChain/LangGraph calls are traced automatically!
+        result = graph.invoke({"messages": [...]})
+
+    Args:
+        enabled: Enable tracing (default reads AGENTLENS_ENABLED env var)
+        endpoint: Server URL (default: http://localhost:6832)
+        project: Project name for grouping traces
+        tags: Default tags added to every trace
+        auto_trace: Auto-register as global LangChain callback
+    """
+    import os
+
+    if enabled is not None:
+        os.environ["AGENTLENS_ENABLED"] = str(enabled).lower()
+    if endpoint is not None:
+        os.environ["AGENTLENS_ENDPOINT"] = endpoint
+    if project is not None:
+        os.environ["AGENTLENS_PROJECT"] = project
+    if tags is not None:
+        os.environ["AGENTLENS_TAGS"] = ",".join(tags)
+    if auto_trace is not None:
+        os.environ["AGENTLENS_AUTO_TRACE"] = str(auto_trace).lower()
+
+    # Reload config from env
+    config.reload()
+
+    # Install auto-tracing if enabled
+    if config.is_active and config.auto_trace:
+        install_auto_trace()
+
+
+def install_auto_trace() -> None:
+    """
+    Register AgentLens as a global LangChain callback handler.
+
+    After calling this, ALL LangChain/LangGraph invocations are traced
+    automatically without passing callbacks explicitly.
+    """
+    global _auto_trace_installed
+    if _auto_trace_installed:
+        return
+
+    try:
+        from langchain_core.callbacks import BaseCallbackHandler
+        from langchain_core.callbacks.manager import (
+            CallbackManager,
+        )
+        # Try to use the global callback approach
+        _install_via_env(config)
+        _auto_trace_installed = True
+        logger.info(
+            f"AgentLens auto-tracing enabled → {config.endpoint} "
+            f"(project: {config.project})"
+        )
+    except ImportError:
+        logger.debug(
+            "langchain-core not installed — auto-trace unavailable. "
+            "Use lens.callback() manually or install langchain-core."
+        )
+
+
+def _install_via_env(cfg: Any) -> None:
+    """
+    Hook into LangChain's global callback system.
+
+    LangChain checks for callbacks in multiple places. We register our handler
+    as a global default so it runs on every invocation.
+    """
+    from agentlens.callbacks.client import IngestClient
+    from agentlens.callbacks.langchain_cb import AgentLensLangChainCallback
+
+    client = IngestClient(base_url=cfg.endpoint)
+
+    handler = AgentLensLangChainCallback(
+        client=client,
+        trace_name=cfg.project,
+        tags=cfg.tags,
+        metadata={"project": cfg.project, "auto_trace": True},
+    )
+
+    # Method 1: Set as environment-level default callbacks
+    try:
+        import langchain_core
+
+        if hasattr(langchain_core, "callbacks"):
+            from langchain_core.globals import set_llm_cache
+            pass
+    except Exception:
+        pass
+
+    # Method 2: Monkey-patch the default callback manager constructor
+    # This is the most reliable approach (same pattern LangSmith uses)
+    try:
+        from langchain_core.callbacks.manager import CallbackManager
+
+        _original_configure = CallbackManager.configure
+
+        @classmethod  # type: ignore
+        def _patched_configure(
+            cls,
+            inheritable_callbacks=None,
+            local_callbacks=None,
+            verbose=False,
+            inheritable_tags=None,
+            local_tags=None,
+            inheritable_metadata=None,
+            local_metadata=None,
+        ):
+            # Create a fresh handler for each run to avoid state leaks
+            run_handler = AgentLensLangChainCallback(
+                client=client,
+                trace_name=cfg.project,
+                tags=cfg.tags,
+                metadata={"project": cfg.project, "auto_trace": True},
+            )
+
+            # Inject our handler into the inheritable callbacks
+            if inheritable_callbacks is None:
+                inheritable_callbacks = [run_handler]
+            elif isinstance(inheritable_callbacks, list):
+                # Don't add duplicates
+                has_agentlens = any(
+                    isinstance(cb, AgentLensLangChainCallback)
+                    for cb in inheritable_callbacks
+                )
+                if not has_agentlens:
+                    inheritable_callbacks = [run_handler] + list(inheritable_callbacks)
+            elif isinstance(inheritable_callbacks, CallbackManager):
+                has_agentlens = any(
+                    isinstance(cb, AgentLensLangChainCallback)
+                    for cb in inheritable_callbacks.handlers
+                )
+                if not has_agentlens:
+                    inheritable_callbacks.add_handler(run_handler)
+
+            return _original_configure.__func__(
+                cls,
+                inheritable_callbacks=inheritable_callbacks,
+                local_callbacks=local_callbacks,
+                verbose=verbose,
+                inheritable_tags=inheritable_tags,
+                local_tags=local_tags,
+                inheritable_metadata=inheritable_metadata,
+                local_metadata=local_metadata,
+            )
+
+        CallbackManager.configure = _patched_configure
+        logger.debug("AgentLens auto-trace installed via CallbackManager patch")
+
+    except Exception as e:
+        logger.warning(f"Could not install auto-trace: {e}")
+
+
+def disable_auto_trace() -> None:
+    """Remove AgentLens from global callbacks."""
+    global _auto_trace_installed
+    try:
+        from langchain_core.callbacks.manager import CallbackManager
+
+        if hasattr(CallbackManager.configure, "__wrapped__"):
+            CallbackManager.configure = CallbackManager.configure.__wrapped__
+    except Exception:
+        pass
+    _auto_trace_installed = False
+    logger.info("AgentLens auto-tracing disabled")

traceagent-0.1.0/agentlens/callbacks/__init__.py

@@ -0,0 +1 @@
+"""Callbacks package — framework integrations."""

traceagent-0.1.0/agentlens/callbacks/client.py

@@ -0,0 +1,61 @@
+"""HTTP client for sending trace data to the AgentLens server."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import queue
+from typing import Any
+from urllib.request import Request, urlopen
+from urllib.error import URLError
+
+logger = logging.getLogger("agentlens")
+
+
+class IngestClient:
+    """
+    Lightweight HTTP client that sends trace/span data to the AgentLens server.
+    Uses a background thread so tracing never blocks your agent.
+    """
+
+    def __init__(self, base_url: str = "http://localhost:6832"):
+        self.base_url = base_url.rstrip("/")
+        self._queue: queue.Queue[tuple[str, str, dict]] = queue.Queue(maxsize=10_000)
+        self._thread = threading.Thread(target=self._worker, daemon=True)
+        self._thread.start()
+
+    def _worker(self) -> None:
+        """Background worker that drains the queue and sends to server."""
+        while True:
+            try:
+                method, path, data = self._queue.get(timeout=1.0)
+                self._send(method, path, data)
+            except queue.Empty:
+                continue
+            except Exception as e:
+                logger.debug(f"AgentLens ingest error: {e}")
+
+    def _send(self, method: str, path: str, data: dict) -> None:
+        url = f"{self.base_url}/api{path}"
+        body = json.dumps(data, default=str).encode("utf-8")
+        req = Request(url, data=body, method=method)
+        req.add_header("Content-Type", "application/json")
+        try:
+            with urlopen(req, timeout=5) as resp:
+                resp.read()
+        except URLError:
+            # Server might not be running — that's fine, don't crash user's code
+            pass
+
+    def send_trace(self, trace_data: dict) -> None:
+        self._queue.put(("POST", "/ingest/trace", {"trace": trace_data}))
+
+    def update_trace(self, trace_data: dict) -> None:
+        self._queue.put(("POST", "/ingest/trace/update", {"trace": trace_data}))
+
+    def send_span(self, span_data: dict) -> None:
+        self._queue.put(("POST", "/ingest/span", {"span": span_data}))
+
+    def update_span(self, span_data: dict) -> None:
+        self._queue.put(("POST", "/ingest/span/update", {"span": span_data}))

traceagent-0.1.0/agentlens/callbacks/decorator.py

@@ -0,0 +1,142 @@
+"""Decorator-based tracing for any Python function."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import traceback
+from typing import Any, Callable, TypeVar
+
+from agentlens.callbacks.client import IngestClient
+from agentlens.models import Span, SpanKind, Trace, _new_id
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class TracerContext:
+    """Manages trace context for decorator-based tracing."""
+
+    def __init__(self, client: IngestClient):
+        self._client = client
+        self._current_trace_id: str | None = None
+        self._span_stack: list[str] = []  # stack of span IDs
+
+    @property
+    def current_trace_id(self) -> str | None:
+        return self._current_trace_id
+
+    @property
+    def current_span_id(self) -> str | None:
+        return self._span_stack[-1] if self._span_stack else None
+
+    def start_trace(self, name: str, inputs: dict | None = None, **kwargs: Any) -> Trace:
+        trace = Trace(name=name, inputs=inputs, **kwargs)
+        self._current_trace_id = trace.id
+        self._span_stack.clear()
+        self._client.send_trace(trace.model_dump())
+        return trace
+
+    def end_trace(self, trace: Trace, outputs: dict | None = None, error: str | None = None):
+        trace.finish(outputs=outputs, error=error)
+        self._client.update_trace(trace.model_dump())
+        self._current_trace_id = None
+        self._span_stack.clear()
+
+    def start_span(
+        self,
+        name: str,
+        kind: SpanKind = SpanKind.CUSTOM,
+        inputs: dict | None = None,
+        **kwargs: Any,
+    ) -> Span:
+        if not self._current_trace_id:
+            # Auto-create a trace
+            trace = self.start_trace(name)
+
+        span = Span(
+            trace_id=self._current_trace_id,
+            parent_id=self.current_span_id,
+            name=name,
+            kind=kind,
+            inputs=inputs,
+            **kwargs,
+        )
+        self._span_stack.append(span.id)
+        self._client.send_span(span.model_dump())
+        return span
+
+    def end_span(self, span: Span, outputs: dict | None = None, error: str | None = None):
+        span.finish(outputs=outputs, error=error)
+        self._client.update_span(span.model_dump())
+        if self._span_stack and self._span_stack[-1] == span.id:
+            self._span_stack.pop()
+
+
+def observe(
+    client: IngestClient,
+    tracer: TracerContext,
+    name: str | None = None,
+    kind: SpanKind = SpanKind.CUSTOM,
+) -> Callable[[F], F]:
+    """
+    Decorator that traces a function call as a span.
+
+    Usage:
+        lens = AgentLens()
+
+        @lens.observe(name="search", kind="tool")
+        def search(query: str):
+            return results
+    """
+
+    def decorator(fn: F) -> F:
+        span_name = name or fn.__qualname__
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                # Capture inputs
+                sig = inspect.signature(fn)
+                try:
+                    bound = sig.bind(*args, **kwargs)
+                    bound.apply_defaults()
+                    inputs = {k: repr(v)[:500] for k, v in bound.arguments.items()}
+                except Exception:
+                    inputs = {"args": repr(args)[:500], "kwargs": repr(kwargs)[:500]}
+
+                span = tracer.start_span(span_name, kind=kind, inputs=inputs)
+                try:
+                    result = await fn(*args, **kwargs)
+                    tracer.end_span(span, outputs={"result": repr(result)[:1000]})
+                    return result
+                except Exception as e:
+                    tracer.end_span(span, error=f"{type(e).__name__}: {e}")
+                    raise
+
+            return async_wrapper  # type: ignore
+
+        else:
+
+            @functools.wraps(fn)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                sig = inspect.signature(fn)
+                try:
+                    bound = sig.bind(*args, **kwargs)
+                    bound.apply_defaults()
+                    inputs = {k: repr(v)[:500] for k, v in bound.arguments.items()}
+                except Exception:
+                    inputs = {"args": repr(args)[:500], "kwargs": repr(kwargs)[:500]}
+
+                span = tracer.start_span(span_name, kind=kind, inputs=inputs)
+                try:
+                    result = fn(*args, **kwargs)
+                    tracer.end_span(span, outputs={"result": repr(result)[:1000]})
+                    return result
+                except Exception as e:
+                    tracer.end_span(span, error=f"{type(e).__name__}: {e}")
+                    raise
+
+            return sync_wrapper  # type: ignore
+
+    return decorator