ctx-slim 0.1.0__tar.gz

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

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push: { branches: [master] }
+  pull_request:
+  schedule:
+    # Rates go stale at 90 days; catch it on a Monday, not in a launch thread.
+    - cron: "0 6 * * 1"
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python }}" }
+      - run: pip install -e ".[dev]"
+      - run: pytest -q --cov=context_slim --cov-report=term-missing
+      - name: performance (uninstrumented)
+        # The timing assertions skip themselves under a coverage tracer, which
+        # would otherwise measure the tracer rather than the code. Run them
+        # once more with coverage off so the sub-5ms budget is still enforced.
+        # Linux only: hosted macOS/Windows runners are too noisy for a
+        # wall-clock budget, and a flaky perf gate gets ignored, not fixed.
+        run: pytest -q --no-cov tests/test_performance.py
+        if: matrix.os == 'ubuntu-latest'
+      - name: no runtime dependencies
+        run: |
+          pip install pipdeptree
+          pipdeptree -p context-slim --warn silence | tee /tmp/deps.txt
+          test "$(grep -c '^  ' /tmp/deps.txt || true)" -eq 0
+        shell: bash
+        if: matrix.os == 'ubuntu-latest'
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy --strict src/context_slim

ctx_slim-0.1.0/.github/workflows/publish-test.yml

@@ -0,0 +1,20 @@
+name: publish-test
+
+on:
+  workflow_dispatch:  # manual only - a test upload should never fire by accident
+
+jobs:
+  testpypi:
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write  # OIDC token for trusted publishing - no API token or secret needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

ctx_slim-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for trusted publishing - no API token or secret needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

ctx_slim-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+results/.killgate_progress.json

ctx_slim-0.1.0/LICENSE

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

ctx_slim-0.1.0/METHODS.md

@@ -0,0 +1,70 @@
+# Methods and threats to validity
+
+Four runs. Three produced confident headline numbers that were artifacts, each
+pointing the opposite way to the one before it. Run 1 said pruning saves 29.6%;
+run 3 said it costs 41.6% more. Same code, same provider, same week.
+
+That instability is itself the most transferable finding here, so it is
+documented rather than quietly dropped.
+
+## Confound 1 — cross-arm cache sharing (runs 1-2, invalidated)
+
+Provider prompt caches are content-addressed and scoped to the **account**, not
+to the process or the experiment. All arms were built from one identical prefix
+and executed in blocks, so whichever arm ran first paid the cache write and
+every later arm free-rode on it. Execution order was confounded with treatment.
+
+Caught by a variance check, not by inspection: sigma was roughly half the mean;
+every condition declined monotonically across repeats; and different conditions
+returned bit-identical costs ($0.003214 in three arms), which only happens when
+arms are reading the same cache entries.
+
+**Fix.** A unique high-entropy salt at the head of each arm's system prompt, so
+each of the 15 arms occupies its own cache namespace and pays its own way. Arms
+shuffled under a fixed seed so position cannot correlate with treatment.
+
+## Confound 2 — non-monotonic pruning policy (run 3, half invalidated)
+
+`tail_first` came out worst, contradicting prefix-cache theory. Replaying the
+stub sets showed the policy recomputed "newest half of candidates" from scratch
+each turn, so previously-stubbed messages fell out of that half and reverted to
+full content - a deep prefix change on every turn.
+
+Real pruners never un-clear. `clear_tool_uses_20250919` and LangChain's
+truncation are both monotonic.
+
+**Fix.** A persistent cleared-set that only grows.
+
+## Confound 3 — fraction-based clearing erases the variable (found pre-run-4)
+
+Accumulating a fixed fraction converges on clearing every candidate, at which
+point both orderings produce the same set and the independent variable
+disappears (8585 vs 8566 tokens - indistinguishable).
+
+**Fix.** Budget-triggered clearing: clear the minimum needed to get back under a
+token threshold, which is what `clear_tool_uses_20250919` does.
+
+## Run 4 design (the valid one)
+
+Salted namespaces, shuffled arms, monotonic budget-triggered policies, n=5,
+bootstrap 95% CIs on arm-level means. Predictions were pre-registered before the
+data landed: tail-first's hit rate would rise from 69.1%, tail-first would be
+cheaper than oldest-first, and no-prune would stay cheapest. All three held.
+
+## Known limitations
+
+- 8k prefixes, 20 turns, synthetic loops. Larger regimes untested.
+- One model, one provider, one account, one region.
+- `no_prune` sends more tokens by construction; that it still wins on cost is
+  the point, but it is not a like-for-like token comparison.
+- A cache-hit dip at turn 14 appears in all three conditions including
+  `no_prune`, so it is not caused by pruning. Unexplained.
+- Provider cache internals are opaque. We observe billing, not the cache.
+- n=5 arms: adequate for the observed effect sizes, thin for subtle ones.
+
+## A note for anyone benchmarking prompt caches
+
+Prompt-cache experiments are **stateful across arms** in a way ordinary A/B
+benchmarks are not. The cache is a hidden channel between conditions. Any
+comparison that does not explicitly namespace its cache keys is measuring
+execution order as much as treatment.

ctx_slim-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: ctx-slim
+Version: 0.1.0
+Summary: Prune your LLM agent's context without destroying your prompt cache.
+Project-URL: Homepage, https://github.com/Ramtin2000/context-slim
+Project-URL: Repository, https://github.com/Ramtin2000/context-slim
+Project-URL: Issues, https://github.com/Ramtin2000/context-slim/issues
+Author: Ramtin
+License: MIT
+License-File: LICENSE
+Keywords: agents,context-engineering,finops,llm,prompt-caching
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: bench
+Requires-Dist: openai>=1.40; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# context-slim
+
+**Pruning your LLM agent's context can cost more than leaving it alone.**
+
+Measured against a live API, n=5 arms per condition, bootstrap 95% CIs:
+
+| strategy | tokens sent | cache hit | cost/arm | vs no pruning |
+|---|---|---|---|---|
+| don't prune | 928,400 | **92.2%** | **$0.007053** | — |
+| prune oldest-first | 735,790 | 75.5% | $0.011239 | **+59.4%** |
+| prune newest-first | 735,770 | 81.0% | $0.009376 | **+32.9%** |
+
+**20.7% fewer tokens. 33–59% more money.** All three differences significant.
+
+Prompt caches are *prefix* caches, so an un-pruned loop is append-only — every
+turn extends the last and the whole prompt is reusable. Pruning breaks that, and
+the re-write costs more than the tokens saved.
+
+Where you cut still matters: newest-first is **16.6% cheaper** than oldest-first
+at identical token counts (a 20-token difference). Anthropic's context-editing
+API clears oldest-first by default.
+
+```
+cache hit rate by turn
+                t2    t5    t8   t11   t14   t17   t20
+don't prune    95%   96%   96%   96%   77%   97%   97%
+oldest-first   95%   96%   63%   77%   76%   77%   75%
+newest-first   95%   96%   93%   91%   76%   77%   60%
+```
+
+> **Caveat this properly.** 8k prefixes, 20 turns, synthetic loops, one model
+> (`gpt-5.6-luna`), one account. Larger contexts over longer horizons are
+> untested and may behave differently. Three earlier revisions of this
+> experiment produced confident numbers that were artifacts — see
+> [`METHODS.md`](METHODS.md) for what went wrong and how it was caught.
+
+Reproduce: `python -m bench.killgate --repeats 5` (~$0.14). Raw usage blocks in
+[`bench/results/`](bench/results/).
+
+## Why the dedupe is built the way it is
+
+The textbook approach to block deduplication is a byte-level rolling hash with
+content-defined boundaries. In pure Python that is one interpreter iteration per
+byte, and it does not fit a sub-5ms budget. `str.split` plus `hashlib.blake2b`
+does the same job at block granularity with both halves running in C.
+
+Measured on ~93 KB (`python -m bench.bench_dedupe`):
+
+| | time |
+|---|---|
+| rejected: 64-byte rolling hash (per-byte Python loop) | 25.26 ms |
+| shipped: `str.split` + `blake2b` (per-block loop) | **0.24 ms** |
+| shipped: full `dedupe_blocks` pass | 0.54 ms |
+| shipped: `collapse_whitespace` | 1.06 ms |
+
+**104× on the hashing step.** The rejected implementation is kept in
+`bench/bench_dedupe.py` so the comparison is measured rather than asserted.
+
+## The cost model is checkable
+
+Most token accounting asks you to trust it. This one predicts how much of a
+request the API will report as cached, *before* the call, then diffs against
+`usage.prompt_tokens_details`.
+
+Measured over 24 live requests (`python -m bench.validate`, ~$0.01):
+
+| | raw | calibrated |
+|---|---|---|
+| prompt-token error (median) | 26.11% | **0.64%** |
+| cached-token error (median) | 25.80% | **0.84%** |
+
+The raw 26% was a single wrong constant, not a broken model — the
+predicted/actual ratio had a spread of 0.9%, so dividing it out left a max
+residual of 1.78%. The estimator is calibrated by that constant in
+`cache/prefix.py`, with both caveats stated there: it is fit to one tokenizer
+family, and it sits inside the pruning policy's own budget, so it cannot be
+recalibrated and replayed against an old run.
+
+No dollar figure in this repo comes from the estimator. Those all read the
+provider's usage counters.
+
+## Install
+
+> **Not on PyPI yet.** Install from source until v0.1.0 ships:
+
+```bash
+pip install git+https://github.com/Ramtin2000/context-slim
+```
+
+Zero runtime dependencies. No model, no GPU, no network. Python 3.9+.
+
+## Use
+
+```python
+from context_slim import doctor, plan, apply
+
+# 1. Find cache pathologies that cost money silently.
+for d in doctor(messages, model="openai/gpt-5.6-luna"):
+    print(d.code, d.message)
+
+# 2. Decide what is worth pruning. Pure — no I/O, no mutation.
+p = plan(messages, model="openai/gpt-5.6-luna", horizon=30)
+for v in p.verdicts:
+    print(v.decision.value, v.reason)
+
+# 3. Execute only the approved edits.
+messages, report = apply(messages, p)
+print(report)
+```
+
+`plan()` and `apply()` are separate so that **"don't prune" is an ordinary
+outcome you can inspect**, not an exception or a silent no-op:
+
+```
+REFUSE  msg 2   structurally unprofitable: W/S = 41.2 means 461.3 turns to pay
+                back $0.000412, against a horizon of 20. Prune closer to the tail.
+PLAN    msg 14  pays back after 4.1 turns (horizon 20); costs $0.000082 now,
+                saves $0.000020/turn, net $0.000318 at horizon
+```
+
+## The `doctor` check
+
+Two pathologies cost money with no pruning involved at all:
+
+- **`lookback-overrun`** — Anthropic checks at most 20 positions behind a cache
+  breakpoint. Grow past that and the hit is missed silently. No error. Just a bill.
+- **`no-breakpoint`** — Anthropic caching is opt-in. Without a breakpoint,
+  nothing is cached and every turn pays full price.
+
+`context-slim doctor conversation.json` exits non-zero on an error-severity
+finding, so it can sit in CI.
+
+## What this is NOT
+
+- ❌ Not a summarizer, embedder, or tokenizer. No model is ever loaded.
+- ❌ Not a competitor to Anthropic's context editing or LangChain's compaction —
+  a **cost-aware controller** that decides whether and where to invoke them.
+- ❌ Not "fewer tokens at any cost." Sometimes the answer is *don't*, and this
+  is the only tool that will tell you so.
+
+## When NOT to use it
+
+Short loops, uncached workloads, and any prefix below the model's cache minimum
+(512 tokens on Claude Opus 5, 1024 on GPT-5.6). `doctor` reports all three.
+
+## Repository layout
+
+```
+src/context_slim/
+  core.py       CacheAlignedContext — pins the Anchor Zone, orchestrates plan/apply
+  expiry.py     candidate generation, tail-first ordering, ATOMIC_PURGE / TOMBSTONE
+  pruner.py     block dedupe and whitespace collapse (Layer 4 text ops)
+  json_ast.py   schema-preserving trim, and dependency-free JSON minification
+  schemas.py    frozen dataclasses — Money is exact-integer, never float
+  audit.py      CLI: `context-slim doctor|plan|apply|simulate`
+  policy.py     the break-even decision engine (Law 1 lives here)
+  ledger.py     defers unprofitable prunes until the cache breaks anyway
+  cache/        the cost model, rate tables, and prefix diagnostics
+  providers/    OpenAI / Anthropic wire-shape adapters
+bench/          the real benchmark: live API calls, salted cache namespaces,
+                bootstrap CIs. Costs real money to run — see METHODS.md for
+                what it took to make it trustworthy.
+benchmarks/     an offline, zero-cost illustration of the same idea, using
+                the same cost primitives against a synthetic trace. Useful to
+                see the shape of the argument before spending anything
+                confirming it — not a substitute for bench/.
+```
+
+`CacheAlignedContext` (`core.py`) is an optional stateful wrapper around the
+same four functions exported at the package root — it computes the Anchor
+Zone boundary once and threads it through every call, so a candidate can
+never be proposed inside the immutable prefix regardless of preset:
+
+```python
+from context_slim import CacheAlignedContext
+
+ctx = CacheAlignedContext(messages, model="openai/gpt-5.6-luna", preset="balanced")
+ctx.anchor              # the immutable prefix — system prompt, tools, Turn 1
+ctx.compaction_zone      # everything eligible for pruning
+messages, report = ctx.apply(ctx.plan(horizon=30))
+```
+
+## Status
+
+Pre-release, built in public over 14 days. The cost model is validated against
+providers' own `cached_tokens` counters — see `bench/killgate.py`.
+
+## License
+
+MIT

ctx_slim-0.1.0/README.md

@@ -0,0 +1,190 @@
+# context-slim
+
+**Pruning your LLM agent's context can cost more than leaving it alone.**
+
+Measured against a live API, n=5 arms per condition, bootstrap 95% CIs:
+
+| strategy | tokens sent | cache hit | cost/arm | vs no pruning |
+|---|---|---|---|---|
+| don't prune | 928,400 | **92.2%** | **$0.007053** | — |
+| prune oldest-first | 735,790 | 75.5% | $0.011239 | **+59.4%** |
+| prune newest-first | 735,770 | 81.0% | $0.009376 | **+32.9%** |
+
+**20.7% fewer tokens. 33–59% more money.** All three differences significant.
+
+Prompt caches are *prefix* caches, so an un-pruned loop is append-only — every
+turn extends the last and the whole prompt is reusable. Pruning breaks that, and
+the re-write costs more than the tokens saved.
+
+Where you cut still matters: newest-first is **16.6% cheaper** than oldest-first
+at identical token counts (a 20-token difference). Anthropic's context-editing
+API clears oldest-first by default.
+
+```
+cache hit rate by turn
+                t2    t5    t8   t11   t14   t17   t20
+don't prune    95%   96%   96%   96%   77%   97%   97%
+oldest-first   95%   96%   63%   77%   76%   77%   75%
+newest-first   95%   96%   93%   91%   76%   77%   60%
+```
+
+> **Caveat this properly.** 8k prefixes, 20 turns, synthetic loops, one model
+> (`gpt-5.6-luna`), one account. Larger contexts over longer horizons are
+> untested and may behave differently. Three earlier revisions of this
+> experiment produced confident numbers that were artifacts — see
+> [`METHODS.md`](METHODS.md) for what went wrong and how it was caught.
+
+Reproduce: `python -m bench.killgate --repeats 5` (~$0.14). Raw usage blocks in
+[`bench/results/`](bench/results/).
+
+## Why the dedupe is built the way it is
+
+The textbook approach to block deduplication is a byte-level rolling hash with
+content-defined boundaries. In pure Python that is one interpreter iteration per
+byte, and it does not fit a sub-5ms budget. `str.split` plus `hashlib.blake2b`
+does the same job at block granularity with both halves running in C.
+
+Measured on ~93 KB (`python -m bench.bench_dedupe`):
+
+| | time |
+|---|---|
+| rejected: 64-byte rolling hash (per-byte Python loop) | 25.26 ms |
+| shipped: `str.split` + `blake2b` (per-block loop) | **0.24 ms** |
+| shipped: full `dedupe_blocks` pass | 0.54 ms |
+| shipped: `collapse_whitespace` | 1.06 ms |
+
+**104× on the hashing step.** The rejected implementation is kept in
+`bench/bench_dedupe.py` so the comparison is measured rather than asserted.
+
+## The cost model is checkable
+
+Most token accounting asks you to trust it. This one predicts how much of a
+request the API will report as cached, *before* the call, then diffs against
+`usage.prompt_tokens_details`.
+
+Measured over 24 live requests (`python -m bench.validate`, ~$0.01):
+
+| | raw | calibrated |
+|---|---|---|
+| prompt-token error (median) | 26.11% | **0.64%** |
+| cached-token error (median) | 25.80% | **0.84%** |
+
+The raw 26% was a single wrong constant, not a broken model — the
+predicted/actual ratio had a spread of 0.9%, so dividing it out left a max
+residual of 1.78%. The estimator is calibrated by that constant in
+`cache/prefix.py`, with both caveats stated there: it is fit to one tokenizer
+family, and it sits inside the pruning policy's own budget, so it cannot be
+recalibrated and replayed against an old run.
+
+No dollar figure in this repo comes from the estimator. Those all read the
+provider's usage counters.
+
+## Install
+
+> **Not on PyPI yet.** Install from source until v0.1.0 ships:
+
+```bash
+pip install git+https://github.com/Ramtin2000/context-slim
+```
+
+Zero runtime dependencies. No model, no GPU, no network. Python 3.9+.
+
+## Use
+
+```python
+from context_slim import doctor, plan, apply
+
+# 1. Find cache pathologies that cost money silently.
+for d in doctor(messages, model="openai/gpt-5.6-luna"):
+    print(d.code, d.message)
+
+# 2. Decide what is worth pruning. Pure — no I/O, no mutation.
+p = plan(messages, model="openai/gpt-5.6-luna", horizon=30)
+for v in p.verdicts:
+    print(v.decision.value, v.reason)
+
+# 3. Execute only the approved edits.
+messages, report = apply(messages, p)
+print(report)
+```
+
+`plan()` and `apply()` are separate so that **"don't prune" is an ordinary
+outcome you can inspect**, not an exception or a silent no-op:
+
+```
+REFUSE  msg 2   structurally unprofitable: W/S = 41.2 means 461.3 turns to pay
+                back $0.000412, against a horizon of 20. Prune closer to the tail.
+PLAN    msg 14  pays back after 4.1 turns (horizon 20); costs $0.000082 now,
+                saves $0.000020/turn, net $0.000318 at horizon
+```
+
+## The `doctor` check
+
+Two pathologies cost money with no pruning involved at all:
+
+- **`lookback-overrun`** — Anthropic checks at most 20 positions behind a cache
+  breakpoint. Grow past that and the hit is missed silently. No error. Just a bill.
+- **`no-breakpoint`** — Anthropic caching is opt-in. Without a breakpoint,
+  nothing is cached and every turn pays full price.
+
+`context-slim doctor conversation.json` exits non-zero on an error-severity
+finding, so it can sit in CI.
+
+## What this is NOT
+
+- ❌ Not a summarizer, embedder, or tokenizer. No model is ever loaded.
+- ❌ Not a competitor to Anthropic's context editing or LangChain's compaction —
+  a **cost-aware controller** that decides whether and where to invoke them.
+- ❌ Not "fewer tokens at any cost." Sometimes the answer is *don't*, and this
+  is the only tool that will tell you so.
+
+## When NOT to use it
+
+Short loops, uncached workloads, and any prefix below the model's cache minimum
+(512 tokens on Claude Opus 5, 1024 on GPT-5.6). `doctor` reports all three.
+
+## Repository layout
+
+```
+src/context_slim/
+  core.py       CacheAlignedContext — pins the Anchor Zone, orchestrates plan/apply
+  expiry.py     candidate generation, tail-first ordering, ATOMIC_PURGE / TOMBSTONE
+  pruner.py     block dedupe and whitespace collapse (Layer 4 text ops)
+  json_ast.py   schema-preserving trim, and dependency-free JSON minification
+  schemas.py    frozen dataclasses — Money is exact-integer, never float
+  audit.py      CLI: `context-slim doctor|plan|apply|simulate`
+  policy.py     the break-even decision engine (Law 1 lives here)
+  ledger.py     defers unprofitable prunes until the cache breaks anyway
+  cache/        the cost model, rate tables, and prefix diagnostics
+  providers/    OpenAI / Anthropic wire-shape adapters
+bench/          the real benchmark: live API calls, salted cache namespaces,
+                bootstrap CIs. Costs real money to run — see METHODS.md for
+                what it took to make it trustworthy.
+benchmarks/     an offline, zero-cost illustration of the same idea, using
+                the same cost primitives against a synthetic trace. Useful to
+                see the shape of the argument before spending anything
+                confirming it — not a substitute for bench/.
+```
+
+`CacheAlignedContext` (`core.py`) is an optional stateful wrapper around the
+same four functions exported at the package root — it computes the Anchor
+Zone boundary once and threads it through every call, so a candidate can
+never be proposed inside the immutable prefix regardless of preset:
+
+```python
+from context_slim import CacheAlignedContext
+
+ctx = CacheAlignedContext(messages, model="openai/gpt-5.6-luna", preset="balanced")
+ctx.anchor              # the immutable prefix — system prompt, tools, Turn 1
+ctx.compaction_zone      # everything eligible for pruning
+messages, report = ctx.apply(ctx.plan(horizon=30))
+```
+
+## Status
+
+Pre-release, built in public over 14 days. The cost model is validated against
+providers' own `cached_tokens` counters — see `bench/killgate.py`.
+
+## License
+
+MIT