prompt-cache-fit 0.1.0__tar.gz

prompt_cache_fit-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+*.log
+.DS_Store

prompt_cache_fit-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: prompt-cache-fit
+Version: 0.1.0
+Summary: Reorder LLM prompt blocks from least- to most-volatile so provider prefix caches stay hot, and measure whether it actually worked.
+Project-URL: Homepage, https://github.com/pjdurden/prompt-cache-fit
+Project-URL: Source, https://github.com/pjdurden/prompt-cache-fit
+Author: Prajjwal Chittori
+License: MIT
+Keywords: anthropic,llm,openai,prefix-cache,prompt-caching,prompt-engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# prompt-cache-fit
+
+Reorder LLM prompt blocks from least- to most-volatile so provider prefix caches stay hot, and measure whether it actually worked. This is the Python port of the JavaScript package of the same name.
+
+## The problem
+
+Anthropic, OpenAI, xAI and DeepSeek all cache prompt *prefixes*. The cache is only reusable up to the first byte that differs between two requests. Teams that put a timestamp, a request id, or "today's date" near the top of the system prompt throw away the cache for every token below it, even though the rest of the prompt (the system message, the tool schema, the RAG chunks) did not actually change. The published advice is "order your prompt from least-variable to most-variable", but every team hand-rolls that ordering, and almost nobody measures whether the reordering actually raised the hit rate. This package does the reordering and the measurement, nothing else: no tokenizer, no provider SDK, no network calls.
+
+## Install
+
+```
+pip install prompt-cache-fit
+```
+
+## Usage
+
+```python
+from prompt_cache_fit import fit, hit_rate
+
+static_block = {"text": "You are a helpful coding assistant.", "volatility": "static"}
+tools_block = {"text": "Tools: search_docs(query), run_tests()", "volatility": "shared"}
+session_block = {
+    "text": "User profile: senior backend engineer, prefers concise answers.",
+    "volatility": "session",
+}
+timestamp1 = {"text": "Timestamp: 2026-09-04T10:00:00Z", "volatility": "turn"}
+question1 = {"text": "Turn: how do I retry a failed HTTP request?", "volatility": "turn"}
+timestamp2 = {"text": "Timestamp: 2026-09-04T10:05:00Z", "volatility": "turn"}
+question2 = {"text": "Turn: how do I cancel an in-flight fetch?", "volatility": "turn"}
+
+# Hand-rolled: the volatile timestamp sits in the middle of the prompt.
+hand_rolled1 = "\n\n".join(
+    b["text"] for b in [static_block, timestamp1, tools_block, session_block, question1]
+)
+hand_rolled2 = "\n\n".join(
+    b["text"] for b in [static_block, timestamp2, tools_block, session_block, question2]
+)
+
+# fit(): volatile blocks (rank 'turn') sort to the end automatically.
+fitted1 = fit([static_block, timestamp1, tools_block, session_block, question1])
+fitted2 = fit([static_block, timestamp2, tools_block, session_block, question2])
+
+print(hit_rate([hand_rolled1, hand_rolled2]).mean)  # 0.2916666666666667
+print(hit_rate([fitted1.text, fitted2.text]).mean)  # 0.7777777777777778
+```
+
+Moving the two `turn`-tier blocks to the end of the prompt takes the measured prefix hit rate on the second request from about 29% to about 78%, because the shared system prompt, tool schema and session block now form one unbroken prefix instead of being interrupted by the timestamp.
+
+## API
+
+### `fit(blocks, *, separator="\n\n") -> FitResult`
+
+- `blocks: List[Dict[str, Any]]`, each dict with a required `text: str` key and optional `volatility: str`, `id`, `pin: bool` keys. Plain dicts are accepted; no class is required.
+- `volatility` is one of `"static" | "shared" | "session" | "turn"`, ranked in that order (`static` sorts first, `turn` sorts last). Missing or unrecognized values default to `"turn"`; unknown strings never raise.
+- `pin=True` on a block keeps that block at its original index. Every other block is sorted around it.
+- The sort is stable: two blocks with the same rank keep their original relative order.
+- `separator` (keyword-only, default `"\n\n"`): the string joined between rendered blocks.
+- Returns a frozen `FitResult` dataclass:
+  - `blocks`: the input blocks, reordered.
+  - `text`: the reordered blocks joined with `separator`.
+  - `moved`: count of blocks whose index differs from the input.
+  - `stable_prefix_chars`: characters from the start of `text` through the end of the last block ranked below `turn`, including the separator that follows it if another block comes after. `0` if every block is `turn`.
+
+### `shared_prefix(a, b) -> int`
+
+Number of shared leading characters between two strings. `shared_prefix("abc", "abd")` is `2`. Returns `0` for empty strings.
+
+### `hit_rate(prompts) -> HitRateReport`
+
+`prompts` is a list of already-rendered prompt strings, in send order. For each prompt after the first, computes `shared_prefix(prompts[i-1], prompts[i]) / len(prompts[i])`. Returns a frozen `HitRateReport` dataclass:
+
+- `per_request`: one fraction (`0..1`) per request after the first.
+- `mean`: mean of `per_request`, `0` if fewer than 2 prompts were given.
+- `cached_chars`: sum of shared prefix lengths across all requests after the first.
+- `total_chars`: sum of `len(prompts[i])` for `i >= 1`.
+
+An empty prompt string contributes `0` instead of dividing by zero.
+
+### `VOLATILITY`
+
+`{"static": 0, "shared": 1, "session": 2, "turn": 3}`, exported as a plain dict so forkers can add their own tiers or change the ranks.
+
+## How it works
+
+`fit()` is a stable sort by volatility rank plus a reinsertion pass for pinned blocks; `hit_rate()` is a character-by-character common-prefix scan. That is the whole library. It does not know how any provider actually tokenizes or chunks its cache, so `stable_prefix_chars` and `hit_rate` are character-level proxies, not a guarantee of a provider-side cache hit: real caches key on token boundaries and have their own minimum prefix length and TTL. This package also does not inject provider-specific cache markers (Anthropic's `cache_control`, OpenAI's automatic prefix caching, etc.) into the output; ordering the blocks correctly is a precondition for those markers to help, but adding the markers themselves is left to the caller, since the marker format is provider-specific and out of scope here.
+
+The JavaScript version of this package lives at the repository root: https://github.com/pjdurden/prompt-cache-fit
+
+## License
+
+MIT

prompt_cache_fit-0.1.0/README.md

@@ -0,0 +1,91 @@
+# prompt-cache-fit
+
+Reorder LLM prompt blocks from least- to most-volatile so provider prefix caches stay hot, and measure whether it actually worked. This is the Python port of the JavaScript package of the same name.
+
+## The problem
+
+Anthropic, OpenAI, xAI and DeepSeek all cache prompt *prefixes*. The cache is only reusable up to the first byte that differs between two requests. Teams that put a timestamp, a request id, or "today's date" near the top of the system prompt throw away the cache for every token below it, even though the rest of the prompt (the system message, the tool schema, the RAG chunks) did not actually change. The published advice is "order your prompt from least-variable to most-variable", but every team hand-rolls that ordering, and almost nobody measures whether the reordering actually raised the hit rate. This package does the reordering and the measurement, nothing else: no tokenizer, no provider SDK, no network calls.
+
+## Install
+
+```
+pip install prompt-cache-fit
+```
+
+## Usage
+
+```python
+from prompt_cache_fit import fit, hit_rate
+
+static_block = {"text": "You are a helpful coding assistant.", "volatility": "static"}
+tools_block = {"text": "Tools: search_docs(query), run_tests()", "volatility": "shared"}
+session_block = {
+    "text": "User profile: senior backend engineer, prefers concise answers.",
+    "volatility": "session",
+}
+timestamp1 = {"text": "Timestamp: 2026-09-04T10:00:00Z", "volatility": "turn"}
+question1 = {"text": "Turn: how do I retry a failed HTTP request?", "volatility": "turn"}
+timestamp2 = {"text": "Timestamp: 2026-09-04T10:05:00Z", "volatility": "turn"}
+question2 = {"text": "Turn: how do I cancel an in-flight fetch?", "volatility": "turn"}
+
+# Hand-rolled: the volatile timestamp sits in the middle of the prompt.
+hand_rolled1 = "\n\n".join(
+    b["text"] for b in [static_block, timestamp1, tools_block, session_block, question1]
+)
+hand_rolled2 = "\n\n".join(
+    b["text"] for b in [static_block, timestamp2, tools_block, session_block, question2]
+)
+
+# fit(): volatile blocks (rank 'turn') sort to the end automatically.
+fitted1 = fit([static_block, timestamp1, tools_block, session_block, question1])
+fitted2 = fit([static_block, timestamp2, tools_block, session_block, question2])
+
+print(hit_rate([hand_rolled1, hand_rolled2]).mean)  # 0.2916666666666667
+print(hit_rate([fitted1.text, fitted2.text]).mean)  # 0.7777777777777778
+```
+
+Moving the two `turn`-tier blocks to the end of the prompt takes the measured prefix hit rate on the second request from about 29% to about 78%, because the shared system prompt, tool schema and session block now form one unbroken prefix instead of being interrupted by the timestamp.
+
+## API
+
+### `fit(blocks, *, separator="\n\n") -> FitResult`
+
+- `blocks: List[Dict[str, Any]]`, each dict with a required `text: str` key and optional `volatility: str`, `id`, `pin: bool` keys. Plain dicts are accepted; no class is required.
+- `volatility` is one of `"static" | "shared" | "session" | "turn"`, ranked in that order (`static` sorts first, `turn` sorts last). Missing or unrecognized values default to `"turn"`; unknown strings never raise.
+- `pin=True` on a block keeps that block at its original index. Every other block is sorted around it.
+- The sort is stable: two blocks with the same rank keep their original relative order.
+- `separator` (keyword-only, default `"\n\n"`): the string joined between rendered blocks.
+- Returns a frozen `FitResult` dataclass:
+  - `blocks`: the input blocks, reordered.
+  - `text`: the reordered blocks joined with `separator`.
+  - `moved`: count of blocks whose index differs from the input.
+  - `stable_prefix_chars`: characters from the start of `text` through the end of the last block ranked below `turn`, including the separator that follows it if another block comes after. `0` if every block is `turn`.
+
+### `shared_prefix(a, b) -> int`
+
+Number of shared leading characters between two strings. `shared_prefix("abc", "abd")` is `2`. Returns `0` for empty strings.
+
+### `hit_rate(prompts) -> HitRateReport`
+
+`prompts` is a list of already-rendered prompt strings, in send order. For each prompt after the first, computes `shared_prefix(prompts[i-1], prompts[i]) / len(prompts[i])`. Returns a frozen `HitRateReport` dataclass:
+
+- `per_request`: one fraction (`0..1`) per request after the first.
+- `mean`: mean of `per_request`, `0` if fewer than 2 prompts were given.
+- `cached_chars`: sum of shared prefix lengths across all requests after the first.
+- `total_chars`: sum of `len(prompts[i])` for `i >= 1`.
+
+An empty prompt string contributes `0` instead of dividing by zero.
+
+### `VOLATILITY`
+
+`{"static": 0, "shared": 1, "session": 2, "turn": 3}`, exported as a plain dict so forkers can add their own tiers or change the ranks.
+
+## How it works
+
+`fit()` is a stable sort by volatility rank plus a reinsertion pass for pinned blocks; `hit_rate()` is a character-by-character common-prefix scan. That is the whole library. It does not know how any provider actually tokenizes or chunks its cache, so `stable_prefix_chars` and `hit_rate` are character-level proxies, not a guarantee of a provider-side cache hit: real caches key on token boundaries and have their own minimum prefix length and TTL. This package also does not inject provider-specific cache markers (Anthropic's `cache_control`, OpenAI's automatic prefix caching, etc.) into the output; ordering the blocks correctly is a precondition for those markers to help, but adding the markers themselves is left to the caller, since the marker format is provider-specific and out of scope here.
+
+The JavaScript version of this package lives at the repository root: https://github.com/pjdurden/prompt-cache-fit
+
+## License
+
+MIT

prompt_cache_fit-0.1.0/prompt_cache_fit.py

@@ -0,0 +1,148 @@
+"""
+prompt-cache-fit
+
+Providers cache prompt prefixes. The cache breaks at the first byte that
+differs between two requests, so volatile content (timestamps, user ids,
+the live turn) needs to sit at the end of the prompt, not the top. This
+module reorders prompt blocks from least-volatile to most-volatile and
+measures how much of the prefix is expected to survive between requests.
+
+This is a Python port of the JavaScript package `prompt-cache-fit`. It
+matches the JavaScript version's behavior exactly.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+__all__ = ["VOLATILITY", "fit", "shared_prefix", "hit_rate", "FitResult", "HitRateReport"]
+
+# Volatility tiers and their sort rank. Lower rank sorts first (stays near
+# the top of the prompt, closer to the cacheable prefix). Exported as a
+# plain dict so forkers can add their own tiers.
+VOLATILITY: Dict[str, int] = {"static": 0, "shared": 1, "session": 2, "turn": 3}
+
+
+def _rank_of(volatility: Optional[str]) -> int:
+    """
+    Resolve the sort rank for a volatility label. Missing or unrecognized
+    labels fall back to 'turn' (the most volatile tier) rather than raising.
+    """
+    if volatility is not None and volatility in VOLATILITY:
+        return VOLATILITY[volatility]
+    return VOLATILITY["turn"]
+
+
+@dataclass(frozen=True)
+class FitResult:
+    blocks: List[Dict[str, Any]]
+    text: str
+    moved: int
+    stable_prefix_chars: int
+
+
+@dataclass(frozen=True)
+class HitRateReport:
+    per_request: List[float]
+    mean: float
+    cached_chars: int
+    total_chars: int
+
+
+def fit(blocks: List[Dict[str, Any]], *, separator: str = "\n\n") -> FitResult:
+    """
+    Reorder prompt blocks from least-volatile to most-volatile so that the
+    shared, cacheable prefix is as long as possible, and render them into a
+    single prompt string.
+
+    blocks: a list of dicts, each with a required "text" key and optional
+        "volatility", "id", "pin" keys.
+    separator: the string joined between rendered blocks.
+    """
+    if not isinstance(blocks, (list, tuple)) or len(blocks) == 0:
+        return FitResult(blocks=[], text="", moved=0, stable_prefix_chars=0)
+
+    blocks = list(blocks)
+
+    # Split into pinned (keep original index) and non-pinned (sortable) blocks.
+    pinned_indices: List[int] = []
+    non_pinned: List[Any] = []  # list of (block, index) tuples
+    for index, block in enumerate(blocks):
+        if block.get("pin") is True:
+            pinned_indices.append(index)
+        else:
+            non_pinned.append((block, index))
+
+    # Python's sorted() is stable, so ties keep original order.
+    non_pinned.sort(key=lambda item: _rank_of(item[0].get("volatility")))
+
+    # Reinsert pinned blocks at their original indices; fill the rest in
+    # sorted order.
+    result: List[Any] = [None] * len(blocks)
+    for idx in pinned_indices:
+        result[idx] = blocks[idx]
+    cursor = 0
+    for i in range(len(result)):
+        if result[i] is None:
+            result[i] = non_pinned[cursor][0]
+            cursor += 1
+
+    text = separator.join(block["text"] for block in result)
+
+    moved = 0
+    for i in range(len(blocks)):
+        if result[i] is not blocks[i]:
+            moved += 1
+
+    # Chars from the start through the end of the last block whose rank is
+    # less than 'turn' (3), including the separator that follows it if
+    # another block comes after it. 0 if every block is 'turn'.
+    last_stable_index = -1
+    for i in range(len(result)):
+        if _rank_of(result[i].get("volatility")) < VOLATILITY["turn"]:
+            last_stable_index = i
+
+    stable_prefix_chars = 0
+    if last_stable_index >= 0:
+        for i in range(last_stable_index + 1):
+            stable_prefix_chars += len(result[i]["text"])
+            if i < last_stable_index:
+                stable_prefix_chars += len(separator)
+        if last_stable_index < len(result) - 1:
+            stable_prefix_chars += len(separator)
+
+    return FitResult(blocks=result, text=text, moved=moved, stable_prefix_chars=stable_prefix_chars)
+
+
+def shared_prefix(a: str, b: str) -> int:
+    """Count the shared leading characters between two strings."""
+    length = min(len(a), len(b))
+    i = 0
+    while i < length and a[i] == b[i]:
+        i += 1
+    return i
+
+
+def hit_rate(prompts: List[str]) -> HitRateReport:
+    """
+    Measure how much of each rendered prompt's prefix was shared with the
+    prompt sent immediately before it, as a proxy for provider prefix-cache
+    hit rate.
+
+    prompts: rendered prompt strings, in send order.
+    """
+    per_request: List[float] = []
+    cached_chars = 0
+    total_chars = 0
+
+    for i in range(1, len(prompts)):
+        previous = prompts[i - 1]
+        current = prompts[i]
+        shared = shared_prefix(previous, current)
+        fraction = 0 if len(current) == 0 else shared / len(current)
+        per_request.append(fraction)
+        cached_chars += shared
+        total_chars += len(current)
+
+    mean = 0 if len(per_request) == 0 else sum(per_request) / len(per_request)
+
+    return HitRateReport(per_request=per_request, mean=mean, cached_chars=cached_chars, total_chars=total_chars)

prompt_cache_fit-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "prompt-cache-fit"
+version = "0.1.0"
+description = "Reorder LLM prompt blocks from least- to most-volatile so provider prefix caches stay hot, and measure whether it actually worked."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "Prajjwal Chittori"}]
+keywords = ["llm", "prompt-caching", "prefix-cache", "anthropic", "openai", "prompt-engineering"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/pjdurden/prompt-cache-fit"
+Source = "https://github.com/pjdurden/prompt-cache-fit"
+
+[tool.hatch.build.targets.wheel]
+include = ["prompt_cache_fit.py", "py.typed"]

prompt_cache_fit-0.1.0/test_prompt_cache_fit.py

@@ -0,0 +1,191 @@
+import unittest
+
+from prompt_cache_fit import VOLATILITY, FitResult, HitRateReport, fit, hit_rate, shared_prefix
+
+
+class TestVolatility(unittest.TestCase):
+    def test_volatility_exposes_the_exact_rank_table(self):
+        self.assertEqual(VOLATILITY, {"static": 0, "shared": 1, "session": 2, "turn": 3})
+
+
+class TestFit(unittest.TestCase):
+    def test_fit_on_an_empty_list_returns_the_exact_empty_result(self):
+        self.assertEqual(fit([]), FitResult(blocks=[], text="", moved=0, stable_prefix_chars=0))
+
+    def test_fit_leaves_order_unchanged_when_every_block_shares_a_volatility(self):
+        blocks = [
+            {"text": "p", "volatility": "session"},
+            {"text": "q", "volatility": "session"},
+            {"text": "r", "volatility": "session"},
+        ]
+        result = fit(blocks)
+        self.assertEqual(result.moved, 0)
+        self.assertEqual(result.text, "p\n\nq\n\nr")
+        self.assertEqual(result.blocks, blocks)
+
+    def test_fit_sorts_by_volatility_rank_static_first(self):
+        a = {"text": "A", "volatility": "turn"}
+        b = {"text": "B", "volatility": "static"}
+        c = {"text": "C", "volatility": "shared"}
+        result = fit([a, b, c])
+        self.assertEqual(result.blocks, [b, c, a])
+        self.assertEqual(result.text, "B\n\nC\n\nA")
+
+    def test_fit_keeps_original_relative_order_for_blocks_tied_on_rank_stable_sort(self):
+        t1 = {"text": "x", "volatility": "turn", "id": "t1"}
+        s1 = {"text": "y", "volatility": "static", "id": "s1"}
+        t2 = {"text": "z", "volatility": "turn", "id": "t2"}
+        result = fit([t1, s1, t2])
+        self.assertEqual([block["id"] for block in result.blocks], ["s1", "t1", "t2"])
+
+    def test_fit_treats_a_missing_volatility_as_turn_default(self):
+        m = {"text": "M"}
+        n = {"text": "N", "volatility": "static"}
+        result = fit([m, n])
+        self.assertEqual(result.blocks, [n, m])
+
+    def test_fit_treats_an_unknown_volatility_string_as_turn_instead_of_raising(self):
+        x = {"text": "X", "volatility": "made-up-tier"}
+        y = {"text": "Y", "volatility": "static"}
+        try:
+            fit([x, y])
+        except Exception as exc:  # pragma: no cover - fails the test if raised
+            self.fail(f"fit() raised unexpectedly for an unknown volatility: {exc!r}")
+        result = fit([x, y])
+        self.assertEqual(result.blocks, [y, x])
+
+    def test_fit_keeps_a_pinned_block_at_its_original_index_and_counts_moved_correctly(self):
+        a = {"text": "A", "volatility": "turn"}
+        b = {"text": "B", "volatility": "static", "pin": True}
+        c = {"text": "C", "volatility": "static"}
+        d = {"text": "D", "volatility": "turn"}
+        result = fit([a, b, c, d])
+        # B is static and would otherwise jump to index 0, but pin holds it at index 1.
+        self.assertEqual(result.blocks[1], b)
+        self.assertEqual(result.blocks, [c, b, a, d])
+        # A and C changed index; B (pinned) and D did not.
+        self.assertEqual(result.moved, 2)
+
+    def test_fit_supports_a_custom_separator(self):
+        result = fit([{"text": "a"}, {"text": "b"}], separator="|")
+        self.assertEqual(result.text, "a|b")
+
+    def test_fit_uses_double_newline_as_the_default_separator(self):
+        result = fit([{"text": "a"}, {"text": "b"}])
+        self.assertEqual(result.text, "a\n\nb")
+
+    def test_fit_omitted_separator_keyword_matches_explicit_default(self):
+        # The JS suite has a test asserting that an explicit null options
+        # object behaves identically to omitted options. There is no
+        # equivalent to port literally in Python: options are keyword
+        # arguments with defaults, so there is no separate "null options"
+        # state to test. This instead confirms that omitting the separator
+        # keyword produces the same result as passing the documented default
+        # explicitly.
+        omitted = fit([{"text": "a"}])
+        explicit_default = fit([{"text": "a"}], separator="\n\n")
+        self.assertEqual(omitted, explicit_default)
+        self.assertEqual(
+            omitted,
+            FitResult(blocks=[{"text": "a"}], text="a", moved=0, stable_prefix_chars=0),
+        )
+
+    def test_fit_computes_stable_prefix_chars_through_the_last_non_turn_block(self):
+        static_block = {"text": "sys", "volatility": "static"}
+        shared_block = {"text": "tools", "volatility": "shared"}
+        turn_block = {"text": "question", "volatility": "turn"}
+        result = fit([static_block, turn_block, shared_block])
+        self.assertEqual(result.blocks, [static_block, shared_block, turn_block])
+        # 'sys' (3) + sep (2) + 'tools' (5) + sep (2) = 12, up through and including
+        # the separator that follows the last non-turn block.
+        self.assertEqual(result.stable_prefix_chars, 12)
+
+    def test_fit_stable_prefix_chars_is_0_when_every_block_is_turn(self):
+        result = fit([{"text": "a"}, {"text": "b"}])
+        self.assertEqual(result.stable_prefix_chars, 0)
+
+
+class TestSharedPrefix(unittest.TestCase):
+    def test_shared_prefix_counts_matching_leading_characters(self):
+        self.assertEqual(shared_prefix("abc", "abd"), 2)
+        self.assertEqual(shared_prefix("abc", "abc"), 3)
+        self.assertEqual(shared_prefix("ab", "abc"), 2)
+
+    def test_shared_prefix_handles_empty_strings(self):
+        self.assertEqual(shared_prefix("", ""), 0)
+        self.assertEqual(shared_prefix("abc", ""), 0)
+
+
+class TestHitRate(unittest.TestCase):
+    def test_hit_rate_empty_reports_all_zeros_with_no_per_request_entries(self):
+        report = hit_rate([])
+        self.assertEqual(report.per_request, [])
+        self.assertEqual(report.mean, 0)
+        self.assertEqual(report.cached_chars, 0)
+        self.assertEqual(report.total_chars, 0)
+
+    def test_hit_rate_with_a_single_prompt_reports_all_zeros_with_no_per_request_entries(self):
+        report = hit_rate(["only one"])
+        self.assertEqual(report.per_request, [])
+        self.assertEqual(report.mean, 0)
+        self.assertEqual(report.cached_chars, 0)
+        self.assertEqual(report.total_chars, 0)
+
+    def test_hit_rate_guards_against_division_by_zero_on_an_empty_prompt(self):
+        report = hit_rate(["abc", ""])
+        self.assertEqual(report.per_request, [0])
+        self.assertEqual(report.mean, 0)
+        self.assertEqual(report.cached_chars, 0)
+        self.assertEqual(report.total_chars, 0)
+
+    def test_hit_rate_computes_per_request_fractions_mean_cached_chars_and_total_chars(self):
+        report = hit_rate(["hello world", "hello there", "hello there friend"])
+        # 'hello world' vs 'hello there' share 'hello ' -> 6 chars / 11 = 0.5454...
+        # 'hello there' vs 'hello there friend' share all 11 chars / 18 = 0.6111...
+        self.assertEqual(len(report.per_request), 2)
+        self.assertEqual(report.per_request[0], 6 / 11)
+        self.assertEqual(report.per_request[1], 11 / 18)
+        self.assertEqual(report.cached_chars, 6 + 11)
+        self.assertEqual(report.total_chars, 11 + 18)
+        self.assertEqual(report.mean, (6 / 11 + 11 / 18) / 2)
+
+
+class TestReadmeWorkedCase(unittest.TestCase):
+    def test_readme_worked_case_moving_the_volatile_block_to_the_end_raises_the_measured_hit_rate(self):
+        static_block = {"text": "You are a helpful coding assistant.", "volatility": "static"}
+        tools_block = {"text": "Tools: search_docs(query), run_tests()", "volatility": "shared"}
+        session_block = {
+            "text": "User profile: senior backend engineer, prefers concise answers.",
+            "volatility": "session",
+        }
+        timestamp1 = {"text": "Timestamp: 2026-09-04T10:00:00Z", "volatility": "turn"}
+        question1 = {"text": "Turn: how do I retry a failed HTTP request?", "volatility": "turn"}
+        timestamp2 = {"text": "Timestamp: 2026-09-04T10:05:00Z", "volatility": "turn"}
+        question2 = {"text": "Turn: how do I cancel an in-flight fetch?", "volatility": "turn"}
+
+        # Hand-rolled order: the volatile timestamp sits in the middle.
+        hand_rolled1 = "\n\n".join(
+            block["text"] for block in [static_block, timestamp1, tools_block, session_block, question1]
+        )
+        hand_rolled2 = "\n\n".join(
+            block["text"] for block in [static_block, timestamp2, tools_block, session_block, question2]
+        )
+
+        # fit(): volatile blocks pushed to the end.
+        fitted1 = fit([static_block, timestamp1, tools_block, session_block, question1])
+        fitted2 = fit([static_block, timestamp2, tools_block, session_block, question2])
+
+        hand_rolled_report = hit_rate([hand_rolled1, hand_rolled2])
+        fitted_report = hit_rate([fitted1.text, fitted2.text])
+
+        self.assertEqual(hand_rolled_report.mean, 63 / 216)
+        self.assertEqual(fitted_report.mean, 168 / 216)
+        self.assertGreater(fitted_report.mean, hand_rolled_report.mean)
+
+        # These are the exact numbers quoted in the README's worked example.
+        self.assertEqual(hand_rolled_report.mean, 0.2916666666666667)
+        self.assertEqual(fitted_report.mean, 0.7777777777777778)
+
+
+if __name__ == "__main__":
+    unittest.main()