cachelens 1.0.0__tar.gz

cachelens-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+cache_reports/
+SPEC.md
+.claude/

cachelens-1.0.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-06-09
+
+### Added
+- Wrapper interception for Anthropic, Gemini, and OpenAI clients (`wrap`, `CacheLens`, `CacheLensClient`)
+- Request capture: normalises prompt to ordered `PromptSegment` list per call
+- Content-based layer classification via longest-common-prefix analysis (system_prompt / context / conversation layers)
+- Terminal report with cache hit rate, cost, savings, and per-layer breakdown
+- JSON export (`json_export=` arg or `CACHE_LENS_JSON` env var)
+- OpenTelemetry metrics output (`otel=True`)
+- Overridable pricing table (native dict, JSON file, or `CACHE_LENS_PRICING` env var; LiteLLM format auto-detected)
+- Gemini support for modern `google-genai` SDK (`config` kwarg pattern)

cachelens-1.0.0/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md — cache-lens
+
+Context for Claude Code sessions on this repo.
+
+## What this is
+
+A Python library that instruments prompt caching in LLM API apps (Anthropic,
+Gemini, OpenAI). You wrap a provider client; on each intercepted call it captures
+both the **request prompt** (normalised to ordered `PromptSegment`s) and the
+**response cache metrics**. At session end the analyzer does content-based layer
+classification and produces a `SessionReport` rendered to terminal / JSON / OTEL.
+Full design in [SPEC.md](SPEC.md).
+
+The differentiator (see [docs/positioning.md](docs/positioning.md)): it doesn't
+just report cached-token counts (LiteLLM/Langfuse/Helicone already do that) — it
+diffs the prompt prefix across calls to name *which layer* is stable-but-uncached
+and what restructuring would save.
+
+## Layout
+
+- `cache_lens/wrapper.py` — interception (`wrap`, `CacheLens`, `CacheLensClient`);
+  stores `List[CallCapture]` (request segments + response metrics) per session
+- `cache_lens/providers/{anthropic,gemini,openai}.py` — `extract()` (response →
+  `RawCallMetrics`) and `capture()` (request → `List[PromptSegment]`)
+- `cache_lens/analyzer.py` — longest-common-prefix layer classification, cost,
+  savings, ceiling, content-aware tips
+- `cache_lens/models.py` — dataclasses (`RawCallMetrics`, `PromptSegment`,
+  `CallCapture`, `LayerReport`, `SessionReport`)
+- `cache_lens/pricing.py` — price registry (USD per 1M tokens): bundled
+  `DEFAULT_PRICING` + runtime overrides via `CACHE_LENS_PRICING` env var or
+  `pricing=` arg (native or LiteLLM JSON, auto-detected, merged over defaults)
+- `cache_lens/outputs/{terminal,json_export,otel}.py` — sinks
+- `cache_lens/cli.py` — `cache-lens run` (scaffolded, not implemented)
+- `tests/` — pytest; fixtures are JSON, loaded via `tests/conftest.py`
+
+## Conventions
+
+- Never let instrumentation break the wrapped caller — both `capture()` and
+  `extract()` are wrapped in try/except in `wrapper._wrap_call`; capture failure
+  yields empty segments (analyzer degrades to no layer diagnosis, aggregates still
+  exact).
+- Provider SDKs and OTEL are optional deps; import them lazily inside functions,
+  not at module top level.
+- Pricing/cost is per-token internally (`pricing.rate`), table is per-1M.
+- Overall session aggregates (cost, savings, hit rate) are computed **exactly**
+  from response metrics; per-layer token splits are **estimated** by char-share
+  scaled to the real `input_tokens` (no tokenizer dep).
+- Cost model: actual = miss·input + creation·cache_write + read·cache_read +
+  output·output; cold = all input at full input rate.
+
+## Run tests
+
+```bash
+pip install -e .[dev] && pytest
+```

cachelens-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to cachelens
+
+Thanks for your interest in contributing!
+
+## Setup
+
+```bash
+git clone https://github.com/ChingEnLin/CacheLens.git
+cd CacheLens
+pip install -e .[dev]
+```
+
+## Running tests
+
+```bash
+pytest
+```
+
+All tests must pass before opening a PR.
+
+## Adding a provider
+
+1. Create `cache_lens/providers/<name>.py` with `extract(response) -> RawCallMetrics` and `capture(request, client) -> List[PromptSegment]`
+2. Register it in `cache_lens/wrapper.py` (`_detect_provider`)
+3. Add tests in `tests/providers/test_<name>.py`
+
+## Pull requests
+
+- Keep PRs focused — one feature or fix per PR
+- Include tests for new behavior
+- Update `CHANGELOG.md` under `[Unreleased]`
+
+## Reporting issues
+
+Open an issue at https://github.com/ChingEnLin/CacheLens/issues with:
+- Python version and OS
+- Provider SDK version
+- Minimal reproducer

cachelens-1.0.0/LICENSE

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

cachelens-1.0.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.1
+Name: cachelens
+Version: 1.0.0
+Summary: Non-invasive prompt cache instrumentation for LLM API apps
+Project-URL: Homepage, https://github.com/ChingEnLin/CacheLens
+Project-URL: Repository, https://github.com/ChingEnLin/CacheLens
+Project-URL: Issues, https://github.com/ChingEnLin/CacheLens/issues
+Author-email: Ching En Lin <chingenlin71@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,gemini,llm,observability,otel,prompt-caching
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: rich>=13.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: google-generativeai>=0.8; extra == 'all'
+Requires-Dist: openai>=1.40; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.8; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# cache-lens
+
+> Non-invasive prompt cache instrumentation for LLM API apps.
+> Wrap your client in one line. Get terminal reports, JSON exports, and OTEL metrics.
+
+Prompt caching gives steep discounts on cached tokens — but nothing tells you
+whether your app is actually getting cache hits, or why not. cache-lens wraps
+your Anthropic, Gemini, or OpenAI client and reports cache hit rate, cost,
+savings, and the money you're leaving on the table, broken down by prompt layer.
+
+See [SPEC.md](SPEC.md) for the full design.
+
+## Install
+
+```bash
+pip install cache-lens                # core + rich
+pip install cache-lens[anthropic]     # + Anthropic SDK
+pip install cache-lens[gemini]        # + Gemini SDK
+pip install cache-lens[openai]        # + OpenAI SDK
+pip install cache-lens[otel]          # + OpenTelemetry
+pip install cache-lens[all]           # everything
+```
+
+## Quickstart
+
+```python
+import anthropic
+from cache_lens import wrap
+
+client = wrap(anthropic.Anthropic())
+# ... use client exactly as before; report prints on exit
+```
+
+Explicit session boundary with exports:
+
+```python
+from cache_lens import CacheLens
+
+with CacheLens(client, json_export="report.json", otel=True) as session:
+    agent.run(...)        # your code, unchanged
+report = session.report
+```
+
+Suppress the terminal report in CI with `CACHE_LENS_TERMINAL=0`.
+
+## Custom pricing
+
+cache-lens ships a default price table, but you can override or extend it without
+forking — handy when a new model lands. User entries merge over the defaults:
+
+```python
+# in-memory dict (native format, USD per 1M tokens)
+wrap(client, pricing={"openai": {"gpt-5": {"input": 1.25, "output": 10.0, "cache_read": 0.125}}})
+
+# or a JSON file (native or LiteLLM model_prices_and_context_window.json format)
+wrap(client, pricing="pricing.json")
+```
+
+Or point at a file process-wide with `CACHE_LENS_PRICING=/path/to/pricing.json`.
+A bad pricing file falls back to defaults rather than breaking the run. See
+[SPEC.md §12](SPEC.md#12-pricing-table).
+
+## Status
+
+v1.0. Implemented: wrapper interception with **request capture**, provider
+extraction + capture (Anthropic + Gemini + OpenAI), **content-based layer
+classification** (longest-common-prefix → named system_prompt / context /
+conversation layers, cross-referenced against actual cache reads),
+terminal/JSON/OTEL outputs, overridable pricing, tests.
+Pending: `cache-lens run` CLI injection, streaming support, and cross-run
+static/semi-static separation (see [docs/architecture.md](docs/architecture.md)).
+
+## Develop
+
+```bash
+pip install -e .[dev]
+pytest
+```

cachelens-1.0.0/README.md

@@ -0,0 +1,78 @@
+# cache-lens
+
+> Non-invasive prompt cache instrumentation for LLM API apps.
+> Wrap your client in one line. Get terminal reports, JSON exports, and OTEL metrics.
+
+Prompt caching gives steep discounts on cached tokens — but nothing tells you
+whether your app is actually getting cache hits, or why not. cache-lens wraps
+your Anthropic, Gemini, or OpenAI client and reports cache hit rate, cost,
+savings, and the money you're leaving on the table, broken down by prompt layer.
+
+See [SPEC.md](SPEC.md) for the full design.
+
+## Install
+
+```bash
+pip install cache-lens                # core + rich
+pip install cache-lens[anthropic]     # + Anthropic SDK
+pip install cache-lens[gemini]        # + Gemini SDK
+pip install cache-lens[openai]        # + OpenAI SDK
+pip install cache-lens[otel]          # + OpenTelemetry
+pip install cache-lens[all]           # everything
+```
+
+## Quickstart
+
+```python
+import anthropic
+from cache_lens import wrap
+
+client = wrap(anthropic.Anthropic())
+# ... use client exactly as before; report prints on exit
+```
+
+Explicit session boundary with exports:
+
+```python
+from cache_lens import CacheLens
+
+with CacheLens(client, json_export="report.json", otel=True) as session:
+    agent.run(...)        # your code, unchanged
+report = session.report
+```
+
+Suppress the terminal report in CI with `CACHE_LENS_TERMINAL=0`.
+
+## Custom pricing
+
+cache-lens ships a default price table, but you can override or extend it without
+forking — handy when a new model lands. User entries merge over the defaults:
+
+```python
+# in-memory dict (native format, USD per 1M tokens)
+wrap(client, pricing={"openai": {"gpt-5": {"input": 1.25, "output": 10.0, "cache_read": 0.125}}})
+
+# or a JSON file (native or LiteLLM model_prices_and_context_window.json format)
+wrap(client, pricing="pricing.json")
+```
+
+Or point at a file process-wide with `CACHE_LENS_PRICING=/path/to/pricing.json`.
+A bad pricing file falls back to defaults rather than breaking the run. See
+[SPEC.md §12](SPEC.md#12-pricing-table).
+
+## Status
+
+v1.0. Implemented: wrapper interception with **request capture**, provider
+extraction + capture (Anthropic + Gemini + OpenAI), **content-based layer
+classification** (longest-common-prefix → named system_prompt / context /
+conversation layers, cross-referenced against actual cache reads),
+terminal/JSON/OTEL outputs, overridable pricing, tests.
+Pending: `cache-lens run` CLI injection, streaming support, and cross-run
+static/semi-static separation (see [docs/architecture.md](docs/architecture.md)).
+
+## Develop
+
+```bash
+pip install -e .[dev]
+pytest
+```

cachelens-1.0.0/cache_lens/__init__.py

@@ -0,0 +1,18 @@
+"""cache-lens — non-invasive prompt cache instrumentation for LLM API apps."""
+
+from __future__ import annotations
+
+from .models import LayerReport, RawCallMetrics, SessionReport
+from .wrapper import CacheLens, CacheLensClient, wrap
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "wrap",
+    "CacheLens",
+    "CacheLensClient",
+    "RawCallMetrics",
+    "LayerReport",
+    "SessionReport",
+    "__version__",
+]

cachelens-1.0.0/cache_lens/analyzer.py

@@ -0,0 +1,254 @@
+"""Aggregate intercepted calls into a SessionReport.
+
+Layer classification is content-based: the analyzer reconstructs each call's
+prompt as an ordered list of segments, finds the longest prefix that is byte
+-identical across every call in the session (the cacheable region), and names
+the layers within it. It then cross-references that content-derived prefix
+against the cache-read tokens the provider actually reported — surfacing which
+named layer is stable-but-uncached and what it costs.
+
+Token attribution per layer is estimated by character share, then scaled so each
+call's layer tokens sum to the *real* input_tokens the provider returned. Overall
+session aggregates (cost, savings, hit rate) are computed exactly from the
+response metrics; only the per-layer split is an estimate.
+
+Static vs semi-static is a single-run heuristic (a system-role prefix segment is
+static; other stable-prefix content is semi-static). True static/semi-static
+separation needs cross-run comparison, which a single in-memory session can't see.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Dict, List
+
+from . import pricing
+from .models import CallCapture, LayerReport, RawCallMetrics, SessionReport
+
+
+def analyze(captures: List[CallCapture], session_id: str = "") -> SessionReport:
+    session_id = session_id or str(uuid.uuid4())
+    now = datetime.now(timezone.utc)
+
+    if not captures:
+        return SessionReport(
+            session_id=session_id,
+            provider="",
+            model="",
+            started_at=now,
+            ended_at=now,
+            total_calls=0,
+            total_turns=0,
+        )
+
+    metrics = [c.metrics for c in captures]
+    provider = metrics[0].provider
+    model = metrics[0].model
+
+    total_input = sum(m.input_tokens for m in metrics)
+    total_output = sum(m.output_tokens for m in metrics)
+    total_cached = sum(m.cache_read_tokens for m in metrics)
+    total_miss = sum(m.cache_miss_tokens for m in metrics)
+
+    actual_cost = _actual_cost(metrics)
+    cold_cost = _cold_cost(metrics)
+    savings = max(cold_cost - actual_cost, 0.0)
+    overall_hit_rate = (total_cached / total_input) if total_input else 0.0
+
+    layers, prefix_len, prefix_per_call_tokens = _classify_layers(captures, provider, model)
+
+    input_rate = pricing.rate(provider, model, "input")
+    read_rate = pricing.rate(provider, model, "cache_read")
+    theoretical_max = max(
+        prefix_per_call_tokens * (len(captures) - 1) * (input_rate - read_rate), 0.0
+    )
+
+    report = SessionReport(
+        session_id=session_id,
+        provider=provider,
+        model=model,
+        started_at=metrics[0].timestamp,
+        ended_at=metrics[-1].timestamp,
+        total_calls=len(metrics),
+        total_turns=len(metrics),
+        layers=layers,
+        total_input_tokens=total_input,
+        total_output_tokens=total_output,
+        total_cached_tokens=total_cached,
+        overall_hit_rate=overall_hit_rate,
+        actual_cost_usd=round(actual_cost, 6),
+        cold_cost_usd=round(cold_cost, 6),
+        total_savings_usd=round(savings, 6),
+        theoretical_max_savings_usd=round(theoretical_max, 6),
+    )
+    report.tips = _build_tips(report, captures, layers, prefix_len, total_miss)
+    return report
+
+
+def _actual_cost(metrics: List[RawCallMetrics]) -> float:
+    cost = 0.0
+    for m in metrics:
+        cost += m.cache_miss_tokens * pricing.rate(m.provider, m.model, "input")
+        cost += m.cache_creation_tokens * pricing.rate(m.provider, m.model, "cache_write")
+        cost += m.cache_read_tokens * pricing.rate(m.provider, m.model, "cache_read")
+        cost += m.output_tokens * pricing.rate(m.provider, m.model, "output")
+    return cost
+
+
+def _cold_cost(metrics: List[RawCallMetrics]) -> float:
+    """Cost if every input token were billed at the full input rate."""
+    cost = 0.0
+    for m in metrics:
+        cost += m.input_tokens * pricing.rate(m.provider, m.model, "input")
+        cost += m.output_tokens * pricing.rate(m.provider, m.model, "output")
+    return cost
+
+
+def _common_prefix_len(captures: List[CallCapture]) -> int:
+    """Number of leading segments identical (role + text) across all calls."""
+    seq_lists = [c.segments for c in captures]
+    if not seq_lists or any(not s for s in seq_lists):
+        return 0
+    shortest = min(len(s) for s in seq_lists)
+    n = 0
+    for i in range(shortest):
+        first = seq_lists[0][i]
+        if all(
+            s[i].role == first.role and s[i].text == first.text for s in seq_lists
+        ):
+            n += 1
+        else:
+            break
+    return n
+
+
+def _classify_layers(captures: List[CallCapture], provider: str, model: str):
+    """Return (layers, prefix_len, prefix_tokens_per_call)."""
+    prefix_len = _common_prefix_len(captures)
+
+    sys_tok = ctx_tok = conv_tok = 0.0
+    for cap in captures:
+        segs = cap.segments
+        total_chars = sum(len(s.text) for s in segs)
+        if total_chars <= 0:
+            # No capturable content — attribute everything to the dynamic layer.
+            conv_tok += cap.metrics.input_tokens
+            continue
+        for i, seg in enumerate(segs):
+            tok = cap.metrics.input_tokens * (len(seg.text) / total_chars)
+            if i < prefix_len:
+                if seg.role == "system":
+                    sys_tok += tok
+                else:
+                    ctx_tok += tok
+            else:
+                conv_tok += tok
+
+    # The stable prefix is sent on every call; cache reads (prefix-based) are
+    # attributed to it, split across system_prompt and context by token share.
+    prefix_tok = sys_tok + ctx_tok
+    cached_total = sum(c.metrics.cache_read_tokens for c in captures)
+    cached_in_prefix = min(cached_total, prefix_tok)
+    sys_cached = cached_in_prefix * (sys_tok / prefix_tok) if prefix_tok else 0.0
+    ctx_cached = cached_in_prefix - sys_cached
+
+    input_rate = pricing.rate(provider, model, "input")
+    read_rate = pricing.rate(provider, model, "cache_read")
+
+    def make(name: str, layer_type: str, total: float, cached: float) -> LayerReport:
+        cached = min(cached, total)
+        cold = total * input_rate
+        actual = cached * read_rate + (total - cached) * input_rate
+        return LayerReport(
+            name=name,
+            layer_type=layer_type,
+            total_tokens=int(round(total)),
+            cached_tokens=int(round(cached)),
+            hit_rate=(cached / total) if total else 0.0,
+            actual_cost_usd=round(actual, 6),
+            cold_cost_usd=round(cold, 6),
+            savings_usd=round(max(cold - actual, 0.0), 6),
+        )
+
+    layers: List[LayerReport] = []
+    if sys_tok > 0:
+        layers.append(make("system_prompt", "static", sys_tok, sys_cached))
+    if ctx_tok > 0:
+        layers.append(make("context", "semi_static", ctx_tok, ctx_cached))
+    if conv_tok > 0:
+        layers.append(make("conversation", "dynamic", conv_tok, 0.0))
+
+    prefix_tokens_per_call = _prefix_tokens_per_call(captures, prefix_len)
+    return layers, prefix_len, prefix_tokens_per_call
+
+
+def _prefix_tokens_per_call(captures: List[CallCapture], prefix_len: int) -> float:
+    """Estimated token size of the stable prefix as sent on a single call."""
+    if not captures or prefix_len <= 0:
+        return 0.0
+    cap = captures[0]
+    total_chars = sum(len(s.text) for s in cap.segments)
+    if total_chars <= 0:
+        return 0.0
+    return sum(
+        cap.metrics.input_tokens * (len(cap.segments[i].text) / total_chars)
+        for i in range(prefix_len)
+    )
+
+
+def _build_tips(
+    report: SessionReport,
+    captures: List[CallCapture],
+    layers: List[LayerReport],
+    prefix_len: int,
+    total_miss: int,
+) -> List[str]:
+    tips: List[str] = []
+    by_name: Dict[str, LayerReport] = {layer.name: layer for layer in layers}
+    multi_call = report.total_calls > 1
+    have_content = any(c.segments for c in captures)
+
+    if report.provider == "gemini" and report.total_cached_tokens == 0:
+        tips.append(
+            "No Gemini context cache detected — create a cacheContent object for "
+            "stable context (system prompt, schema) to enable cache reads."
+        )
+
+    context = by_name.get("context")
+    if context and multi_call and context.hit_rate < 0.5:
+        tips.append(
+            f"context layer (~{context.total_tokens:,} tokens) is identical across "
+            f"all {report.total_calls} calls but only {context.hit_rate:.0%} cached — "
+            f"move it behind a cache_control breakpoint before the conversation "
+            f"history (est. ${report.theoretical_max_savings_usd:.3f} recoverable)."
+        )
+
+    system = by_name.get("system_prompt")
+    if system and multi_call and system.hit_rate < 0.9:
+        tips.append(
+            f"system_prompt cache hit rate is {system.hit_rate:.0%} — check the "
+            "prefix isn't being prepended with dynamic content that breaks the cache."
+        )
+
+    if have_content and multi_call and prefix_len == 0:
+        tips.append(
+            "No stable prompt prefix detected across calls — content differs every "
+            "turn, so prefix caching cannot help. Ensure your system prompt and "
+            "static context are byte-identical on each call (and placed first)."
+        )
+
+    if captures and captures[0].metrics.cache_read_tokens == 0:
+        tips.append(
+            "First call always misses the cache (expected). Pre-warm with a dummy "
+            "call before the loop starts to eliminate the cold miss."
+        )
+
+    if report.total_input_tokens and total_miss / report.total_input_tokens > 0.3:
+        tips.append(
+            f"{total_miss / report.total_input_tokens:.0%} of input tokens are "
+            "uncached and re-sent each turn — consider summarising tool results "
+            "instead of appending them verbatim."
+        )
+
+    return tips

cachelens-1.0.0/cache_lens/cli.py

@@ -0,0 +1,43 @@
+"""cache-lens CLI: `cache-lens run <command>` for zero-code instrumentation."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        _print_usage()
+        return 0
+
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "run":
+        return _run(rest)
+
+    sys.stderr.write(f"cache-lens: unknown command '{cmd}'\n")
+    _print_usage()
+    return 2
+
+
+def _run(command: list) -> int:
+    if not command:
+        sys.stderr.write("cache-lens run: no command given\n")
+        return 2
+    # v1.0: sitecustomize injection that patches the SDK at import time and
+    # registers an atexit report. Implementation tracked in docs/architecture.md.
+    raise NotImplementedError(
+        "cache-lens run is scaffolded; sitecustomize injection not yet implemented"
+    )
+
+
+def _print_usage() -> None:
+    sys.stdout.write(
+        "cache-lens — prompt cache instrumentation\n\n"
+        "Usage:\n"
+        "  cache-lens run <command> [args...]   Instrument a subprocess\n"
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())