loopview 0.1.0__py3-none-any.whl

loopview/live.py

@@ -0,0 +1,154 @@
+"""The live hub: keeps normalized runs up to date and pushes changes to browsers.
+
+Flow:
+    receiver -> store.add_spans -> hub.mark(trace ids)
+    every 100 ms: for each marked run, normalize it, work out which steps changed
+    since the last push, and send one event to every connected browser.
+
+Batching every 100 ms bounds the work when an exporter sends many small requests,
+and makes one event per run per tick. Events are idempotent upserts, so a browser
+can fetch a full snapshot and subscribe in any order without losing anything.
+
+Transport is Server-Sent Events (see DECISIONS.md D7): one HTTP response that
+stays open, each event a `data: {json}` line.
+"""
+
+import asyncio
+import contextlib
+import time
+from collections.abc import AsyncIterator, Iterable
+
+from loopview.cost.pricing import Pricing
+from loopview.normalize.normalizer import normalize_run
+from loopview.normalize.schema import NormalizedRun, RunInfo
+from loopview.store.memory import TraceStore
+
+FLUSH_INTERVAL_S = 0.1
+# Runs still marked running are re-checked this often, so a run whose process
+# died flips to finished without any new data arriving.
+STALE_CHECK_INTERVAL_S = 2.0
+HEARTBEAT_INTERVAL_S = 15.0
+MAX_QUEUED_EVENTS = 1000
+
+
+class LiveHub:
+    def __init__(self, store: TraceStore, pricing: Pricing | None = None) -> None:
+        self.store = store
+        self.pricing = pricing  # None: the bundled prices
+        self._dirty: set[str] = set()
+        self._cache: dict[str, NormalizedRun] = {}
+        # Per run, the JSON of each step as last pushed, to send only what changed.
+        self._pushed: dict[str, dict[str, str]] = {}
+        # Each browser's queue of SSE messages; None tells the stream to end.
+        self._subscribers: set[asyncio.Queue[str | None]] = set()
+        self._closing = False
+
+    # --- called by the receiver and the API --------------------------------------------
+
+    def mark(self, trace_ids: Iterable[str]) -> None:
+        self._dirty.update(trace_ids)
+
+    def get(self, trace_id: str) -> NormalizedRun | None:
+        if trace_id in self._dirty or trace_id not in self._cache:
+            run = self.store.get_run(trace_id)
+            if run is None:
+                return None
+            self._cache[trace_id] = normalize_run(run, pricing=self.pricing)
+        return self._cache[trace_id]
+
+    def run_infos(self) -> list[RunInfo]:
+        infos = []
+        for run in self.store.runs():
+            normalized = self.get(run.trace_id)
+            if normalized is not None:
+                infos.append(normalized.run)
+        return infos
+
+    # --- subscribers ------------------------------------------------------------------
+
+    async def events(self) -> AsyncIterator[str]:
+        """Yield SSE-formatted events for one browser until it disconnects or the
+        server shuts down."""
+        queue: asyncio.Queue[str | None] = asyncio.Queue(MAX_QUEUED_EVENTS)
+        self._subscribers.add(queue)
+        try:
+            yield ": connected\n\n"
+            while not self._closing:
+                try:
+                    message = await asyncio.wait_for(queue.get(), HEARTBEAT_INTERVAL_S)
+                except TimeoutError:
+                    yield ": heartbeat\n\n"  # keeps proxies from closing the connection
+                    continue
+                if message is None:
+                    return
+                yield message
+        finally:
+            self._subscribers.discard(queue)
+
+    def close(self) -> None:
+        """End every open stream. Called when the server starts shutting down:
+        a stream never ends on its own, and the server waits for open
+        connections before it stops, so without this Ctrl+C would hang."""
+        self._closing = True
+        for queue in list(self._subscribers):
+            try:
+                queue.put_nowait(None)
+            except asyncio.QueueFull:
+                self._subscribers.discard(queue)
+
+    def _publish(self, payload: str) -> None:
+        for queue in list(self._subscribers):
+            try:
+                queue.put_nowait(f"data: {payload}\n\n")
+            except asyncio.QueueFull:
+                # A browser that stopped reading: drop it; it reconnects and refetches.
+                self._subscribers.discard(queue)
+
+    # --- the background loop ------------------------------------------------------------
+
+    async def run_forever(self) -> None:
+        last_stale_check = time.monotonic()
+        while True:
+            await asyncio.sleep(FLUSH_INTERVAL_S)
+            if time.monotonic() - last_stale_check > STALE_CHECK_INTERVAL_S:
+                last_stale_check = time.monotonic()
+                self.mark(t for t, n in self._cache.items() if n.run.status == "running")
+            self.flush()
+
+    def flush(self) -> None:
+        dirty, self._dirty = self._dirty, set()
+        for trace_id in dirty:
+            run = self.store.get_run(trace_id)
+            if run is None:  # evicted from the ring buffer
+                self._cache.pop(trace_id, None)
+                self._pushed.pop(trace_id, None)
+                continue
+            normalized = normalize_run(run, pricing=self.pricing)
+            self._cache[trace_id] = normalized
+            pushed = self._pushed.setdefault(trace_id, {})
+            changed = []
+            for step in normalized.steps:
+                as_json = step.model_dump_json()
+                if pushed.get(step.id) != as_json:
+                    pushed[step.id] = as_json
+                    changed.append(as_json)
+            transitions = ",".join(t.model_dump_json() for t in normalized.transitions)
+            self._publish(
+                f'{{"type":"run.update","run":{normalized.run.model_dump_json()},'
+                f'"steps":[{",".join(changed)}],"transitions":[{transitions}]}}'
+            )
+        # Forget caches of runs the store evicted without them being marked.
+        for trace_id in [t for t in self._cache if self.store.get_run(t) is None]:
+            self._cache.pop(trace_id, None)
+            self._pushed.pop(trace_id, None)
+
+
+@contextlib.asynccontextmanager
+async def running(hub: LiveHub) -> AsyncIterator[None]:
+    task = asyncio.create_task(hub.run_forever())
+    try:
+        yield
+    finally:
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task

loopview/normalize/__init__.py

@@ -0,0 +1 @@
+"""Normalization: raw spans from any convention in, one small schema out."""

loopview/normalize/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""The adapter registry. The first adapter whose `matches` is true wins, so the
+generic fallback must stay last."""
+
+from loopview.ingest.raw import RawSpan
+from loopview.normalize.adapters.base import Adapter
+from loopview.normalize.adapters.gen_ai import GenAiAdapter
+from loopview.normalize.adapters.generic import GenericAdapter
+from loopview.normalize.adapters.openinference import OpenInferenceAdapter
+
+ADAPTERS: list[Adapter] = [OpenInferenceAdapter(), GenAiAdapter(), GenericAdapter()]
+
+
+def adapter_for(span: RawSpan) -> Adapter:
+    return next(a for a in ADAPTERS if a.matches(span))

loopview/normalize/adapters/base.py

@@ -0,0 +1,87 @@
+"""The adapter contract.
+
+An adapter knows one span convention. For one span, it answers:
+- does this span follow my convention? (`matches`)
+- what is it? (`classify`, returning a Classification)
+- if this span arrived but its parent hasn't yet, what can I tell about the
+  parent? (`infer_parent`, used to show still-running steps with a real name)
+
+Adding a convention means writing one adapter and adding it to ADAPTERS in
+normalize/adapters/__init__.py. Nothing else changes.
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from loopview.ingest.raw import RawSpan
+from loopview.normalize.schema import ModelCall, StepKind, ToolCall
+
+
+@dataclass
+class Classification:
+    kind: StepKind
+    name: str
+    type_label: str
+    hidden: bool = False
+    model: ModelCall | None = None
+    tool: ToolCall | None = None
+    input: Any = None
+    output: Any = None
+    # When True, a later pass hides this step if its parent has the same name
+    # (a subgraph span nested directly in the node that runs it).
+    collapse_into_parent: bool = False
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ParentHint:
+    name: str
+    kind: StepKind
+    type_label: str
+
+
+class Adapter(Protocol):
+    name: str
+
+    def matches(self, span: RawSpan) -> bool: ...
+
+    def classify(self, span: RawSpan) -> Classification: ...
+
+    def infer_parent(self, span: RawSpan) -> ParentHint | None: ...
+
+
+# --- helpers shared by adapters ---------------------------------------------------
+
+
+def maybe_json(value: Any) -> Any:
+    """Parse a JSON string; return anything else (or unparseable text) unchanged.
+
+    Conventions allow structured values to be recorded as JSON strings when the
+    exporter can't carry structure, so the same attribute can arrive either way."""
+    if isinstance(value, str) and value[:1] in ("{", "[", '"'):
+        try:
+            return json.loads(value)
+        except ValueError:
+            return value
+    return value
+
+
+def as_int(value: Any) -> int | None:
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def error_message(span: RawSpan) -> str | None:
+    """The error of a failed span: the status message, or the recorded exception."""
+    if span.status_code != "error":
+        return None
+    for event in span.events:
+        if event.name == "exception":
+            message = event.attributes.get("exception.message")
+            kind = event.attributes.get("exception.type")
+            if message or kind:
+                return ": ".join(str(x) for x in (kind, message) if x)
+    return span.status_message or span.attributes.get("error.type") or "error"

loopview/normalize/adapters/gen_ai.py

@@ -0,0 +1,252 @@
+"""Adapter for the OpenTelemetry GenAI semantic conventions.
+
+Written against open-telemetry/semantic-conventions-genai at commit bcc7f9c
+(2026-09-29), status Development. Also reads the older shape that existing
+instrumentations still emit: messages as span events (gen_ai.user.message,
+gen_ai.choice, ...) and gen_ai.system instead of gen_ai.provider.name.
+
+A span is GenAI if it has gen_ai.operation.name.
+"""
+
+from typing import Any
+
+from loopview.ingest.raw import RawSpan
+from loopview.normalize.adapters.base import (
+    Classification,
+    ParentHint,
+    as_int,
+    maybe_json,
+)
+from loopview.normalize.schema import Message, MessagePart, ModelCall, ToolCall, Usage
+
+MODEL_OPERATIONS = {"chat", "text_completion", "generate_content", "embeddings"}
+TOOL_LIKE_OPERATIONS = {
+    "execute_tool",
+    "retrieval",
+    "create_memory",
+    "search_memory",
+    "update_memory",
+    "upsert_memory",
+    "delete_memory",
+    "create_memory_store",
+    "delete_memory_store",
+}
+# The event that carries messages when content is recorded on events.
+DETAILS_EVENT = "gen_ai.client.inference.operation.details"
+# Older, deprecated per-message events.
+LEGACY_MESSAGE_EVENTS = {
+    "gen_ai.system.message": "system",
+    "gen_ai.user.message": "user",
+    "gen_ai.assistant.message": "assistant",
+    "gen_ai.tool.message": "tool",
+}
+
+
+class GenAiAdapter:
+    name = "gen_ai"
+
+    def matches(self, span: RawSpan) -> bool:
+        return "gen_ai.operation.name" in span.attributes
+
+    def classify(self, span: RawSpan) -> Classification:
+        attrs = span.attributes
+        operation = str(attrs["gen_ai.operation.name"])
+
+        if operation == "invoke_agent":
+            name = attrs.get("gen_ai.agent.name") or _name_after_operation(span.name, operation)
+            return Classification("agent", str(name), "agent", output=_final_output(attrs))
+        if operation == "invoke_workflow":
+            name = attrs.get("gen_ai.workflow.name") or _name_after_operation(span.name, operation)
+            return Classification("agent", str(name), "workflow")
+        if operation in MODEL_OPERATIONS:
+            model = attrs.get("gen_ai.request.model") or attrs.get("gen_ai.response.model")
+            return Classification(
+                "model_call", str(model or span.name), "llm", model=_model_call(span)
+            )
+        if operation in TOOL_LIKE_OPERATIONS:
+            tool_name = attrs.get("gen_ai.tool.name") or _name_after_operation(span.name, operation)
+            label = "tool" if operation == "execute_tool" else operation
+            return Classification(
+                "tool_call",
+                str(tool_name),
+                label,
+                tool=ToolCall(
+                    name=str(tool_name),
+                    call_id=attrs.get("gen_ai.tool.call.id"),
+                    arguments=maybe_json(attrs.get("gen_ai.tool.call.arguments")),
+                    result=maybe_json(attrs.get("gen_ai.tool.call.result")),
+                ),
+            )
+        # plan, create_agent, or an operation this version doesn't know yet.
+        name = attrs.get("gen_ai.agent.name") or span.name
+        return Classification("node", str(name), operation)
+
+    def infer_parent(self, span: RawSpan) -> ParentHint | None:
+        # Model and tool calls made inside an agent carry the agent's name.
+        operation = span.attributes.get("gen_ai.operation.name")
+        agent = span.attributes.get("gen_ai.agent.name")
+        if agent and operation != "invoke_agent":
+            return ParentHint(str(agent), "agent", "agent")
+        return None
+
+
+def _name_after_operation(span_name: str, operation: str) -> str:
+    """Span names look like '{operation} {name}'; take the name part."""
+    prefix = operation + " "
+    return span_name[len(prefix) :] if span_name.startswith(prefix) else span_name
+
+
+def _final_output(attrs: dict[str, Any]) -> Any:
+    messages = _messages(attrs.get("gen_ai.output.messages"))
+    return _text_of(messages) if messages else None
+
+
+def _model_call(span: RawSpan) -> ModelCall:
+    attrs = dict(span.attributes)
+    # Content can live on the inference details event instead of the span.
+    for event in span.events:
+        if event.name == DETAILS_EVENT:
+            for key in (
+                "gen_ai.input.messages",
+                "gen_ai.output.messages",
+                "gen_ai.system_instructions",
+            ):
+                attrs.setdefault(key, event.attributes.get(key))
+
+    inputs = _messages(attrs.get("gen_ai.input.messages"))
+    outputs = _messages(attrs.get("gen_ai.output.messages"))
+    system = _parts(maybe_json(attrs.get("gen_ai.system_instructions")))
+    if system:
+        inputs = [Message(role="system", parts=system), *inputs]
+    if not inputs and not outputs:
+        inputs, outputs = _legacy_event_messages(span)
+
+    return ModelCall(
+        provider=attrs.get("gen_ai.provider.name") or attrs.get("gen_ai.system"),
+        model=attrs.get("gen_ai.response.model") or attrs.get("gen_ai.request.model"),
+        input=inputs,
+        output=outputs,
+        tool_definitions=_list(attrs.get("gen_ai.tool.definitions")),
+        usage=usage_from_attributes(attrs),
+    )
+
+
+# Token counts. The spec's names first, then the names instrumentations are known
+# to use instead (Pydantic AI writes gen_ai.usage.details.*, from the provider's
+# own field names). The spec defines input_tokens as including cache reads and
+# writes, and output_tokens as including reasoning.
+_CACHE_READ_KEYS = (
+    "gen_ai.usage.cache_read.input_tokens",
+    "gen_ai.usage.details.cache_read_input_tokens",
+)
+_CACHE_WRITE_KEYS = (
+    "gen_ai.usage.cache_write.input_tokens",
+    "gen_ai.usage.details.cache_creation_input_tokens",  # Pydantic AI
+    "gen_ai.usage.cache_creation.input_tokens",  # OpenLLMetry
+)
+
+
+def usage_from_attributes(attrs: dict[str, Any]) -> Usage | None:
+    usage = Usage(
+        input_tokens=as_int(attrs.get("gen_ai.usage.input_tokens")),
+        output_tokens=as_int(attrs.get("gen_ai.usage.output_tokens")),
+        cache_read_tokens=_first_int(attrs, _CACHE_READ_KEYS),
+        cache_write_tokens=_first_int(attrs, _CACHE_WRITE_KEYS),
+        reasoning_tokens=as_int(attrs.get("gen_ai.usage.reasoning.output_tokens")),
+    )
+    return usage if usage.model_dump(exclude_none=True) else None
+
+
+def _first_int(attrs: dict[str, Any], keys: tuple[str, ...]) -> int | None:
+    for key in keys:
+        value = as_int(attrs.get(key))
+        if value is not None:
+            return value
+    return None
+
+
+def _list(value: Any) -> list[Any]:
+    value = maybe_json(value)
+    return value if isinstance(value, list) else []
+
+
+def _messages(value: Any) -> list[Message]:
+    value = maybe_json(value)
+    if not isinstance(value, list):
+        return []
+    return [
+        Message(role=str(m.get("role", "unknown")), parts=_parts(m.get("parts")))
+        for m in value
+        if isinstance(m, dict)
+    ]
+
+
+def _parts(value: Any) -> list[MessagePart]:
+    if isinstance(value, str):
+        return [MessagePart(type="text", text=value)]
+    if not isinstance(value, list):
+        return []
+    parts = []
+    for p in value:
+        if not isinstance(p, dict):
+            continue
+        kind = p.get("type")
+        if kind == "text":
+            parts.append(MessagePart(type="text", text=str(p.get("content", ""))))
+        elif kind == "tool_call":
+            parts.append(
+                MessagePart(
+                    type="tool_call",
+                    id=p.get("id"),
+                    name=p.get("name"),
+                    arguments=maybe_json(p.get("arguments")),
+                )
+            )
+        elif kind == "reasoning":
+            parts.append(MessagePart(type="reasoning", text=str(p.get("content", ""))))
+        elif kind == "tool_call_response":
+            parts.append(
+                MessagePart(
+                    type="tool_result",
+                    id=p.get("id"),
+                    result=maybe_json(p.get("response", p.get("result"))),
+                    # Not in the spec; read when an instrumentation records it.
+                    is_error=p.get("is_error") if isinstance(p.get("is_error"), bool) else None,
+                )
+            )
+        else:
+            # reasoning, blob, uri, file and future part types: keep them readable.
+            content = p.get("content")
+            parts.append(
+                MessagePart(type="other", name=kind, text=None if content is None else str(content))
+            )
+    return parts
+
+
+def _legacy_event_messages(span: RawSpan) -> tuple[list[Message], list[Message]]:
+    inputs, outputs = [], []
+    for event in span.events:
+        a = event.attributes
+        if event.name in LEGACY_MESSAGE_EVENTS:
+            content = maybe_json(a.get("content"))
+            inputs.append(
+                Message(
+                    role=LEGACY_MESSAGE_EVENTS[event.name],
+                    parts=[MessagePart(type="text", text=_as_text(content))],
+                )
+            )
+        elif event.name == "gen_ai.choice":
+            message = maybe_json(a.get("message"))
+            content = message.get("content") if isinstance(message, dict) else message
+            outputs.append(
+                Message(role="assistant", parts=[MessagePart(type="text", text=_as_text(content))])
+            )
+    return inputs, outputs
+
+
+def _as_text(value: Any) -> str:
+    return value if isinstance(value, str) else ("" if value is None else str(value))
+
+
+def _text_of(messages: list[Message]) -> str:
+    return "\n".join(p.text for m in messages for p in m.parts if p.type == "text" and p.text)

loopview/normalize/adapters/generic.py

@@ -0,0 +1,22 @@
+"""Fallback adapter: any span no other adapter recognised.
+
+It becomes an `unknown` step that keeps its raw attributes, so nothing is ever
+dropped. Whether it is drawn is decided in the normalizer (unknown spans inside a
+model or tool call, such as HTTP client spans, are implementation detail).
+"""
+
+from loopview.ingest.raw import RawSpan
+from loopview.normalize.adapters.base import Classification, ParentHint
+
+
+class GenericAdapter:
+    name = "generic"
+
+    def matches(self, span: RawSpan) -> bool:
+        return True
+
+    def classify(self, span: RawSpan) -> Classification:
+        return Classification("unknown", span.name, span.kind, attributes=dict(span.attributes))
+
+    def infer_parent(self, span: RawSpan) -> ParentHint | None:
+        return None