loopview 0.1.0__py3-none-any.whl

loopview/devtools/__init__.py

@@ -0,0 +1 @@
+"""Developer tools, not used at runtime."""

loopview/devtools/dump_normalized.py

@@ -0,0 +1,211 @@
+"""Write the normalized form of every fixture as JSON.
+
+Used for the UI tests, and for the hosted demo (a static build of the UI that
+reads recorded runs from files instead of a server). Also writes tools.json, the
+Tools tab's report.
+
+Most fixtures hold one run and become `<name>.json`. A fixture with several runs
+(the MCP tools study) becomes `<name>-01.json`, `<name>-02.json`... but only for
+the demo (--index): the UI tests don't use them, and they are several MB.
+
+With --index (the demo), only the fixtures in DEMO_RUNS and DEMO_TOOLS_ONLY are
+written. index.json lists each run file with its RunInfo, so the demo can show
+the run list without downloading every run. DEMO_RUNS are the curated examples
+shown in the run list, each with a short description of the agent and its task;
+DEMO_TOOLS_ONLY runs are not listed but feed the Tools tab, whose links can still
+open them. Without --index, tools.json covers every fixture.
+
+Usage (from server/):
+    uv run python -m loopview.devtools.dump_normalized ../ui/src/test-data
+    uv run python -m loopview.devtools.dump_normalized ../ui/pages-public/demo --index
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from loopview.normalize.normalizer import normalize_run
+from loopview.normalize.schema import NormalizedRun
+from loopview.store.capture import load_capture
+from loopview.store.memory import TraceStore
+from loopview.tools.report import tools_report
+
+REPO = Path(__file__).resolve().parents[4]
+FIXTURES = REPO / "fixtures"
+MCP_STUDY_TASKS = REPO / "examples" / "mcp_tools_study_tasks.txt"
+
+# The examples the hosted demo lists, in order, with what the demo says about each.
+# `prompt` is the task the agent was given, as written in the example's source.
+DEMO_RUNS: dict[str, dict[str, Any]] = {
+    "flagship": {
+        "title": "Database comparison team",
+        "framework": "LangGraph",
+        "source": "examples/demo/flagship.py",
+        "summary": (
+            "A supervisor splits the question into three briefs. Three analyst agents research "
+            "benchmarks, operations and ecosystem in parallel, each with its own tools. Their "
+            "notes are merged, a critic sends the draft back once, and a writer produces the "
+            "answer."
+        ),
+        "prompt": (
+            "Compare PostgreSQL, SQLite and DuckDB for a small internal analytics dashboard: "
+            "5 users, about 20 GB of event data, loaded once a day. Recommend one."
+        ),
+        "look_for": [
+            "the fan-out to three analysts running at the same time",
+            "fetch_repo_stats failing on its first call, then the retry",
+            "the critic's loop back to synthesize, then the handoff to the writer",
+            "the Cost tab: a 4,300-token handbook read from the prompt cache",
+        ],
+    },
+    "multi_agent_pydantic": {
+        "title": "Laptop advice, multi-agent",
+        "framework": "Pydantic AI",
+        "source": "examples/multi_agent_pydantic.py",
+        "summary": (
+            "A coordinator agent delegates to two researchers (specs and reviews) that run in "
+            "parallel behind one tool call, then hands its notes to a writer agent."
+        ),
+        "prompt": (
+            "A student needs a laptop for programming and light video editing, budget 1300 EUR. "
+            "Compare the Aster Pro 14 and the Kestrel Air 15 and recommend one."
+        ),
+        "look_for": [
+            "agents nested inside a tool call (delegation)",
+            "the two researchers overlapping in time",
+            "the handoff from the coordinator to the writer",
+        ],
+    },
+    "langgraph_router": {
+        "title": "Date question router",
+        "framework": "LangGraph",
+        "source": "examples/langgraph_router.py",
+        "summary": (
+            "A classifier routes the question to a tool-using agent. The agent loops with its date "
+            "tools, then a strict reviewer asks for one revision and sends it back."
+        ),
+        "prompt": (
+            "How many days are there from 2026-09-30 until the next February 29th, "
+            "and what day of the week will that February 29th be?"
+        ),
+        "look_for": [
+            "the conditional route out of classify",
+            "the agent and tools loop",
+            "the reviewer's loop back to an earlier node",
+        ],
+    },
+    "failing_tools_pydantic": {
+        "title": "Shop assistant, failing tools",
+        "framework": "Pydantic AI + MCP",
+        "source": "examples/failing_tools_pydantic.py",
+        "summary": (
+            "A support agent with an order tool and an inventory MCP server. The question is "
+            "worded so both tools fail first: the agent has to read the errors and recover."
+        ),
+        "prompt": (
+            "What is the status of order 1234, and how many units of SKU-0099 (the blue mug) "
+            "are in stock?"
+        ),
+        "look_for": [
+            "red tool calls: a ModelRetry and an MCP isError result",
+            "what the model does next: fixes its arguments, or switches tool",
+            "the Tools tab, where these recoveries are counted",
+        ],
+    },
+    "react_anthropic": {
+        "title": "Trip budget, hand-rolled loop",
+        "framework": "Anthropic SDK",
+        "source": "examples/react_anthropic.py",
+        "summary": (
+            "A plain ReAct loop written by hand on the Anthropic SDK, traced with the "
+            "OpenTelemetry GenAI conventions. Extended thinking is on, so the model's reasoning "
+            "is recorded."
+        ),
+        "prompt": (
+            "I'm planning 3 nights in Lisbon and 2 nights in Porto. Look up the average "
+            "hotel price per night in each city, then tell me the total in EUR and in USD."
+        ),
+        "look_for": [
+            "the model's thinking, shown inside each model call",
+            "several tool calls asked for in one model turn",
+        ],
+    },
+}
+# Not listed (20 short tasks against GitHub's MCP server), but the Tools tab is built on them.
+DEMO_TOOLS_ONLY = ["mcp_tools_study"]
+
+
+def tools_only_about(name: str, run: NormalizedRun) -> dict[str, Any] | None:
+    """What the demo says about an unlisted run that a Tools tab link opened."""
+    if name != "mcp_tools_study" or not run.run.name.startswith("task "):
+        return None  # the study's first run only opens the MCP connection
+    lines = MCP_STUDY_TASKS.read_text(encoding="utf-8").splitlines()
+    tasks = [line for line in lines if line.strip() and not line.startswith("#")]
+    number = int(run.run.name.removeprefix("task "))
+    return {
+        "title": f"GitHub MCP study, task {number}",
+        "framework": "Pydantic AI + GitHub MCP",
+        "source": "examples/mcp_tools_study.py",
+        "summary": (
+            "One of 20 read-only questions a Pydantic AI agent answered with the tools of GitHub's "
+            "official MCP server. Together, these runs feed the Tools tab."
+        ),
+        "prompt": tasks[number - 1],
+        "look_for": [
+            "which of the server's many tools the model picks",
+            "how big the tool results are, in the Cost tab",
+        ],
+    }
+
+
+def main() -> None:
+    out = Path(sys.argv[1])
+    demo = "--index" in sys.argv
+    out.mkdir(parents=True, exist_ok=True)
+    all_runs: list[NormalizedRun] = []
+    index: list[tuple[int, str, NormalizedRun, str]] = []  # (demo position, file, run, fixture)
+    for fixture in sorted(FIXTURES.glob("*.otlp.jsonl")):
+        name = fixture.name.removesuffix(".otlp.jsonl")
+        if demo and name not in DEMO_RUNS and name not in DEMO_TOOLS_ONLY:
+            continue
+        store = TraceStore()
+        load_capture(store, fixture)
+        runs = [
+            normalize_run(run, now_ns=run.last_received_ns)
+            for run in sorted(store.runs(), key=lambda r: r.first_received_ns)
+        ]
+        all_runs += runs
+        if len(runs) > 1 and not demo:
+            print(f"skipped {name} ({len(runs)} runs: written for the demo only)")
+            continue
+        position = list(DEMO_RUNS).index(name) if name in DEMO_RUNS else len(DEMO_RUNS)
+        for i, normalized in enumerate(runs, 1):
+            file = f"{name}.json" if len(runs) == 1 else f"{name}-{i:02d}.json"
+            (out / file).write_text(normalized.model_dump_json(), encoding="utf-8")
+            index.append((position, file, normalized, name))
+        print(f"wrote {name} ({len(runs)} run{'s' if len(runs) > 1 else ''})")
+    (out / "tools.json").write_text(json.dumps(tools_report(all_runs)), encoding="utf-8")
+    print("wrote tools.json")
+    if demo:
+        missing = [
+            name for name in [*DEMO_RUNS, *DEMO_TOOLS_ONLY] if not any(e[3] == name for e in index)
+        ]
+        if missing:
+            sys.exit(f"no fixture for {', '.join(missing)}")
+        index.sort(key=lambda entry: entry[0])  # stable: a fixture's runs keep their order
+        entries = [
+            {
+                "file": file,
+                "run": n.run.model_dump(mode="json"),
+                "listed": name in DEMO_RUNS,
+                "about": DEMO_RUNS.get(name) or tools_only_about(name, n),
+            }
+            for _, file, n, name in index
+        ]
+        (out / "index.json").write_text(json.dumps(entries), encoding="utf-8")
+        print("wrote index.json")
+
+
+if __name__ == "__main__":
+    main()

loopview/ingest/__init__.py

@@ -0,0 +1 @@
+"""Ingestion: OTLP/HTTP request bodies in, RawSpans out."""

loopview/ingest/otlp.py

@@ -0,0 +1,305 @@
+"""Decode OTLP/HTTP trace export requests into RawSpans.
+
+Follows the OTLP specification v1.11.0 (https://opentelemetry.io/docs/specs/otlp/).
+
+Both encodings go through one path: JSON is parsed into the same protobuf message
+as the binary encoding, then a single function converts the message to RawSpans.
+That works because OTLP/JSON is the standard protobuf JSON mapping with one
+exception: trace and span ids are hex strings instead of base64. We rewrite those
+ids before parsing and let protobuf handle everything else (camelCase keys, enums
+as integers, 64-bit integers as strings, unknown fields ignored).
+"""
+
+import base64
+import json
+import zlib
+from typing import Any
+
+from google.protobuf import json_format
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
+    ExportTraceServiceRequest,
+    ExportTraceServiceResponse,
+)
+from opentelemetry.proto.common.v1.common_pb2 import AnyValue, KeyValue
+from opentelemetry.proto.trace.v1.trace_pb2 import Span, Status
+
+from loopview.ingest.raw import RawSpan, SpanEvent, SpanKind, SpanLink, StatusCode
+
+PROTOBUF = "application/x-protobuf"
+JSON = "application/json"
+
+# Largest request body we accept, after decompression. Big enough for thousands of
+# spans with full prompts; small enough that a bad request can't eat all memory.
+MAX_BODY_BYTES = 64 * 1024 * 1024
+
+
+class OtlpDecodeError(ValueError):
+    """The request could not be decoded. Maps to HTTP 400 (not retryable)."""
+
+
+class UnsupportedContentType(OtlpDecodeError):
+    """Neither protobuf nor JSON. Maps to HTTP 415."""
+
+
+class BodyTooLarge(OtlpDecodeError):
+    """Maps to HTTP 413 (not retryable)."""
+
+
+def decode_request(
+    body: bytes, content_type: str | None, content_encoding: str | None = None
+) -> list[RawSpan]:
+    """Decode one POST /v1/traces body into RawSpans."""
+    return decode_body(decompress(body, content_encoding), content_type)
+
+
+def decode_body(body: bytes, content_type: str | None) -> list[RawSpan]:
+    """Decode an already decompressed body into RawSpans."""
+    media_type = (content_type or "").split(";")[0].strip().lower()
+    if media_type == PROTOBUF:
+        request = _parse_protobuf(body)
+    elif media_type == JSON:
+        request = _parse_json(body)
+    else:
+        raise UnsupportedContentType(f"unsupported content type: {content_type!r}")
+    return request_to_spans(request)
+
+
+def encode_success_response(content_type: str | None) -> tuple[bytes, str]:
+    """An empty ExportTraceServiceResponse in the same encoding as the request."""
+    response = ExportTraceServiceResponse()
+    if (content_type or "").lower().startswith(JSON):
+        return json_format.MessageToJson(response).encode(), JSON
+    return response.SerializeToString(), PROTOBUF
+
+
+def request_to_spans(request: ExportTraceServiceRequest) -> list[RawSpan]:
+    spans: list[RawSpan] = []
+    for resource_spans in request.resource_spans:
+        resource_attributes = _attributes(resource_spans.resource.attributes)
+        for scope_spans in resource_spans.scope_spans:
+            scope = scope_spans.scope
+            for span in scope_spans.spans:
+                spans.append(_span(span, resource_attributes, scope.name, scope.version))
+    return spans
+
+
+# --- decoding the body ----------------------------------------------------------
+
+
+def decompress(body: bytes, content_encoding: str | None) -> bytes:
+    """Undo Content-Encoding (identity or gzip), enforcing MAX_BODY_BYTES."""
+    encoding = (content_encoding or "identity").strip().lower()
+    if encoding == "identity":
+        result = body
+    elif encoding == "gzip":
+        # wbits=16+MAX_WBITS means "expect a gzip header". max_length stops a small
+        # compressed body from expanding into gigabytes.
+        decompressor = zlib.decompressobj(16 + zlib.MAX_WBITS)
+        try:
+            result = decompressor.decompress(body, MAX_BODY_BYTES + 1)
+        except zlib.error as exc:
+            raise OtlpDecodeError(f"invalid gzip body: {exc}") from exc
+    else:
+        raise OtlpDecodeError(f"unsupported content encoding: {content_encoding!r}")
+    if len(result) > MAX_BODY_BYTES:
+        raise BodyTooLarge(f"request body larger than {MAX_BODY_BYTES} bytes")
+    return result
+
+
+def _parse_protobuf(body: bytes) -> ExportTraceServiceRequest:
+    request = ExportTraceServiceRequest()
+    try:
+        request.ParseFromString(body)
+    except Exception as exc:  # protobuf raises DecodeError, but be safe
+        raise OtlpDecodeError(f"invalid protobuf body: {exc}") from exc
+    return request
+
+
+def _parse_json(body: bytes) -> ExportTraceServiceRequest:
+    try:
+        data = json.loads(body)
+        _hex_ids_to_base64(data)
+        return json_format.ParseDict(data, ExportTraceServiceRequest(), ignore_unknown_fields=True)
+    except (ValueError, TypeError, json_format.ParseError) as exc:
+        raise OtlpDecodeError(f"invalid JSON body: {exc}") from exc
+
+
+# OTLP/JSON fields that hold hex ids. Protobuf's JSON parser expects base64 for bytes.
+_ID_FIELDS = ("traceId", "spanId", "parentSpanId")
+
+
+def _hex_ids_to_base64(data: Any) -> None:
+    """Rewrite hex trace/span ids in place, on spans and on span links."""
+    for resource_spans in data.get("resourceSpans", []):
+        for scope_spans in resource_spans.get("scopeSpans", []):
+            for span in scope_spans.get("spans", []):
+                _convert_ids(span)
+                for link in span.get("links", []):
+                    _convert_ids(link)
+
+
+def _convert_ids(obj: dict[str, Any]) -> None:
+    for field in _ID_FIELDS:
+        value = obj.get(field)
+        if value:
+            obj[field] = base64.b64encode(bytes.fromhex(value)).decode()
+
+
+# --- protobuf message to RawSpan ------------------------------------------------
+
+_KINDS: dict[int, SpanKind] = {
+    Span.SPAN_KIND_UNSPECIFIED: "unspecified",
+    Span.SPAN_KIND_INTERNAL: "internal",
+    Span.SPAN_KIND_SERVER: "server",
+    Span.SPAN_KIND_CLIENT: "client",
+    Span.SPAN_KIND_PRODUCER: "producer",
+    Span.SPAN_KIND_CONSUMER: "consumer",
+}
+
+_STATUS: dict[int, StatusCode] = {
+    Status.STATUS_CODE_UNSET: "unset",
+    Status.STATUS_CODE_OK: "ok",
+    Status.STATUS_CODE_ERROR: "error",
+}
+
+
+def _span(
+    span: Span, resource_attributes: dict[str, Any], scope_name: str, scope_version: str
+) -> RawSpan:
+    return RawSpan(
+        trace_id=span.trace_id.hex(),
+        span_id=span.span_id.hex(),
+        parent_span_id=span.parent_span_id.hex() or None,
+        name=span.name,
+        kind=_KINDS.get(span.kind, "unspecified"),
+        start_time_unix_nano=span.start_time_unix_nano,
+        end_time_unix_nano=span.end_time_unix_nano,
+        attributes=_attributes(span.attributes),
+        events=[
+            SpanEvent(
+                name=event.name,
+                time_unix_nano=event.time_unix_nano,
+                attributes=_attributes(event.attributes),
+            )
+            for event in span.events
+        ],
+        links=[
+            SpanLink(
+                trace_id=link.trace_id.hex(),
+                span_id=link.span_id.hex(),
+                attributes=_attributes(link.attributes),
+            )
+            for link in span.links
+        ],
+        status_code=_STATUS.get(span.status.code, "unset"),
+        status_message=span.status.message,
+        resource_attributes=resource_attributes,
+        scope_name=scope_name,
+        scope_version=scope_version,
+    )
+
+
+def _attributes(key_values: "list[KeyValue] | Any") -> dict[str, Any]:
+    return {kv.key: _value(kv.value) for kv in key_values}
+
+
+def _value(value: AnyValue) -> Any:
+    """Convert an OTLP AnyValue into a plain Python value."""
+    kind = value.WhichOneof("value")
+    if kind is None:
+        return None
+    if kind == "array_value":
+        return [_value(v) for v in value.array_value.values]
+    if kind == "kvlist_value":
+        return _attributes(value.kvlist_value.values)
+    if kind == "bytes_value":
+        # Keep RawSpans JSON-friendly: bytes become base64 text.
+        return base64.b64encode(value.bytes_value).decode()
+    return getattr(value, kind)  # string_value, bool_value, int_value, double_value
+
+
+# --- RawSpan back to OTLP/JSON (for exporting a run) ----------------------------------
+
+_KIND_NUMBERS = {name: number for number, name in _KINDS.items()}
+_STATUS_NUMBERS = {name: number for number, name in _STATUS.items()}
+
+
+def spans_to_otlp_json(spans: list[RawSpan]) -> dict[str, Any]:
+    """Encode RawSpans as an OTLP/JSON ExportTraceServiceRequest.
+
+    The inverse of decoding, so an exported run can be imported again through
+    the normal receiver path. (Bytes attributes come back as base64 strings.)"""
+    groups: dict[tuple[str, str, str], list[RawSpan]] = {}
+    for span in spans:
+        key = (
+            json.dumps(span.resource_attributes, sort_keys=True),
+            span.scope_name,
+            span.scope_version,
+        )
+        groups.setdefault(key, []).append(span)
+    resource_spans = []
+    for (resource_json, scope_name, scope_version), group in groups.items():
+        resource_spans.append(
+            {
+                "resource": {"attributes": _kv_json(json.loads(resource_json))},
+                "scopeSpans": [
+                    {
+                        "scope": {"name": scope_name, "version": scope_version},
+                        "spans": [_span_json(s) for s in group],
+                    }
+                ],
+            }
+        )
+    return {"resourceSpans": resource_spans}
+
+
+def _span_json(span: RawSpan) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "traceId": span.trace_id,
+        "spanId": span.span_id,
+        "name": span.name,
+        "kind": _KIND_NUMBERS[span.kind],
+        "startTimeUnixNano": str(span.start_time_unix_nano),
+        "endTimeUnixNano": str(span.end_time_unix_nano),
+        "attributes": _kv_json(span.attributes),
+        "events": [
+            {
+                "name": e.name,
+                "timeUnixNano": str(e.time_unix_nano),
+                "attributes": _kv_json(e.attributes),
+            }
+            for e in span.events
+        ],
+        "links": [
+            {
+                "traceId": link.trace_id,
+                "spanId": link.span_id,
+                "attributes": _kv_json(link.attributes),
+            }
+            for link in span.links
+        ],
+        "status": {"code": _STATUS_NUMBERS[span.status_code], "message": span.status_message},
+    }
+    if span.parent_span_id:
+        result["parentSpanId"] = span.parent_span_id
+    return result
+
+
+def _kv_json(attributes: dict[str, Any]) -> list[dict[str, Any]]:
+    return [{"key": key, "value": _any_value_json(value)} for key, value in attributes.items()]
+
+
+def _any_value_json(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, bool):  # before int: bool is a subclass of int
+        return {"boolValue": value}
+    if isinstance(value, int):
+        return {"intValue": str(value)}
+    if isinstance(value, float):
+        return {"doubleValue": value}
+    if isinstance(value, list):
+        return {"arrayValue": {"values": [_any_value_json(v) for v in value]}}
+    if isinstance(value, dict):
+        return {"kvlistValue": {"values": _kv_json(value)}}
+    return {"stringValue": str(value)}

loopview/ingest/raw.py

@@ -0,0 +1,47 @@
+"""RawSpan: an OpenTelemetry span decoded from OTLP, with no interpretation.
+
+This is the boundary between "wire format" and "meaning". The ingest layer turns
+OTLP bytes into RawSpans; the normalize layer (M3) turns RawSpans into the
+internal schema. Nothing here knows about gen_ai, OpenInference or any framework.
+
+Attribute values are plain Python values (str, bool, int, float, list, dict), so
+RawSpans are easy to test, print and write to JSON.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+SpanKind = Literal["unspecified", "internal", "server", "client", "producer", "consumer"]
+StatusCode = Literal["unset", "ok", "error"]
+
+
+class SpanEvent(BaseModel):
+    name: str
+    time_unix_nano: int
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+class SpanLink(BaseModel):
+    trace_id: str
+    span_id: str
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+class RawSpan(BaseModel):
+    trace_id: str  # 32 lowercase hex chars
+    span_id: str  # 16 lowercase hex chars
+    parent_span_id: str | None = None  # None for a root span
+    name: str
+    kind: SpanKind = "unspecified"
+    start_time_unix_nano: int
+    end_time_unix_nano: int
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    events: list[SpanEvent] = Field(default_factory=list)
+    links: list[SpanLink] = Field(default_factory=list)
+    status_code: StatusCode = "unset"
+    status_message: str = ""
+    # Where the span came from: the process (resource) and the library (scope).
+    resource_attributes: dict[str, Any] = Field(default_factory=dict)
+    scope_name: str = ""
+    scope_version: str = ""