agentprof 0.1.0__py3-none-any.whl

agentprof/analysis/agent_summary.py

@@ -0,0 +1,161 @@
+"""Aggregate a session by owning agent without adding descendant cost to own cost."""
+
+from dataclasses import dataclass
+
+from agentprof.analysis.rollup import sum_tokens
+from agentprof.model import CostMetric, Metric, Node, NodeKind, Provenance, Tokens, sum_costs, worst_provenance
+
+
+@dataclass(frozen=True)
+class AgentGroup:
+    agent_id: int
+    harness_agent_id: str | None
+    parent_agent_id: int | None
+    topic: str
+    models: list[str]
+    llm_calls: Metric
+    context_peak: Metric
+    tokens: Tokens
+    own_cost: CostMetric
+    subtree_cost: CostMetric
+    start: Metric
+    end: Metric
+    cost_parts: dict[str, CostMetric]
+    cache_ttl: str
+    cold_rewrites: Metric
+    cold_rewrite_cost: CostMetric
+    longest_gap: Metric
+    findings_count: int
+    resume_count: int
+
+
+def agent_ids(root: Node) -> dict[str, int]:
+    """Assign chronological display IDs to distinct subagent identities."""
+    agents: list[Node] = []
+
+    def visit(node: Node) -> None:
+        if node.kind is NodeKind.AGENT:
+            agents.append(node)
+        for child in node.children:
+            visit(child)
+
+    visit(root)
+    if all(node.start.value is not None for node in agents):
+        agents.sort(key=lambda node: node.start.number())
+    identities = dict.fromkeys(node.agent_uuid or node.node_id for node in agents)
+    return {identity: index for index, identity in enumerate(identities, start=2)}
+
+
+def _sum_metrics(metrics: list[Metric]) -> Metric:
+    available = [metric for metric in metrics if metric.value is not None]
+    if not available:
+        return Metric.not_available()
+    provenance = worst_provenance(*(metric.provenance for metric in available))
+    if len(available) != len(metrics):
+        provenance = worst_provenance(provenance, Provenance.ESTIMATED)
+    return Metric(value=sum(metric.number() for metric in available), provenance=provenance)
+
+
+def _extreme(metrics: list[Metric], greatest: bool) -> Metric:
+    available = [metric for metric in metrics if metric.value is not None]
+    if not available:
+        return Metric.not_available()
+    chosen = (max if greatest else min)(available, key=Metric.number)
+    provenance = chosen.provenance
+    if len(available) != len(metrics):
+        provenance = worst_provenance(provenance, Provenance.ESTIMATED)
+    return Metric(value=chosen.value, provenance=provenance)
+
+
+def agent_groups(root: Node) -> list[AgentGroup]:
+    """Return one row for the main agent and each distinct subagent identity."""
+    ids = agent_ids(root)
+    owned: dict[int, list[Node]] = {1: []}
+    tops: dict[int, list[Node]] = {1: [root]}
+    parents: dict[int, set[int]] = {1: set()}
+    finding_counts: dict[int, int] = {1: 0}
+
+    def visit(node: Node, owner: int) -> None:
+        if node.kind is NodeKind.AGENT:
+            agent_id = ids[node.agent_uuid or node.node_id]
+            if agent_id != owner:
+                parents.setdefault(agent_id, set()).add(owner)
+                tops.setdefault(agent_id, []).append(node)
+            owner = agent_id
+        if node.kind in (NodeKind.TURN, NodeKind.AGENT):
+            owned.setdefault(owner, []).append(node)
+        finding_counts[owner] = finding_counts.get(owner, 0) + len(node.findings)
+        for child in node.children:
+            visit(child, owner)
+
+    visit(root, 1)
+    groups: list[AgentGroup] = []
+    for agent_id, nodes in sorted(owned.items()):
+        representative = root if agent_id == 1 else next(node for node in nodes if node.kind is NodeKind.AGENT)
+        observed = {
+            call.model for node in nodes for call in node.llm_calls if call.model and not call.model.startswith("<")
+        }
+        models = sorted(observed or {node.model for node in nodes if node.model is not None})
+        counts = [
+            node.llm_call_count
+            if node.llm_call_count.value is not None or not node.llm_calls
+            else Metric.exact(len(node.llm_calls))
+            for node in nodes
+        ]
+        parent_ids = parents.get(agent_id, set())
+        calls = [call for node in nodes for call in node.llm_calls]
+        cost_kinds = ("input", "output", "cache_read", "cache_write_5m", "cache_write_1h")
+        cost_parts = {
+            kind: sum_costs([call.cost_parts.get(kind, CostMetric.not_available()) for call in calls])
+            for kind in cost_kinds
+        }
+        writes = [
+            call for call in calls if call.tokens.cache_write.value is not None and call.tokens.cache_write.number() > 0
+        ]
+        known_ttls = [
+            call
+            for call in writes
+            if call.tokens.cache_write_5m.value is not None and call.tokens.cache_write_1h.value is not None
+        ]
+        if not writes or len(known_ttls) != len(writes):
+            cache_ttl = "unknown"
+        else:
+            five = any(call.tokens.cache_write_5m.number() > 0 for call in known_ttls)
+            one = any(call.tokens.cache_write_1h.number() > 0 for call in known_ttls)
+            cache_ttl = "mixed" if five and one else "5m" if five else "1h"
+        cold_calls = [call for call in calls if call.cold_rewrite]
+        cold_costs = [
+            sum_costs(
+                [
+                    call.cost_parts.get("cache_write_5m", CostMetric.not_available()),
+                    call.cost_parts.get("cache_write_1h", CostMetric.not_available()),
+                ]
+            )
+            for call in cold_calls
+        ]
+        groups.append(
+            AgentGroup(
+                agent_id=agent_id,
+                harness_agent_id=representative.agent_uuid if agent_id != 1 else None,
+                parent_agent_id=next(iter(parent_ids)) if len(parent_ids) == 1 else None,
+                topic=representative.topic,
+                models=models,
+                llm_calls=_sum_metrics(counts),
+                context_peak=(
+                    root.context_peak if agent_id == 1 else _extreme([node.context_peak for node in nodes], True)
+                ),
+                tokens=sum_tokens([node.tokens for node in nodes]),
+                own_cost=sum_costs([node.cost_own for node in nodes]),
+                subtree_cost=sum_costs([node.cost_total for node in tops[agent_id]]),
+                start=_extreme([node.start for node in nodes], False),
+                end=_extreme([node.end for node in nodes], True),
+                cost_parts=cost_parts,
+                cache_ttl=cache_ttl,
+                cold_rewrites=Metric.exact(len(cold_calls)),
+                cold_rewrite_cost=sum_costs(cold_costs),
+                longest_gap=_extreme([call.gap for call in calls], True),
+                findings_count=finding_counts.get(agent_id, 0),
+                resume_count=sum(len(node.resume_times) for node in nodes),
+            )
+        )
+    return groups

agentprof/analysis/call_context.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Same-agent call intervals and short references to intervening activity."""
+
+from bisect import bisect_left, bisect_right
+from collections import defaultdict
+from itertools import pairwise
+
+from agentprof.model import CallEvent, LlmCall, Metric, Node, NodeKind, Provenance, worst_provenance
+
+_LARGE_CACHE_WRITE_TOKENS = 50_000
+_LOW_CACHE_READ_RATIO = 0.1
+
+
+def is_cold_rewrite(call: LlmCall) -> bool:
+    """A measured large rewrite with little reuse, excluding an agent's first call."""
+    write = call.tokens.cache_write.value
+    read = call.tokens.cache_read.value
+    return (
+        call.gap.value is not None
+        and write is not None
+        and read is not None
+        and write >= _LARGE_CACHE_WRITE_TOKENS
+        and read <= write * _LOW_CACHE_READ_RATIO
+    )
+
+
+def _event(node: Node) -> CallEvent | None:
+    if node.kind is NodeKind.AGENT:
+        if node.end.value is None:
+            return None
+        return CallEvent("child_completion", node.node_id, node.end, node.end, node.duration)
+    if node.kind is NodeKind.TOOL:
+        if node.start.value is None or node.end.value is None:
+            return None
+        return CallEvent("tool", node.node_id, node.start, node.end, node.duration)
+    return None
+
+
+def annotate_call_context(root: Node) -> None:
+    """Annotate calls using only timestamps that can place events in their interval.
+
+    The main agent owns all turns. Repeated subagent nodes with the same harness ID
+    are treated as one conversation, including a resumed agent.
+    """
+    calls: dict[str, list[LlmCall]] = defaultdict(list)
+    events: dict[str, list[CallEvent]] = defaultdict(list)
+    compactions: dict[str, list[Metric]] = defaultdict(list)
+
+    def visit(node: Node, owner: str) -> None:
+        if node.kind is NodeKind.AGENT:
+            owner = node.agent_uuid or node.node_id
+        if node.kind in (NodeKind.TURN, NodeKind.AGENT):
+            calls[owner].extend(call for call in node.llm_calls if call.in_context and call.start.value is not None)
+            compactions[owner].extend(node.compactions)
+            if node.kind is NodeKind.TURN and node.start.value is not None:
+                events[owner].append(CallEvent("user_message", node.node_id, node.start, node.start))
+        for child in node.children:
+            event = _event(child)
+            if event is not None:
+                events[owner].append(event)
+            visit(child, owner)
+
+    visit(root, "main")
+    for owner, owned_calls in calls.items():
+        owned_calls.sort(key=lambda call: call.start.number())
+        timed_events = sorted(
+            (event for event in events[owner] if event.start.value is not None and event.end.value is not None),
+            key=lambda event: event.start.number(),
+        )
+        event_starts = [event.start.number() for event in timed_events]
+        compact_times = sorted(point.number() for point in compactions[owner] if point.value is not None)
+        if owned_calls:
+            owned_calls[0].cold_reason = "first_call"
+        for previous, current in pairwise(owned_calls):
+            baseline = previous.start
+            basis = "previous_start"
+            if previous.duration.value is not None:
+                baseline = Metric(
+                    previous.start.number() + previous.duration.number(),
+                    previous.start.provenance
+                    if previous.duration.provenance is Provenance.EXACT
+                    else Provenance.ESTIMATED,
+                )
+                basis = "previous_end"
+            if current.start.number() < baseline.number():
+                continue
+            provenance = worst_provenance(current.start.provenance, baseline.provenance)
+            if basis == "previous_start":
+                provenance = worst_provenance(provenance, Provenance.ESTIMATED)
+            current.gap = Metric(current.start.number() - baseline.number(), provenance)
+            current.gap_basis = basis
+            first = bisect_left(event_starts, baseline.number())
+            last = bisect_right(event_starts, current.start.number())
+            current.preceding_events = [
+                event for event in timed_events[first:last] if event.end.number() <= current.start.number()
+            ]
+            compact_index = bisect_left(compact_times, baseline.number())
+            if compact_index < len(compact_times) and compact_times[compact_index] <= current.start.number():
+                current.cold_reason = "compaction"
+            current.cold_rewrite = is_cold_rewrite(current)

agentprof/analysis/evidence_findings.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Findings that cite measured call intervals and cache behavior.
+
+These are diagnostic hints. A large rewrite does not, by itself, establish
+cache expiry or prove that its cost could have been avoided.
+"""
+
+from collections import defaultdict
+from itertools import pairwise
+
+from agentprof.model import Finding, LlmCall, Node, NodeKind, context_size, iter_nodes, worst_provenance
+
+_BLOCKING_WAIT_MS = 5 * 60 * 1000
+_PARENT_IDLE_MS = 5 * 60 * 1000
+_CONTEXT_GROWTH_TOKENS = 100_000
+_CONTEXT_GROWTH_FACTOR = 2
+
+
+def find_evidence_findings(root: Node) -> list[Finding]:
+    """Return evidence-backed findings over the neutral call tree."""
+    by_id = {node.node_id: node for node in iter_nodes(root)}
+    findings: list[Finding] = []
+    owned_calls: dict[str, list[tuple[LlmCall, Node]]] = defaultdict(list)
+
+    def gather(node: Node, owner: str) -> None:
+        if node.kind is NodeKind.AGENT:
+            owner = node.agent_uuid or node.node_id
+        if node.kind in (NodeKind.TURN, NodeKind.AGENT):
+            owned_calls[owner].extend((call, node) for call in node.llm_calls if call.in_context)
+        for child in node.children:
+            gather(child, owner)
+
+    gather(root, "main")
+    for node in by_id.values():
+        if node.kind is NodeKind.TOOL and node.tool is not None and node.tool.is_resume:
+            findings.append(
+                Finding(
+                    heuristic_id="E5",
+                    node_id=node.node_id,
+                    severity="low",
+                    message="Agent resume reported by a SendMessage result",
+                    evidence={
+                        "tool_node_id": node.node_id,
+                        "target_agent_id": node.tool.target_agent_id,
+                        "linked_agent_node_id": node.tool.linked_agent_node_id,
+                        "provenance": "exact",
+                    },
+                )
+            )
+        if node.kind not in (NodeKind.TURN, NodeKind.AGENT):
+            continue
+        for call in node.llm_calls:
+            for event in call.preceding_events:
+                if (
+                    event.kind == "child_completion"
+                    and event.end.value is not None
+                    and call.start.value is not None
+                    and call.start.number() - event.end.number() >= _PARENT_IDLE_MS
+                ):
+                    findings.append(
+                        Finding(
+                            heuristic_id="E4",
+                            node_id=node.node_id,
+                            severity="low",
+                            message="Parent agent was idle after a child completed",
+                            evidence={
+                                "call_id": call.call_id,
+                                "child_node_id": event.event_id,
+                                "idle_ms": call.start.number() - event.end.number(),
+                                "provenance": worst_provenance(call.start.provenance, event.end.provenance).value,
+                            },
+                        )
+                    )
+            if not call.cold_rewrite:
+                continue
+            evidence: dict[str, object] = {
+                "call_id": call.call_id,
+                "call_start_ms": call.start.value,
+                "cache_write_tokens": call.tokens.cache_write.value,
+                "cache_read_tokens": call.tokens.cache_read.value,
+                "gap_ms": call.gap.value,
+                "cold_reason": call.cold_reason,
+                "provenance": worst_provenance(
+                    call.tokens.cache_write.provenance, call.tokens.cache_read.provenance
+                ).value,
+            }
+            findings.append(
+                Finding(
+                    heuristic_id="E1",
+                    node_id=node.node_id,
+                    severity="medium",
+                    message="Large cache rewrite with little cache reuse",
+                    evidence=evidence,
+                )
+            )
+            for event in call.preceding_events:
+                tool_node = by_id.get(event.event_id)
+                if (
+                    event.kind == "tool"
+                    and tool_node is not None
+                    and tool_node.tool is not None
+                    and tool_node.tool.native_id.casefold() == "askuserquestion"
+                    and event.duration.value is not None
+                    and event.duration.number() >= _BLOCKING_WAIT_MS
+                ):
+                    findings.append(
+                        Finding(
+                            heuristic_id="E2",
+                            node_id=node.node_id,
+                            severity="medium",
+                            message="Blocking user wait preceded a large cache rewrite",
+                            evidence={
+                                **evidence,
+                                "tool_node_id": event.event_id,
+                                "wait_ms": event.duration.value,
+                                "wait_provenance": event.duration.provenance.value,
+                            },
+                        )
+                    )
+                    break
+    for calls in owned_calls.values():
+        ordered = sorted(
+            ((call, node) for call, node in calls if call.start.value is not None),
+            key=lambda item: item[0].start.number(),
+        )
+        for (earlier, _), (later, node) in pairwise(ordered):
+            before = context_size(earlier.tokens)
+            after = context_size(later.tokens)
+            if (
+                before.value is not None
+                and after.value is not None
+                and after.number() >= _CONTEXT_GROWTH_TOKENS
+                and after.number() >= before.number() * _CONTEXT_GROWTH_FACTOR
+            ):
+                findings.append(
+                    Finding(
+                        heuristic_id="E3",
+                        node_id=node.node_id,
+                        severity="low",
+                        message="Model context grew sharply between calls",
+                        evidence={
+                            "earlier_call_id": earlier.call_id,
+                            "later_call_id": later.call_id,
+                            "earlier_context_tokens": before.value,
+                            "later_context_tokens": after.value,
+                            "provenance": worst_provenance(before.provenance, after.provenance).value,
+                        },
+                    )
+                )
+    return findings

agentprof/analysis/execution.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Resolve source-record relationships to model calls."""
+
+from collections import defaultdict
+
+from agentprof.model import EventCallLink, LlmCall, Node, NodeKind
+
+_VALID_EVIDENCE = {
+    "requested_by": "recorded",
+    "consumed_by": "recorded",
+    "next_observed_call": "observed_order",
+}
+
+
+def resolve_execution_links(root: Node) -> None:
+    """Resolve event links to one request in the same logical agent stream."""
+    calls: dict[str, dict[str, list[tuple[str, LlmCall]]]] = defaultdict(lambda: defaultdict(list))
+    pending: list[tuple[str, EventCallLink]] = []
+
+    def visit(node: Node, owner: str) -> None:
+        if node.kind is NodeKind.AGENT:
+            owner = node.agent_uuid or node.node_id
+        if node.kind in (NodeKind.SESSION, NodeKind.TURN, NodeKind.AGENT):
+            for call in node.llm_calls:
+                if call.source_request_id:
+                    calls[owner][call.source_request_id].append((node.node_id, call))
+        pending.extend((owner, link) for event in node.execution_events for link in event.links)
+        for child in node.children:
+            visit(child, owner)
+
+    visit(root, "main")
+    for owner, link in pending:
+        link.owner_id = None
+        if _VALID_EVIDENCE.get(link.relation) != link.evidence:
+            continue
+        matches = calls[owner].get(link.source_request_id, [])
+        if len(matches) == 1:
+            link.owner_id = matches[0][0]