agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/drift_windows.py

@@ -0,0 +1,340 @@
+"""Bounded cohort windows built from native traces or existing aggregate artifacts."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from collections import Counter
+from dataclasses import asdict
+
+from agentloop.aggregate_stats import AggregateConfig, number, total
+from agentloop.aggregates import TraceAggregate
+from agentloop.drift_types import QualityMetric, WindowSpec, label, timestamp
+from agentloop.onboarding import validate_capture
+from agentloop.operations import operation_kind
+from agentloop.retention import read_retention
+from agentloop.rules import BUILTIN_RULES
+from agentloop.workflow_types import stage_summary, workflow_summary
+
+DRIFT_VERSION = "1.0"
+
+
+def digest(value):
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()
+    ).hexdigest()
+
+
+def seal(value):
+    result = copy.deepcopy(value)
+    result["sha256"] = digest(result)
+    return result
+
+
+def verify(value, kind):
+    if (
+        not isinstance(value, dict)
+        or value.get("schema_version") != DRIFT_VERSION
+        or value.get("kind") != kind
+    ):
+        raise ValueError(f"unsupported {kind} artifact")
+    content = dict(value)
+    if content.pop("sha256", None) != digest(content):
+        raise ValueError(f"{kind} content hash mismatch")
+
+
+def _mix():
+    return {"counts": Counter(), "overflow": 0, "missing": 0, "total": 0}
+
+
+def _mix_add(mix, value):
+    mix["total"] += 1
+    if value is None:
+        mix["missing"] += 1
+        return
+    key = digest(value)
+    if key in mix["counts"] or len(mix["counts"]) < 128:
+        mix["counts"][key] += 1
+    else:
+        mix["overflow"] += 1
+
+
+class WindowBuilder:
+    def __init__(
+        self,
+        spec: WindowSpec,
+        *,
+        quality_metrics: tuple[QualityMetric, ...] = (),
+        config: AggregateConfig | None = None,
+        include_findings=False,
+    ):
+        if not isinstance(spec, WindowSpec):
+            raise TypeError("spec must be WindowSpec")
+        if (
+            not isinstance(quality_metrics, tuple)
+            or len(quality_metrics) > 16
+            or any(not isinstance(metric, QualityMetric) for metric in quality_metrics)
+        ):
+            raise ValueError("quality_metrics must be a tuple of at most 16 declarations")
+        if len({metric.name for metric in quality_metrics}) != len(quality_metrics):
+            raise ValueError("quality metric names must be unique")
+        if type(include_findings) is not bool:
+            raise ValueError("include_findings must be boolean")
+        self.spec = spec
+        self.quality_metrics = tuple(sorted(quality_metrics, key=lambda metric: metric.name))
+        self.config = AggregateConfig() if config is None else config
+        if not isinstance(self.config, AggregateConfig):
+            raise TypeError("config must be AggregateConfig")
+        self.include_findings = include_findings
+        self._cohorts = {}
+        self._chain = digest([])
+        self._sources = 0
+
+    def _cohort(self, cohort):
+        label(cohort, "cohort")
+        if cohort not in self._cohorts and len(self._cohorts) >= 32:
+            raise ValueError("a drift window supports at most 32 explicit cohorts")
+        if cohort in self._cohorts:
+            return copy.deepcopy(self._cohorts[cohort])
+        return {
+            "aggregate": TraceAggregate(self.config),
+            "flags": {
+                key: {"known": 0, "true": 0}
+                for key in ("timeout", "abstention", "finding", "instrumentation")
+            },
+            "quality": {metric.name: {"count": 0, "sum": 0.0} for metric in self.quality_metrics},
+            "mixes": {key: _mix() for key in ("model", "stage", "outcome", "decision_outcome")},
+            "individual_evidence_missing_runs": 0,
+            "producer_markers": {"synthetic": 0, "declared_real": 0, "unspecified": 0},
+            "time_membership": {
+                "native_ended_at_verified_runs": 0,
+                "host_assigned_aggregate_runs": 0,
+            },
+        }
+
+    def add(self, trace, *, cohort="all", timeout=None, abstention=None, quality=None):
+        ended = timestamp(trace.ended_at)
+        if not timestamp(self.spec.started_at) <= ended < timestamp(self.spec.ended_at):
+            raise ValueError("trace completion is outside the declared window")
+        for value in (timeout, abstention):
+            if value is not None and type(value) is not bool:
+                raise ValueError("timeout/abstention must be boolean or None")
+        quality = {} if quality is None else quality
+        if not isinstance(quality, dict) or not set(quality) <= {
+            metric.name for metric in self.quality_metrics
+        }:
+            raise ValueError("quality values must match declared metrics")
+        for value in quality.values():
+            if value is not None and (
+                type(value) not in {int, float} or not 0 <= number(value) <= 1
+            ):
+                raise ValueError("quality values must be in [0,1] or None")
+        owned = self._cohort(cohort)
+        owned["aggregate"].add(trace)
+        owned["time_membership"]["native_ended_at_verified_runs"] += 1
+        synthetic = trace.metadata.get("synthetic")
+        owned["producer_markers"][
+            "synthetic"
+            if synthetic is True
+            else "declared_real"
+            if synthetic is False
+            else "unspecified"
+        ] += 1
+        retained = read_retention(trace)
+        complete = retained is None or retained["complete_evidence"]
+        for key, value in (("timeout", timeout), ("abstention", abstention)):
+            if value is not None:
+                owned["flags"][key]["known"] += 1
+                owned["flags"][key]["true"] += value
+        for key, value in quality.items():
+            if value is not None:
+                owned["quality"][key]["count"] += 1
+                owned["quality"][key]["sum"] = total(owned["quality"][key]["sum"], value)
+        owned["flags"]["instrumentation"]["known"] += 1
+        if complete:
+            validation = validate_capture(trace)
+            missing_codes = {
+                "no_execution_spans",
+                "unsupported_operation",
+                "usage_not_exact",
+                "model_identity_missing",
+                "trace_boundary_missing",
+                "span_timing_unavailable",
+                "span_outside_boundary",
+                "retained_evidence_incomplete",
+            }
+            owned["flags"]["instrumentation"]["true"] += not any(
+                check["severity"] == "error" or check["code"] in missing_codes
+                for check in validation["checks"]
+            )
+            for event in trace.events:
+                if operation_kind(event) == "model":
+                    _mix_add(owned["mixes"]["model"], event.model)
+                stage = stage_summary(event)
+                _mix_add(
+                    owned["mixes"]["stage"],
+                    [stage.get("stage_id"), stage.get("version")]
+                    if stage and stage.get("stage_id")
+                    else None,
+                )
+                if operation_kind(event) in {"classifier", "rule"}:
+                    _mix_add(
+                        owned["mixes"]["decision_outcome"], stage.get("outcome") if stage else None
+                    )
+            execution = workflow_summary(trace.metadata)
+            _mix_add(owned["mixes"]["outcome"], execution.get("outcome") if execution else None)
+            if self.include_findings and len(trace.events) <= 2000:
+                report = trace.report()
+                if report.get("analysis_complete"):
+                    owned["flags"]["finding"]["known"] += 1
+                    owned["flags"]["finding"]["true"] += bool(report["finding_candidates"])
+        else:
+            owned["individual_evidence_missing_runs"] += 1
+        source_hash = digest(trace.to_dict())
+        chain = digest([self._chain, source_hash, cohort, timeout, abstention, quality])
+        # All validation/analysis/hash work precedes mutation of builder state.
+        self._cohorts[cohort] = owned
+        self._chain, self._sources = chain, self._sources + 1
+
+    def add_aggregate(self, aggregate: TraceAggregate, *, cohort="all", time_assignment_ref):
+        """Existing aggregates contribute original metrics, with missing per-run extras explicit."""
+        if not isinstance(aggregate, TraceAggregate):
+            raise TypeError("aggregate must be TraceAggregate")
+        label(time_assignment_ref, "time_assignment_ref")
+        owned = self._cohort(cohort)
+        owned["aggregate"].merge(aggregate)
+        report = aggregate.to_dict()
+        owned["individual_evidence_missing_runs"] += report["counts"]["runs"]
+        owned["time_membership"]["host_assigned_aggregate_runs"] += report["counts"]["runs"]
+        owned["producer_markers"]["unspecified"] += report["counts"]["runs"]
+        chain = digest([self._chain, report["sha256"], cohort, time_assignment_ref])
+        self._cohorts[cohort] = owned
+        self._chain, self._sources = chain, self._sources + 1
+
+    def to_dict(self):
+        cohorts = copy.deepcopy(self._cohorts)
+        for values in cohorts.values():
+            values["aggregate"] = values["aggregate"].to_dict()
+            for mix in values["mixes"].values():
+                mix["counts"] = dict(mix["counts"])
+        return seal(
+            {
+                "schema_version": DRIFT_VERSION,
+                "kind": "agentloop.drift_window",
+                "spec": asdict(self.spec),
+                "quality_metrics": [asdict(metric) for metric in self.quality_metrics],
+                "settings": {
+                    "include_findings": self.include_findings,
+                    "rule_versions": [[rule.rule_id, rule.version] for rule in BUILTIN_RULES]
+                    if self.include_findings
+                    else None,
+                },
+                "cohorts": cohorts,
+                "source_count": self._sources,
+                "source_chain_sha256": self._chain,
+                "scope": "Supplied disjoint records only; cohort labels and quality/timeout/abstention annotations are host observations.",
+            }
+        )
+
+
+def validate_window(value):
+    verify(value, "agentloop.drift_window")
+    WindowSpec(**value["spec"])
+    metrics = tuple(QualityMetric(**item) for item in value["quality_metrics"])
+    if (
+        type(value["source_count"]) is not int
+        or value["source_count"] < 0
+        or not isinstance(value["source_chain_sha256"], str)
+        or len(value["source_chain_sha256"]) != 64
+        or any(char not in "0123456789abcdef" for char in value["source_chain_sha256"])
+    ):
+        raise ValueError("invalid source chain")
+    settings = value["settings"]
+    if (
+        not isinstance(settings, dict)
+        or set(settings) != {"include_findings", "rule_versions"}
+        or type(settings["include_findings"]) is not bool
+    ):
+        raise ValueError("invalid window analysis settings")
+    if settings["include_findings"]:
+        if not isinstance(settings["rule_versions"], list) or len(settings["rule_versions"]) > 128:
+            raise ValueError("invalid finding rule versions")
+        for entry in settings["rule_versions"]:
+            if not isinstance(entry, list) or len(entry) != 2:
+                raise ValueError("invalid finding rule version entry")
+            for field in entry:
+                label(field, "finding rule version")
+    elif settings["rule_versions"] is not None:
+        raise ValueError("unexpected finding rule versions")
+    if (
+        len(metrics) > 16
+        or len({metric.name for metric in metrics}) != len(metrics)
+        or not isinstance(value["cohorts"], dict)
+        or len(value["cohorts"]) > 32
+    ):
+        raise ValueError("invalid drift window dimensions")
+    for cohort, data in value["cohorts"].items():
+        label(cohort, "cohort")
+        report = TraceAggregate.from_dict(data["aggregate"]).to_dict()
+        runs = report["counts"]["runs"]
+        markers = data["producer_markers"]
+        if (
+            set(markers) != {"synthetic", "declared_real", "unspecified"}
+            or any(type(count) is not int or count < 0 for count in markers.values())
+            or sum(markers.values()) != runs
+        ):
+            raise ValueError("invalid producer marker counts")
+        membership = data["time_membership"]
+        if (
+            set(membership) != {"native_ended_at_verified_runs", "host_assigned_aggregate_runs"}
+            or any(type(count) is not int or count < 0 for count in membership.values())
+            or sum(membership.values()) != runs
+        ):
+            raise ValueError("invalid time membership counts")
+        if (
+            set(data["quality"]) != {metric.name for metric in metrics}
+            or set(data["flags"]) != {"timeout", "abstention", "finding", "instrumentation"}
+            or set(data["mixes"]) != {"model", "stage", "outcome", "decision_outcome"}
+        ):
+            raise ValueError("invalid window metric fields")
+        for flag in data["flags"].values():
+            if (
+                any(type(flag[key]) is not int for key in ("known", "true"))
+                or not 0 <= flag["true"] <= flag["known"] <= runs
+            ):
+                raise ValueError("invalid window flag denominator")
+        for quality in data["quality"].values():
+            if (
+                type(quality["count"]) is not int
+                or not 0 <= quality["count"] <= runs
+                or not 0 <= number(quality["sum"]) <= quality["count"]
+            ):
+                raise ValueError("invalid window quality denominator")
+        for mix in data["mixes"].values():
+            counts = mix["counts"]
+            if (
+                not isinstance(counts, dict)
+                or len(counts) > 128
+                or any(
+                    not isinstance(key, str)
+                    or len(key) != 64
+                    or any(char not in "0123456789abcdef" for char in key)
+                    for key in counts
+                )
+            ):
+                raise ValueError("invalid window mix keys")
+            if (
+                any(
+                    type(item) is not int or item < 0
+                    for item in [*counts.values(), mix["missing"], mix["overflow"], mix["total"]]
+                )
+                or sum(counts.values()) + mix["missing"] + mix["overflow"] != mix["total"]
+            ):
+                raise ValueError("invalid window mix denominator")
+        if (
+            type(data["individual_evidence_missing_runs"]) is not int
+            or not 0 <= data["individual_evidence_missing_runs"] <= runs
+        ):
+            raise ValueError("invalid individual evidence count")
+    return copy.deepcopy(value)

agentloop/entrypoint.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.table import Table
+
+from agentloop.cli import _build_quality_report_from_file, _load_trace, _write_json, app, console
+from agentloop.events import AgentEvent
+from agentloop.findings import build_diagnosis
+from agentloop.html_report import analysis_to_html
+from agentloop.optimizer import build_optimization_plan
+from agentloop.ranking import RankingSort
+from agentloop.replay import ReplayGates, build_replay_report
+from agentloop.timing import format_duration_ms
+from agentloop.tracer import AgentTrace
+
+
+def _quickstart_trace() -> AgentTrace:
+    """Build a deterministic synthetic trace with several obvious bottlenecks."""
+    run_id = "run_agentloop_quickstart"
+    trace = AgentTrace(
+        name="agentloop_quickstart",
+        run_id=run_id,
+        metadata={"synthetic": True, "source": "agentloop_quickstart"},
+        started_at="2026-01-01T00:00:00+00:00",
+        ended_at="2026-01-01T00:00:01+00:00",
+        elapsed_ms=1000.0,
+    )
+    events = [
+        ("tool_call", "retrieve", 0.0, 180.0, None, 0, 0),
+        ("tool_call", "retrieve", 180.0, 360.0, None, 0, 0),
+        ("tool_call", "retrieve", 360.0, 540.0, None, 0, 0),
+        ("model_call", "summarize", 540.0, 650.0, "gpt-4.1", 700, 80),
+        ("model_call", "summarize", 650.0, 760.0, "gpt-4.1", 700, 80),
+        ("model_call", "summarize", 760.0, 870.0, "gpt-4.1", 700, 80),
+        ("retry", "repair_json", 870.0, 930.0, None, 0, 0),
+    ]
+    for index, (
+        event_type,
+        name,
+        start_ms,
+        end_ms,
+        model,
+        input_tokens,
+        output_tokens,
+    ) in enumerate(events, start=1):
+        start_seconds = start_ms / 1000
+        end_seconds = end_ms / 1000
+        trace.add_event(
+            AgentEvent(
+                event_id=f"evt_quickstart_{index:02d}",
+                run_id=run_id,
+                event_type=event_type,
+                name=name,
+                started_at=f"2026-01-01T00:00:{start_seconds:06.3f}+00:00",
+                ended_at=f"2026-01-01T00:00:{end_seconds:06.3f}+00:00",
+                duration_ms=end_ms - start_ms,
+                model=model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                input_text=("stable research instruction " * 30 if model else None),
+            )
+        )
+    return trace
+
+
+def _print_analysis(trace: AgentTrace, diagnosis: dict, plan: dict) -> None:
+    report = trace.report()
+    summary = diagnosis["summary"]
+    table = Table(title=f"AgentLoop Analysis: {trace.name}")
+    table.add_column("Metric")
+    table.add_column("Value")
+    table.add_row("Runtime", format_duration_ms(report["total_runtime_ms"], precision=3))
+    if report.get("external_evidence"):
+        source = report["external_evidence"]["source"]
+        table.add_row("External source", str(source.get("system", "unknown")))
+        table.add_row("Execution status", report["external_evidence"]["execution_status"])
+        table.add_row("Timing coverage", report["timing_status"])
+    table.add_row("Findings", str(summary["finding_count"]))
+    table.add_row("High severity", str(summary["high_severity_count"]))
+    table.add_row("Patchable", str(summary["patchable_count"]))
+    table.add_row("Retries", str(report["retry_count"]))
+    table.add_row("Input tokens", str(report["input_tokens"]))
+    console.print(table)
+
+    if report.get("rule_errors"):
+        console.print(
+            "Analysis incomplete; failed rules: "
+            + ", ".join(error["rule_id"] for error in report["rule_errors"]),
+            markup=False,
+        )
+
+    findings = diagnosis.get("findings", [])
+    if not findings:
+        console.print("No optimization findings detected.")
+        return
+    console.print("\nTop findings:")
+    for finding in findings[:5]:
+        console.print(
+            f"- [{finding['ranking']['status'].replace('_', ' ')}] {finding['title']} ({finding['confidence']} confidence)",
+            markup=False,
+        )
+    aggregation = plan.get("savings_aggregation", {})
+    if aggregation.get("selection_optimal") is False:
+        console.print("Savings selection includes an approximate large-component fallback.")
+
+
+def _analysis_payload(trace: AgentTrace, *, sort_by="priority") -> dict:
+    report = trace.report()
+    diagnosis = build_diagnosis(trace, sort_by=sort_by)
+    plan = build_optimization_plan(trace, report=report)
+    return {
+        "trace": trace.to_dict(),
+        "report": report,
+        "diagnosis": diagnosis,
+        "optimization": plan,
+    }
+
+
+@app.command("quickstart")
+def quickstart_command(
+    out: Path = typer.Option(
+        Path("runs/agentloop_quickstart.json"),
+        help="Where to write the deterministic synthetic trace.",
+    ),
+    json_out: Path | None = typer.Option(
+        None, help="Optional path for the combined analysis JSON."
+    ),
+) -> None:
+    """Generate one offline trace and show useful findings with no account or API key."""
+    trace = _quickstart_trace()
+    trace.export_json(out)
+    payload = _analysis_payload(trace)
+    _print_analysis(trace, payload["diagnosis"], payload["optimization"])
+    console.print(f"\nSynthetic trace: {out}")
+    console.print(f"Next: agentloop analyze {out}")
+    if json_out is not None:
+        _write_json(json_out, payload)
+        console.print(f"Analysis JSON: {json_out}")
+
+
+@app.command("analyze")
+def analyze_command(
+    path: Path,
+    json_out: Path | None = typer.Option(
+        None, help="Optional path for report, diagnosis, and optimization JSON."
+    ),
+    html_out: Path | None = typer.Option(
+        None, "--html", help="Write a single offline HTML report."
+    ),
+    baseline: Path | None = typer.Option(
+        None, help="Optional baseline trace; the positional trace is the candidate."
+    ),
+    quality_fixtures: Path | None = typer.Option(
+        None, help="Quality fixtures for the optional baseline comparison."
+    ),
+    min_quality_score: float | None = typer.Option(None, min=0, max=1),
+    include_content: bool = typer.Option(
+        False, help="Include raw event text and full event metadata in HTML."
+    ),
+    sort_by: RankingSort = typer.Option(
+        RankingSort.PRIORITY, help="Order findings by an explicit ranking dimension."
+    ),
+) -> None:
+    """Analyze one existing AgentLoop trace in a single command."""
+    trace = _load_trace(path, param_hint="path")
+    if (quality_fixtures is not None or min_quality_score is not None) and baseline is None:
+        raise typer.BadParameter("quality comparison options require --baseline")
+    if include_content and html_out is None:
+        raise typer.BadParameter("--include-content requires --html")
+    payload = _analysis_payload(trace, sort_by=sort_by.value)
+    if baseline is not None:
+        baseline_trace = _load_trace(baseline, param_hint="--baseline")
+        quality = (
+            _build_quality_report_from_file(
+                quality_fixtures,
+                param_hint="--quality-fixtures",
+                baseline_trace=baseline_trace,
+                candidate_trace=trace,
+                min_score=min_quality_score,
+            )
+            if quality_fixtures is not None
+            else None
+        )
+        payload["replay"] = build_replay_report(
+            baseline_trace,
+            trace,
+            gates=ReplayGates(min_quality_score=min_quality_score),
+            quality_report=quality,
+        )
+    _print_analysis(trace, payload["diagnosis"], payload["optimization"])
+    if json_out is not None:
+        _write_json(json_out, payload)
+        console.print(f"Wrote analysis JSON to {json_out}")
+    if html_out is not None:
+        html_out.parent.mkdir(parents=True, exist_ok=True)
+        html_out.write_text(
+            analysis_to_html(payload, include_content=include_content), encoding="utf-8"
+        )
+        console.print(f"Wrote HTML report to {html_out}")

agentloop/estimates.py

@@ -0,0 +1,133 @@
+"""Versioned, uncalibrated savings models and self-contained evidence snapshots."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from agentloop.costs import is_cost_evaluable
+from agentloop.markdown import markdown_code_span, markdown_text
+
+
+@dataclass(frozen=True)
+class Estimator:
+    formula: str
+    assumptions: tuple[str, ...]
+    parameters: tuple[tuple[str, float], ...] = ()
+    version: str = "1.0"
+
+    def parameter(self, name: str) -> float:
+        return dict(self.parameters)[name]
+
+
+ESTIMATORS = {
+    "parallelize_tools": Estimator(
+        "sum_duration_ms - max_duration_ms",
+        ("The formula applies assuming concurrent execution has negligible scheduling overhead.",),
+    ),
+    "cache_context": Estimator(
+        "current_cost_usd * min(max_cost_fraction, repeated_context_ratio)",
+        (
+            "Repeated context can be reused without changing required outputs.",
+            "The reusable share of total priced cost approximates the repeated context ratio.",
+            "The provider or application supports the proposed cache.",
+        ),
+        (("max_cost_fraction", 0.5),),
+    ),
+    "add_schema_validation": Estimator(
+        "sum_duration_ms * latency_fraction",
+        (
+            "Most observed retries are preventable with validation or repair.",
+            "Added validation overhead is smaller than avoided retry time.",
+        ),
+        (("latency_fraction", 0.8),),
+    ),
+    "batch_model_calls": Estimator(
+        "sum_duration_ms * latency_fraction",
+        (
+            "Repeated calls accept a shared batch without changing item-level outputs.",
+            "Batch size, token limits, and provider throughput permit the estimated reduction.",
+        ),
+        (("latency_fraction", 0.35),),
+    ),
+    "route_to_smaller_model": Estimator(
+        "sum_duration_ms * latency_fraction",
+        (
+            "A smaller model meets the task's quality requirements.",
+            "Its serving latency is lower under comparable load.",
+        ),
+        (("latency_fraction", 0.25),),
+    ),
+    "split_large_step": Estimator(
+        "sum_duration_ms * latency_fraction",
+        (
+            "Context can be compressed or split without losing necessary information.",
+            "Extra orchestration and model calls do not consume the estimated savings.",
+        ),
+        (("latency_fraction", 0.20),),
+    ),
+    "runaway_loop": Estimator(
+        "sum_duration_ms * latency_fraction",
+        (
+            "Some repeated steps are unnecessary for successful task completion.",
+            "A guard can stop them without prematurely terminating useful work.",
+        ),
+        (("latency_fraction", 0.30),),
+    ),
+    "tool_oscillation": Estimator(
+        "sum_duration_ms * latency_fraction",
+        (
+            "Some alternating tool calls repeat equivalent state transitions.",
+            "A state-change check can remove them without losing required transitions.",
+        ),
+        (("latency_fraction", 0.40),),
+    ),
+}
+
+
+def estimate_snapshot(candidate: Any, report: dict[str, Any], nodes: list[Any]) -> dict[str, Any]:
+    """Copy the estimator and its inputs; never reconstruct historical records on read."""
+    spec = ESTIMATORS[candidate.rule_id]
+    affected = set(candidate.affected_nodes or [])
+    durations = [node.duration_ms for node in nodes if node.node_id in affected]
+    cost_status = report.get("cost_status", "complete")
+    return {
+        "estimator_id": candidate.rule_id,
+        "estimator_version": spec.version,
+        "method": "heuristic",
+        "confidence": candidate.confidence,
+        "calibrated": False,
+        "formula": spec.formula,
+        "parameters": dict(spec.parameters),
+        "inputs": {
+            "sum_duration_ms": sum(durations),
+            "max_duration_ms": max(durations, default=0.0),
+            "span_count": len(durations),
+            "current_cost_usd": (
+                report.get("estimated_cost_usd", 0.0) if is_cost_evaluable(cost_status) else None
+            ),
+            "repeated_context_ratio": report.get("repeated_context_ratio", 0.0),
+            "cost_status": cost_status,
+            "token_status": report.get("token_status", "unspecified"),
+        },
+        "assumptions": list(dict.fromkeys([*(candidate.assumptions or []), *spec.assumptions])),
+        "unmodeled_metrics": (["latency"] if candidate.rule_id == "cache_context" else ["cost"]),
+    }
+
+
+def estimate_markdown(estimate: dict[str, Any] | None) -> list[str]:
+    if not estimate:
+        return []
+    calibration = "calibrated" if estimate.get("calibrated") is True else "uncalibrated"
+    return [
+        f"- Estimator: {markdown_code_span(estimate['estimator_id'])} "
+        f"version {markdown_text(estimate['estimator_version'])}",
+        f"- Method: {markdown_text(estimate['method'])} ({calibration}; predicted savings)",
+        f"- Savings formula: {markdown_code_span(estimate['formula'])}",
+        "- Parameters: "
+        + markdown_code_span(json.dumps(estimate.get("parameters", {}), sort_keys=True)),
+        "- Assumptions: "
+        + "; ".join(markdown_text(value) for value in estimate.get("assumptions", [])),
+        "",
+    ]