agent-tracegraph 0.2.0__py3-none-any.whl

tracegraph/adapters/phoenix_export.py

@@ -0,0 +1,218 @@
+"""Body-free ingestion of trace JSON exported by the official Phoenix CLI."""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime
+from pathlib import Path
+import re
+from typing import Any
+
+from tracegraph.adapters.otlp_spans import OTLPSpanAdapter, _span_array
+from tracegraph.input_validation import loads, object_field
+from tracegraph.model import CausalFidelity, RawTrace
+
+_SAFE_ATTRIBUTES = {
+    "graph.node.id",
+    "graph.node.parent_id",
+    "llm.token_count.prompt",
+    "llm.token_count.completion",
+    "llm.token_count.total",
+    "llm.token_count.input",
+    "llm.token_count.output",
+    "llm.cost.prompt",
+    "llm.cost.completion",
+    "llm.cost.total",
+    "llm.cost.input",
+    "llm.cost.output",
+    "llm.cost.currency",
+}
+
+
+def _first(mapping: dict[str, Any], *names: str) -> Any:
+    for name in names:
+        value = mapping.get(name)
+        if value is not None:
+            return value
+    return None
+
+
+def _nanos(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return str(int(value))
+    text = str(value)
+    if text.isdigit():
+        return text
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return str(int(parsed.timestamp() * 1_000_000_000))
+
+
+_OPERATION_NAME = re.compile(r"[A-Za-z0-9_.:/#@-]{1,200}")
+
+
+def _safe_operation_name(value: Any) -> str | None:
+    if value is None:
+        return None
+    # Operation identifiers are useful, but natural-language span names can themselves be
+    # prompts. Keep identifier-shaped names only; reports fall back to the normalized kind.
+    clean = str(value).strip()
+    return clean if _OPERATION_NAME.fullmatch(clean) else None
+
+
+def _safe_evaluation_text(value: Any) -> str | None:
+    if value is None:
+        return None
+    clean = " ".join(str(value).split())
+    return clean[:200] or None
+
+
+def _attrs(span: dict[str, Any]) -> dict[str, Any]:
+    from tracegraph.adapters.otlp_spans import _attributes
+    raw = _attributes(span)
+    safe = {key: raw[key] for key in _SAFE_ATTRIBUTES if key in raw}
+    kind = _first(span, "span_kind", "spanKind") or raw.get("openinference.span.kind")
+    if kind is not None:
+        safe["openinference.span.kind"] = kind
+    return safe
+
+
+def _evaluations(span: dict[str, Any]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for annotation in span.get("annotations") or []:
+        if not isinstance(annotation, dict):
+            continue
+        result = annotation.get("result") or {}
+        if not isinstance(result, dict):
+            result = {}
+        name = annotation.get("name")
+        if not name:
+            continue
+        label = _first(result, "label") or annotation.get("label")
+        score = _first(result, "score")
+        if score is None:
+            score = annotation.get("score")
+        try:
+            score = float(score) if score is not None else None
+        except (TypeError, ValueError):
+            score = None
+        if score is not None and not math.isfinite(score):
+            score = None
+        out.append(
+            {
+                "name": _safe_evaluation_text(name),
+                "label": _safe_evaluation_text(label),
+                "score": score,
+            }
+        )
+    return out
+
+
+def _trace_objects(document: Any) -> list[dict[str, Any]]:
+    if isinstance(document, list):
+        candidates = document
+    elif isinstance(document, dict) and isinstance(document.get("traces"), list):
+        candidates = document["traces"]
+    elif isinstance(document, dict) and isinstance(document.get("data"), list):
+        candidates = document["data"]
+    elif isinstance(document, dict) and isinstance(document.get("spans"), list):
+        candidates = [document]
+    else:
+        raise ValueError("Phoenix export must be a trace object or an array of trace objects")
+    if not all(isinstance(item, dict) and isinstance(item.get("spans"), list) for item in candidates):
+        raise ValueError("every Phoenix trace must be an object with a spans array")
+    return candidates
+
+
+class PhoenixExportAdapter:
+    """Convert Phoenix CLI trace DTOs through the shared OTLP causal builder."""
+
+    def __init__(self, document: Any) -> None:
+        self._traces = _trace_objects(document)
+        self._ids: list[str] = []
+        self._by_id: dict[str, dict[str, Any]] = {}
+        for trace in self._traces:
+            trace_id = self._trace_id(trace)
+            if trace_id in self._by_id:
+                raise ValueError(f"duplicate Phoenix traceId {trace_id!r}")
+            self._ids.append(trace_id)
+            self._by_id[trace_id] = trace
+
+    @classmethod
+    def from_json(cls, text: str) -> "PhoenixExportAdapter":
+        return cls(loads(text))
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "PhoenixExportAdapter":
+        return cls.from_json(Path(path).read_text(encoding="utf-8"))
+
+    def discover(self) -> list[str]:
+        return list(self._ids)
+
+    def ingest(self, trace_id: str) -> RawTrace:
+        try:
+            trace = self._by_id[trace_id]
+        except KeyError as exc:
+            raise KeyError(f"no Phoenix trace {trace_id!r}") from exc
+        spans = [self._span(trace_id, span) for span in trace["spans"]]
+        document = {"resourceSpans": [{"scopeSpans": [{"spans": spans}]}]}
+        return OTLPSpanAdapter(
+            document,
+            source_kind="phoenix_cli",
+            links_as_causes=False,
+            include_error_messages=False,
+            preserve_unset_status=True,
+            causal_fidelity=CausalFidelity.PARENT_ONLY,
+            links_preserved=False,
+        ).ingest(trace_id)
+
+    @staticmethod
+    def _trace_id(trace: dict[str, Any]) -> str:
+        declared = _first(trace, "traceId", "trace_id")
+        span_ids = set()
+        for span in trace["spans"]:
+            if not isinstance(span, dict):
+                raise ValueError("spans[] must be an object")
+            context = object_field(span.get("context"), "spans[].context")
+            sid = _first(context, "trace_id", "traceId")
+            if sid is not None and not isinstance(sid, str):
+                raise ValueError("spans[].context.trace_id must be a string")
+            span_ids.add(sid)
+        span_ids.discard(None)
+        if declared is None and len(span_ids) == 1:
+            declared = next(iter(span_ids))
+        if not isinstance(declared, str) or not declared:
+            raise ValueError("Phoenix trace has no usable traceId")
+        if span_ids and span_ids != {declared}:
+            raise ValueError(f"Phoenix trace {declared!r} contains spans from another trace")
+        return declared
+
+    @staticmethod
+    def _span(trace_id: str, span: Any) -> dict[str, Any]:
+        if not isinstance(span, dict):
+            raise ValueError(f"Phoenix trace {trace_id!r} contains a non-object span")
+        context = object_field(span.get("context"), "spans[].context")
+        span_id = _first(context, "span_id", "spanId") or _first(span, "id", "span_id", "spanId")
+        if not isinstance(span_id, str) or not span_id:
+            raise ValueError(f"Phoenix trace {trace_id!r} contains a span with no id")
+        status = _first(span, "status_code", "statusCode")
+        return {
+            "traceId": trace_id,
+            "spanId": span_id,
+            "parentSpanId": _first(span, "parent_id", "parentId"),
+            "name": _safe_operation_name(span.get("name")),
+            "startTimeUnixNano": _nanos(_first(span, "start_time", "startTime")),
+            "endTimeUnixNano": _nanos(_first(span, "end_time", "endTime")),
+            "status": {
+                "code": status,
+                # Read transiently for status normalization; Phoenix imports never persist it.
+                "message": _first(span, "status_message", "statusMessage"),
+            },
+            "attributes": _attrs(span),
+            "events": _span_array(span, "events"),
+            "_tracegraph_evaluations": _evaluations(span),
+        }

tracegraph/analysis/__init__.py

@@ -0,0 +1,55 @@
+"""Analysis layer. Each analysis declares which graph layer it reads.
+
+| analysis           | layer                      |
+|--------------------|----------------------------|
+| explain / RCA      | raw CAUSED_BY              |
+| diff (AHU)         | derived TREE_PARENT        |
+| inspect render     | derived TREE_PARENT        |
+"""
+
+from tracegraph.analysis.ahu import (
+    TreeDiff,
+    canonical,
+    default_label,
+    diff,
+    is_isomorphic,
+    structure_only,
+)
+from tracegraph.analysis.explain import Explanation, explain
+from tracegraph.analysis.diagnose import AnalysisReport, analyze, dumps as dump_analysis
+from tracegraph.analysis.patterns import (
+    MAX_GAP,
+    PRESETS,
+    CompiledQuery,
+    Match,
+    PathPattern,
+    StepPredicate,
+    UncompilablePattern,
+    compile_to_cypher,
+    find_matches,
+    search,
+)
+
+__all__ = [
+    "Explanation",
+    "explain",
+    "AnalysisReport",
+    "analyze",
+    "dump_analysis",
+    "TreeDiff",
+    "canonical",
+    "default_label",
+    "diff",
+    "is_isomorphic",
+    "structure_only",
+    "MAX_GAP",
+    "PRESETS",
+    "CompiledQuery",
+    "Match",
+    "PathPattern",
+    "StepPredicate",
+    "UncompilablePattern",
+    "compile_to_cypher",
+    "find_matches",
+    "search",
+]

tracegraph/analysis/ahu.py

@@ -0,0 +1,329 @@
+"""Structural regression diff over the **derived** ``TREE_PARENT`` forest.
+
+Two runs are compared as rooted trees. Isomorphism uses the Aho–Hopcroft–Ullman (AHU)
+canonical form — each node's canonical value is its label plus the *sorted* canonical values
+of its children — which is exact on a forest (the whole reason we project the
+multi-parent causal graph down to a single-parent tree for diffing).
+
+The public canonical values remain **nested tuples**, not strings: ``(label, (child_canon, ...))``. Tuples
+preserve structure, so — unlike string concatenation — a label containing
+``(``, ``)`` or ``,`` can never forge a false match.
+
+Diff and equality intern (label, sorted child IDs) in a table shared by both trees,
+avoiding recursive tuple hashing/comparison. Sorting adds O(d log d) per sibling set.
+
+Per the layer contract this reads ``TREE_PARENT`` only. ``CAUSED_BY`` (the raw layer) is for
+``explain``/RCA, never for structural diff.
+
+Note on ``diff``: the boolean ``identical`` is exact (AHU). The "diverges at …" explanation is
+a readable *heuristic* localization (it pairs unmatched children only on structural/label
+evidence, never positionally), not a proven minimal tree-edit script; on trees with several
+changed siblings it may point at a plausible-but-not-unique node, but it will not invent a
+correspondence between two genuinely unrelated siblings.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from functools import cmp_to_key
+from typing import Callable
+
+from tracegraph.model import EdgeType, NormalizedTrace, Step
+from tracegraph.normalize import validate_tree
+
+#: How a node is identified for structural comparison. Default = node name, falling back to
+#: kind. Pass ``structure_only`` to compare pure topology (shape) ignoring labels.
+LabelFn = Callable[[Step], str]
+
+#: A collision-free canonical value: ``(label, (sorted child canons...))``.
+Canon = tuple
+
+
+def default_label(step: Step) -> str:
+    return step.name or step.kind.value
+
+
+def structure_only(step: Step) -> str:  # noqa: ARG001 - intentionally ignores the node
+    return ""
+
+
+def _children(nt: NormalizedTrace) -> dict[str, list[str]]:
+    """parent_id -> [child_id, ...] from TREE_PARENT (which points child -> parent)."""
+    out: dict[str, list[str]] = {}
+    for e in nt.edges_of(EdgeType.TREE_PARENT):
+        out.setdefault(e.dst, []).append(e.src)
+    return out
+
+
+def _roots(nt: NormalizedTrace, children: dict[str, list[str]]) -> list[str]:
+    has_parent = {e.src for e in nt.edges_of(EdgeType.TREE_PARENT)}
+    return [s.step_id for s in nt.steps if s.step_id not in has_parent]
+
+
+def _require_forest(nt: NormalizedTrace, side: str) -> None:
+    """Reject a derived layer that is not a forest, *before* walking it.
+
+    ``_roots`` treats "has no TREE_PARENT edge" as "is a root", which makes three malformed
+    shapes dangerous, and only a pre-check catches all of them:
+
+    * a **disconnected** cycle leaves its whole component rootless and therefore unvisited,
+      so the comparison silently ran on a subset — two traces could be reported identical
+      while one held an entire component the other lacked;
+    * a cycle **reachable** from a root (a self-edge, say) is walked forever, so a check
+      placed after traversal never runs at all;
+    * duplicate step ids make any count-based check unreliable.
+
+    ``validate_tree`` already rejects unknown endpoints, multi-parent steps and cycles; a
+    trace that passes it has every node reachable from a root, because following parents is
+    then a terminating walk. Unique ids are checked here since ``validate_tree`` does not.
+    """
+    ids = [step.step_id for step in nt.steps]
+    if len(ids) != len(set(ids)):
+        # One pass, not `ids.count()` per id: rejecting a large malformed trace should not
+        # itself be quadratic.
+        duplicates = sorted(sid for sid, n in Counter(ids).items() if n > 1)
+        raise ValueError(f"{side}: duplicate step_id in trace: {', '.join(duplicates)}")
+    try:
+        validate_tree(nt)
+    except ValueError as exc:
+        raise ValueError(
+            f"{side}: the derived TREE_PARENT layer is not a forest ({exc}), so a structural "
+            "comparison would silently ignore or endlessly revisit part of it."
+        ) from exc
+
+
+def _compare(left: Canon, right: Canon) -> int:
+    # Tuple-compatible lexical order without Python's recursive tuple comparison.
+    stack = [(left, right)]
+    while stack:
+        a, b = stack.pop()
+        if a is b:
+            continue
+        if isinstance(a, str):
+            if a != b:
+                return -1 if a < b else 1
+            continue
+        common = min(len(a), len(b))
+        if len(a) != len(b):
+            stack.append(("" if len(a) < len(b) else "x", "x" if len(a) < len(b) else ""))
+        stack.extend((a[i], b[i]) for i in range(common - 1, -1, -1))
+    return 0
+
+
+def _intern(steps, children, roots, label, table):
+    result = {}
+    stack = [(root, False) for root in roots]
+    while stack:
+        node, ready = stack.pop()
+        if ready:
+            signature = (label(steps[node]), tuple(sorted(result[c] for c in children.get(node, []))))
+            result[node] = table.setdefault(signature, len(table))
+        else:
+            stack.append((node, True))
+            stack.extend((child, False) for child in children.get(node, []))
+    return result
+
+
+def _subtree_canons(
+    steps: dict[str, Step], children: dict[str, list[str]], roots: list[str], label: LabelFn
+) -> dict[str, Canon]:
+    """Canonical AHU tuple per node id (iterative post-order over the whole forest).
+
+    Iterative on purpose: agent traces are deep and near-linear, so a recursive post-order
+    overflows Python's recursion limit at ~500 nodes. The two-phase stack visits each node
+    once and computes its canon only after every child's canon already exists.
+    """
+    canon: dict[str, Canon] = {}
+    for root in roots:
+        stack: list[tuple[str, bool]] = [(root, False)]
+        while stack:
+            nid, ready = stack.pop()
+            if ready:
+                kids = tuple(sorted((canon[c] for c in children.get(nid, [])), key=cmp_to_key(_compare)))
+                canon[nid] = (label(steps[nid]), kids)
+            else:
+                stack.append((nid, True))
+                for c in children.get(nid, []):
+                    stack.append((c, False))
+    return canon
+
+
+def canonical(nt: NormalizedTrace, label: LabelFn = default_label) -> Canon:
+    """Sorted nested root tuples; use is_isomorphic for recursion-safe deep equality."""
+    _require_forest(nt, "trace")
+    children = _children(nt)
+    steps = nt.steps_by_id()
+    roots = _roots(nt, children)
+    canon = _subtree_canons(steps, children, roots, label)
+    return tuple(sorted((canon[r] for r in roots), key=cmp_to_key(_compare)))
+
+
+def is_isomorphic(a: NormalizedTrace, b: NormalizedTrace, label: LabelFn = default_label) -> bool:
+    _require_forest(a, "A")
+    _require_forest(b, "B")
+    table = {}
+    ca, cb = _children(a), _children(b)
+    ra, rb = _roots(a, ca), _roots(b, cb)
+    aa = _intern(a.steps_by_id(), ca, ra, label, table)
+    bb = _intern(b.steps_by_id(), cb, rb, label, table)
+    return sorted(aa[r] for r in ra) == sorted(bb[r] for r in rb)
+
+
+@dataclass
+class TreeDiff:
+    identical: bool
+    changes: list[str] = field(default_factory=list)
+
+    def __bool__(self) -> bool:  # truthy when there IS a difference
+        return not self.identical
+
+
+def diff(a: NormalizedTrace, b: NormalizedTrace, label: LabelFn = default_label, *, display_label: LabelFn | None = None) -> TreeDiff:
+    """Compare two runs structurally. ``identical`` is exact; ``changes`` is a heuristic localization.
+
+    Aligns children by canonical subtree (so identical subtrees match regardless of order),
+    descends through *corresponding* mismatched pairs (paired only on real structural/label
+    evidence, never positionally) to pinpoint the deepest divergence, and reports genuinely
+    unmatched subtrees as present-only-in-A / present-only-in-B. Iterative throughout, so it
+    handles the deep-linear traces LangGraph produces without overflowing the stack.
+    """
+    _require_forest(a, "A")
+    _require_forest(b, "B")
+    sa, sb = a.steps_by_id(), b.steps_by_id()
+    ca, cb = _children(a), _children(b)
+    ra, rb = _roots(a, ca), _roots(b, cb)
+    table = {}
+    canA = _intern(sa, ca, ra, label, table)
+    canB = _intern(sb, cb, rb, label, table)
+    show = display_label or label
+
+    def render(node, steps, children):
+        parts = []
+        stack = [(node, False)]
+        while stack:
+            item, literal = stack.pop()
+            if literal:
+                parts.append(item)
+                continue
+            parts.append(show(steps[item]) or "·")
+            kids = children.get(item, [])
+            if kids:
+                parts.append("(")
+                stack.append((")", True))
+                for i in range(len(kids) - 1, -1, -1):
+                    stack.append((kids[i], False))
+                    if i:
+                        stack.append((", ", True))
+        return "".join(parts)
+
+    def path_text(path):
+        parts = []
+        while path is not None:
+            path, name = path
+            parts.append(name)
+        return " > ".join(reversed(parts))
+    # Same comparison as is_isomorphic(), reusing the canons computed above.
+    if tuple(sorted(canA[r] for r in ra)) == tuple(sorted(canB[r] for r in rb)):
+        return TreeDiff(identical=True)
+
+    changes: list[str] = []
+
+    def align(a_ids: list[str], b_ids: list[str]) -> tuple[list[str], list[str]]:
+        """Pop A/B ids whose canonical subtrees match; return the leftovers on each side."""
+        bucket: dict[int, list[str]] = {}
+        for k in b_ids:
+            bucket.setdefault(canB[k], []).append(k)
+        a_only: list[str] = []
+        for k in a_ids:
+            pool = bucket.get(canA[k])
+            if pool:
+                pool.pop()  # identical subtree on both sides -> matched, nothing to report
+            else:
+                a_only.append(k)
+        b_only = [k for pool in bucket.values() for k in pool]
+        return a_only, b_only
+
+    def pair_leftovers(
+        a_ids: list[str], b_ids: list[str]
+    ) -> tuple[list[tuple[str, str]], list[str], list[str]]:
+        """Pair unmatched subtrees that genuinely correspond, so "diverges at" never asserts
+        a false A<->B correspondence between unrelated siblings.
+
+        Correspondence requires real evidence — identical *non-empty* child structure (a
+        relabel of this node, surfaced as "diverges at"), then identical root label (a node
+        with changed descendants, localized by descending). Everything else is honest
+        add/remove. There is deliberately NO positional fallback: one unmatched leaf per side
+        with nothing in common is an add+remove, not a relabel — and "one leftover each" is
+        not itself evidence (the parent may simply have had several children, all but one of
+        which aligned away), so we never pair on sibling position alone. That positional
+        guess was the bug this replaced.
+        """
+        pairs: list[tuple[str, str]] = []
+        a_left, b_left = list(a_ids), list(b_ids)
+
+        def greedy(key_a: Callable[[str], object], key_b: Callable[[str], object]) -> None:
+            nonlocal a_left, b_left
+            index: dict[object, list[str]] = {}
+            for k in b_left:
+                kb = key_b(k)
+                if kb is not None:
+                    index.setdefault(kb, []).append(k)
+            still_a, used_b = [], set()
+            for k in a_left:
+                ka = key_a(k)
+                pool = index.get(ka) if ka is not None else None
+                if pool:
+                    bk = pool.pop()
+                    used_b.add(bk)
+                    pairs.append((k, bk))
+                else:
+                    still_a.append(k)
+            a_left = still_a
+            b_left = [k for k in b_left if k not in used_b]
+
+        def child_canons(
+            canon_map: dict[str, int], child_map: dict[str, list[str]], k: str
+        ) -> object:
+            kids = child_map.get(k, [])
+            return tuple(sorted(canon_map[c] for c in kids)) if kids else None
+
+        greedy(  # identical non-empty child structure == a relabel of this node
+            lambda k: child_canons(canA, ca, k),
+            lambda k: child_canons(canB, cb, k),
+        )
+        greedy(lambda k: label(sa[k]), lambda k: label(sb[k]))  # same label, changed kids
+        return pairs, a_left, b_left
+
+    def localize(
+        a_ids: list[str], b_ids: list[str], here, root_level: bool
+    ) -> list[tuple[str, str]]:
+        """Report unpairable leftovers as add/remove; return the genuine pairs to descend."""
+        pairs, a_left, b_left = pair_leftovers(a_ids, b_ids)
+        prefix = path_text(here) if a_left or b_left else ""
+        tail = "root subtree" if root_level else "subtree"
+        for k in a_left:
+            scope = "only in A" if root_level else f"only in A under {prefix}"
+            changes.append(f"{scope}: {tail} {render(k, sa, ca)}")
+        for k in b_left:
+            scope = "only in B" if root_level else f"only in B under {prefix}"
+            changes.append(f"{scope}: {tail} {render(k, sb, cb)}")
+        return pairs
+
+    # Iterative worklist: a recursive descent would overflow on a deep-linear divergence.
+    worklist = [
+        (an, bn, None) for an, bn in localize(*align(ra, rb), here=None, root_level=True)
+    ]
+    while worklist:
+        an, bn, path = worklist.pop()
+        la, lb = label(sa[an]), label(sb[bn])
+        if la != lb:
+            changes.append(f"diverges at {path_text(path) or '(root)'}: A={show(sa[an])!r} B={show(sb[bn])!r}")
+            continue
+        here = (path, show(sa[an]))
+        a_only, b_only = align(ca.get(an, []), cb.get(bn, []))
+        worklist.extend(
+            (ca_id, cb_id, here) for ca_id, cb_id in localize(a_only, b_only, here, False)
+        )
+
+    return TreeDiff(identical=False, changes=changes or ["trees differ"])