traceburn 0.1.0__tar.gz

traceburn-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+.traceburn/
+*.db
+*.db-wal
+*.db-shm
+.DS_Store
+node_modules/

traceburn-0.1.0/CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "If you use traceburn in your work, please cite it as below."
+title: "traceburn: a local-first tracer and efficiency profiler for AI agents"
+type: software
+authors:
+  - family-names: "Tran"
+    given-names: "Tommy"
+    email: "tommy.tranxhec@gmail.com"
+repository-code: "https://github.com/TommyTranX/traceburn"
+license: MIT
+version: 0.1.0
+date-released: "2026-07-05"
+keywords:
+  - AI agents
+  - LLM observability
+  - tracing
+  - profiling
+  - cost efficiency

traceburn-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Contributions are welcome, and two kinds are especially wanted: new
+instrumentation adapters and new waste rules. Both are deliberately small
+interfaces; either is an afternoon of work.
+
+## Setup
+
+```
+git clone https://github.com/TommyTranX/traceburn
+cd traceburn
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[ui]" pytest openai anthropic httpx
+pytest
+```
+
+The test suite makes no network calls. Instrumentation tests run the real
+provider SDKs over `httpx.MockTransport`, so they exercise the exact
+objects the patchers see in production without a key.
+
+## Adding an instrumentation adapter
+
+One module in `src/traceburn/instrument/`, three functions:
+`is_available()`, `patch()`, `unpatch()`. The walkthrough with the span
+attribute conventions, streaming wrappers, and the never-break rule is in
+[docs/instrumentation.md](docs/instrumentation.md). Requirements:
+
+- lazy imports, so the module is importable when the client library is not
+- capture failures are swallowed and logged, never raised into the host
+- tests via a mock transport: sync, async, streaming, tool calls, an error
+- register it in `instrument/__init__.py`
+
+## Adding a waste rule
+
+One module in `src/traceburn/analyze/waste/` with `run(ctx) -> list[Finding]`.
+The contract, helpers, and the precision bar are in
+[docs/waste-rules.md](docs/waste-rules.md). The short version: a positive
+test, a negative test, no dollar figure that does not follow from observed
+tokens and the pricing table, and an honest confidence level.
+
+## Ground rules
+
+- `pytest` passes; new behavior comes with tests.
+- The core package imports stdlib only. Anything heavier goes behind an
+  extra.
+- No telemetry, no network calls of the tool's own, ever.
+- Plain prose in docs and messages. Cost figures are always labeled
+  estimates.
+
+## Updating the pricing table
+
+`src/traceburn/pricing.json` carries provider list prices with an `as_of`
+date. Corrections and new models are welcome; cite the public pricing page
+in the PR and update `as_of`.

traceburn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tommy Tran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

traceburn-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: traceburn
+Version: 0.1.0
+Summary: Local-first tracer and efficiency profiler for AI agents: cost and latency flamegraphs, deterministic replay, run diffs, and waste detection over one SQLite file.
+Project-URL: Homepage, https://github.com/TommyTranX/traceburn
+Project-URL: Repository, https://github.com/TommyTranX/traceburn
+Project-URL: Issues, https://github.com/TommyTranX/traceburn/issues
+Author-email: Tommy Tran <tommy.tranxhec@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,cost,llm,observability,profiling,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: starlette>=0.37; extra == 'all'
+Requires-Dist: uvicorn>=0.29; extra == 'all'
+Provides-Extra: ui
+Requires-Dist: starlette>=0.37; extra == 'ui'
+Requires-Dist: uvicorn>=0.29; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# traceburn
+
+## The finding that made me build this
+
+I wrote a small support ticket triage agent: five tickets, one tool call each, a roughly 4,700
+token static policy prompt sent fresh on every call, model claude-haiku-4-5. Running it uncached
+cost $0.0539. traceburn's waste report looked at the trace, noticed that same 4,700 token prefix
+going out uncached on all 10 calls, and estimated that about 82 percent of that spend was
+avoidable. So I added exactly the one cache_control block it suggested and reran the same five
+tickets: $0.0167.
+
+That's a 69 percent measured saving. The tool's estimate landed within 18 percent of what actually
+happened, close enough to trust as a first signal, not close enough to treat as gospel. That's
+roughly how I want a cost estimator to behave.
+
+Prices change and models get repriced, so do not take my word for it: the reproduction is a few
+cents and a couple of minutes, at
+[examples/cache_before_after.py](https://github.com/TommyTranX/traceburn/blob/main/examples/cache_before_after.py).
+Measured 2026-07-05.
+
+![traceburn's waste report on the uncached run: $0.0539 total, about 82 percent flagged avoidable, with the repeated 5,618-token prefix identified as the cause](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/waste-report.png)
+
+That's the whole pitch in one run. traceburn is a local-first tracer and efficiency profiler for
+AI agents, built on top of the openai and anthropic Python SDKs: a cost and latency flamegraph, a
+waste report that quantifies avoidable spend instead of just gesturing at it, deterministic replay
+of recorded calls, and run diffs, all backed by one SQLite file on disk. No account, no server to
+stand up for basic use, no telemetry leaving your machine.
+
+## Install
+
+Core tracer, stdlib only, zero dependencies:
+
+```bash
+pip install traceburn
+```
+
+Tracer plus the local web viewer (adds starlette and uvicorn):
+
+```bash
+pip install "traceburn[ui]"
+```
+
+Requires Python 3.10 or later.
+
+## Quickstart
+
+Patch the SDKs at the top of your agent:
+
+```python
+import traceburn
+traceburn.install()
+
+# your existing openai / anthropic code, unchanged
+```
+
+Every sync call, async call, streaming response, tool call, and prompt cache hit on either SDK now
+gets recorded as a span. Traces live in one SQLite file, `./.traceburn/traces.db` by default; set
+the `TRACEBURN_DB` environment variable if you want it somewhere else. If you'd rather not touch
+the source at all, wrap the run instead:
+
+```bash
+TRACEBURN=1 python your_agent.py
+```
+
+Then look at what happened:
+
+```bash
+traceburn ui             # opens the web viewer at 127.0.0.1:8765
+traceburn ls              # list recorded traces
+traceburn show <id>       # inspect one trace
+traceburn waste <id>      # run the waste report on one trace
+traceburn diff <a> <b>    # compare two traces span by span
+```
+
+No API keys and nothing to configure: `python examples/offline_demo.py` records a simulated agent
+run with realistic token counts, including one deliberate duplicate call, so you can see a real
+trace, a real flamegraph, and a real waste finding inside a minute.
+
+## What it actually does
+
+**Trace.** `traceburn.install()` patches both SDKs so every call becomes a span with tokens,
+latency, and cost attached, no code changes required past that one line. Want manual control
+instead, or you're using a framework outside the two supported SDKs? The explicit API, `@trace`,
+`span()`, and `session()`, works by hand with anything.
+
+![traceburn's expandable trace tree, showing an agent's nested spans with per-call tokens and cost](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/trace-tree.png)
+
+**Flamegraph.** Spans render as a flamegraph you can size two ways: by wall-clock time or by
+dollars spent, with self-time kept separate from time spent in children, so a slow parent span
+doesn't hide which child call actually burned the seconds or the money.
+
+**Waste report.** Heuristics look for duplicate calls, unused cache opportunities, bloated
+prompts, model overkill, and retry loops. Each finding ships with a confidence level and, where the
+numbers support it, a dollar figure. More on this below.
+
+**Replay.** `traceburn.analyze.replay.replay()` plays recorded provider responses back through the
+real SDK types, so your agent code runs again exactly as before with zero tokens spent. That's
+useful for tests and for debugging without burning a budget. Streaming calls aren't replayable
+yet; replay currently only serves non-streaming recordings.
+
+**Diff.** `traceburn diff <a> <b>` lines up two traces span by span and reports the delta in
+tokens, cost, and latency, alongside text diffs of the prompts and responses that changed between
+the runs. Good for answering "did that prompt tweak actually help."
+
+## The web viewer
+
+`traceburn ui` starts a small, read-only Starlette API in front of a vendored single-page app: no
+build step, no CDN, everything ships in the package. It gives you the trace tree, the flamegraph,
+a waterfall timeline, the waste report, and the run diff view.
+
+It binds to 127.0.0.1 only and checks the request's host header against DNS rebinding, but it has
+no authentication of any kind. That's a deliberate tradeoff: the viewer isn't meant to be reachable
+from anywhere but your own machine.
+
+![traceburn's flamegraph view of an agent run, one row per depth, frame width proportional to latency](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/flamegraph.png)
+
+![traceburn's waterfall view of the same run, a timeline of every call with its duration and cost](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/waterfall.png)
+
+## Framework support
+
+Today, that means the raw `openai` and `anthropic` Python SDKs, patched automatically by
+`traceburn.install()`. If you're on something else, the explicit `span()` / `trace()` / `session()`
+API works with any framework right now, by hand, since it doesn't care what's making the call.
+LangChain, LlamaIndex, and anything already emitting OpenTelemetry GenAI spans aren't instrumented
+automatically yet. That's real, planned work for v0.2, not something already built and just
+undocumented, and it's covered in the roadmap below.
+
+## How the waste rules work
+
+The rules live in `traceburn/analyze/waste/` and are documented in full at
+[docs/waste-rules.md](https://github.com/TommyTranX/traceburn/blob/main/docs/waste-rules.md). Five
+kinds of waste get checked for: duplicates (exact and near-duplicate repeated calls), cache (a
+stable prompt prefix resent without ever hitting a provider cache), context_bloat (duplicate
+blocks inside one prompt, or a huge prompt for a tiny output), model_overkill (a frontier-priced
+model spent on trivial short calls, phrased as a suggestion and kept at low confidence on purpose),
+and loops (retry storms, repeated identical tool calls, or a runaway step count). Every finding
+also carries a confidence level: high, medium, low, or info.
+
+Two principles govern all of them. A wrong finding does more damage than a missed one, so the
+rules are tuned for precision over recall and would rather stay quiet than guess. And no dollar
+figure is ever printed without observed tokens behind it and a price in the pricing table to
+multiply against; everything the tool prints is labeled an estimate, because it is one.
+
+## Privacy
+
+traceburn makes no network calls of its own and sends no telemetry anywhere. The only traffic on
+the wire is your own calls to your own model provider, exactly as they'd happen without traceburn
+installed. A test,
+[tests/test_no_network.py](https://github.com/TommyTranX/traceburn/blob/main/tests/test_no_network.py),
+blocks all socket access at the interpreter level and then runs the recorder, the store, every
+analyzer, and the CLI against that blockade, to prove the point rather than just assert it. Auth
+headers are never recorded in a trace, so an API key cannot end up sitting in a stored span.
+
+## Limitations
+
+Instrumentation currently covers only the `openai` and `anthropic` Python SDKs. Within those,
+`parse()` convenience methods and `with_raw_response` calls pass through untraced rather than being
+recorded incorrectly, and multi-choice requests (`n > 1`) only record the first choice.
+
+Cost figures come from a dated public pricing table
+([pricing.json](https://github.com/TommyTranX/traceburn/blob/main/src/traceburn/pricing.json)) and
+don't model long-context pricing tiers or regional surcharges. Token counts prefer whatever the
+provider itself reports as usage; anything estimated is flagged as estimated rather than presented
+as measured.
+
+The waste rules are heuristics tuned for precision over recall, which means they'll miss real
+waste sooner than they'll invent fake waste, and every finding states its own confidence so you
+can judge it accordingly. Streaming calls aren't replayable yet; only non-streaming recordings are.
+
+The web viewer is read-only, bound to 127.0.0.1 only, and has no authentication.
+
+## Roadmap: v0.2
+
+- OpenTelemetry GenAI span ingest plus OTLP export. This is also the path for capturing LangChain
+  and LlamaIndex traces, since it rides on their existing OTel instrumentation rather than
+  requiring bespoke adapters for each.
+- A pytest plugin built on replay, for deterministic, token-free agent tests.
+- litellm instrumentation.
+- More waste rules.
+
+## Related work
+
+[Langfuse](https://github.com/langfuse/langfuse) is a full open-source LLM platform: tracing,
+evals, and prompt management, backed by Postgres and ClickHouse and meant to run as a server.
+
+[Arize Phoenix](https://github.com/Arize-ai/phoenix) is the closest neighbor here. It runs locally
+against SQLite with no account needed, and it's strong on tracing and evals, but it runs as a
+server process with a fairly large dependency set, and it doesn't focus on waste detection, a
+cost-weighted flamegraph, deterministic replay, or run diffs.
+
+MLflow has been adding GenAI tracing, trace comparison, and efficiency scoring to its tracking
+server; see [mlflow/mlflow](https://github.com/mlflow/mlflow).
+
+[LangSmith](https://smith.langchain.com) is LangChain's hosted, proprietary platform.
+[OpenLLMetry](https://github.com/traceloop/openllmetry) takes a different approach: it instruments
+your code and exports OpenTelemetry spans to whatever backend you choose to point it at, rather
+than shipping a backend of its own.
+
+[AgentSight](https://github.com/eunomia-bpf/agentsight) renders token flamegraphs of coding agents
+from the system side using eBPF, a genuinely different vantage point, though it's Linux only.
+
+Helicone ([Helicone/helicone](https://github.com/Helicone/helicone)), OpenLIT
+([openlit/openlit](https://github.com/openlit/openlit)), Braintrust
+([braintrust.dev](https://braintrust.dev)), and Logfire
+([pydantic.dev/logfire](https://pydantic.dev/logfire)) each pair instrumentation with a server or a
+cloud backend of their own.
+
+traceburn's own position is narrower than most of the above: strictly local, one file, no account
+and no server needed for basic use, framework-agnostic at the SDK level, and built around
+efficiency first, meaning the waste report, the dollar-weighted flamegraph, replay, and diff all
+live together in one small package. It's meant to sit next to whatever observability stack you
+already run, not replace it.
+
+## Contributing
+
+There are two extension points, each documented and each meant to be roughly an afternoon of work:
+an [instrumentation adapter](https://github.com/TommyTranX/traceburn/blob/main/docs/instrumentation.md)
+for a new SDK or framework, and a
+[waste rule](https://github.com/TommyTranX/traceburn/blob/main/docs/waste-rules.md) for a new
+pattern of avoidable spend. The full guide is at
+[CONTRIBUTING.md](https://github.com/TommyTranX/traceburn/blob/main/CONTRIBUTING.md).
+
+## Citation
+
+A citation file is included at
+[CITATION.cff](https://github.com/TommyTranX/traceburn/blob/main/CITATION.cff).
+
+## License
+
+MIT. Full text at
+[LICENSE](https://github.com/TommyTranX/traceburn/blob/main/LICENSE).
+
+Written by Tommy Tran.

traceburn-0.1.0/README.md

@@ -0,0 +1,233 @@
+# traceburn
+
+## The finding that made me build this
+
+I wrote a small support ticket triage agent: five tickets, one tool call each, a roughly 4,700
+token static policy prompt sent fresh on every call, model claude-haiku-4-5. Running it uncached
+cost $0.0539. traceburn's waste report looked at the trace, noticed that same 4,700 token prefix
+going out uncached on all 10 calls, and estimated that about 82 percent of that spend was
+avoidable. So I added exactly the one cache_control block it suggested and reran the same five
+tickets: $0.0167.
+
+That's a 69 percent measured saving. The tool's estimate landed within 18 percent of what actually
+happened, close enough to trust as a first signal, not close enough to treat as gospel. That's
+roughly how I want a cost estimator to behave.
+
+Prices change and models get repriced, so do not take my word for it: the reproduction is a few
+cents and a couple of minutes, at
+[examples/cache_before_after.py](https://github.com/TommyTranX/traceburn/blob/main/examples/cache_before_after.py).
+Measured 2026-07-05.
+
+![traceburn's waste report on the uncached run: $0.0539 total, about 82 percent flagged avoidable, with the repeated 5,618-token prefix identified as the cause](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/waste-report.png)
+
+That's the whole pitch in one run. traceburn is a local-first tracer and efficiency profiler for
+AI agents, built on top of the openai and anthropic Python SDKs: a cost and latency flamegraph, a
+waste report that quantifies avoidable spend instead of just gesturing at it, deterministic replay
+of recorded calls, and run diffs, all backed by one SQLite file on disk. No account, no server to
+stand up for basic use, no telemetry leaving your machine.
+
+## Install
+
+Core tracer, stdlib only, zero dependencies:
+
+```bash
+pip install traceburn
+```
+
+Tracer plus the local web viewer (adds starlette and uvicorn):
+
+```bash
+pip install "traceburn[ui]"
+```
+
+Requires Python 3.10 or later.
+
+## Quickstart
+
+Patch the SDKs at the top of your agent:
+
+```python
+import traceburn
+traceburn.install()
+
+# your existing openai / anthropic code, unchanged
+```
+
+Every sync call, async call, streaming response, tool call, and prompt cache hit on either SDK now
+gets recorded as a span. Traces live in one SQLite file, `./.traceburn/traces.db` by default; set
+the `TRACEBURN_DB` environment variable if you want it somewhere else. If you'd rather not touch
+the source at all, wrap the run instead:
+
+```bash
+TRACEBURN=1 python your_agent.py
+```
+
+Then look at what happened:
+
+```bash
+traceburn ui             # opens the web viewer at 127.0.0.1:8765
+traceburn ls              # list recorded traces
+traceburn show <id>       # inspect one trace
+traceburn waste <id>      # run the waste report on one trace
+traceburn diff <a> <b>    # compare two traces span by span
+```
+
+No API keys and nothing to configure: `python examples/offline_demo.py` records a simulated agent
+run with realistic token counts, including one deliberate duplicate call, so you can see a real
+trace, a real flamegraph, and a real waste finding inside a minute.
+
+## What it actually does
+
+**Trace.** `traceburn.install()` patches both SDKs so every call becomes a span with tokens,
+latency, and cost attached, no code changes required past that one line. Want manual control
+instead, or you're using a framework outside the two supported SDKs? The explicit API, `@trace`,
+`span()`, and `session()`, works by hand with anything.
+
+![traceburn's expandable trace tree, showing an agent's nested spans with per-call tokens and cost](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/trace-tree.png)
+
+**Flamegraph.** Spans render as a flamegraph you can size two ways: by wall-clock time or by
+dollars spent, with self-time kept separate from time spent in children, so a slow parent span
+doesn't hide which child call actually burned the seconds or the money.
+
+**Waste report.** Heuristics look for duplicate calls, unused cache opportunities, bloated
+prompts, model overkill, and retry loops. Each finding ships with a confidence level and, where the
+numbers support it, a dollar figure. More on this below.
+
+**Replay.** `traceburn.analyze.replay.replay()` plays recorded provider responses back through the
+real SDK types, so your agent code runs again exactly as before with zero tokens spent. That's
+useful for tests and for debugging without burning a budget. Streaming calls aren't replayable
+yet; replay currently only serves non-streaming recordings.
+
+**Diff.** `traceburn diff <a> <b>` lines up two traces span by span and reports the delta in
+tokens, cost, and latency, alongside text diffs of the prompts and responses that changed between
+the runs. Good for answering "did that prompt tweak actually help."
+
+## The web viewer
+
+`traceburn ui` starts a small, read-only Starlette API in front of a vendored single-page app: no
+build step, no CDN, everything ships in the package. It gives you the trace tree, the flamegraph,
+a waterfall timeline, the waste report, and the run diff view.
+
+It binds to 127.0.0.1 only and checks the request's host header against DNS rebinding, but it has
+no authentication of any kind. That's a deliberate tradeoff: the viewer isn't meant to be reachable
+from anywhere but your own machine.
+
+![traceburn's flamegraph view of an agent run, one row per depth, frame width proportional to latency](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/flamegraph.png)
+
+![traceburn's waterfall view of the same run, a timeline of every call with its duration and cost](https://raw.githubusercontent.com/TommyTranX/traceburn/main/assets/waterfall.png)
+
+## Framework support
+
+Today, that means the raw `openai` and `anthropic` Python SDKs, patched automatically by
+`traceburn.install()`. If you're on something else, the explicit `span()` / `trace()` / `session()`
+API works with any framework right now, by hand, since it doesn't care what's making the call.
+LangChain, LlamaIndex, and anything already emitting OpenTelemetry GenAI spans aren't instrumented
+automatically yet. That's real, planned work for v0.2, not something already built and just
+undocumented, and it's covered in the roadmap below.
+
+## How the waste rules work
+
+The rules live in `traceburn/analyze/waste/` and are documented in full at
+[docs/waste-rules.md](https://github.com/TommyTranX/traceburn/blob/main/docs/waste-rules.md). Five
+kinds of waste get checked for: duplicates (exact and near-duplicate repeated calls), cache (a
+stable prompt prefix resent without ever hitting a provider cache), context_bloat (duplicate
+blocks inside one prompt, or a huge prompt for a tiny output), model_overkill (a frontier-priced
+model spent on trivial short calls, phrased as a suggestion and kept at low confidence on purpose),
+and loops (retry storms, repeated identical tool calls, or a runaway step count). Every finding
+also carries a confidence level: high, medium, low, or info.
+
+Two principles govern all of them. A wrong finding does more damage than a missed one, so the
+rules are tuned for precision over recall and would rather stay quiet than guess. And no dollar
+figure is ever printed without observed tokens behind it and a price in the pricing table to
+multiply against; everything the tool prints is labeled an estimate, because it is one.
+
+## Privacy
+
+traceburn makes no network calls of its own and sends no telemetry anywhere. The only traffic on
+the wire is your own calls to your own model provider, exactly as they'd happen without traceburn
+installed. A test,
+[tests/test_no_network.py](https://github.com/TommyTranX/traceburn/blob/main/tests/test_no_network.py),
+blocks all socket access at the interpreter level and then runs the recorder, the store, every
+analyzer, and the CLI against that blockade, to prove the point rather than just assert it. Auth
+headers are never recorded in a trace, so an API key cannot end up sitting in a stored span.
+
+## Limitations
+
+Instrumentation currently covers only the `openai` and `anthropic` Python SDKs. Within those,
+`parse()` convenience methods and `with_raw_response` calls pass through untraced rather than being
+recorded incorrectly, and multi-choice requests (`n > 1`) only record the first choice.
+
+Cost figures come from a dated public pricing table
+([pricing.json](https://github.com/TommyTranX/traceburn/blob/main/src/traceburn/pricing.json)) and
+don't model long-context pricing tiers or regional surcharges. Token counts prefer whatever the
+provider itself reports as usage; anything estimated is flagged as estimated rather than presented
+as measured.
+
+The waste rules are heuristics tuned for precision over recall, which means they'll miss real
+waste sooner than they'll invent fake waste, and every finding states its own confidence so you
+can judge it accordingly. Streaming calls aren't replayable yet; only non-streaming recordings are.
+
+The web viewer is read-only, bound to 127.0.0.1 only, and has no authentication.
+
+## Roadmap: v0.2
+
+- OpenTelemetry GenAI span ingest plus OTLP export. This is also the path for capturing LangChain
+  and LlamaIndex traces, since it rides on their existing OTel instrumentation rather than
+  requiring bespoke adapters for each.
+- A pytest plugin built on replay, for deterministic, token-free agent tests.
+- litellm instrumentation.
+- More waste rules.
+
+## Related work
+
+[Langfuse](https://github.com/langfuse/langfuse) is a full open-source LLM platform: tracing,
+evals, and prompt management, backed by Postgres and ClickHouse and meant to run as a server.
+
+[Arize Phoenix](https://github.com/Arize-ai/phoenix) is the closest neighbor here. It runs locally
+against SQLite with no account needed, and it's strong on tracing and evals, but it runs as a
+server process with a fairly large dependency set, and it doesn't focus on waste detection, a
+cost-weighted flamegraph, deterministic replay, or run diffs.
+
+MLflow has been adding GenAI tracing, trace comparison, and efficiency scoring to its tracking
+server; see [mlflow/mlflow](https://github.com/mlflow/mlflow).
+
+[LangSmith](https://smith.langchain.com) is LangChain's hosted, proprietary platform.
+[OpenLLMetry](https://github.com/traceloop/openllmetry) takes a different approach: it instruments
+your code and exports OpenTelemetry spans to whatever backend you choose to point it at, rather
+than shipping a backend of its own.
+
+[AgentSight](https://github.com/eunomia-bpf/agentsight) renders token flamegraphs of coding agents
+from the system side using eBPF, a genuinely different vantage point, though it's Linux only.
+
+Helicone ([Helicone/helicone](https://github.com/Helicone/helicone)), OpenLIT
+([openlit/openlit](https://github.com/openlit/openlit)), Braintrust
+([braintrust.dev](https://braintrust.dev)), and Logfire
+([pydantic.dev/logfire](https://pydantic.dev/logfire)) each pair instrumentation with a server or a
+cloud backend of their own.
+
+traceburn's own position is narrower than most of the above: strictly local, one file, no account
+and no server needed for basic use, framework-agnostic at the SDK level, and built around
+efficiency first, meaning the waste report, the dollar-weighted flamegraph, replay, and diff all
+live together in one small package. It's meant to sit next to whatever observability stack you
+already run, not replace it.
+
+## Contributing
+
+There are two extension points, each documented and each meant to be roughly an afternoon of work:
+an [instrumentation adapter](https://github.com/TommyTranX/traceburn/blob/main/docs/instrumentation.md)
+for a new SDK or framework, and a
+[waste rule](https://github.com/TommyTranX/traceburn/blob/main/docs/waste-rules.md) for a new
+pattern of avoidable spend. The full guide is at
+[CONTRIBUTING.md](https://github.com/TommyTranX/traceburn/blob/main/CONTRIBUTING.md).
+
+## Citation
+
+A citation file is included at
+[CITATION.cff](https://github.com/TommyTranX/traceburn/blob/main/CITATION.cff).
+
+## License
+
+MIT. Full text at
+[LICENSE](https://github.com/TommyTranX/traceburn/blob/main/LICENSE).
+
+Written by Tommy Tran.

traceburn-0.1.0/docs/concepts.md

@@ -0,0 +1,57 @@
+# Concepts
+
+## The data model
+
+Three tables, plus content-addressed blobs, in one SQLite file:
+
+- A **session** groups related traces (a batch run, a test suite pass).
+- A **trace** is one run: everything under one root span.
+- A **span** is one timed operation with a `kind`: `llm`, `tool`, `agent`,
+  `retrieval`, or `custom`. Spans nest via `parent_id`.
+
+LLM spans follow the OpenTelemetry GenAI attribute names where they exist
+(`gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, and
+so on) plus traceburn extensions: cache token splits, estimated cost, the
+normalized request and response, and a `request_hash` used by replay and
+duplicate detection. The full conventions live in `schema.py` and are a
+public, versioned interface.
+
+## Token accounting
+
+`gen_ai.usage.input_tokens` counts only tokens billed at the full input
+rate. Cache reads (`cached_input_tokens`) and cache writes
+(`cache_write_tokens`) are separate, so cost math stays auditable:
+
+```
+cost = input * input_rate + cached * cached_rate
+     + cache_write * write_rate + output * output_rate
+```
+
+Rates come from a dated, user-overridable pricing table
+(`pricing.json`, `TRACEBURN_PRICING`). When a provider omits usage (some
+streaming shapes), counts are estimated and the span carries
+`usage_estimated: true`.
+
+## Storage
+
+WAL mode, so the viewer reads while your agent writes. Large request and
+response payloads are stored once in a blobs table, keyed by content hash;
+identical payloads across calls cost one row, which is also what makes
+duplicate detection and replay lookups cheap. The schema is versioned via
+a meta row.
+
+## Write path guarantees
+
+A failure inside traceburn never breaks your agent: store writes are
+guarded, patcher capture errors degrade to an untraced call, and spans for
+abandoned streams finalize at garbage collection. Exceptions from your own
+code always propagate; the span just records the error first.
+
+## The analyzers
+
+Everything in `traceburn/analyze/` reads the store and computes:
+flamegraph folds (latency- or cost-weighted), waterfall timelines, run
+diffs, deterministic replay, and the waste report. None of it makes a
+network call. The CLI and the web viewer are two skins over the same
+functions, and every JSON shape they emit is a public interface you can
+consume without importing the analyzers.