aeyeagent 0.1.0__tar.gz

aeyeagent-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Database
+aeyeagent.db
+
+# Node
+frontend/node_modules/
+frontend/dist/
+backend/static/

aeyeagent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

aeyeagent-0.1.0/Makefile

@@ -0,0 +1,47 @@
+.PHONY: dev backend frontend install seed test test-backend test-reset build package
+
+# Isolated DB for the end-to-end test harness (keeps real traces untouched)
+TESTDB ?= $(PWD)/tests/aeyeagent_test.db
+
+# Start both servers concurrently (Ctrl+C kills both)
+dev:
+	@make -j2 backend frontend
+
+# Backend — FastAPI on :7891 with auto-reload
+backend:
+	uv run uvicorn backend.main:app --port 7891 --reload
+
+# Frontend — Vite dev server on :5173
+frontend:
+	cd frontend && npm run dev -- --port 8008
+
+# Install all deps (Python + Node)
+install:
+	uv sync
+	cd frontend && npm install
+
+# Build the React frontend into backend/static/ for bundled pip distribution
+build:
+	cd frontend && npm install && npm run build
+
+# Build a distributable wheel (run `make build` first)
+package: build
+	uv build
+
+# Seed the DB with demo traces
+seed:
+	uv run python -m backend.demo_agent
+
+# ── End-to-end test harness ──────────────────────────────────────────────────
+# 1) make test-backend   → dashboard API on :7891 against the isolated test DB
+# 2) make frontend       → UI on :5173
+# 3) make test           → run every agent scenario into that DB, then refresh UI
+test-backend:
+	AEYEAGENT_DB="$(TESTDB)" uv run uvicorn backend.main:app --port 7891 --reload
+
+test:
+	AEYEAGENT_DB="$(TESTDB)" uv run python -m tests.run_all
+
+# Wipe the test DB for a clean slate
+test-reset:
+	rm -f "$(TESTDB)" "$(TESTDB)-wal" "$(TESTDB)-shm"

aeyeagent-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,236 @@
+# AeyeAgent
+
+> **Visual debugger and observability dashboard for PydanticAI agent pipelines**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![PydanticAI 1.x](https://img.shields.io/badge/pydantic--ai-1.x-purple.svg)](https://docs.pydantic.dev/ai)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+AeyeAgent instruments your PydanticAI agents via OpenTelemetry, stores every span locally in SQLite, and serves a React dashboard at `http://localhost:7891`. Zero config. Nothing leaves your machine.
+
+---
+
+## Features
+
+- **Run Graph** — React Flow graph of each run: agent node, tool nodes clustered by toolset, animated data-flow edges, sub-agent delegation chains
+- **Topology View** — full architecture map of all agents and tools ever seen across all runs; unused nodes dimmed
+- **Timeline** — per-run causal story: `INPUT → [agent band + named tool pills] → OUTPUT`. Tool pills sized by real duration, parallel tool calls stacked on separate rows. Scroll to zoom, scroll left/right to pan.
+- **Inspector Panel** — click any node to open a right-side panel with all spans for that node, plus a **Tool Calls** section listing every tool's input/output (expandable, Text/JSON toggle) when viewing an agent
+- **Conversation Grouping** — multi-turn runs sharing a `message_history` are grouped in the run selector (Turn 1 → Turn N), so you can trace a full conversation, not just isolated runs
+- **Error Highlighting** — red glow on failing nodes and edges; `ERROR` output cap on the timeline
+- **Toolset Clustering** — tools from the same `FunctionToolset` share a color across graph, timeline, and inspector
+- **Light / Dark Mode** — one-click toggle
+- **Live Runs** — auto-refreshes every 5s; animated live indicator for in-progress runs
+- **Persistent Layouts** — node positions dragged on the graph are saved to DB per agent
+- **Local-first** — all data in `~/.aeyeagent/aeyeagent.db`; no cloud, no external service
+
+---
+
+## Quick Start
+
+```bash
+pip install aeyeagent
+```
+
+```python
+# At the top of your script, before any agents are defined or run:
+from aeyeagent import instrument_pydantic_ai
+instrument_pydantic_ai()
+
+from pydantic_ai import Agent
+
+agent = Agent("openai:gpt-4o", name="my_agent")
+result = agent.run_sync("Hello!")
+# → AeyeAgent dashboard: http://localhost:7891
+```
+
+> **Using Logfire or another OTEL tool?**
+> Call `instrument_pydantic_ai()` **after** any other OpenTelemetry setup. AeyeAgent detects an existing `TracerProvider` and attaches to it rather than replacing it, so both tools capture spans side-by-side without conflict.
+>
+> ```python
+> import logfire
+> logfire.configure()                # set up Logfire first
+>
+> from aeyeagent import instrument_pydantic_ai
+> instrument_pydantic_ai()          # attaches to Logfire's existing provider
+> ```
+
+**Always name your agents.** AeyeAgent auto-generates a name if you omit one (e.g. `str_a3f2`), but an explicit name keeps the dashboard readable and run history consistent:
+
+```python
+agent = Agent("openai:gpt-4o", name="onboarding_agent")
+```
+
+---
+
+## How It Works
+
+```
+Your App
+  └─ instrument_pydantic_ai()
+       ├─ OTEL SDK → AeyeAgentExporter → SQLite (~/.aeyeagent/aeyeagent.db)
+       └─ Background scanner (every 5s) → topology discovery
+Dashboard (http://localhost:7891)
+  └─ FastAPI backend  ←→  React + React Flow frontend
+```
+
+- **Agent naming** — monkeypatches `pydantic_ai.Agent.__init__` to assign a deterministic name to unnamed agents at construction time, keeping topology and run views consistent
+- **Span classification** — OTEL spans are classified by `gen_ai.operation.name`: `invoke_agent` → agent, `execute_tool` → tool, `chat` → model
+- **Run splitting** — one OTEL trace may contain multiple independent top-level agents (e.g. siblings under a Logfire request span); AeyeAgent splits them into separate logical runs automatically
+- **Conversation grouping** — PydanticAI's `gen_ai.conversation.id` (shared across runs that reuse `message_history`) is read from span attributes and used to group multi-turn conversations in the run selector
+
+---
+
+## Dashboard Walkthrough
+
+### Top Bar
+
+- **Run selector** — dropdown grouped by conversation. Multi-turn runs appear as `AgentName · 14:03:21 · 3 turns` with each turn listed as `Turn 1 · 14:03 (12 spans)`. Includes a live indicator for in-progress runs.
+- **Show Topology** — switch to the full architecture overview
+- **Refresh / Theme toggle** — manual re-fetch; light/dark switch
+
+### Run View (Graph)
+
+- **Agent node** at center — label, model name, LLM call count; click to open the inspector
+- **Tool nodes** around it, clustered and color-coded by `FunctionToolset`
+- **Animated dashed edges** — marching dashes show data flowing tool → agent
+- **Dimmed nodes/edges** — tools wired in topology but not called in this run appear faded
+- **Error state** — failing node gets a red border + glow; edge leading into it glows red
+
+### Topology View
+
+All agents and tools seen across every run, laid out as an architecture diagram. Used nodes are fully opaque; unused are dimmed. Click **Show Run View** to return.
+
+### Timeline Strip
+
+The strip at the bottom is a **causal story**, not a raw span dump. It reads left-to-right:
+
+```
+INPUT  ┌─ AgentName · 112ms ───────────────────────────────────┐  OUTPUT
+"..."  │  ▢ tool_a   ▢ tool_b  (parallel calls, row-stacked)   │  "result"
+       └───────────────────────────────────────────────────────┘
+```
+
+- **INPUT cap** (far left) — the prompt that started the run. Hover → preview; click → agent in inspector.
+- **Agent band** — translucent band spanning the agent's full duration. Sub-agents nest as indented sub-bands with a shared time axis, so you can see delegation and where a sub-agent failed.
+- **Tool pills** — the primary events. Named on the pill, colored by toolset (matching graph nodes), sized by actual duration. Concurrent calls stack on separate rows — parallelism is visible at a glance.
+- **OUTPUT cap** (far right) — the final result. Green = success; turns red and shows `ERROR` on failure.
+- **Scroll up/down** → zoom in/out (cursor-anchored)
+- **Scroll left/right** → pan when zoomed
+- **Hover any element** → peek card with input, output, duration
+- **Click any pill or band** → selects that node in the inspector
+
+### Inspector Panel
+
+Opens on the right when a node is selected:
+
+- **Stats** — call count, error count, avg latency, total time
+- **SPANS** — this node's raw spans with full INPUT/OUTPUT (click to expand; Text/JSON toggle when value is valid JSON)
+- **TOOL CALLS** *(agent nodes only)* — every tool called in this run, in order, each with expandable INPUT/OUTPUT and Text/JSON toggle. See all tool I/O in one place without clicking node-by-node.
+
+---
+
+## Configuration
+
+```python
+instrument_pydantic_ai(
+    port=7891,                            # dashboard port (auto-increments if taken)
+    db_path="~/.aeyeagent/aeyeagent.db", # or set AEYEAGENT_DB env var
+    open_browser=False,                   # open the dashboard automatically on start
+)
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `port` | `7891` | Dashboard port; finds next free port if already in use |
+| `db_path` | `~/.aeyeagent/aeyeagent.db` | SQLite file path |
+| `open_browser` | `False` | Open `http://localhost:<port>` in browser on startup |
+
+**Environment variable:** `AEYEAGENT_DB=/path/to/file.db` overrides `db_path`.
+
+---
+
+## Extending to Other Frameworks
+
+AeyeAgent's capture layer is built around a `FrameworkAdapter` interface. Adding support for LangChain, CrewAI, or any other framework means creating one file — no edits to shared code.
+
+```python
+# backend/adapters/my_framework.py
+from backend.adapters.base import FrameworkAdapter
+
+class MyFrameworkAdapter(FrameworkAdapter):
+    name = "my_framework"
+
+    def owns_span(self, raw) -> bool:
+        # Return True only for spans emitted by this framework
+        ...
+
+    def parse_span(self, trace_id: str, raw):
+        # Convert a ReadableSpan → Span model
+        ...
+
+    def discover_topology(self) -> dict[str, dict]:
+        # Introspect live objects to build the agent/tool map
+        ...
+
+# aeyeagent/__init__.py
+def instrument_my_framework(**kwargs):
+    from backend.adapters import register
+    register(MyFrameworkAdapter())
+    ...
+```
+
+See `backend/adapters/pydantic_ai.py` as the reference implementation.
+
+---
+
+## Development Setup
+
+**Requirements:** Python 3.10+, Node 18+, [`uv`](https://github.com/astral-sh/uv) (recommended) or `pip`
+
+```bash
+git clone https://github.com/emumba/aeyeagent
+cd AeyeAgent
+
+# Python deps
+uv sync
+
+# Backend (port 7891)
+uvicorn backend.main:app --reload --port 7891
+
+# Frontend (separate terminal) — proxies API calls to :7891
+cd frontend && npm install && npm run dev
+# → http://localhost:5173
+```
+
+**Test harness** — 24 end-to-end scenarios covering basic runs, tool chains, multi-toolset agents, sub-agent delegation, error handling, and agent renaming:
+
+```bash
+make test          # run all scenarios against an isolated test DB
+make test-reset    # wipe test DB and re-run
+make test-backend  # start backend pointed at the test DB
+```
+
+Frontend type check:
+
+```bash
+cd frontend && npx tsc --noEmit
+```
+
+---
+
+## Contributing
+
+- Fork → branch → PR
+- **New framework adapter** — implement `FrameworkAdapter`, register it, add scenarios in `tests/scenarios/`
+- **Frontend changes** — `npx tsc --noEmit` must pass before submitting
+
+---
+
+## Roadmap
+
+- [ ] LangChain adapter
+- [ ] CrewAI adapter
+- [ ] Span search and filter in the timeline
+- [ ] Export run as JSON / HTML report
+- [ ] Multi-machine / shared DB mode

aeyeagent-0.1.0/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/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",
+]

aeyeagent-0.1.0/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