tiershift 0.1.0__tar.gz

tiershift-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# secrets
+.env
+.env.*
+!.env.example
+
+# deps and build
+node_modules/
+dist/
+.venv/
+__pycache__/
+
+# os
+.DS_Store
+
+# runtime
+*.log
+decisions.jsonl
+.tiershift/
+.claude/worktrees/
+
+# python
+python/.venv/
+python/dist/
+*.egg-info/
+.pytest_cache/

tiershift-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: tiershift
+Version: 0.1.0
+Summary: Shift every LLM call to the cheapest model that can handle it. Routing decided by TypeSafe Jev in ~300 ms. No training data. Policy in plain YAML.
+Project-URL: Homepage, https://github.com/iamvatsalpatel/tiershift
+Project-URL: Repository, https://github.com/iamvatsalpatel/tiershift
+Project-URL: Changelog, https://github.com/iamvatsalpatel/tiershift/blob/main/CHANGELOG.md
+Author: Vatsal Patel
+License-Expression: MIT
+Keywords: agents,cost-optimization,jev,llm,model-routing,router,typesafe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typesafe-sdk>=0.6.0
+Description-Content-Type: text/markdown
+
+# tiershift (Python)
+
+**Shift every LLM call to the cheapest model that can handle it.**
+Routing decided by [TypeSafe Jev](https://docs.typesafe.ai) in about 300 ms for $0.00004 per call. No training data. Policy in plain YAML.
+
+This is the Python package. It shares one `tiershift.yaml` format, one `prices.yaml`, and one decision-log format with the [npm package](https://github.com/iamvatsalpatel/tiershift), so `report` and `tune` read logs written by either.
+
+## Install
+
+```bash
+uv add tiershift          # or: pip install tiershift
+export TYPESAFE_API_KEY=...   # get one at typesafe.ai
+```
+
+Provider keys are optional. A tier skips any model whose key is missing. With only [Ollama](https://ollama.com) running, everything routes to the local model and the decision is flagged `degraded=True`.
+
+## Use
+
+```python
+from tiershift import create_router
+
+router = create_router()                        # reads ./tiershift.yaml, else the bundled default
+
+d = router.route(messages, tools=tools, step="plan", retries=0)
+d.model          # "deepseek/deepseek-flash"
+d.tier           # "fast"
+d.fallback       # "openai/gpt-5.6-terra"       use this if the call fails
+d.signals        # Signals(difficulty=0.31, stakes=0.12, needs_reasoning=0.08, ...)
+d.reason         # ['rule "difficulty < 0.5" → fast']
+d.est_cost_usd   # 0.00006
+
+r = router.complete(messages, tools=tools, max_tokens=1024)   # decide, call, fall back one tier up on failure
+r.text, r.model, r.fell_back, r.cost_usd, r.attempts
+```
+
+`route()` calls Jev only. It never calls a provider. `complete()` tries the chosen model, then the fallback one tier up. 4xx validation errors do not trigger a fallback.
+
+Messages are plain dicts with `role` and `content`, the same shape the OpenAI and Anthropic SDKs use. Tools are dicts with `name`, `description`, and `parameters`.
+
+## CLI
+
+```bash
+tiershift check                        # which configured models have keys
+tiershift route "your prompt"          # decide only; Jev call, no model call
+tiershift ask "your prompt"            # decide, call the model, fall back on failure
+tiershift report                       # tier mix, spend, saving vs always-flagship from the log
+tiershift tune --candidate other.yaml  # replay the log against another policy; no API calls
+```
+
+Add `--json` for the full object and `--config path` for a custom policy.
+
+## Configure
+
+Copy `tiershift.yaml` from the [repository](https://github.com/iamvatsalpatel/tiershift/blob/main/tiershift.yaml) into your project and edit. Every threshold is a probability or score from Jev. The format, the available signals, and the provider quirks are documented in the main README.
+
+## Status
+
+v0.1.0. Sync API only. Async `route`/`complete` are planned. The test suite needs no network and includes every shared conformance case from `conformance/`.
+
+## License
+
+MIT

tiershift-0.1.0/README.md

@@ -0,0 +1,62 @@
+# tiershift (Python)
+
+**Shift every LLM call to the cheapest model that can handle it.**
+Routing decided by [TypeSafe Jev](https://docs.typesafe.ai) in about 300 ms for $0.00004 per call. No training data. Policy in plain YAML.
+
+This is the Python package. It shares one `tiershift.yaml` format, one `prices.yaml`, and one decision-log format with the [npm package](https://github.com/iamvatsalpatel/tiershift), so `report` and `tune` read logs written by either.
+
+## Install
+
+```bash
+uv add tiershift          # or: pip install tiershift
+export TYPESAFE_API_KEY=...   # get one at typesafe.ai
+```
+
+Provider keys are optional. A tier skips any model whose key is missing. With only [Ollama](https://ollama.com) running, everything routes to the local model and the decision is flagged `degraded=True`.
+
+## Use
+
+```python
+from tiershift import create_router
+
+router = create_router()                        # reads ./tiershift.yaml, else the bundled default
+
+d = router.route(messages, tools=tools, step="plan", retries=0)
+d.model          # "deepseek/deepseek-flash"
+d.tier           # "fast"
+d.fallback       # "openai/gpt-5.6-terra"       use this if the call fails
+d.signals        # Signals(difficulty=0.31, stakes=0.12, needs_reasoning=0.08, ...)
+d.reason         # ['rule "difficulty < 0.5" → fast']
+d.est_cost_usd   # 0.00006
+
+r = router.complete(messages, tools=tools, max_tokens=1024)   # decide, call, fall back one tier up on failure
+r.text, r.model, r.fell_back, r.cost_usd, r.attempts
+```
+
+`route()` calls Jev only. It never calls a provider. `complete()` tries the chosen model, then the fallback one tier up. 4xx validation errors do not trigger a fallback.
+
+Messages are plain dicts with `role` and `content`, the same shape the OpenAI and Anthropic SDKs use. Tools are dicts with `name`, `description`, and `parameters`.
+
+## CLI
+
+```bash
+tiershift check                        # which configured models have keys
+tiershift route "your prompt"          # decide only; Jev call, no model call
+tiershift ask "your prompt"            # decide, call the model, fall back on failure
+tiershift report                       # tier mix, spend, saving vs always-flagship from the log
+tiershift tune --candidate other.yaml  # replay the log against another policy; no API calls
+```
+
+Add `--json` for the full object and `--config path` for a custom policy.
+
+## Configure
+
+Copy `tiershift.yaml` from the [repository](https://github.com/iamvatsalpatel/tiershift/blob/main/tiershift.yaml) into your project and edit. Every threshold is a probability or score from Jev. The format, the available signals, and the provider quirks are documented in the main README.
+
+## Status
+
+v0.1.0. Sync API only. Async `route`/`complete` are planned. The test suite needs no network and includes every shared conformance case from `conformance/`.
+
+## License
+
+MIT

tiershift-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "tiershift"
+version = "0.1.0"
+description = "Shift every LLM call to the cheapest model that can handle it. Routing decided by TypeSafe Jev in ~300 ms. No training data. Policy in plain YAML."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Vatsal Patel" }]
+requires-python = ">=3.10"
+keywords = ["llm", "router", "model-routing", "agents", "typesafe", "jev", "cost-optimization"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "typesafe-sdk>=0.6.0",
+  "pyyaml>=6.0",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/iamvatsalpatel/tiershift"
+Repository = "https://github.com/iamvatsalpatel/tiershift"
+Changelog = "https://github.com/iamvatsalpatel/tiershift/blob/main/CHANGELOG.md"
+
+[project.scripts]
+tiershift = "tiershift.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tiershift"]
+
+[tool.hatch.build.targets.sdist]
+include = ["tiershift", "tests", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["live: calls the real TypeSafe or Ollama API; runs only with RUN_LIVE=1"]
+asyncio_mode = "auto"

tiershift-0.1.0/tests/conftest.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import yaml
+
+ROOT = Path(__file__).resolve().parents[2]
+CONFORMANCE = ROOT / "conformance"
+
+
+@pytest.fixture(scope="session")
+def conformance_fixture() -> dict:
+    """The whole cases.json: top-level `policy` plus `cases`, each of which may name its own `policy`."""
+    return json.loads((CONFORMANCE / "cases.json").read_text())
+
+
+@pytest.fixture(scope="session")
+def load_policy():
+    cache: dict[str, dict] = {}
+
+    def _load(name: str) -> dict:
+        if name not in cache:
+            cache[name] = yaml.safe_load((CONFORMANCE / name).read_text())
+        return cache[name]
+    return _load
+
+
+@pytest.fixture(scope="session")
+def conformance_policy(conformance_fixture, load_policy) -> dict:
+    return load_policy(conformance_fixture["policy"])
+
+
+@pytest.fixture(scope="session")
+def conformance_cases(conformance_fixture) -> list[dict]:
+    return conformance_fixture["cases"]
+
+
+@pytest.fixture(scope="session")
+def conformance_log_entry() -> dict:
+    return json.loads((CONFORMANCE / "log-entry.json").read_text())
+
+
+@pytest.fixture(scope="session")
+def repo_root() -> Path:
+    return ROOT

tiershift-0.1.0/tests/test_config.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import pytest
+
+import copy
+
+from tiershift import DEFAULT_JEV_MODEL, available_tiers, load_config, load_prices, merge_model_meta, split_model, validate
+
+
+def test_bundled_default_loads_and_merges_prices():
+    cfg = load_config()
+    assert "tiers" in cfg and "flagship" in cfg["tiers"]
+    # a models: override that only sets params keeps the bundled price
+    flash = cfg["models"]["deepseek/deepseek-flash"]
+    assert flash.get("params") and "price" in flash
+
+
+def test_load_prices_has_entries():
+    prices = load_prices()
+    assert "anthropic/claude-fable-5-1" in prices
+    assert prices["anthropic/claude-fable-5-1"]["price"]["input"] > 0
+
+
+def test_merge_model_meta():
+    bundled = {"a/x": {"price": {"input": 1, "output": 2}, "context": 1000}}
+    m = merge_model_meta(bundled, {"a/x": {"params": {"k": 1}}, "b/y": {"context": 8}})
+    assert m["a/x"] == {"price": {"input": 1, "output": 2}, "context": 1000, "params": {"k": 1}}
+    assert m["b/y"] == {"context": 8}
+    assert bundled["a/x"] == {"price": {"input": 1, "output": 2}, "context": 1000}  # not mutated
+
+
+def test_split_model():
+    assert split_model("ollama/qwen2.5:7b") == ("ollama", "qwen2.5:7b")
+    assert split_model("openrouter/anthropic/claude-sonnet-5") == ("openrouter", "anthropic/claude-sonnet-5")
+    with pytest.raises(ValueError, match="provider/model"):
+        split_model("nope")
+
+
+class TestValidate:
+    BASE = {"providers": {"p": {"type": "openai-compatible"}}, "tiers": {"t": ["p/m"]}, "rules": [{"default": "t"}]}
+
+    def test_minimal_ok(self):
+        validate(self.BASE)
+
+    def test_unknown_provider(self):
+        with pytest.raises(ValueError, match='unknown provider "zzz"'):
+            validate({**self.BASE, "tiers": {"t": ["zzz/m"]}})
+
+    def test_empty_sections(self):
+        with pytest.raises(ValueError, match="rules"):
+            validate({**self.BASE, "rules": []})
+        with pytest.raises(ValueError, match="tiers"):
+            validate({**self.BASE, "tiers": {}})
+        with pytest.raises(ValueError, match="providers"):
+            validate({**self.BASE, "providers": {}})
+
+
+def test_available_tiers():
+    cfg = {"providers": {"a": {"type": "anthropic", "api_key_env": "A_KEY"}, "o": {"type": "openai-compatible"}}, "tiers": {"fast": ["a/x", "o/y"], "top": ["a/z"]}, "rules": [{"default": "top"}]}
+    assert available_tiers(cfg, {}) == {"fast": ["o/y"], "top": ["a/z"]}
+    assert available_tiers(cfg, {"A_KEY": "k"}) == {"fast": ["a/x", "o/y"], "top": ["a/z"]}
+
+
+def test_cli_common_flags_in_either_position(tmp_path, capsys):
+    from tiershift.cli import main
+    cfg = tmp_path / "only.yaml"
+    cfg.write_text("providers:\n  o: { type: openai-compatible, base_url: http://localhost:1/v1 }\ntiers:\n  local: [o/m]\nrules:\n  - { default: local }\nlog: { enabled: false }\n")
+    assert main(["--config", str(cfg), "check"]) == 0
+    before = capsys.readouterr().out
+    assert main(["check", "--config", str(cfg)]) == 0
+    after = capsys.readouterr().out
+    assert before == after and "o/m" in before and "flagship" not in before
+
+
+def _ok() -> dict:
+    return copy.deepcopy({
+        "providers": {"p": {"type": "openai-compatible", "base_url": "http://localhost:1/v1"}},
+        "tiers": {"local": ["p/l"], "fast": ["p/f"], "mid": ["p/m"], "flagship": ["p/x"]},
+        "rules": [{"when": "trivial_ack > 0.8", "tier": "local"}, {"when": "difficulty < 0.5", "tier": "fast"}, {"default": "flagship"}],
+        "overrides": [{"when": "stakes > 1.5", "at_least": "flagship"}, {"when": "mid_tier_ok > 0.8", "at_most": "mid"}, {"when": "retries >= 1", "up": 1}],
+    })
+
+
+class TestLoadTimeValidation:
+    def test_accepts_full_policy(self):
+        validate(_ok())
+
+    def test_misspelled_signal_names_location_and_suggests(self):
+        c = _ok(); c["overrides"][1] = {"when": "difficlty > 1", "at_most": "mid"}
+        with pytest.raises(ValueError) as ei:
+            validate(c)
+        assert str(ei.value) == 'config: overrides[1].when: unknown signal "difficlty" (did you mean "difficulty"?)'
+
+    def test_unparsable_condition_quoted(self):
+        c = _ok(); c["rules"][0]["when"] = "difficulty <> 0.5"
+        with pytest.raises(ValueError, match=r'config: rules\[0\]\.when: cannot parse "difficulty <> 0.5"'):
+            validate(c)
+
+    def test_unknown_tiers_everywhere_with_suggestion(self):
+        c = _ok(); c["rules"][1]["tier"] = "fsat"
+        with pytest.raises(ValueError) as ei:
+            validate(c)
+        assert str(ei.value).startswith('config: rules[1].tier: unknown tier "fsat" (did you mean "fast"?)')
+        c = _ok(); c["rules"][2] = {"default": "flagshp"}
+        with pytest.raises(ValueError, match=r'rules\[2\]\.default: unknown tier "flagshp"'):
+            validate(c)
+        c = _ok(); c["overrides"][0]["at_least"] = "top"
+        with pytest.raises(ValueError, match=r'overrides\[0\]\.at_least: unknown tier "top"'):
+            validate(c)
+        c = _ok(); c["overrides"][1]["at_most"] = "midd"
+        with pytest.raises(ValueError) as ei2:
+            validate(c)
+        assert str(ei2.value).startswith('config: overrides[1].at_most: unknown tier "midd" (did you mean "mid"?)')
+
+    def test_bad_up(self):
+        for bad in (0, -1, 1.5, True):
+            c = _ok(); c["overrides"][2] = {"when": "retries >= 1", "up": bad}
+            with pytest.raises(ValueError, match=r"overrides\[2\]\.up: must be a positive integer"):
+                validate(c)
+
+    def test_rule_shape(self):
+        c = _ok(); c["rules"][0] = {"when": "difficulty < 0.5"}
+        with pytest.raises(ValueError, match=r"rules\[0\]: a rule needs both `when` and `tier`, or a single `default`"):
+            validate(c)
+        c = _ok(); c["rules"] = [{"default": "flagship"}, {"when": "difficulty < 0.5", "tier": "fast"}]
+        with pytest.raises(ValueError, match=r"rules\[0\]: `default` must be the last rule"):
+            validate(c)
+        c = _ok(); c["rules"][2] = {"default": "flagship", "when": "difficulty < 0.5"}
+        with pytest.raises(ValueError, match=r"rules\[2\]: a `default` rule cannot also have `when` or `tier`"):
+            validate(c)
+
+    def test_override_without_action(self):
+        c = _ok(); c["overrides"][0] = {"when": "stakes > 1.5"}
+        with pytest.raises(ValueError, match=r"overrides\[0\]: needs one of `at_least`, `at_most`, or `up`"):
+            validate(c)
+
+    def test_bad_enums_and_min_output_tokens(self):
+        with pytest.raises(ValueError, match=r"budget\.prefer"):
+            validate({**_ok(), "budget": {"prefer": "random"}})
+        with pytest.raises(ValueError, match=r'fallback: must be "up" or "none"'):
+            validate({**_ok(), "fallback": "sideways"})
+        with pytest.raises(ValueError, match=r"defaults\.min_output_tokens"):
+            validate({**_ok(), "defaults": {"min_output_tokens": -5}})
+
+    def test_unknown_provider_suggests(self):
+        c = _ok(); c["tiers"]["fast"] = ["q/f"]
+        with pytest.raises(ValueError) as ei:
+            validate(c)
+        assert str(ei.value) == 'config: tiers.fast: model "q/f" uses unknown provider "q" (did you mean "p"?)'
+
+    def test_bad_provider_type(self):
+        c = _ok(); c["providers"]["p"]["type"] = "grpc"
+        with pytest.raises(ValueError, match=r"providers\.p: `type` must be"):
+            validate(c)
+
+    def test_bundled_default_and_examples_validate(self):
+        load_config()
+        load_config(str(__import__("pathlib").Path(__file__).resolve().parents[2] / "examples" / "policies" / "bolder.yaml"))
+        load_config(str(__import__("pathlib").Path(__file__).resolve().parents[2] / "conformance" / "policy-at-most.yaml"))
+
+
+def test_pinned_jev_model_default():
+    from tiershift import Router
+    r = Router(config={**_ok(), "log": {"enabled": False}}, env={}, log=False)
+    assert r._jev_model == DEFAULT_JEV_MODEL == "jev-1.13.0"
+    r2 = Router(config={**_ok(), "log": {"enabled": False}, "jev": {"model": "jev-9.9.9"}}, env={}, log=False)
+    assert r2._jev_model == "jev-9.9.9"

tiershift-0.1.0/tests/test_conformance.py

@@ -0,0 +1,50 @@
+"""The Python side of the cross-language contract in conformance/."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from tiershift import CodeSignals, Signals, apply_policy, validate
+from tiershift.log import LOG_FIELDS
+
+pytestmark = pytest.mark.usefixtures("conformance_policy")
+
+
+def test_fixture_policies_validate(conformance_fixture, conformance_cases, load_policy):
+    for name in {conformance_fixture["policy"], *(c["policy"] for c in conformance_cases if "policy" in c)}:
+        validate(load_policy(name))
+
+
+def test_all_cases(conformance_fixture, conformance_cases, load_policy):
+    failures = []
+    for c in conformance_cases:
+        policy = load_policy(c.get("policy", conformance_fixture["policy"]))
+        r = apply_policy(policy, Signals.from_dict(c["signals"]), CodeSignals.from_dict(c["code_signals"]))
+        if r.tier != c["expected_tier"]:
+            failures.append(f'{c["name"]}: tier {r.tier!r} != {c["expected_tier"]!r}')
+        for frag in c["reason_contains"]:
+            if frag not in "\n".join(r.reason):
+                failures.append(f'{c["name"]}: reason {r.reason!r} lacks {frag!r}')
+    assert not failures, "\n".join(failures)
+    assert len(conformance_cases) >= 24
+
+
+def test_log_entry_shape(conformance_log_entry):
+    for k in LOG_FIELDS:
+        assert k in conformance_log_entry, f"missing {k}"
+    assert sorted(conformance_log_entry["signals"]) == sorted(Signals.__dataclass_fields__)
+    assert sorted(conformance_log_entry["code_signals"]) == sorted(CodeSignals.__dataclass_fields__)
+    # round-trips through our dataclasses without loss
+    assert Signals.from_dict(conformance_log_entry["signals"]).to_dict() == conformance_log_entry["signals"]
+    assert json.loads(json.dumps(conformance_log_entry)) == conformance_log_entry
+
+
+def test_bundled_yaml_copies_match_repo_root(repo_root):
+    """The package ships copies of the root tiershift.yaml and prices.yaml. Drift fails here."""
+    from importlib import resources
+    for name in ("tiershift.yaml", "prices.yaml"):
+        bundled = resources.files("tiershift").joinpath("data", name).read_bytes()
+        root = (repo_root / name).read_bytes()
+        assert bundled == root, f"python/tiershift/data/{name} differs from the repo root {name}; copy it again"

tiershift-0.1.0/tests/test_live.py

@@ -0,0 +1,17 @@
+"""Opt-in live checks. Jev only (fraction of a cent) and Ollama. Never OpenAI, DeepSeek, or Anthropic."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+live = pytest.mark.skipif(not (os.environ.get("RUN_LIVE") == "1" and os.environ.get("TYPESAFE_API_KEY")), reason="set RUN_LIVE=1 and TYPESAFE_API_KEY")
+
+
+@live
+def test_route_live_jev_only():
+    from tiershift import create_router
+    r = create_router(env={"TYPESAFE_API_KEY": os.environ["TYPESAFE_API_KEY"]}, log=False)
+    d = r.route([{"role": "user", "content": "ok thanks"}])
+    assert d.signals.trivial_ack > 0.5 and d.jev_latency_ms > 0 and d.jev_input_tokens > 0

tiershift-0.1.0/tests/test_log_analytics.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from tiershift import CodeSignals, Decision, Signals, build_report, from_decision, log_entry, read_log, tune
+
+SIG = dict(difficulty=1.0, difficulty_confidence=0.8, needs_reasoning=0.5, stakes=0.2, stakes_confidence=0.9, domain="code", domain_confidence=0.9, has_code=0.9, ambiguous=0.1, output_length=1.0, creative=0.0, safety_sensitive=0.0, trivial_ack=0.0, mid_tier_ok=0.3)
+CODE = dict(est_input_tokens=1000, has_tools=False, tool_count=0, step=None, retries=0, turn_count=1)
+CFG = {
+    "providers": {"p": {"type": "openai-compatible"}},
+    "tiers": {"local": ["p/l"], "fast": ["p/f"], "mid": ["p/m"], "flagship": ["p/x"]},
+    "rules": [{"when": "trivial_ack > 0.8", "tier": "local"}, {"when": "difficulty < 0.5", "tier": "fast"}, {"when": "difficulty < 1.3", "tier": "mid"}, {"default": "flagship"}],
+    "overrides": [{"when": "stakes > 1.5", "at_least": "flagship"}],
+    "models": {"p/l": {"price": {"input": 0, "output": 0}}, "p/f": {"price": {"input": 0.2, "output": 1}}, "p/m": {"price": {"input": 2, "output": 10}}, "p/x": {"price": {"input": 10, "output": 50}}},
+}
+
+
+def decision(**over) -> Decision:
+    base = dict(model="p/m", provider="p", tier="mid", tier_index=2, requested_tier="mid", degraded=False, fallback="p/x", signals=Signals(**SIG), code_signals=CodeSignals(**CODE),
+                confidence=0.8, reason=['rule "difficulty < 1.3" → mid'], est_cost_usd=0.004, est_output_tokens=400, jev_latency_ms=210, jev_input_tokens=950)
+    base.update(over)
+    return Decision(**base)
+
+
+def entry(tier, model, difficulty, kind="route", **over):
+    e = from_decision(decision(model=model, tier=tier, requested_tier=tier, signals=Signals(**{**SIG, "difficulty": difficulty})), kind, **over)
+    e["ts"] = "2026-09-17T00:00:00.000Z"
+    return e
+
+
+def test_log_round_trip(tmp_path: Path):
+    path = tmp_path / "nested" / "d.jsonl"
+    log_entry(str(path), from_decision(decision(), "route", tag="agent-a"))
+    log_entry(str(path), from_decision(decision(), "complete", cost_usd=0.0031, input_tokens=100, output_tokens=50, model_latency_ms=900))
+    rows = read_log(str(path))
+    assert len(rows) == 2
+    assert rows[0]["kind"] == "route" and rows[0]["tag"] == "agent-a" and rows[0]["cost_usd"] is None and rows[0]["est_cost_usd"] == 0.004
+    assert rows[1]["kind"] == "complete" and rows[1]["output_tokens"] == 50
+    assert "prompt" not in json.dumps(rows[0])
+    assert read_log(str(tmp_path / "missing.jsonl")) == []
+
+
+def test_build_report():
+    entries = [entry("fast", "p/f", 0.2, est_cost_usd=0.0006), entry("fast", "p/f", 0.3, est_cost_usd=0.0006), entry("flagship", "p/x", 1.9, est_cost_usd=0.03, reason=['override "stakes > 1.5" → at_least flagship'])]
+    r = build_report(entries, CFG)
+    assert r.n == 3
+    assert next(t for t in r.tiers if t.tier == "fast").n == 2
+    assert next(t for t in r.tiers if t.tier == "flagship").share == pytest.approx(1 / 3)
+    assert r.total_cost == pytest.approx(0.0312)
+    assert r.flagship_est_cost == pytest.approx(0.09)  # 1000 in * $10 + 400 out * $50 per 1M, times 3
+    assert r.saving_vs_flagship == pytest.approx(1 - 0.0312 / 0.09)
+    assert r.overrides[0] == {"reason": 'override "stakes > 1.5"', "n": 1}
+    assert r.jev["p50_ms"] == 210
+
+
+def test_report_prefers_actual_cost_and_handles_empty():
+    r = build_report([entry("mid", "p/m", 1.0, kind="complete", est_cost_usd=0.01, cost_usd=0.02)], CFG)
+    assert r.total_cost == pytest.approx(0.02)
+    empty = build_report([], CFG)
+    assert empty.n == 0 and empty.saving_vs_flagship is None
+
+
+def test_report_estimate_check_per_tier():
+    r = build_report([entry("mid", "p/m", 1.0, kind="complete", est_cost_usd=0.01, cost_usd=0.02), entry("mid", "p/m", 1.0, est_cost_usd=0.01)], CFG)
+    mid = next(t for t in r.tiers if t.tier == "mid")
+    assert mid.estimate_check == {"n": 1, "est": 0.01, "actual": 0.02, "ratio": 0.5}
+    assert next(t for t in r.tiers if t.tier == "fast").estimate_check is None
+
+
+def test_report_uses_supplied_available_tiers_for_baseline():
+    r = build_report([entry("mid", "p/m", 1.0)], CFG, tiers={**CFG["tiers"], "flagship": ["p/m"]})
+    assert r.flagship_model == "p/m"
+
+
+def test_tune_moves_and_saving():
+    entries = [entry("mid", "p/m", 0.9), entry("mid", "p/m", 1.1), entry("flagship", "p/x", 1.5), entry("flagship", "p/x", 1.9)]
+    bolder = {**CFG, "rules": [{"when": "trivial_ack > 0.8", "tier": "local"}, {"when": "difficulty < 0.5", "tier": "fast"}, {"when": "difficulty < 1.6", "tier": "mid"}, {"default": "flagship"}]}
+    t = tune(entries, CFG, bolder)
+    assert t.baseline["tiers"] == {"local": 0, "fast": 0, "mid": 2, "flagship": 2}
+    assert t.candidate["tiers"] == {"local": 0, "fast": 0, "mid": 3, "flagship": 1}
+    assert (t.moved_down, t.moved_up, t.unchanged) == (1, 0, 3)
+    assert t.moves[0]["from"] == "flagship" and t.moves[0]["to"] == "mid" and t.moves[0]["difficulty"] == 1.5
+    assert t.saving is not None and t.saving > 0
+
+
+def test_tune_held_by_override():
+    e = entry("flagship", "p/x", 1.5)
+    e["signals"]["difficulty_confidence"] = 0.3
+    with_low = {**CFG, "overrides": [{"when": "difficulty_confidence < 0.5", "up": 1}]}
+    bolder = {**with_low, "rules": [{"when": "difficulty < 1.6", "tier": "mid"}, {"default": "flagship"}]}
+    t = tune([e], with_low, bolder)
+    assert t.unchanged == 1 and t.held_by_override == 1