aeyeagent 0.1.0__py3-none-any.whl

aeyeagent/__init__.py

@@ -0,0 +1,201 @@
+"""AeyeAgent — local-first visual debugger for AI agent pipelines.
+
+Usage in your project:
+    import aeyeagent
+    aeyeagent.instrument_pydantic_ai()
+
+    # Then run your PydanticAI agents as normal.
+    # Open http://localhost:7891 (or your chosen port) to view traces.
+
+For future frameworks:
+    aeyeagent.instrument_langchain()   # not yet implemented
+    aeyeagent.instrument_crewai()      # not yet implemented
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+
+_initialized = False
+
+
+# ── Base instrument — framework-agnostic ─────────────────────────────────────
+
+def instrument(
+    port: int = 7891,
+    db_path: str | Path | None = None,
+    open_browser: bool = False,
+) -> int:
+    """Start the AeyeAgent backend server and configure the database.
+
+    This is the framework-agnostic base. It sets up the DB and web UI
+    but does NOT wire up any OTEL or agent discovery. Use a framework-
+    specific function like ``instrument_pydantic_ai()`` instead.
+
+    Returns the actual port the server is listening on.
+    """
+    global _initialized
+
+    from backend import store
+
+    # ── 1. Point the store at the right DB file ──────────────────────────
+    if db_path is not None:
+        resolved = Path(db_path)
+    else:
+        resolved = Path.home() / ".aeyeagent" / "aeyeagent.db"
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    store.configure_db(resolved)
+
+    # ── 2. Start the web UI backend in the background ────────────────────
+    actual_port = _start_server(port)
+
+    _initialized = True
+    time.sleep(0.3)
+    print(f"[aeyeagent] dashboard → http://localhost:{actual_port}")
+
+    if open_browser:
+        import webbrowser
+        webbrowser.open(f"http://localhost:{actual_port}")
+
+    return actual_port
+
+
+# ── PydanticAI-specific instrumentation ──────────────────────────────────────
+
+def instrument_pydantic_ai(
+    port: int = 7891,
+    db_path: str | Path | None = None,
+    open_browser: bool = False,
+) -> None:
+    """One-line setup for PydanticAI projects.
+
+    Wires up OpenTelemetry span capture, starts PydanticAI-specific
+    agent/tool auto-discovery, and launches the AeyeAgent web UI.
+
+    Call once at the top of your script, before any agents run.
+
+    Args:
+        port:         Port for the AeyeAgent web UI (default 7891).
+        db_path:      Where to store the SQLite database.
+                      Defaults to ~/.aeyeagent/aeyeagent.db
+        open_browser: Open http://localhost:<port> automatically after startup.
+    """
+    # ── 1. Base setup (DB + server) ──────────────────────────────────────
+    instrument(port=port, db_path=db_path, open_browser=open_browser)
+
+    # ── 2. Wire up OpenTelemetry ─────────────────────────────────────────
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+
+    from backend.collector import AeyeAgentExporter
+
+    exporter = AeyeAgentExporter()
+    processor = SimpleSpanProcessor(exporter)
+
+    existing = trace.get_tracer_provider()
+    if hasattr(existing, 'add_span_processor'):
+        existing.add_span_processor(processor)
+    else:
+        provider = TracerProvider()
+        provider.add_span_processor(processor)
+        trace.set_tracer_provider(provider)
+
+    # ── 3. Register the PydanticAI adapter, then start topology discovery ─
+    from backend import adapters
+    from backend.adapters.pydantic_ai import PydanticAIAdapter
+
+    adapters.register(PydanticAIAdapter())   # setup() applies the auto-naming patch
+    _start_topology_scanner()
+
+
+# ── Topology auto-discovery (framework-neutral) ──────────────────────────────
+
+def _start_topology_scanner() -> None:
+    """Background thread: every 5s merge each registered adapter's discovered
+    topology and persist it when it changes.
+
+    Framework specifics (how agents are found, named, introspected) live in the
+    adapters — this orchestrator is framework-neutral.
+    """
+    import hashlib
+    import json
+
+    from backend import adapters, store
+
+    _last_hash: list[str | None] = [None]
+
+    def _scan() -> None:
+        while True:
+            time.sleep(5)
+            try:
+                topology: dict[str, dict] = {}
+                for adapter in adapters.registered():
+                    try:
+                        topology.update(adapter.discover_topology())
+                    except Exception:
+                        continue
+                if not topology:
+                    continue
+
+                h = hashlib.md5(json.dumps(topology, sort_keys=True).encode()).hexdigest()
+                if h != _last_hash[0]:
+                    store.save_topology(topology)
+                    _last_hash[0] = h
+            except Exception:
+                pass  # never crash the background thread
+
+    threading.Thread(target=_scan, daemon=True).start()
+
+
+# ── Server management ────────────────────────────────────────────────────────
+
+def _is_aeyeagent(port: int) -> bool:
+    import urllib.request
+    try:
+        with urllib.request.urlopen(f"http://localhost:{port}/_health", timeout=1) as r:
+            import json
+            return json.loads(r.read()).get("service") == "aeyeagent"
+    except Exception:
+        return False
+
+
+def _port_in_use(port: int) -> bool:
+    import socket
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        return s.connect_ex(('localhost', port)) == 0
+
+
+def _find_free_port(start: int) -> int:
+    """Find the first free port at or after `start`."""
+    import socket
+    port = start
+    while True:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                s.bind(('localhost', port))
+                return port   # bind succeeded → port is free
+            except OSError:
+                port += 1
+
+
+def _start_server(port: int) -> int:
+    if _port_in_use(port):
+        if _is_aeyeagent(port):
+            return port  # our server already running (e.g. hot-reload) — reuse silently
+        free = _find_free_port(port + 1)
+        print(f"[aeyeagent] port {port} in use, using {free} instead")
+        port = free
+
+    import uvicorn
+    from backend.main import app
+
+    def _run() -> None:
+        uvicorn.run(app, host="localhost", port=port, log_level="error")
+
+    threading.Thread(target=_run, daemon=True).start()
+    return port

aeyeagent-0.1.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: aeyeagent
+Version: 0.1.0
+Summary: Local-first visual debugger for PydanticAI agent pipelines
+Requires-Python: <3.15,>=3.11
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: opentelemetry-api>=1.24.0
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: pydantic-ai>=0.0.13
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'

aeyeagent-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+aeyeagent/__init__.py,sha256=kWm8ElK8njZgjplrj1yGlIGC4vDg65Y67KErN6NxLOs,7160
+backend/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+backend/collector.py,sha256=VUge_aGNDu_3Wo1Lhyc4K9dwX-jj96oqqQkjA-sAGuQ,3814
+backend/config.py,sha256=TXQCKOpswKYEUpqfl_FdauJhdGvE6-UdZ1FBvOTcIJc,560
+backend/demo_agent.py,sha256=mmXa7zTRff-gOTNiYWpJF3D-QjTOFYRTXr3MvN4ImBY,10091
+backend/graph.py,sha256=GrgzPyRfDmEqBJwEpe5ne9q1NnQ8xJZRohTfr3WWyB4,17762
+backend/main.py,sha256=hL3v64x1xqXKJOX0LCzoAdlgH3AFtMgH1MaszYqmJ3A,2105
+backend/models.py,sha256=cXGMI8ZgWhtghiCeoqk-br-2IZKOxGZslJqw6xMzPww,2457
+backend/store.py,sha256=85oc-8WKgHHcXAzsCZbs00sUjrJwssUkUHg4n333hO8,23805
+backend/adapters/__init__.py,sha256=1ZVOl5qWfj6zvISnV_w3CW7xfXMFiHbE6qJcXuTqdXU,432
+backend/adapters/base.py,sha256=ZO2D4ohoctZHg3Nsd88yVEiVlurOe_JwtKKP-KItSq4,3283
+backend/adapters/pydantic_ai.py,sha256=fSOzWtHlvYmlcwz5ej9f3xS4uDBPj_1mzjNR0Rl68DA,14166
+backend/routers/__init__.py,sha256=g4T93NGpmq95O-voyfV81YTCHQDUECTRgvUJsVxD7X8,46
+backend/routers/health.py,sha256=aZLGSp4vGOO5COsCDB28KwZx9lUFqeybMm0Y0L_tmFw,228
+backend/routers/layout.py,sha256=lq2_w73tZ45xFT9wiXbOMzNJZPHtstdBx6VmXOHVUUQ,561
+backend/routers/runs.py,sha256=dkdaQbXnObeVxeh3cZJyBk_GN_o9-BrCj8fOE5mdaGg,1070
+backend/routers/topology.py,sha256=yCk1seIetEnbYlarouxDnl_cSCcUbk5UIP4qDd5lcBU,530
+aeyeagent-0.1.0.dist-info/METADATA,sha256=u3GMprJyUnKl2qtWkuovSiYU7yjxOhQXMqW5RzhehSs,437
+aeyeagent-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+aeyeagent-0.1.0.dist-info/RECORD,,

aeyeagent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

backend/adapters/__init__.py

@@ -0,0 +1,23 @@
+"""Framework adapters.
+
+Public surface for the rest of the app. Adding a framework = add a module here
+with a FrameworkAdapter subclass and register it from its instrument_* entrypoint.
+"""
+
+from .base import (
+    FrameworkAdapter,
+    attr,
+    ns_to_dt,
+    owning_adapter,
+    register,
+    registered,
+)
+
+__all__ = [
+    "FrameworkAdapter",
+    "attr",
+    "ns_to_dt",
+    "owning_adapter",
+    "register",
+    "registered",
+]

backend/adapters/base.py

@@ -0,0 +1,89 @@
+"""Framework adapter interface + registry.
+
+Each agentic framework plugs in by subclassing :class:`FrameworkAdapter` and
+registering an instance via :func:`register`. Shared code — the OTEL collector
+and the topology scanner — only talks to this registry, so adding a framework
+is purely additive and can't break the existing ones.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+
+from opentelemetry.sdk.trace import ReadableSpan
+
+from ..models import Span
+
+
+# ── Shared helpers for adapters ──────────────────────────────────────────────
+
+def ns_to_dt(ns: int) -> datetime:
+    """Nanosecond epoch → timezone-aware datetime."""
+    return datetime.fromtimestamp(ns / 1e9, tz=timezone.utc)
+
+
+def attr(span: ReadableSpan, key: str) -> str | None:
+    """Read a span attribute as a string (or None)."""
+    val = span.attributes.get(key) if span.attributes else None
+    return str(val) if val is not None else None
+
+
+# ── Adapter interface ────────────────────────────────────────────────────────
+
+class FrameworkAdapter(ABC):
+    """Captures one agentic framework into AeyeAgent's generic data model.
+
+    Subclasses live in their own file under ``backend/adapters/`` and implement
+    the methods below; nothing else in the codebase needs to change to add one.
+    """
+
+    name: str = "framework"
+
+    def setup(self) -> None:
+        """One-time side effects (e.g. monkeypatching). Default: nothing."""
+
+    @abstractmethod
+    def owns_span(self, raw: ReadableSpan) -> bool:
+        """Return True if this OTEL span was emitted by this framework."""
+
+    @abstractmethod
+    def parse_span(self, trace_id: str, raw: ReadableSpan) -> Span | None:
+        """Convert a ReadableSpan into a generic :class:`Span` (None to skip)."""
+
+    def discover_topology(self) -> dict[str, dict]:
+        """Discover the static architecture as ``{agent_name: info}``.
+
+        ``info`` shape: ``{model_name, output_type, deps_type, has_instructions,
+        name_inferred, tools: [{name, toolset_index, max_retries}]}``.
+        Default: nothing (frameworks without static discovery can rely on spans).
+        """
+        return {}
+
+
+# ── Registry ─────────────────────────────────────────────────────────────────
+
+_ADAPTERS: list[FrameworkAdapter] = []
+
+
+def register(adapter: FrameworkAdapter) -> None:
+    """Register an adapter (idempotent per type) and run its one-time setup."""
+    if any(type(a) is type(adapter) for a in _ADAPTERS):
+        return
+    adapter.setup()
+    _ADAPTERS.append(adapter)
+
+
+def registered() -> list[FrameworkAdapter]:
+    return list(_ADAPTERS)
+
+
+def owning_adapter(raw: ReadableSpan) -> FrameworkAdapter | None:
+    """First registered adapter that claims this span, or None."""
+    for a in _ADAPTERS:
+        try:
+            if a.owns_span(raw):
+                return a
+        except Exception:
+            continue
+    return None