Add SDK savings ledger foundation

[bmdhodl]

Summary

• add sdk/agentguard/savings.py to normalize provider usage and compute a local exact-vs-estimated savings ledger from traces
• thread savings data into agentguard report and incident markdown/html/json output without adding any runtime dependencies
• normalize OpenAI/Anthropic/LangChain usage payloads, refresh docs/roadmap/PyPI README, and add regression coverage for cache hits, retry savings, and retry incident classification

Testing

• python -m ruff check sdk/agentguard/
• python -m pytest sdk/tests/test_architecture.py -v
• python -m bandit -r sdk/agentguard/ -s B101,B110,B112,B311 -q
• python -m pytest sdk/tests/ -v --cov=agentguard --cov-report=term-missing --cov-fail-under=80
• python -m pytest sdk/tests/test_pypi_readme_sync.py -v

Proof

• real local agent fixture produced exact_tokens_saved=800, estimated_tokens_saved=1500, exact_usd_saved=0.001, estimated_usd_saved=0.0075
• visible desktop proof captured during a live PowerShell run on this machine
• Playwright health checks captured fresh screenshots for https://agentguard47.com and https://app.agentguard47.com/sign-in

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[Copilot]

Pull request overview

This PR adds a “savings ledger” capability to the AgentGuard SDK to normalize provider usage payloads and compute exact-vs-estimated token/$ savings from local trace files, then threads that data into agentguard report and incident report outputs.

Changes:

• Added agentguard.savings with provider inference, usage normalization, and savings summarization from JSONL traces.
• Updated CLI and reporting to include savings ledger data in text/JSON and incident markdown/HTML/JSON outputs.
• Expanded test coverage across savings logic, CLI reporting, incident classification, and LangChain integration normalization.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
sdk/agentguard/savings.py	New core module for usage normalization and savings ledger computation.
sdk/agentguard/reporting.py	Adds savings ledger into incident summaries and rendered markdown/HTML/JSON.
sdk/agentguard/cli.py	Includes savings ledger in agentguard report output (text + JSON).
sdk/agentguard/instrument.py	Normalizes emitted llm.result usage and adds provider into event payload.
sdk/agentguard/integrations/langchain.py	Normalizes LangChain token usage, infers provider, and passes provider into cost estimation.
sdk/tests/test_savings.py	New regression tests for usage normalization and savings summarization.
sdk/tests/test_reporting.py	Asserts savings ledger is present in incident summaries and adds retry primary-cause coverage.
sdk/tests/test_langchain_integration.py	Extends assertions for normalized token usage/provider/model in llm.end.
sdk/tests/test_instrument.py	Adds tests covering normalized llm.result emission for OpenAI/Anthropic shapes.
sdk/tests/test_cli_report.py	Verifies CLI report text/markdown/JSON include savings ledger information.
sdk/tests/test_architecture.py	Adds savings.py to the architectural surface-area checks.
sdk/README.md	Documents that agentguard report now includes a savings ledger.
sdk/PYPI_README.md	Updates examples and narrative to reflect exact-vs-estimated savings.
README.md	Updates root README examples and incident description for savings ledger.
docs/guides/getting-started.md	Updates getting-started guide outputs and incident description.
ops/02-ARCHITECTURE.md	Documents savings.py and updated module dependency graph.
ops/03-ROADMAP_NOW_NEXT_LATER.md	Marks “Savings Ledger foundation” as completed in roadmap.

Comments suppressed due to low confidence (1)

sdk/agentguard/cli.py:82

• _report() computes savings = summarize_savings(events) even when output_format is "markdown"/"html" and the function immediately delegates to render_incident_report() (which recomputes savings internally). To avoid redundant work on large traces, move summarize_savings() behind the markdown/html early-return, or only compute it for the JSON/text branches that actually use it.

    savings = summarize_savings(events)

    total_ms: Optional[float] = None
    if span_durations:
        total_ms = max(span_durations)

    if wants_json:
        result = {
            "total_events": total,
            "spans": kinds.get("span", 0),
            "events": kinds.get("event", 0),
            "approx_run_time_ms": total_ms,
            "reasoning_steps": names.get("reasoning.step", 0),
            "tool_results": names.get("tool.result", 0),
            "llm_results": names.get("llm.result", 0),
            "estimated_cost_usd": round(total_cost, 4),
            "loop_guard_triggered": loop_hits,
            "savings": savings,
        }
        print(json.dumps(result))
        return
    if output_format in {"markdown", "html"}:
        print(render_incident_report(events, output_format=output_format))
        return

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.