loopview 0.1.0__tar.gz

loopview-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: loopview
+Version: 0.1.0
+Summary: Watch your AI agents run as a live graph, from any OpenTelemetry trace.
+Keywords: ai-agents,llm,opentelemetry,observability,debugging,tracing
+Author: YasmineZerai
+Author-email: YasmineZerai <zeraiyasmine7@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: pydantic>=2.7
+Requires-Dist: opentelemetry-proto>=1.45
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/YasmineZerai/loopview
+Project-URL: Demo, https://yasminezerai.github.io/loopview/
+Project-URL: Documentation, https://github.com/YasmineZerai/loopview#readme
+Project-URL: Issues, https://github.com/YasmineZerai/loopview/issues
+Description-Content-Type: text/markdown
+
+# loopview
+
+**Debug your AI agents as a live graph, whatever framework they're built with.**
+
+See which agent ran, what it thought, which tool failed, what it did next, and what it cost.
+LangGraph, Pydantic AI, CrewAI, the OpenAI Agents SDK or your own loop: one view, from
+standard OpenTelemetry, on your machine.
+
+![loopview replaying a multi-agent run](https://raw.githubusercontent.com/YasmineZerai/loopview/main/docs/demo.gif)
+
+[Live demo](https://yasminezerai.github.io/loopview/) ·
+[Documentation](https://github.com/YasmineZerai/loopview#readme)
+
+## Try it
+
+```sh
+uvx loopview demo
+```
+
+Your browser opens on a recorded multi-agent run. No API key needed.
+
+## Watch your own agent
+
+```sh
+uvx loopview      # UI and OTLP endpoint on http://127.0.0.1:4318
+```
+
+In your agent's environment:
+
+```sh
+pip install loopview-sdk
+```
+
+```python
+import loopview_sdk
+
+loopview_sdk.connect()  # at the start of your program
+```
+
+`connect()` switches on the OpenTelemetry instrumentation of every agent framework and model
+SDK it finds installed. Agents in other languages can send OTLP over HTTP to
+`http://127.0.0.1:4318/v1/traces`.
+
+Which instrumentation package each framework needs, and everything else, is in the
+[README on GitHub](https://github.com/YasmineZerai/loopview#connect-your-agent).

loopview-0.1.0/README.md

@@ -0,0 +1,45 @@
+# loopview
+
+**Debug your AI agents as a live graph, whatever framework they're built with.**
+
+See which agent ran, what it thought, which tool failed, what it did next, and what it cost.
+LangGraph, Pydantic AI, CrewAI, the OpenAI Agents SDK or your own loop: one view, from
+standard OpenTelemetry, on your machine.
+
+![loopview replaying a multi-agent run](https://raw.githubusercontent.com/YasmineZerai/loopview/main/docs/demo.gif)
+
+[Live demo](https://yasminezerai.github.io/loopview/) ·
+[Documentation](https://github.com/YasmineZerai/loopview#readme)
+
+## Try it
+
+```sh
+uvx loopview demo
+```
+
+Your browser opens on a recorded multi-agent run. No API key needed.
+
+## Watch your own agent
+
+```sh
+uvx loopview      # UI and OTLP endpoint on http://127.0.0.1:4318
+```
+
+In your agent's environment:
+
+```sh
+pip install loopview-sdk
+```
+
+```python
+import loopview_sdk
+
+loopview_sdk.connect()  # at the start of your program
+```
+
+`connect()` switches on the OpenTelemetry instrumentation of every agent framework and model
+SDK it finds installed. Agents in other languages can send OTLP over HTTP to
+`http://127.0.0.1:4318/v1/traces`.
+
+Which instrumentation package each framework needs, and everything else, is in the
+[README on GitHub](https://github.com/YasmineZerai/loopview#connect-your-agent).

loopview-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "loopview"
+version = "0.1.0"
+description = "Watch your AI agents run as a live graph, from any OpenTelemetry trace."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+keywords = [
+    "ai-agents",
+    "llm",
+    "opentelemetry",
+    "observability",
+    "debugging",
+    "tracing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "pydantic>=2.7",
+    "opentelemetry-proto>=1.45",
+]
+
+[[project.authors]]
+name = "YasmineZerai"
+email = "zeraiyasmine7@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/YasmineZerai/loopview"
+Demo = "https://yasminezerai.github.io/loopview/"
+Documentation = "https://github.com/YasmineZerai/loopview#readme"
+Issues = "https://github.com/YasmineZerai/loopview/issues"
+
+[project.scripts]
+loopview = "loopview.cli:main"
+
+[dependency-groups]
+dev = [
+    "httpx2>=2.13.1",
+    "opentelemetry-exporter-otlp-proto-http>=1.45",
+    "opentelemetry-sdk>=1.45",
+    "pytest>=8",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

loopview-0.1.0/pyproject.toml.orig

@@ -0,0 +1,59 @@
+[project]
+name = "loopview"
+version = "0.1.0"
+description = "Watch your AI agents run as a live graph, from any OpenTelemetry trace."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "YasmineZerai", email = "zeraiyasmine7@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["ai-agents", "llm", "opentelemetry", "observability", "debugging", "tracing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "pydantic>=2.7",
+    "opentelemetry-proto>=1.45",
+]
+
+[project.urls]
+Homepage = "https://github.com/YasmineZerai/loopview"
+Demo = "https://yasminezerai.github.io/loopview/"
+Documentation = "https://github.com/YasmineZerai/loopview#readme"
+Issues = "https://github.com/YasmineZerai/loopview/issues"
+
+[project.scripts]
+loopview = "loopview.cli:main"
+
+[dependency-groups]
+dev = [
+    "httpx2>=2.13.1",
+    "opentelemetry-exporter-otlp-proto-http>=1.45",
+    "opentelemetry-sdk>=1.45",
+    "pytest>=8",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

loopview-0.1.0/src/loopview/__init__.py

@@ -0,0 +1,3 @@
+"""loopview: watch AI agents run as a live graph, from any OpenTelemetry trace."""
+
+__version__ = "0.1.0"

loopview-0.1.0/src/loopview/app.py

@@ -0,0 +1,252 @@
+"""The FastAPI application.
+
+One process serves everything on one port:
+- the OTLP/HTTP trace receiver at POST /v1/traces,
+- the JSON API and the live event stream under /api,
+- the browser UI (static files built from ui/).
+
+The UI only ever receives the normalized schema (normalize/schema.py), never
+raw spans; /api/runs/{id}/spans exists for debugging.
+"""
+
+import inspect
+import json
+import time
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import HTMLResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from loopview import __version__
+from loopview.cost.pricing import Pricing
+from loopview.ingest.otlp import (
+    JSON,
+    MAX_BODY_BYTES,
+    BodyTooLarge,
+    OtlpDecodeError,
+    UnsupportedContentType,
+    decode_body,
+    decompress,
+    encode_success_response,
+    spans_to_otlp_json,
+)
+from loopview.ingest.raw import RawSpan
+from loopview.live import LiveHub, running
+from loopview.normalize.schema import NormalizedRun, RunInfo
+from loopview.store.capture import CapturedRequest, CaptureWriter, from_line, load_capture, to_line
+from loopview.store.memory import SessionSummary, TraceStore
+from loopview.tools.report import tools_report
+
+# The UI build (vite) writes its output here. It is generated, not committed.
+STATIC_DIR = Path(__file__).parent / "static"
+# The flagship demo run, recorded from examples/demo (a copy of fixtures/flagship.otlp.jsonl).
+DEMO_RECORDING = Path(__file__).parent / "demo_data" / "flagship.otlp.jsonl"
+
+# Shown when someone runs the server from a source checkout without building the UI.
+_MISSING_UI_PAGE = """<!doctype html>
+<html><body style="font-family:sans-serif;background:#0a0a0b;color:#e5e5e5;padding:40px">
+<h1>loopview is running</h1>
+<p>The UI has not been built. Run <code>npm run build</code> in <code>ui/</code>.</p>
+</body></html>"""
+
+
+# Recent FastAPI versions trace themselves and, on startup, export to the OTLP
+# endpoint in OTEL_* variables: the very ones users set to point their agents at
+# loopview. loopview would then trace every request it receives and send the spans
+# to itself, a loop without end. Older versions have no such option.
+_NO_SELF_TELEMETRY = (
+    {"telemetry": {"tracing": False, "metrics": False, "logs": False, "auto_configure": False}}
+    if "telemetry" in inspect.signature(FastAPI.__init__).parameters
+    else {}
+)
+
+
+def create_app(
+    store: TraceStore | None = None,
+    capture: CaptureWriter | None = None,
+    static_dir: Path = STATIC_DIR,
+    pricing: Pricing | None = None,
+) -> FastAPI:
+    store = store if store is not None else TraceStore()
+    hub = LiveHub(store, pricing)
+    hub.mark(run.trace_id for run in store.runs())  # runs loaded from --persist
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        async with running(hub):
+            yield
+
+    app = FastAPI(title="loopview", version=__version__, lifespan=lifespan, **_NO_SELF_TELEMETRY)
+    app.state.store = store
+    app.state.hub = hub
+
+    # --- OTLP receiver ----------------------------------------------------------
+
+    @app.post("/v1/traces")
+    async def receive_traces(request: Request) -> Response:
+        # `async def` keeps every store update on the event loop, one at a time.
+        content_type = request.headers.get("content-type", "")
+        declared_length = int(request.headers.get("content-length") or 0)
+        if declared_length > MAX_BODY_BYTES:
+            raise HTTPException(413, "request body too large")
+        try:
+            body = decompress(await request.body(), request.headers.get("content-encoding"))
+            spans = decode_body(body, content_type)
+        except UnsupportedContentType as exc:
+            raise HTTPException(415, str(exc)) from exc
+        except BodyTooLarge as exc:
+            raise HTTPException(413, str(exc)) from exc
+        except OtlpDecodeError as exc:
+            # 400 tells the exporter not to retry.
+            raise HTTPException(400, str(exc)) from exc
+
+        received_at_ns = time.time_ns()
+        hub.mark(store.add_spans(spans, received_at_ns=received_at_ns))
+        if capture is not None:
+            capture.write(CapturedRequest(received_at_ns, content_type, body))
+
+        payload, media_type = encode_success_response(content_type)
+        return Response(content=payload, media_type=media_type)
+
+    @app.post("/v1/loopview/span-starts")
+    async def receive_span_starts(request: Request) -> Response:
+        """Start reports from loopview-sdk: OTLP-encoded spans that have just
+        started (no end time). Standard exporters only send ended spans, so this
+        is what lets a step show as running the moment it begins."""
+        content_type = request.headers.get("content-type", "")
+        try:
+            body = decompress(await request.body(), request.headers.get("content-encoding"))
+            spans = decode_body(body, content_type)
+        except UnsupportedContentType as exc:
+            raise HTTPException(415, str(exc)) from exc
+        except OtlpDecodeError as exc:
+            raise HTTPException(400, str(exc)) from exc
+        hub.mark(store.add_started_spans(spans))
+        payload, media_type = encode_success_response(content_type)
+        return Response(content=payload, media_type=media_type)
+
+    # --- normalized runs and live events ------------------------------------------
+
+    @app.get("/api/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok", "version": __version__}
+
+    @app.get("/api/runs")
+    def list_runs() -> list[RunInfo]:
+        return hub.run_infos()
+
+    @app.get("/api/runs/{trace_id}")
+    def get_run(trace_id: str) -> NormalizedRun:
+        normalized = hub.get(trace_id)
+        if normalized is None:
+            raise HTTPException(404, "run not found")
+        return normalized
+
+    @app.get("/api/sessions")
+    def list_sessions() -> list[SessionSummary]:
+        return store.sessions()
+
+    @app.get("/api/tools")
+    def tools(session: str | None = None, runs: str | None = None) -> dict[str, Any]:
+        """The Tools tab: how tools behave across runs. All runs by default, or one
+        session's (`?session=id`), or a list (`?runs=id1,id2`). Recomputed on
+        every request, which is cheap at a few hundred runs."""
+        if runs:
+            trace_ids = [t for t in runs.split(",") if t]
+        elif session:
+            match = [s for s in store.sessions() if s.session_id == session]
+            if not match:
+                raise HTTPException(404, "session not found")
+            trace_ids = match[0].trace_ids
+        else:
+            trace_ids = [run.trace_id for run in store.runs()]
+        normalized = [n for n in (hub.get(t) for t in trace_ids) if n is not None]
+        if runs and not normalized:
+            raise HTTPException(404, "none of these runs were found")
+        return tools_report(normalized)
+
+    @app.get("/api/events")
+    async def events() -> StreamingResponse:
+        return StreamingResponse(
+            hub.events(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    # --- import, export, demo -----------------------------------------------------
+
+    @app.get("/api/runs/{trace_id}/export")
+    def export_run(trace_id: str) -> Response:
+        """The run as a capture file: one OTLP/JSON request per original arrival
+        batch, so importing it replays the same timing."""
+        run = store.get_run(trace_id)
+        if run is None:
+            raise HTTPException(404, "run not found")
+        batches: dict[int, list[RawSpan]] = {}
+        for span_id, span in run.spans.items():
+            batches.setdefault(run.received_ns[span_id], []).append(span)
+        lines = [
+            to_line(CapturedRequest(received, JSON, json.dumps(spans_to_otlp_json(spans)).encode()))
+            for received, spans in sorted(batches.items())
+        ]
+        return Response(
+            content="\n".join(lines) + "\n",
+            media_type="application/x-ndjson",
+            headers={"Content-Disposition": f'attachment; filename="run-{trace_id[:8]}.jsonl"'},
+        )
+
+    @app.post("/api/import")
+    async def import_runs(request: Request) -> dict[str, list[str]]:
+        changed: list[str] = []
+        try:
+            for line in (await request.body()).decode("utf-8").splitlines():
+                if not line.strip():
+                    continue
+                captured = from_line(line)
+                spans = decode_body(captured.body, captured.content_type)
+                changed += store.add_spans(spans, received_at_ns=captured.received_at_ns)
+        except (ValueError, KeyError, TypeError) as exc:
+            raise HTTPException(400, f"not a loopview JSONL file: {exc}") from exc
+        hub.mark(changed)
+        return {"trace_ids": sorted(set(changed))}
+
+    @app.post("/api/demo")
+    def load_demo() -> dict[str, list[str]]:
+        return {"trace_ids": load_demo_into(store, hub)}
+
+    @app.get("/api/runs/{trace_id}/spans")
+    def run_spans(trace_id: str) -> list[RawSpan]:
+        """Raw spans of one run, for debugging only. The UI never uses this."""
+        run = store.get_run(trace_id)
+        if run is None:
+            raise HTTPException(404, "run not found")
+        return sorted(run.spans.values(), key=lambda s: s.start_time_unix_nano)
+
+    # --- UI ---------------------------------------------------------------------
+
+    if (static_dir / "index.html").exists():
+        # html=True makes "/" serve index.html. Mounted last so /api and /v1 win.
+        app.mount("/", StaticFiles(directory=static_dir, html=True), name="ui")
+    else:
+
+        @app.get("/", response_class=HTMLResponse)
+        def missing_ui() -> str:
+            return _MISSING_UI_PAGE
+
+    return app
+
+
+def load_demo_into(store: TraceStore, hub: LiveHub | None = None) -> list[str]:
+    """Load the bundled demo recording. Loading it twice is harmless: spans are
+    keyed by id, so the same run is simply updated."""
+    demo = TraceStore()
+    load_capture(demo, DEMO_RECORDING)
+    trace_ids = [run.trace_id for run in demo.runs()]
+    load_capture(store, DEMO_RECORDING)
+    if hub is not None:
+        hub.mark(trace_ids)
+    return trace_ids

loopview-0.1.0/src/loopview/cli.py

@@ -0,0 +1,128 @@
+"""Command line entry point: `loopview`.
+
+argparse (standard library) instead of click/typer: we only need a few flags,
+so an extra dependency is not worth it.
+"""
+
+import argparse
+import logging
+import threading
+import webbrowser
+from pathlib import Path
+from types import FrameType
+
+import uvicorn
+
+from loopview import __version__
+from loopview.app import create_app, load_demo_into
+from loopview.cost.pricing import merged_pricing
+from loopview.live import LiveHub
+from loopview.store.capture import CaptureWriter, load_capture
+from loopview.store.memory import DEFAULT_MAX_RUNS, TraceStore
+
+# 4318 is the standard OTLP/HTTP port, so exporters work with only an endpoint change.
+DEFAULT_PORT = 4318
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="loopview", description="Watch your AI agents run as a live graph."
+    )
+    parser.add_argument(
+        "command",
+        nargs="?",
+        choices=["demo"],
+        help="demo: start with a recorded multi-agent run loaded and open the browser",
+    )
+    parser.add_argument(
+        "--host", default="127.0.0.1", help="interface to bind (default: localhost only)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=DEFAULT_PORT, help=f"port (default: {DEFAULT_PORT})"
+    )
+    parser.add_argument(
+        "--persist",
+        type=Path,
+        metavar="FILE",
+        help="save every received request to this JSONL file and reload it on start",
+    )
+    parser.add_argument(
+        "--max-runs",
+        type=int,
+        default=DEFAULT_MAX_RUNS,
+        help=f"how many recent runs to keep in memory (default: {DEFAULT_MAX_RUNS})",
+    )
+    parser.add_argument(
+        "--prices",
+        type=Path,
+        metavar="FILE",
+        help="JSON file of model prices, replacing the bundled ones (see cost/pricing.json)",
+    )
+    parser.add_argument("--no-browser", action="store_true", help="don't open the browser")
+    parser.add_argument("--version", action="version", version=f"loopview {__version__}")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    logging.getLogger("asyncio").addFilter(_IgnoreWindowsConnectionReset())
+    store = TraceStore(max_runs=args.max_runs)
+    capture = None
+    if args.persist is not None:
+        if args.persist.exists():
+            loaded = load_capture(store, args.persist)
+            print(f"loaded {loaded} requests from {args.persist}")
+        capture = CaptureWriter(args.persist)
+    if args.command == "demo":
+        load_demo_into(store)
+
+    print(f"loopview {__version__}")
+    print(f"  UI:            http://{args.host}:{args.port}")
+    print(f"  OTLP endpoint: http://{args.host}:{args.port}/v1/traces")
+    if capture is not None:
+        print(f"  persisting to: {args.persist}")
+    # Flush now: when stdout is a pipe, Python buffers it and the banner would
+    # only appear when the server stops.
+    print(flush=True)
+    if args.command == "demo" and not args.no_browser:
+        # Give the server a moment to start listening before the browser asks.
+        url = f"http://{args.host}:{args.port}"
+        threading.Timer(1.0, webbrowser.open, args=[url]).start()
+    app = create_app(store=store, capture=capture, pricing=merged_pricing(args.prices))
+    server = _Server(
+        uvicorn.Config(app, host=args.host, port=args.port, log_level="warning"), app.state.hub
+    )
+    try:
+        server.run()
+    except KeyboardInterrupt:
+        # uvicorn re-raises Ctrl+C once it has shut down cleanly; that's the
+        # normal way out, not an error.
+        print("loopview stopped")
+    finally:
+        if capture is not None:
+            capture.close()
+
+
+class _Server(uvicorn.Server):
+    """uvicorn's server, which also ends the live streams as soon as Ctrl+C is
+    pressed. Otherwise it would wait for the browser's open event stream, which
+    never closes on its own, and then cancel it with a traceback."""
+
+    def __init__(self, config: uvicorn.Config, hub: LiveHub) -> None:
+        super().__init__(config)
+        self.hub = hub
+
+    def handle_exit(self, sig: int, frame: FrameType | None) -> None:
+        self.hub.close()
+        super().handle_exit(sig, frame)
+
+
+class _IgnoreWindowsConnectionReset(logging.Filter):
+    """On Windows, asyncio logs a ConnectionResetError when a browser closes a
+    connection abruptly (a known, harmless Python issue). Drop that one record."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        error = record.exc_info[1] if record.exc_info else None
+        return not isinstance(error, ConnectionResetError)
+
+
+if __name__ == "__main__":
+    main()

loopview-0.1.0/src/loopview/cost/__init__.py

@@ -0,0 +1 @@
+"""Cost: where the tokens of each model call came from, and what they cost."""