loopview 0.1.0__py3-none-any.whl

loopview/normalize/normalizer.py

@@ -0,0 +1,326 @@
+"""Turn one stored run (raw spans) into a NormalizedRun (steps + transitions).
+
+The normalizer is pure: same spans and same `now` give the same output. It runs
+again over the whole run whenever new spans arrive, which is simple and fast
+enough for runs of a few hundred spans.
+
+Passes:
+1. classify every span with its convention's adapter;
+2. infer running steps: a span whose parent hasn't arrived means the parent is
+   still running (exporters send a span only when it ends), so we add an
+   "inferred" step for it, named from what the child tells us;
+3. decide what is hidden (plumbing, duplicate subgraph spans, HTTP spans inside
+   model or tool calls);
+4. link each step to its nearest visible parent and to its scope (the flow step
+   it belongs to), promote nodes that contain other nodes to groups, build keys;
+5. rebuild tool calls from the conversation when no span records them
+   (derived_tools.py), and give flat agent loops `model` and `tools` nodes, as
+   LangGraph records them (loop_nodes.py);
+6. derive transitions.
+"""
+
+import time
+from dataclasses import dataclass
+
+from loopview.cost.pricing import Pricing, default_pricing
+from loopview.cost.split import call_cost
+from loopview.ingest.raw import RawSpan
+from loopview.normalize.adapters import adapter_for
+from loopview.normalize.adapters.base import Classification, ParentHint, error_message
+from loopview.normalize.derived_tools import derive_tool_calls
+from loopview.normalize.loop_nodes import add_loop_nodes
+from loopview.normalize.schema import (
+    FLOW_KINDS,
+    NormalizedRun,
+    RunInfo,
+    Step,
+    StepStatus,
+)
+from loopview.normalize.transitions import derive_transitions
+from loopview.store.memory import Run
+
+# A run that has received nothing for this long is treated as finished even if
+# its root span never arrived (for example, the process was killed).
+STALE_AFTER_NS = 30 * 1_000_000_000
+
+
+@dataclass
+class _Draft:
+    id: str
+    raw_parent: str | None
+    c: Classification
+    span: RawSpan | None  # None for inferred (still running) steps
+    convention: str
+    start_ns: int
+    end_ns: int | None
+    hidden: bool = False
+    started_only: bool = False  # reported started by loopview-sdk, not ended yet
+
+
+def normalize_run(
+    run: Run, now_ns: int | None = None, pricing: Pricing | None = None
+) -> NormalizedRun:
+    now_ns = time.time_ns() if now_ns is None else now_ns
+    stale = now_ns - run.last_received_ns > STALE_AFTER_NS
+    drafts = _classify(run)
+    _add_costs(drafts, pricing or default_pricing())
+    _add_inferred_parents(run, drafts, stale)
+    _place_unclassified_starts(drafts)
+    _decide_hidden(drafts)
+    steps = derive_tool_calls(_link(run.trace_id, drafts, stale))
+    steps = add_loop_nodes(steps, root_name=_service_name(run))
+    transitions = derive_transitions(steps)
+    return NormalizedRun(run=_run_info(run, steps, stale), steps=steps, transitions=transitions)
+
+
+# --- pass 1 --------------------------------------------------------------------------
+
+
+def _classify(run: Run) -> dict[str, _Draft]:
+    drafts = {}
+    for span in run.spans.values():
+        adapter = adapter_for(span)
+        drafts[span.span_id] = _Draft(
+            id=span.span_id,
+            raw_parent=span.parent_span_id,
+            c=adapter.classify(span),
+            span=span,
+            convention=adapter.name,
+            start_ns=span.start_time_unix_nano,
+            end_ns=span.end_time_unix_nano,
+        )
+    # Start reports (loopview-sdk): real steps, with real names, still running.
+    for span in run.started.values():
+        adapter = adapter_for(span)
+        drafts[span.span_id] = _Draft(
+            id=span.span_id,
+            raw_parent=span.parent_span_id,
+            c=adapter.classify(span),
+            span=span,
+            convention=adapter.name,
+            start_ns=span.start_time_unix_nano,
+            end_ns=None,
+            started_only=True,
+        )
+    return drafts
+
+
+def _add_costs(drafts: dict[str, _Draft], pricing: Pricing) -> None:
+    """Each finished model call gets its cost split. A call still running has no
+    usage yet, so it gets none."""
+    for d in drafts.values():
+        if d.c.model is not None and not d.started_only:
+            d.c.model.cost = call_cost(d.c.model, pricing)
+
+
+# --- pass 2 --------------------------------------------------------------------------
+
+
+def _add_inferred_parents(run: Run, drafts: dict[str, _Draft], stale: bool) -> None:
+    known = run.spans.keys() | run.started.keys()
+    missing: dict[str, list[RawSpan]] = {}
+    for span in [*run.spans.values(), *run.started.values()]:
+        if span.parent_span_id and span.parent_span_id not in known:
+            missing.setdefault(span.parent_span_id, []).append(span)
+
+    for parent_id, children in missing.items():
+        hint: ParentHint | None = None
+        convention = "generic"
+        for child in children:
+            adapter = adapter_for(child)
+            hint = adapter.infer_parent(child)
+            if hint:
+                convention = adapter.name
+                break
+        if hint:
+            c = Classification(hint.kind, hint.name, hint.type_label)
+        else:
+            # Nothing names it yet: use the service name, which is usually the
+            # application the whole run belongs to.
+            service = children[0].resource_attributes.get("service.name")
+            c = Classification("node", str(service or "running"), "running")
+        drafts[parent_id] = _Draft(
+            id=parent_id,
+            raw_parent=None,  # unknown until its span arrives
+            c=c,
+            span=None,
+            convention=convention,
+            start_ns=min(child.start_time_unix_nano for child in children),
+            # A stale run won't send this span any more: close it at its last child.
+            end_ns=max(c.end_time_unix_nano or c.start_time_unix_nano for c in children)
+            if stale
+            else None,
+        )
+
+    # A trace has exactly one root. Until it arrives, several inferred steps can
+    # have no known parent; they all descend from the root, so hang them under
+    # the one that started first, which is the closest guess for the root.
+    if run.root is None:
+        orphans = sorted(
+            (d for d in drafts.values() if d.raw_parent is None),
+            key=lambda d: (d.start_ns, d.id),
+        )
+        for orphan in orphans[1:]:
+            orphan.raw_parent = orphans[0].id
+
+
+def _place_unclassified_starts(drafts: dict[str, _Draft]) -> None:
+    """Start reports (loopview-sdk) of spans no adapter recognises yet.
+
+    Some instrumentations (OpenInference for LangChain) set every attribute when
+    the span ends, so at start a span is just a name. Position is the only clue:
+    steps of a flow are direct children of a container (the run's root, or an
+    agent), while plumbing (model wrappers, parsers) sits inside a step. So an
+    unclassified start is shown as a running node only under a container, and is
+    kept hidden otherwise until it ends and its adapter can classify it.
+    """
+    for d in drafts.values():
+        if not d.started_only or d.c.kind != "unknown":
+            continue
+        parent = drafts.get(d.raw_parent) if d.raw_parent else None
+        is_root = d.raw_parent is None
+        under_container = parent is not None and (
+            parent.raw_parent is None or parent.c.kind == "agent"
+        )
+        if is_root or under_container:
+            d.c.kind = "node"
+            d.c.type_label = "running"
+            d.c.attributes = {}
+        else:
+            d.c.hidden = True
+
+
+# --- pass 3 --------------------------------------------------------------------------
+
+
+def _decide_hidden(drafts: dict[str, _Draft]) -> None:
+    for d in drafts.values():
+        parent = drafts.get(d.raw_parent) if d.raw_parent else None
+        if d.c.hidden:
+            d.hidden = True
+        elif d.c.collapse_into_parent and parent is not None and parent.c.name == d.c.name:
+            d.hidden = True  # a subgraph span directly inside the node that runs it
+        elif d.c.kind == "unknown" and _inside_call(d, drafts):
+            d.hidden = True  # e.g. the HTTP request made by a model call
+
+
+def _inside_call(d: _Draft, drafts: dict[str, _Draft]) -> bool:
+    parent_id = d.raw_parent
+    while parent_id and parent_id in drafts:
+        parent = drafts[parent_id]
+        if parent.c.kind in ("model_call", "tool_call"):
+            return True
+        if parent.c.kind != "unknown":
+            return False
+        parent_id = parent.raw_parent
+    return False
+
+
+# --- pass 4 --------------------------------------------------------------------------
+
+
+def _link(run_id: str, drafts: dict[str, _Draft], stale: bool) -> list[Step]:
+    def visible_ancestor(d: _Draft, flow_only: bool) -> str | None:
+        parent_id = d.raw_parent
+        while parent_id and parent_id in drafts:
+            parent = drafts[parent_id]
+            if not parent.hidden and (not flow_only or parent.c.kind in FLOW_KINDS):
+                return parent_id
+            parent_id = parent.raw_parent
+        return None
+
+    parent_of = {d.id: visible_ancestor(d, flow_only=False) for d in drafts.values()}
+    scope_of = {d.id: visible_ancestor(d, flow_only=True) for d in drafts.values()}
+
+    # A node that contains other flow steps is a group: a subgraph or nested agent.
+    owners = {
+        scope_of[d.id]
+        for d in drafts.values()
+        if not d.hidden and d.c.kind in FLOW_KINDS and scope_of[d.id]
+    }
+    for owner_id in owners:
+        owner = drafts[owner_id]
+        if owner.c.kind == "node":
+            owner.c.kind = "agent"
+            owner.c.type_label = "agent"
+
+    keys: dict[str, str] = {}
+
+    def key_of(step_id: str) -> str:
+        if step_id not in keys:
+            d = drafts[step_id]
+            name = d.c.name if d.c.kind in FLOW_KINDS else f"{d.c.kind}:{d.c.name}"
+            scope = scope_of[step_id]
+            keys[step_id] = f"{key_of(scope)}/{name}" if scope else name
+        return keys[step_id]
+
+    steps = []
+    for d in drafts.values():
+        status: StepStatus
+        if d.span is None or d.started_only:
+            status = "ok" if stale else "running"
+        else:
+            status = "error" if d.span.status_code == "error" else "ok"
+        steps.append(
+            Step(
+                id=d.id,
+                run_id=run_id,
+                parent_id=parent_of[d.id],
+                scope_id=scope_of[d.id],
+                kind=d.c.kind,
+                type_label=d.c.type_label,
+                name=d.c.name,
+                key=key_of(d.id),
+                status=status,
+                inferred=d.span is None,
+                hidden=d.hidden,
+                start_ns=d.start_ns,
+                end_ns=d.end_ns,
+                error=error_message(d.span) if d.span is not None and not d.started_only else None,
+                model=d.c.model,
+                tool=d.c.tool,
+                input=d.c.input,
+                output=d.c.output,
+                convention=d.convention,
+                attributes=d.c.attributes,
+            )
+        )
+    # Deterministic order: by start time, then span id (timestamps can tie).
+    steps.sort(key=lambda s: (s.start_ns, s.id))
+    return steps
+
+
+def _service_name(run: Run) -> str:
+    """What to call a run's synthetic agent: the service that sent it."""
+    for span in run.spans.values():
+        name = span.resource_attributes.get("service.name")
+        if name and not str(name).startswith("unknown_service"):
+            return str(name)
+    return "agent"
+
+
+# --- run info ------------------------------------------------------------------------
+
+
+def _run_info(run: Run, steps: list[Step], stale: bool) -> RunInfo:
+    root = run.root
+    running = root is None and not stale
+    if root is not None and root.status_code == "error":
+        status: StepStatus = "error"
+    else:
+        status = "running" if running else "ok"
+    known = [*run.spans.values(), *run.started.values()]
+    named_after = root or min(known, key=lambda s: s.start_time_unix_nano)
+    # The top step: the real root, or while it's missing the provisional one.
+    top_step = next((s for s in steps if s.parent_id is None), None)
+    return RunInfo(
+        id=run.trace_id,
+        name=top_step.name if top_step else named_after.name,
+        service_name=named_after.resource_attributes.get("service.name"),
+        session_id=run.session_id,
+        status=status,
+        start_ns=min(s.start_ns for s in steps),
+        end_ns=None if running else max(s.end_ns or s.start_ns for s in steps),
+        step_count=len(steps),
+        last_received_ns=run.last_received_ns,
+    )

loopview/normalize/schema.py

@@ -0,0 +1,161 @@
+"""The normalized schema: the only shape the UI ever sees.
+
+Every span, whatever convention it follows, becomes one Step. Transitions
+between steps are derived afterwards (transitions.py). A NormalizedRun is
+everything the UI needs to draw one run: its steps and its transitions.
+
+Kinds of steps:
+- agent:      a named actor that contains other steps (an agent, a workflow, a
+              graph or subgraph). Drawn as a group.
+- node:       a named step in a flow (a graph node, a chain step). Drawn as a card.
+- model_call: one call to a model. Drawn as a detail of its node, not as a node.
+- tool_call:  one tool execution. Drawn as a small satellite of its node.
+- unknown:    a span no adapter recognised. Drawn generically, never dropped.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+StepKind = Literal["agent", "node", "model_call", "tool_call", "unknown"]
+StepStatus = Literal["running", "ok", "error"]
+TransitionKind = Literal["sequence", "loop", "fan_out", "fan_in", "handoff", "delegate", "return"]
+
+# Steps that take part in control flow (graph nodes). Model and tool calls hang off them.
+FLOW_KINDS: frozenset[str] = frozenset({"agent", "node", "unknown"})
+
+
+class MessagePart(BaseModel):
+    type: Literal["text", "reasoning", "tool_call", "tool_result", "other"]
+    text: str | None = None  # text and reasoning (thinking) parts, a readable form of "other"
+    id: str | None = None  # tool call id, for tool_call and tool_result
+    name: str | None = None  # tool name, for tool_call
+    arguments: Any = None  # tool_call
+    result: Any = None  # tool_result
+    # tool_result: the result was flagged as an error by the caller (Anthropic's
+    # is_error). None when the trace doesn't say, which is not the same as False.
+    is_error: bool | None = None
+
+
+class Message(BaseModel):
+    role: str  # system | user | assistant | tool (kept as given if something else)
+    parts: list[MessagePart]
+
+
+class Usage(BaseModel):
+    """Token counts as the provider reported them. None means "not reported",
+    which is different from 0. Both specs define the input count as including
+    cache reads and writes, and the output count as including thinking."""
+
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cache_read_tokens: int | None = None  # part of input_tokens
+    cache_write_tokens: int | None = None  # part of input_tokens
+    reasoning_tokens: int | None = None  # part of output_tokens
+
+
+CostSegmentName = Literal[
+    "tool_prompt",
+    "tool_definitions",
+    "system",
+    "history",
+    "tool_results",
+    "new_input",
+    "cache_read",
+    "cache_write",
+    "thinking",
+    "reply",
+    "unattributed",
+]
+
+
+class CostSegment(BaseModel):
+    name: CostSegmentName
+    side: Literal["input", "output"]
+    tokens: int
+    dollars: float | None  # None when the model has no price
+
+
+class CallCost(BaseModel):
+    """Where a model call's tokens came from (see loopview/cost/split.py)."""
+
+    # estimated: split from recorded content, scaled to the reported counts
+    # content_not_recorded: reported counts, but nothing to split them with
+    # no_usage: the instrumentation reported no token counts at all
+    status: Literal["estimated", "content_not_recorded", "no_usage"]
+    segments: list[CostSegment] = []
+    tokens: int | None = None  # reported input + output
+    dollars: float | None = None  # None when the model has no price
+    price_key: str | None = None  # the pricing entry used
+    price_source: str | None = None
+
+
+class ModelCall(BaseModel):
+    provider: str | None = None
+    model: str | None = None
+    input: list[Message] = []
+    output: list[Message] = []
+    tool_definitions: list[Any] = []  # the tools the model was given, as recorded
+    usage: Usage | None = None  # None when the instrumentation reported no counts
+    cost: CallCost | None = None  # set by the normalizer
+
+
+class ToolCall(BaseModel):
+    name: str
+    call_id: str | None = None
+    arguments: Any = None
+    result: Any = None
+
+
+class Step(BaseModel):
+    id: str  # the span id
+    run_id: str  # the trace id
+    parent_id: str | None  # nearest ancestor step that is not hidden
+    scope_id: str | None  # nearest ancestor flow step (agent/node) that is not hidden
+    kind: StepKind
+    type_label: str  # small label for the UI: "agent", "graph", "node", "llm", "tool"...
+    name: str
+    key: str  # graph identity: scope path + name. Repeated runs of a node share a key.
+    status: StepStatus
+    # True when we only know this step exists because its children arrived:
+    # exporters send a span when it ends, so a running step has no span yet.
+    inferred: bool = False
+    # True for steps no span stands for: the `model` and `tools` nodes added to a
+    # flat agent loop (normalize/loop_nodes.py).
+    synthetic: bool = False
+    hidden: bool = False  # internal plumbing (routing functions, parsers); kept, not drawn
+    start_ns: int
+    end_ns: int | None  # None while running
+    error: str | None = None
+    model: ModelCall | None = None
+    tool: ToolCall | None = None
+    input: Any = None  # generic input/output when the convention provides one
+    output: Any = None
+    convention: str  # which adapter produced this step: gen_ai | openinference | generic
+    attributes: dict[str, Any] = {}  # raw attributes, only for unknown steps
+
+
+class Transition(BaseModel):
+    id: str
+    source: str  # step id
+    target: str  # step id
+    kind: TransitionKind
+    inferred: bool = True  # derived from timing and nesting, not stated by the framework
+
+
+class RunInfo(BaseModel):
+    id: str
+    name: str
+    service_name: str | None
+    session_id: str | None
+    status: StepStatus
+    start_ns: int
+    end_ns: int | None
+    step_count: int
+    last_received_ns: int
+
+
+class NormalizedRun(BaseModel):
+    run: RunInfo
+    steps: list[Step]
+    transitions: list[Transition]

loopview/normalize/transitions.py

@@ -0,0 +1,106 @@
+"""Derive transitions (control moving between steps) from timing and nesting.
+
+No convention we support states "control went from A to B", so we derive it.
+Only flow steps (agents, nodes, unknown) take part; model and tool calls are
+details of the step that made them.
+
+Within one scope (the steps directly inside the same agent, graph or node):
+
+    A precedes B  when A ended before B started.
+    A -> B        when A precedes B and no step C sits between them
+                  (A precedes C and C precedes B).
+
+That one rule covers every architecture:
+- sequence:  A ends, B starts             -> A -> B
+- parallel:  B1, B2, B3 overlap in time   -> none precedes another, so
+             A -> B1, A -> B2, A -> B3 (fan out) and B1, B2, B3 -> C (fan in)
+- loops:     A runs again later           -> an edge back to A's graph node
+- handoffs:  agent X ends, agent Y starts -> X -> Y
+
+Across scopes: the first steps in a scope get a `delegate` edge from the scope's
+owner (a supervisor calling a worker, a graph entering its first node), and the
+last steps a `return` edge back once the owner has finished.
+
+A running step (no end yet) precedes nothing, so edges out of it appear once it ends.
+"""
+
+from loopview.normalize.schema import FLOW_KINDS, Step, Transition, TransitionKind
+
+
+def derive_transitions(steps: list[Step]) -> list[Transition]:
+    by_id = {s.id: s for s in steps}
+    scopes: dict[str | None, list[Step]] = {}
+    for step in steps:
+        if not step.hidden and step.kind in FLOW_KINDS:
+            scopes.setdefault(step.scope_id, []).append(step)
+
+    transitions: list[Transition] = []
+    for scope_id, members in scopes.items():
+        members.sort(key=lambda s: (s.start_ns, s.id))
+        edges = _immediate_predecessors(members)
+        transitions += _label(edges, members)
+
+        owner = by_id.get(scope_id) if scope_id else None
+        if owner is None:
+            continue
+        has_incoming = {target for _, target in edges}
+        has_outgoing = {source for source, _ in edges}
+        for step in members:
+            if step.id not in has_incoming:
+                transitions.append(_transition(owner, step, "delegate"))
+            if owner.end_ns is not None and step.end_ns is not None and step.id not in has_outgoing:
+                transitions.append(_transition(step, owner, "return"))
+    return transitions
+
+
+def _precedes(a: Step, b: Step) -> bool:
+    return a.end_ns is not None and a.end_ns <= b.start_ns and a.id != b.id
+
+
+def _immediate_predecessors(members: list[Step]) -> list[tuple[str, str]]:
+    """Edges of the "happens before" order with the implied (transitive) ones removed.
+
+    O(n^2) per step in the worst case; scopes hold at most a few hundred steps.
+    """
+    edges = []
+    for b in members:
+        before = [a for a in members if _precedes(a, b)]
+        for a in before:
+            if not any(_precedes(a, c) for c in before):
+                edges.append((a.id, b.id))
+    return edges
+
+
+def _label(edges: list[tuple[str, str]], members: list[Step]) -> list[Transition]:
+    by_id = {s.id: s for s in members}
+    # A graph node's position: when its key first appeared in this scope. An edge
+    # to a node that appeared no later than the source is a loop (a back edge).
+    first_seen: dict[str, int] = {}
+    for index, step in enumerate(members):
+        first_seen.setdefault(step.key, index)
+    out_degree: dict[str, int] = {}
+    in_degree: dict[str, int] = {}
+    for source, target in edges:
+        out_degree[source] = out_degree.get(source, 0) + 1
+        in_degree[target] = in_degree.get(target, 0) + 1
+
+    result = []
+    for source_id, target_id in edges:
+        source, target = by_id[source_id], by_id[target_id]
+        kind: TransitionKind
+        if first_seen[target.key] <= first_seen[source.key]:
+            kind = "loop"
+        elif out_degree[source_id] > 1:
+            kind = "fan_out"
+        elif in_degree[target_id] > 1:
+            kind = "fan_in"
+        elif target.kind == "agent" and not target.synthetic:
+            kind = "handoff"  # a synthetic tools group is a step of the loop, not an agent
+        else:
+            kind = "sequence"
+        result.append(_transition(source, target, kind))
+    return result
+
+
+def _transition(source: Step, target: Step, kind: TransitionKind) -> Transition:
+    return Transition(id=f"{source.id}>{target.id}", source=source.id, target=target.id, kind=kind)