tokenprof 0.1.0__tar.gz

tokenprof-0.1.0/.github/ISSUE_TEMPLATE/adapter-or-payload.md

@@ -0,0 +1,23 @@
+---
+name: Adapter request or unreadable payload
+about: tokenprof cannot read your logs, or you want support for a framework
+title: "Adapter: <framework or provider>"
+labels: adapter
+---
+
+**Framework or provider**
+
+**What happened**
+The error, or the wrong numbers you got.
+
+**Redacted sample**
+One request payload, with prompt and tool result text replaced by filler of
+roughly the same length. Structure is what the parser needs and length is what
+the profiler needs, so a redacted sample is just as useful as a real one.
+
+```json
+
+```
+
+**Anything unusual about the shape**
+Custom message roles, nested content blocks, non-standard tool spec format.

tokenprof-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Adapter request
+    url: https://github.com/muhammadwaqar12/tokenprof/issues/new?template=adapter-or-payload.md
+    about: tokenprof cannot read your logs, or you want support for a framework

tokenprof-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+**What this changes**
+
+**Why**
+
+---
+
+- [ ] `pytest -q` passes
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] Added the test that would fail without this change
+
+**If this adds an adapter**
+
+- [ ] `matches` is exclusive (the detection test asserts exactly one adapter claims a payload)
+- [ ] Segments carry names, so the per-tool breakdown stays useful
+- [ ] Added a fixture under `tests/fixtures/`

tokenprof-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  tokenizer:
+    # The heuristic path is the default, so the exact-tokenizer path needs
+    # its own run or it silently rots.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,tiktoken]"
+      - run: pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - run: pip install dist/*.whl && tokenprof --version

tokenprof-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: release
+
+# Publishing happens on a version tag, never on a push to main, so cutting a
+# release is a deliberate act rather than a side effect of merging.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Refuse to release if the tag and the package disagree
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "tag=$TAG package=$PKG"
+          [ "$TAG" = "$PKG" ] || { echo "::error::tag $TAG does not match version $PKG"; exit 1; }
+
+      - run: pip install build twine
+      - run: python -m build
+      - name: Check the metadata PyPI will render
+        run: twine check --strict dist/*
+      - name: Prove the wheel installs and runs
+        run: |
+          python -m venv /tmp/v
+          /tmp/v/bin/pip install dist/*.whl
+          /tmp/v/bin/tokenprof --version
+          /tmp/v/bin/tokenprof cache tests/fixtures/cache_thrash.jsonl | grep -q "what broke the prefix"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI trusted publishing, no API token anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tokenprof-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+*.jsonl
+!tests/fixtures/*.jsonl
+*.cast
+.probe_*

tokenprof-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainer at m_waqar@live.com. All complaints will be reviewed and investigated promptly and fairly.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned to this Code of Conduct.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

tokenprof-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+The two most useful things you can send: an adapter, or a payload that breaks detection.
+
+## Payloads that break detection
+
+If `tokenprof` cannot read your logs, that is a bug and the fix is usually small. Open an issue with a **redacted** sample: replace the actual prompt and tool result text with filler of roughly the same length, keep the structure. Structure is all the parser cares about, and length is all the profiler cares about, so a redacted sample is just as useful as a real one and safe to post.
+
+## Writing an adapter
+
+An adapter has three methods and no framework dependency in the core:
+
+```python
+class MyAdapter:
+    name = "my_provider"
+
+    def matches(self, request: dict) -> bool: ...
+    def model_of(self, request: dict) -> str: ...
+    def segments(self, request: dict, tok: Tokenizer) -> list[Segment]: ...
+```
+
+Add the module under `src/tokenprof/adapters/`, register it in `ADAPTERS`, and add a fixture under `tests/fixtures/`.
+
+Two rules that matter more than they look:
+
+**`matches` must be exclusive.** There is a test asserting exactly one adapter claims any given payload. If two match, registry ordering silently decides correctness, and that bug surfaces months later as wrong numbers rather than an error. Discriminate on a field only your provider has.
+
+**Emit segments in prompt order.** Cache prefixes are computed over the order you emit, so it has to match the order the provider actually assembles the prompt. Anthropic is tools, then system, then messages. Getting this wrong puts the cache break point in the wrong place and the numbers look plausible while being wrong.
+
+**Name your segments.** A tool schema segment named `search_docs` is actionable. An unnamed one is trivia. The per-tool breakdown is the most useful view in the tool, and it only works if adapters carry names through.
+
+**Carry the digest through.** `measure()` returns `(tokens, chars, digest)`. A segment without a digest can never count as a cache hit, which is the safe default, but it also means `tokenprof cache` goes blind on your provider. Pass it into every `Segment` you build.
+
+**Mark cached segments if your provider has explicit markers.** Anthropic uses `cache_control`, where the marker caches the whole prefix up to and including that block, so only the last marker matters. OpenAI caches automatically with no markers, so its adapter marks nothing and the prefix analysis does the work instead.
+
+## Categories
+
+`Category` is deliberately small. A new one has to pass a simple test: could someone do something different in response to seeing it broken out? If the answer is no, it belongs in an existing bucket.
+
+## Tests
+
+`pytest -q`. Everything runs offline with no API keys and no network.
+
+Fixtures are hand-built rather than captured, so they can be committed without redaction and can encode the specific situations worth testing. The OpenAI fixture deliberately contains one bloated auto-generated tool and registers a new tool partway through the session, because those are the two cases the reports exist to catch.
+
+If you add behavior, add the test that would fail without it. If you fix a bug, add the test that was missing.
+
+## Accuracy claims
+
+Be careful with numbers in docs and output. The default tokenizer is an approximation and every report says so. If you add a counting path, make it report its own name, and do not describe approximate counts as exact anywhere in the interface.
+
+## Style
+
+- `ruff check .` and `ruff format .` before opening a PR. CI runs both.
+- Plain names. `fixed_overhead_tokens` over `calc_fo`.
+- Comments explain why, not what. The code says what.
+
+## Review
+
+Pull requests get looked at within a day or two. Ping the thread if yours goes quiet.

tokenprof-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Waqar
+
+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.

tokenprof-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: tokenprof
+Version: 0.1.0
+Summary: A profiler for the context window. See what is actually eating your tokens, per turn.
+Project-URL: Homepage, https://github.com/muhammadwaqar12/tokenprof
+Project-URL: Issues, https://github.com/muhammadwaqar12/tokenprof/issues
+Author: Muhammad Waqar
+License: MIT
+License-File: LICENSE
+Keywords: agents,context,cost,llm,observability,profiler,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: rich>=13.0; extra == 'all'
+Requires-Dist: tiktoken>=0.7; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == 'rich'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.7; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+<h3 align="center">A profiler for the context window. See what is actually eating your tokens, per turn.</h3>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#where-your-tokens-went">Attribution</a> ·
+  <a href="#is-your-prompt-cache-actually-working">Cache</a> ·
+  <a href="#recording-a-session">Recording</a> ·
+  <a href="#adapters">Adapters</a> ·
+  <a href="https://github.com/muhammadwaqar12/tokenprof/blob/main/CONTRIBUTING.md">Contribute</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/muhammadwaqar12/tokenprof/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-3a6b4d"></a>
+  <img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-3a6b4d">
+  <img alt="Dependencies" src="https://img.shields.io/badge/dependencies-0-9a6a15">
+  <a href="https://github.com/muhammadwaqar12/tokenprof/blob/main/CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-3a6b4d"></a>
+</p>
+
+---
+
+You know how many tokens your last request used, because the API told you. You almost certainly do not know **what they were**.
+
+There are tools that compress your context and tools that retrieve into it. There is nothing that opens it up and shows you the bill line by line. So when a session gets slow and expensive, the usual move is to guess.
+
+## Quickstart
+
+```bash
+pip install tokenprof                                          # once released
+pip install git+https://github.com/muhammadwaqar12/tokenprof   # from source
+```
+
+Run your program through `record`. It attaches to the OpenAI and Anthropic clients, writes every outgoing request to a file, and changes nothing about what your program does.
+
+```bash
+tokenprof record -o session.jsonl -- python your_agent.py
+tokenprof analyze session.jsonl
+tokenprof cache   session.jsonl
+```
+
+No API keys, no config, no code changes. If you already log request payloads, skip `record` and point `analyze` at what you have.
+
+## Where your tokens went
+
+```
+$ tokenprof analyze session.jsonl --turn 2
+
+turn 2  model=gpt-4o  provider=openai_chat
+tokenizer: heuristic(chars/4)
+
+category                tokens   share                                     cost
+-----------------------------------------------------------------------------
+tool result              2,869   66.6%  ###################.........   $0.0072
+tool schema              1,142   26.5%  #######.....................   $0.0029
+system                     205    4.8%  #...........................   $0.0005
+history assistant           67    1.6%  ............................   $0.0002
+history user                14    0.3%  ............................   $0.0000
+current user                 8    0.2%  ............................   $0.0000
+-----------------------------------------------------------------------------
+TOTAL                    4,305  100.0%                                  $0.0108
+
+fixed overhead (system + tool schemas): 1,347 tokens (31.3% of this turn), re-sent on every request
+
+tool schemas (4 registered)
+  bloated_connector                      912  ####..............
+  search_docs                             85  ..................
+  trace_calls                             82  ..................
+  read_file                               63  ..................
+```
+
+One auto-generated tool is eating 80% of the schema budget and is serialized into every request whether the model calls it or not. Nothing errors. Nothing in your dashboard says so.
+
+The per-tool line is the part most tools cannot give you. Not "you have 40 tools registered" but **which ones**, ranked, in tokens.
+
+## Is your prompt cache actually working?
+
+Providers cache a **prefix**. If the first N tokens of a request are byte-identical to the last one, you pay a fraction for them. One volatile value near the front moves the break point to zero, and you quietly pay full price on every turn while your config still says caching is on.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/muhammadwaqar12/tokenprof/main/docs/demo.svg" alt="tokenprof cache finding a broken prompt cache prefix" width="100%">
+</p>
+
+```
+$ tokenprof cache session.jsonl
+
+    turns    stable     total   share  what broke the prefix
+--------------------------------------------------------------------------
+   0 -> 1         68       248   27.4%  system:system
+   1 -> 2         68       302   22.5%  system:system
+   2 -> 3         68       356   19.1%  system:system
+--------------------------------------------------------------------------
+
+reusable across turns: 204 tokens | re-sent after a break: 702
+
+segments that broke the prefix
+  system:system                                  3x
+
+WARNING: the prefix breaks early. Turn 3 reuses only 19.1% of its prompt.
+  Anything that changes near the front of the prompt costs you the whole
+  cache. Timestamps, session ids and reordered tool lists are the usual
+  causes. Move volatile content to the end.
+```
+
+That session has a timestamp at the top of the system prompt. Every turn misses, and the tool names the segment responsible rather than just reporting a bad number.
+
+The other common cause is subtler: **registering one new tool mid-session invalidates the whole prefix**, because tool schemas are serialized ahead of the messages. `tokenprof cache` catches that too.
+
+Cost accounting follows the real pricing. Anthropic bills cache reads at 10% of base and OpenAI at 50%, so a turn with `cache_control` markers reports what it actually bills rather than a blended number that overstates exactly the segments you were smart enough to cache.
+
+## Recording a session
+
+`record` writes a `sitecustomize` shim onto the path of the process you launch, wraps the client `create` methods, and calls through untouched. Two deliberate constraints: it never raises into your program, and it records requests only, never responses.
+
+```bash
+tokenprof record --verbose -o session.jsonl -- python your_agent.py
+# tokenprof: patched openai, anthropic
+# tokenprof: captured 14 request(s) to session.jsonl
+```
+
+If you would rather log payloads yourself, any JSONL of request objects works. Bare payloads and anything wrapping one under `request`, `body`, `payload` or `kwargs` are all accepted, and `-` reads stdin.
+
+> [!NOTE]
+> A recording contains your prompts and your tool results in full, which usually means credentials and customer data. The default `.gitignore` excludes `*.jsonl`. Redact before attaching one to an issue.
+
+## Adapters
+
+An adapter turns one provider's payload shape into a list of segments. Three methods, no framework dependency in the core, which is why adding one is an afternoon rather than a refactor.
+
+| Adapter | Status |
+|---|---|
+| `anthropic_messages` | Shipped, with `cache_control` support |
+| `openai_chat` | Shipped |
+| LangGraph / LangChain | Wanted |
+| CrewAI | Wanted |
+| Google ADK | Wanted |
+| Bedrock Converse | Wanted |
+
+Most frameworks ultimately emit an OpenAI or Anthropic payload, so the two shipped adapters already cover a lot of ground. Detection is automatic, and a test asserts exactly one adapter claims any payload. Pass `--provider` to override.
+
+## Accuracy
+
+Every report states which tokenizer produced it, because the honest answer varies.
+
+With `tiktoken` installed and an OpenAI model, counts are exact. Otherwise it falls back to `chars / 4`, which runs low on code and non-Latin scripts. That is fine for ranking segments against each other, which is what you are here for, and it is not a context budget.
+
+Serialization is close but not exact. Providers wrap messages and schemas in their own formatting, and that wrapper is small next to the payload. Treat the numbers as accurate to a few percent and the ranking as reliable.
+
+## What this is not
+
+Not a tracing tool. Langfuse, Phoenix and LangSmith show latency, spans and token *counts*, and do it well. None show token *composition*. Run both.
+
+Not a compressor. It tells you what to cut. Cutting is your call.
+
+Not a runtime guard. It reads recordings after the fact, on purpose, so a profiler can never sit in the path of a production request.
+
+## Contributing
+
+The most useful contributions are adapters, and payload shapes that break detection. If `tokenprof` cannot read your logs, that is a bug and a redacted sample is the whole fix. See [CONTRIBUTING.md](https://github.com/muhammadwaqar12/tokenprof/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/muhammadwaqar12/tokenprof/blob/main/LICENSE).
+
+---
+
+<sub>Built by <a href="https://github.com/muhammadwaqar12">Muhammad Waqar</a>. Companion to <a href="https://github.com/muhammadwaqar12/awesome-agent-failures">awesome-agent-failures</a>, where CTX-03 covers the tool schema tax and COST-03 covers prompt cache thrash.</sub>

tokenprof-0.1.0/README.md

@@ -0,0 +1,165 @@
+<h3 align="center">A profiler for the context window. See what is actually eating your tokens, per turn.</h3>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#where-your-tokens-went">Attribution</a> ·
+  <a href="#is-your-prompt-cache-actually-working">Cache</a> ·
+  <a href="#recording-a-session">Recording</a> ·
+  <a href="#adapters">Adapters</a> ·
+  <a href="https://github.com/muhammadwaqar12/tokenprof/blob/main/CONTRIBUTING.md">Contribute</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/muhammadwaqar12/tokenprof/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-3a6b4d"></a>
+  <img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-3a6b4d">
+  <img alt="Dependencies" src="https://img.shields.io/badge/dependencies-0-9a6a15">
+  <a href="https://github.com/muhammadwaqar12/tokenprof/blob/main/CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-3a6b4d"></a>
+</p>
+
+---
+
+You know how many tokens your last request used, because the API told you. You almost certainly do not know **what they were**.
+
+There are tools that compress your context and tools that retrieve into it. There is nothing that opens it up and shows you the bill line by line. So when a session gets slow and expensive, the usual move is to guess.
+
+## Quickstart
+
+```bash
+pip install tokenprof                                          # once released
+pip install git+https://github.com/muhammadwaqar12/tokenprof   # from source
+```
+
+Run your program through `record`. It attaches to the OpenAI and Anthropic clients, writes every outgoing request to a file, and changes nothing about what your program does.
+
+```bash
+tokenprof record -o session.jsonl -- python your_agent.py
+tokenprof analyze session.jsonl
+tokenprof cache   session.jsonl
+```
+
+No API keys, no config, no code changes. If you already log request payloads, skip `record` and point `analyze` at what you have.
+
+## Where your tokens went
+
+```
+$ tokenprof analyze session.jsonl --turn 2
+
+turn 2  model=gpt-4o  provider=openai_chat
+tokenizer: heuristic(chars/4)
+
+category                tokens   share                                     cost
+-----------------------------------------------------------------------------
+tool result              2,869   66.6%  ###################.........   $0.0072
+tool schema              1,142   26.5%  #######.....................   $0.0029
+system                     205    4.8%  #...........................   $0.0005
+history assistant           67    1.6%  ............................   $0.0002
+history user                14    0.3%  ............................   $0.0000
+current user                 8    0.2%  ............................   $0.0000
+-----------------------------------------------------------------------------
+TOTAL                    4,305  100.0%                                  $0.0108
+
+fixed overhead (system + tool schemas): 1,347 tokens (31.3% of this turn), re-sent on every request
+
+tool schemas (4 registered)
+  bloated_connector                      912  ####..............
+  search_docs                             85  ..................
+  trace_calls                             82  ..................
+  read_file                               63  ..................
+```
+
+One auto-generated tool is eating 80% of the schema budget and is serialized into every request whether the model calls it or not. Nothing errors. Nothing in your dashboard says so.
+
+The per-tool line is the part most tools cannot give you. Not "you have 40 tools registered" but **which ones**, ranked, in tokens.
+
+## Is your prompt cache actually working?
+
+Providers cache a **prefix**. If the first N tokens of a request are byte-identical to the last one, you pay a fraction for them. One volatile value near the front moves the break point to zero, and you quietly pay full price on every turn while your config still says caching is on.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/muhammadwaqar12/tokenprof/main/docs/demo.svg" alt="tokenprof cache finding a broken prompt cache prefix" width="100%">
+</p>
+
+```
+$ tokenprof cache session.jsonl
+
+    turns    stable     total   share  what broke the prefix
+--------------------------------------------------------------------------
+   0 -> 1         68       248   27.4%  system:system
+   1 -> 2         68       302   22.5%  system:system
+   2 -> 3         68       356   19.1%  system:system
+--------------------------------------------------------------------------
+
+reusable across turns: 204 tokens | re-sent after a break: 702
+
+segments that broke the prefix
+  system:system                                  3x
+
+WARNING: the prefix breaks early. Turn 3 reuses only 19.1% of its prompt.
+  Anything that changes near the front of the prompt costs you the whole
+  cache. Timestamps, session ids and reordered tool lists are the usual
+  causes. Move volatile content to the end.
+```
+
+That session has a timestamp at the top of the system prompt. Every turn misses, and the tool names the segment responsible rather than just reporting a bad number.
+
+The other common cause is subtler: **registering one new tool mid-session invalidates the whole prefix**, because tool schemas are serialized ahead of the messages. `tokenprof cache` catches that too.
+
+Cost accounting follows the real pricing. Anthropic bills cache reads at 10% of base and OpenAI at 50%, so a turn with `cache_control` markers reports what it actually bills rather than a blended number that overstates exactly the segments you were smart enough to cache.
+
+## Recording a session
+
+`record` writes a `sitecustomize` shim onto the path of the process you launch, wraps the client `create` methods, and calls through untouched. Two deliberate constraints: it never raises into your program, and it records requests only, never responses.
+
+```bash
+tokenprof record --verbose -o session.jsonl -- python your_agent.py
+# tokenprof: patched openai, anthropic
+# tokenprof: captured 14 request(s) to session.jsonl
+```
+
+If you would rather log payloads yourself, any JSONL of request objects works. Bare payloads and anything wrapping one under `request`, `body`, `payload` or `kwargs` are all accepted, and `-` reads stdin.
+
+> [!NOTE]
+> A recording contains your prompts and your tool results in full, which usually means credentials and customer data. The default `.gitignore` excludes `*.jsonl`. Redact before attaching one to an issue.
+
+## Adapters
+
+An adapter turns one provider's payload shape into a list of segments. Three methods, no framework dependency in the core, which is why adding one is an afternoon rather than a refactor.
+
+| Adapter | Status |
+|---|---|
+| `anthropic_messages` | Shipped, with `cache_control` support |
+| `openai_chat` | Shipped |
+| LangGraph / LangChain | Wanted |
+| CrewAI | Wanted |
+| Google ADK | Wanted |
+| Bedrock Converse | Wanted |
+
+Most frameworks ultimately emit an OpenAI or Anthropic payload, so the two shipped adapters already cover a lot of ground. Detection is automatic, and a test asserts exactly one adapter claims any payload. Pass `--provider` to override.
+
+## Accuracy
+
+Every report states which tokenizer produced it, because the honest answer varies.
+
+With `tiktoken` installed and an OpenAI model, counts are exact. Otherwise it falls back to `chars / 4`, which runs low on code and non-Latin scripts. That is fine for ranking segments against each other, which is what you are here for, and it is not a context budget.
+
+Serialization is close but not exact. Providers wrap messages and schemas in their own formatting, and that wrapper is small next to the payload. Treat the numbers as accurate to a few percent and the ranking as reliable.
+
+## What this is not
+
+Not a tracing tool. Langfuse, Phoenix and LangSmith show latency, spans and token *counts*, and do it well. None show token *composition*. Run both.
+
+Not a compressor. It tells you what to cut. Cutting is your call.
+
+Not a runtime guard. It reads recordings after the fact, on purpose, so a profiler can never sit in the path of a production request.
+
+## Contributing
+
+The most useful contributions are adapters, and payload shapes that break detection. If `tokenprof` cannot read your logs, that is a bug and a redacted sample is the whole fix. See [CONTRIBUTING.md](https://github.com/muhammadwaqar12/tokenprof/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/muhammadwaqar12/tokenprof/blob/main/LICENSE).
+
+---
+
+<sub>Built by <a href="https://github.com/muhammadwaqar12">Muhammad Waqar</a>. Companion to <a href="https://github.com/muhammadwaqar12/awesome-agent-failures">awesome-agent-failures</a>, where CTX-03 covers the tool schema tax and COST-03 covers prompt cache thrash.</sub>