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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
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.mdxindex 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 areconservative 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 inputsdiff --git a/headroom/cache/ttl_estimator.py b/headroom/cache/ttl_estimator.pynew file mode 100644index 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.tomlindex 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.pynew file mode 100644index 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