Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat(cache): add the headroom-cache-ttl offline TTL estimator the docs reference (#2670)

gglucass52c7aa2e6faa
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdx
index 99bb5670c..ce44b245a 100644
--- a/docs/content/docs/configuration.mdx
+++ b/docs/content/docs/configuration.mdx
@@ -392,6 +392,27 @@ and the **prefix** itself once its prompt cache has lapsed. All flags below are
conservative default until the learner (`HEADROOM_CACHE_TTL_LEARN` + the
`headroom-cache-ttl` plugin) fills in the real value from observed hits/misses.
+**Running the estimator.** With `HEADROOM_CACHE_TTL_LEARN=1` set on the proxy,
+run the batch estimator periodically (cron / launchd — it is deliberately
+out-of-process so it can never touch the request path):
+
+```bash
+headroom-cache-ttl # reads cache_ttl_observations.jsonl, writes cache_ttl_learned.json
+headroom-cache-ttl --dry-run # print the estimate table without writing
+```
+
+It emits a TTL for a `provider/model` only when the observations bound it on
+both sides — hits at some idle prove the cache was still alive (lower bound),
+`ttl_expiry` misses at a larger idle prove it was dead (upper bound) — and it
+writes the upper end of that interval: overestimating a TTL only skips a
+recompaction, while underestimating one would bust a warm cache. Estimates are
+never pooled across models: one model's expiry says nothing about another's
+TTL, so a cross-model aggregate could close one model's interval with another's
+death evidence. Keys without death-evidence beyond their last observed hit are
+skipped, as is any model with no estimate of its own; both keep the
+conservative static default. The proxy picks up a rewritten table by mtime; no
+restart needed.
+
**Can these be on by default?**
- `HEADROOM_THINKING_COMPACT` — **stays opt-in.** It rewrites model inputs
diff --git a/headroom/cache/ttl_estimator.py b/headroom/cache/ttl_estimator.py
new file mode 100644
index 000000000..8520a2537
--- /dev/null
+++ b/headroom/cache/ttl_estimator.py
@@ -0,0 +1,237 @@
+"""Offline cache-TTL estimator — the `headroom-cache-ttl` CLI.
+
+The other half of the seam in :mod:`headroom.cache.ttl_observations`: the proxy
+appends per-turn cache outcomes to ``cache_ttl_observations.jsonl`` (when
+``HEADROOM_CACHE_TTL_LEARN`` is set); this batch tool reads those rows and
+writes the ``cache_ttl_learned.json`` table that
+:func:`~headroom.cache.ttl_observations.resolve_learned_ttl` consults, so cold
+detection (``HEADROOM_COLD_RECOMPACT``) stops guessing for providers that don't
+expose their TTL (Kimi / OpenAI / Codex).
+
+Estimation is interval-based, per the contract in ``ttl_observations``: idle
+gaps that still HIT bound the TTL from below (the cache was alive at that
+idle), and ``ttl_expiry`` misses bound it from above (the cache was dead by
+that idle). We emit the UPPER end of the interval — the smallest observed
+death-idle beyond the largest observed life-idle — because the consumer treats
+a turn as cold only when ``idle > ttl``: overestimating the TTL merely skips a
+recompaction (lost savings), while underestimating it would recompact a
+still-warm prefix and bust the cache (net cost). A key with no death evidence
+beyond its last observed life is skipped entirely for the same reason.
+
+That safety argument only holds when both ends of the interval describe the
+SAME cache population, so estimates are scoped to ``provider/model`` and
+nothing coarser. A ``ttl_expiry`` miss for model B does not upper-bound model
+A's TTL: pooling them per-provider would let B's death evidence close A's life
+interval and hand the consumer a TTL below A's real one — the one direction
+that costs money. Nor is there a conservative aggregate to fall back on: a
+value safe for a model we have never observed would have to upper-bound a TTL
+we have never seen. Models we cannot estimate get the static default instead.
+
+Runs out-of-process on purpose (zero live-feedback risk on the hot path); the
+proxy re-reads the learned table by mtime, so a periodic cron/launchd run is
+enough. Never imports anything request-scoped.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import time
+from collections import defaultdict
+from typing import Any
+
+from headroom.cache.ttl_observations import _learned_path, _obs_path
+
+DEFAULT_MIN_HITS = 3
+DEFAULT_MIN_EXPIRY_MISSES = 3
+
+
+def _iter_rows(path: str) -> list[dict[str, Any]]:
+ """Parse the observation JSONL, skipping malformed lines (best-effort)."""
+ rows: list[dict[str, Any]] = []
+ try:
+ with open(path, encoding="utf-8") as f:
+ for line in f:
+ line = line.strip()
+ if not line:
+ continue
+ try:
+ row = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+ if isinstance(row, dict):
+ rows.append(row)
+ except OSError:
+ pass
+ return rows
+
+
+def estimate_ttls(
+ rows: list[dict[str, Any]],
+ *,
+ min_hits: int = DEFAULT_MIN_HITS,
+ min_expiry_misses: int = DEFAULT_MIN_EXPIRY_MISSES,
+) -> dict[str, dict[str, Any]]:
+ """Per-key TTL estimates from raw observation rows.
+
+ Keyed by ``provider/model`` only — the exact-match half of the
+ ``resolve_learned_ttl`` lookup. Rows carrying no model are dropped rather
+ than pooled under a bare ``provider`` key: see the module docstring for why
+ a cross-model aggregate is not a sound interval.
+
+ A key is emitted only when it has both enough life evidence (``min_hits``
+ hits with a positive, finite idle) and enough death evidence
+ (``min_expiry_misses`` ``ttl_expiry`` misses), AND at least one death was
+ observed at an idle larger than every observed life — otherwise the
+ interval has no safe upper end and the static default is the better
+ fallback.
+ """
+ hits: dict[str, list[float]] = defaultdict(list)
+ expiries: dict[str, list[float]] = defaultdict(list)
+ for row in rows:
+ if not isinstance(row, dict):
+ continue
+ provider = row.get("provider")
+ if not isinstance(provider, str) or not provider:
+ continue
+ model = row.get("model")
+ if not isinstance(model, str) or not model:
+ continue # no model -> no cache population to attribute the row to
+ key = f"{provider}/{model}"
+ try:
+ idle = float(row.get("idle_seconds", 0.0) or 0.0)
+ except (TypeError, ValueError):
+ continue
+ # NaN and ±Inf survive a bare `idle <= 0` (every NaN comparison is False),
+ # then poison max()/min() and finally raise in int() — one malformed row
+ # would abort the whole batch. Drop them with the other bad input.
+ if not math.isfinite(idle) or idle <= 0:
+ continue
+ if row.get("is_miss"):
+ if row.get("reason") == "ttl_expiry":
+ expiries[key].append(idle)
+ else:
+ hits[key].append(idle)
+
+ now = round(time.time(), 3)
+ table: dict[str, dict[str, Any]] = {}
+ for key in sorted(set(hits) | set(expiries)):
+ key_hits = hits.get(key, [])
+ key_expiries = expiries.get(key, [])
+ # Floors of at least 1 either side: an interval needs one life and one
+ # death sample to exist at all, and this keeps the max()/min() below from
+ # running on an empty list no matter what a caller passes.
+ if len(key_hits) < max(1, min_hits) or len(key_expiries) < max(1, min_expiry_misses):
+ continue
+ max_hit_idle = max(key_hits)
+ deaths_after_life = [x for x in key_expiries if x > max_hit_idle]
+ if not deaths_after_life:
+ continue # bounds overlap: no idle at which the cache is provably dead
+ table[key] = {
+ "ttl_seconds": int(min(deaths_after_life)),
+ "max_hit_idle": int(max_hit_idle),
+ "hits": len(key_hits),
+ "ttl_expiry_misses": len(key_expiries),
+ "updated_at": now,
+ }
+ return table
+
+
+def write_learned(table: dict[str, dict[str, Any]], path: str) -> dict[str, Any]:
+ """Merge ``table`` into the learned file at ``path`` (atomic tmp+rename).
+
+ Merging (not replacing) keeps keys learned from an earlier, since-rotated
+ observation window instead of silently un-learning them. Bare-provider
+ aggregates written by earlier versions of this tool are exactly the unsound
+ cross-model intervals the module docstring rules out; left in place they
+ would keep feeding ``resolve_learned_ttl``'s provider fallback forever, so
+ they are dropped on every write. They are identified by the estimator's own
+ metadata shape (``max_hit_idle``) — a bare-provider key WITHOUT that shape
+ is an operator-maintained fallback (``resolve_learned_ttl`` supports both a
+ plain number and a ``{"ttl_seconds": N}`` dict there) and is preserved.
+ """
+ merged: dict[str, Any] = {}
+ try:
+ with open(path, encoding="utf-8") as f:
+ existing = json.load(f)
+ if isinstance(existing, dict):
+ merged.update(existing)
+ except (OSError, json.JSONDecodeError):
+ pass
+ merged.update(table)
+ merged = {
+ k: v
+ for k, v in merged.items()
+ if "/" in k or not (isinstance(v, dict) and "max_hit_idle" in v)
+ }
+ os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+ tmp = f"{path}.tmp.{os.getpid()}"
+ with open(tmp, "w", encoding="utf-8") as f:
+ json.dump(merged, f, indent=2, sort_keys=True)
+ f.write("\n")
+ os.replace(tmp, path)
+ return merged
+
+
+def _sample_floor(value: str) -> int:
+ """argparse type for the evidence floors — below 1 there is no requirement."""
+ n = int(value)
+ if n < 1:
+ raise argparse.ArgumentTypeError(f"must be >= 1, got {n}")
+ return n
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(
+ prog="headroom-cache-ttl",
+ description=(
+ "Estimate provider prompt-cache TTLs from cache_ttl_observations.jsonl "
+ "and write cache_ttl_learned.json for the proxy's cold-prefix detection."
+ ),
+ )
+ parser.add_argument(
+ "--obs",
+ default=None,
+ help="Observation JSONL (default: $HEADROOM_CACHE_TTL_OBS_PATH or "
+ "~/.headroom/cache_ttl_observations.jsonl)",
+ )
+ parser.add_argument(
+ "--out",
+ default=None,
+ help="Learned-table JSON to write (default: $HEADROOM_CACHE_TTL_LEARNED_PATH "
+ "or ~/.headroom/cache_ttl_learned.json)",
+ )
+ parser.add_argument("--min-hits", type=_sample_floor, default=DEFAULT_MIN_HITS)
+ parser.add_argument(
+ "--min-expiry-misses", type=_sample_floor, default=DEFAULT_MIN_EXPIRY_MISSES
+ )
+ parser.add_argument(
+ "--dry-run", action="store_true", help="Print the estimate table without writing"
+ )
+ args = parser.parse_args(argv)
+
+ obs_path = args.obs or _obs_path()
+ out_path = args.out or _learned_path()
+ rows = _iter_rows(obs_path)
+ table = estimate_ttls(rows, min_hits=args.min_hits, min_expiry_misses=args.min_expiry_misses)
+ if args.dry_run:
+ print(json.dumps(table, indent=2, sort_keys=True))
+ return 0
+ # With nothing to add AND no existing file there is nothing to do; if the
+ # file exists we write even an empty table so the legacy-aggregate purge in
+ # write_learned() runs regardless of whether today's window was estimable.
+ if not table and not os.path.exists(out_path):
+ print(
+ f"headroom-cache-ttl: no estimable keys in {obs_path} "
+ f"({len(rows)} rows); nothing written"
+ )
+ return 0
+ merged = write_learned(table, out_path)
+ print(f"headroom-cache-ttl: wrote {len(table)} estimate(s) ({len(merged)} total) to {out_path}")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/pyproject.toml b/pyproject.toml
index 44d87f5e4..4d33f254b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -332,6 +332,7 @@ sandbox = [
[project.scripts]
headroom = "headroom.cli:main"
+headroom-cache-ttl = "headroom.cache.ttl_estimator:main"
[project.urls]
Homepage = "https://docs.headroomlabs.ai"
diff --git a/tests/test_cache/test_ttl_estimator.py b/tests/test_cache/test_ttl_estimator.py
new file mode 100644
index 000000000..84d92e1d8
--- /dev/null
+++ b/tests/test_cache/test_ttl_estimator.py
@@ -0,0 +1,283 @@
+"""Tests for the offline cache-TTL estimator (`headroom-cache-ttl`)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from headroom.cache.ttl_estimator import (
+ estimate_ttls,
+ main,
+ write_learned,
+)
+from headroom.cache.ttl_observations import resolve_learned_ttl
+
+
+def _row(
+ provider: str = "openai",
+ model: str = "gpt-5.5",
+ *,
+ idle: float,
+ hit: bool,
+ reason: str | None = None,
+) -> dict:
+ return {
+ "ts": 1000.0,
+ "provider": provider,
+ "model": model,
+ "reason": reason if reason is not None else ("hit" if hit else "ttl_expiry"),
+ "idle_seconds": idle,
+ "ttl_assumed": 300,
+ "is_miss": not hit,
+ "cache_read": 1000 if hit else 0,
+ "expected_cached": 1000,
+ }
+
+
+def _corpus(hit_idles: list[float], expiry_idles: list[float]) -> list[dict]:
+ return [_row(idle=i, hit=True) for i in hit_idles] + [
+ _row(idle=i, hit=False) for i in expiry_idles
+ ]
+
+
+def _legacy_aggregate(ttl: int) -> dict:
+ # The exact record shape the earlier per-provider estimator wrote under a
+ # bare provider key; `max_hit_idle` is what marks it as estimator output.
+ return {
+ "ttl_seconds": ttl,
+ "max_hit_idle": ttl // 2,
+ "hits": 5,
+ "ttl_expiry_misses": 4,
+ "updated_at": 1000.0,
+ }
+
+
+class TestEstimateTtls:
+ def test_upper_bound_of_interval_is_emitted(self):
+ # Alive at up to 480s, first observed death beyond that at 600s
+ # -> TTL estimate is the safe upper end: 600.
+ table = estimate_ttls(_corpus([120, 300, 480], [600, 900, 1200]))
+ assert table["openai/gpt-5.5"]["ttl_seconds"] == 600
+ assert table["openai/gpt-5.5"]["max_hit_idle"] == 480
+ assert "openai" not in table # provider aggregates are never emitted
+
+ def test_death_at_or_below_max_hit_idle_is_not_an_upper_bound(self):
+ # Deaths at 400/450 sit below a hit at 480 (variable eviction);
+ # only the 700s death is beyond every observed life.
+ table = estimate_ttls(_corpus([120, 300, 480], [400, 450, 700]))
+ assert table["openai/gpt-5.5"]["ttl_seconds"] == 700
+
+ def test_no_death_beyond_life_skips_key(self):
+ # Every observed death overlaps the life range: no safe upper end.
+ table = estimate_ttls(_corpus([120, 480, 900], [400, 450, 600]))
+ assert table == {}
+
+ def test_insufficient_samples_skip_key(self):
+ assert estimate_ttls(_corpus([480], [600, 700, 800])) == {} # 1 hit < 3
+ assert estimate_ttls(_corpus([100, 200, 480], [600])) == {} # 1 expiry < 3
+ # Thresholds are tunable.
+ table = estimate_ttls(_corpus([480], [600]), min_hits=1, min_expiry_misses=1)
+ assert table["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_sub_one_floors_do_not_disable_the_evidence_requirement(self):
+ # An interval needs one life and one death sample to exist; floors below
+ # 1 must not let a key through to max()/min() on an empty list.
+ rows = [_row(idle=i, hit=False) for i in (600, 700, 800)] # deaths only
+ assert estimate_ttls(rows, min_hits=0, min_expiry_misses=0) == {}
+ assert estimate_ttls(rows, min_hits=-5, min_expiry_misses=-5) == {}
+
+ def test_non_ttl_expiry_misses_are_ignored(self):
+ rows = _corpus([100, 200, 480], [600, 700]) + [
+ _row(idle=550, hit=False, reason="prefix_change"),
+ _row(idle=560, hit=False, reason="cold_start"),
+ ]
+ # prefix_change/cold_start misses say nothing about TTL: still only
+ # 2 ttl_expiry rows -> below the min_expiry_misses=3 floor.
+ assert estimate_ttls(rows) == {}
+
+ def test_zero_idle_and_malformed_rows_are_ignored(self):
+ rows = _corpus([100, 200, 480], [600, 700, 800]) + [
+ _row(idle=0.0, hit=True),
+ {"provider": "", "idle_seconds": 50, "is_miss": False},
+ {"provider": "openai", "model": "gpt-5.5", "idle_seconds": "nan-ish"},
+ {"provider": "openai", "idle_seconds": 50, "is_miss": False}, # no model
+ "not a dict", # type: ignore[list-item]
+ ]
+ assert estimate_ttls(rows)["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_non_finite_idles_are_ignored(self):
+ # NaN/±Inf pass a bare `idle <= 0` (NaN comparisons are all False), then
+ # poison max()/min() and raise ValueError/OverflowError in int() — one
+ # such row must not take the whole batch down with it.
+ rows = _corpus([100, 200, 480], [600, 700, 800]) + [
+ _row(idle=float(v), hit=h) for v in ("nan", "inf", "-inf") for h in (True, False)
+ ]
+ assert estimate_ttls(rows)["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_one_models_death_cannot_close_anothers_life_interval(self):
+ # gpt-5.5 is alive at up to 1000s and never observed dead; mini dies at
+ # 1200s+. Pooled per-provider these would emit ttl=1200, which the
+ # consumer would then apply to gpt-5.5 (real TTL far higher) and to any
+ # unseen model, recompacting a still-warm prefix. Only mini is estimable.
+ rows = (
+ [_row(idle=i, hit=True) for i in (900, 950, 1000)]
+ + [_row(model="gpt-5.5-mini", idle=i, hit=True) for i in (100, 200, 300)]
+ + [_row(model="gpt-5.5-mini", idle=i, hit=False) for i in (1200, 1300, 1400)]
+ )
+ table = estimate_ttls(rows)
+ assert table["openai/gpt-5.5-mini"]["ttl_seconds"] == 1200
+ assert "openai/gpt-5.5" not in table # no death evidence of its own
+ assert "openai" not in table
+
+
+class TestWriteLearned:
+ def test_merge_preserves_existing_keys(self, tmp_path):
+ out = tmp_path / "learned.json"
+ out.write_text(json.dumps({"kimi/k2": {"ttl_seconds": 900}}))
+ write_learned({"openai/gpt-5.5": {"ttl_seconds": 600}}, str(out))
+ data = json.loads(out.read_text())
+ assert data["kimi/k2"]["ttl_seconds"] == 900
+ assert data["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_legacy_bare_provider_keys_are_purged_on_write(self, tmp_path):
+ # Files written by the earlier per-provider version of this tool carry
+ # exactly the unsound cross-model aggregates the estimator no longer
+ # emits; a merge that preserves them would keep feeding the consumer's
+ # provider fallback forever. They are recognized by the estimator's own
+ # metadata shape — a bare-provider key withOUT it is an operator-written
+ # fallback and must survive the purge.
+ out = tmp_path / "learned.json"
+ out.write_text(
+ json.dumps({"openai": _legacy_aggregate(1200), "kimi/k2": {"ttl_seconds": 900}})
+ )
+ write_learned({"openai/gpt-5.5": {"ttl_seconds": 600}}, str(out))
+ data = json.loads(out.read_text())
+ assert "openai" not in data
+ assert data["kimi/k2"]["ttl_seconds"] == 900
+ assert data["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_manual_bare_provider_fallbacks_survive_the_purge(self, tmp_path):
+ # Both hand-written forms resolve_learned_ttl accepts for a bare
+ # provider key: a {"ttl_seconds": N} dict and a plain number.
+ out = tmp_path / "learned.json"
+ out.write_text(
+ json.dumps(
+ {"openai": {"ttl_seconds": 3600}, "kimi": 900, "codex": _legacy_aggregate(1200)}
+ )
+ )
+ write_learned({"openai/gpt-5.5": {"ttl_seconds": 600}}, str(out))
+ data = json.loads(out.read_text())
+ assert data["openai"] == {"ttl_seconds": 3600}
+ assert data["kimi"] == 900
+ assert "codex" not in data
+
+ def test_corrupt_existing_file_is_replaced_not_fatal(self, tmp_path):
+ out = tmp_path / "learned.json"
+ out.write_text("{not json")
+ write_learned({"openai/gpt-5.5": {"ttl_seconds": 600}}, str(out))
+ assert json.loads(out.read_text())["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_non_dict_existing_file_is_replaced_not_merged(self, tmp_path):
+ out = tmp_path / "learned.json"
+ out.write_text("[1, 2]")
+ write_learned({"openai/gpt-5.5": {"ttl_seconds": 600}}, str(out))
+ assert json.loads(out.read_text()) == {"openai/gpt-5.5": {"ttl_seconds": 600}}
+
+
+class TestMain:
+ @pytest.fixture()
+ def paths(self, tmp_path, monkeypatch):
+ obs = tmp_path / "obs.jsonl"
+ out = tmp_path / "learned.json"
+ monkeypatch.setenv("HEADROOM_CACHE_TTL_OBS_PATH", str(obs))
+ monkeypatch.setenv("HEADROOM_CACHE_TTL_LEARNED_PATH", str(out))
+ return obs, out
+
+ def test_end_to_end_resolve_learned_ttl_reads_output(self, paths):
+ obs, out = paths
+ rows = _corpus([120, 300, 480], [600, 900])
+ rows += [_row(idle=650, hit=False)]
+ # Trailing junk the parser must skip: invalid JSON, a blank line,
+ # and valid JSON that is not an object.
+ obs.write_text("\n".join(json.dumps(r) for r in rows) + '\nnot-json\n\n[1, 2]\n"scalar"\n')
+
+ assert main([]) == 0
+ assert resolve_learned_ttl("openai", "gpt-5.5") == 600
+ # An unseen model gets nothing rather than gpt-5.5's bound: the consumer
+ # falls back to its own static default instead of a TTL learned from a
+ # cache population it has no evidence about.
+ assert resolve_learned_ttl("openai", "other-model") is None
+
+ def test_upgrade_purges_legacy_provider_aggregate(self, paths):
+ # Upgrade regression: a learned file from the earlier per-provider
+ # version must not keep serving its aggregate to unseen models after
+ # a run of the model-scoped estimator — while an operator-written
+ # provider fallback in the same file keeps resolving.
+ obs, out = paths
+ out.write_text(
+ json.dumps({"openai": _legacy_aggregate(1200), "kimi": {"ttl_seconds": 3600}})
+ )
+ obs.write_text("\n".join(json.dumps(r) for r in _corpus([120, 300, 480], [600, 900, 1200])))
+
+ assert main([]) == 0
+ data = json.loads(out.read_text())
+ assert "openai" not in data
+ assert data["openai/gpt-5.5"]["ttl_seconds"] == 600
+ assert resolve_learned_ttl("openai", "unseen-model") is None
+ assert resolve_learned_ttl("kimi", "unseen-model") == 3600
+
+ def test_upgrade_purge_runs_even_with_no_estimable_data(self, paths, capsys):
+ # The purge must not depend on today's window producing an estimate.
+ obs, out = paths
+ out.write_text(json.dumps({"openai": _legacy_aggregate(1200)}))
+ obs.write_text(json.dumps(_row(idle=120, hit=True)) + "\n")
+
+ assert main([]) == 0
+ assert json.loads(out.read_text()) == {}
+ assert resolve_learned_ttl("openai", "unseen-model") is None
+
+ def test_non_finite_jsonl_row_does_not_abort_the_run(self, paths):
+ obs, out = paths
+ # json.dumps emits bare NaN/Infinity and json.loads reads them back, so
+ # the recorder can put one in the log without any hand-editing.
+ # First row on purpose: max() keeps a leading NaN (every later `x > nan`
+ # is False), so this is the ordering that takes the run down.
+ rows = [_row(idle=float("nan"), hit=True)] + _corpus([120, 300, 480], [600, 900, 1200])
+ obs.write_text("\n".join(json.dumps(r) for r in rows) + "\n")
+ assert "NaN" in obs.read_text()
+
+ assert main([]) == 0
+ assert json.loads(out.read_text())["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_sub_one_sample_floors_are_rejected(self, paths):
+ with pytest.raises(SystemExit):
+ main(["--min-hits", "0"])
+ with pytest.raises(SystemExit):
+ main(["--min-expiry-misses", "-1"])
+
+ def test_no_estimable_data_writes_nothing(self, paths, capsys):
+ obs, out = paths
+ obs.write_text(json.dumps(_row(idle=120, hit=True)) + "\n")
+ assert main([]) == 0
+ assert not out.exists()
+ assert "nothing written" in capsys.readouterr().out
+
+ def test_missing_obs_file_is_not_an_error(self, paths):
+ assert main([]) == 0
+
+ def test_dry_run_prints_without_writing(self, paths, capsys):
+ obs, out = paths
+ obs.write_text("\n".join(json.dumps(r) for r in _corpus([120, 300, 480], [600, 900, 1200])))
+ assert main(["--dry-run"]) == 0
+ assert not out.exists()
+ assert json.loads(capsys.readouterr().out)["openai/gpt-5.5"]["ttl_seconds"] == 600
+
+ def test_explicit_paths_override_env(self, paths, tmp_path):
+ obs2 = tmp_path / "other.jsonl"
+ out2 = tmp_path / "other.json"
+ obs2.write_text(
+ "\n".join(json.dumps(r) for r in _corpus([120, 300, 480], [600, 900, 1200]))
+ )
+ assert main(["--obs", str(obs2), "--out", str(out2)]) == 0
+ assert json.loads(out2.read_text())["openai/gpt-5.5"]["ttl_seconds"] == 600