roadmodel 0.2.71__tar.gz → 0.2.73__tar.gz

{roadmodel-0.2.71 → roadmodel-0.2.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roadmodel
-Version: 0.2.71
+Version: 0.2.73
 Summary: BYO-key CLI that recommends the right AI model, platform, and settings for a prompt.
 Project-URL: Homepage, https://roadmodel.ai
 Project-URL: Repository, https://github.com/nathanramoscfa/roadmodel

{roadmodel-0.2.71/roadmodel/data → roadmodel-0.2.73/docs}/catalog.json

@@ -1,9 +1,9 @@
 {
   "schema_version": "4",
   "output_contract_version": 2,
-  "generated_at_utc": "2026-10-07T15:54:22Z",
+  "generated_at_utc": "2026-10-07T19:13:30Z",
   "source_doc_sha256": {
-    "model-selector.txt": "1608924122bce175e39dcf85f17cb371738164d5c5e171de2568a87ecc794395",
+    "model-selector.txt": "6a75e2265459fa7302cb80d0faf5ec2aad575034fc29866238cd1579c001cc2d",
     "model-tier-cost-scale.md": "2b3b0eb82237eb5cb5bf468a3fe971bcaf0160ad7d0bc700698d2c16640bc41d"
   },
   "models": [

roadmodel-0.2.73/docs/context-windows.json

@@ -0,0 +1,60 @@
+{
+  "_comment": "Each catalogued model's context window in tokens: OpenRouter's context_length, the largest of its routes (update/extract_openrouter_models.py --context-windows, run by the catalog cron). A surface may cap a model lower.",
+  "source": "https://openrouter.ai/api/v1/models",
+  "models": {
+    "claude-4.5-haiku": 200000,
+    "claude-fable-5": 1000000,
+    "claude-fable-5.1": 1000000,
+    "claude-opus-5": 1000000,
+    "claude-opus-5-5": 1000000,
+    "claude-sonnet-5": 1000000,
+    "claude-sonnet-5-5": 1000000,
+    "codestral": 256000,
+    "deepseek-flash": 1048576,
+    "deepseek-v4-pro": 1048576,
+    "gemini-2.5-flash": 1048576,
+    "gemini-3-flash": 1048576,
+    "gemini-3.1-pro": 1048576,
+    "gemini-3.5-flash": 1048576,
+    "gemini-3.6-flash": 1048576,
+    "gemini-3.7-flash": 1048576,
+    "gemini-3.8-flash": 1048576,
+    "glm-4.5-air": 131072,
+    "glm-4.6": 204800,
+    "glm-5.2": 1048576,
+    "glm-5.3": 1048576,
+    "glm-5.3-flash": 1048576,
+    "gpt-5": 400000,
+    "gpt-5-mini": 400000,
+    "gpt-5.1-codex": 400000,
+    "gpt-5.1-codex-max": 400000,
+    "gpt-5.1-codex-mini": 400000,
+    "gpt-5.2": 400000,
+    "gpt-5.2-codex": 400000,
+    "gpt-5.3-codex": 400000,
+    "gpt-5.4": 1050000,
+    "gpt-5.4-mini": 400000,
+    "gpt-5.4-nano": 400000,
+    "gpt-5.5": 1050000,
+    "gpt-5.6-luna": 1050000,
+    "gpt-5.6-sol": 1050000,
+    "gpt-5.6-terra": 1050000,
+    "gpt-6-astra": 1050000,
+    "gpt-6-luna": 1050000,
+    "gpt-6-sol": 1050000,
+    "gpt-6.1-sol": 1050000,
+    "gpt-oss-120b": 131072,
+    "gpt-oss-20b": 131072,
+    "grok-4.3": 1000000,
+    "grok-4.6": 500000,
+    "grok-4.7": 500000,
+    "kimi-k2.7-code": 262144,
+    "kimi-k3": 1048576,
+    "mistral-medium-3.5": 262144,
+    "mistral-small-4": 262144,
+    "muse-spark-1.3": 1048576,
+    "opus-4.7": 1000000,
+    "opus-4.8": 1000000,
+    "sonnet-4.6": 1000000
+  }
+}

{roadmodel-0.2.71 → roadmodel-0.2.73}/docs/model-selector.txt

@@ -469,6 +469,11 @@
       `claude agents` to a busy background session now applies right
       away. 2.1.291 is a hotfix for two regressions. Neither release
       changes the `/effort` vocabulary or the extended-thinking controls.
+      2.1.292 adds an `effort` parameter to the Agent tool, so a sub-agent
+      runs at the effort level you ask for. It also fixes cloud sessions
+      forgetting the client's thinking setting after a container restart.
+      The `/effort` vocabulary and the extended-thinking controls are
+      unchanged.
     - OpenAI (Codex, OpenAI API, ChatGPT advanced controls):
       `reasoning_effort` knob — `low`, `medium`, `high`, `xhigh`, `max`,
       `ultra`. Codex's plan-mode `plan_mode_reasoning_effort` variant

{roadmodel-0.2.71 → roadmodel-0.2.73}/hatch_build.py

@@ -37,6 +37,7 @@ BUNDLED_DOCS: dict[str, str] = {
     "user-context.example.md": "user-context.example.md",
     "catalog.json": "catalog.json",
     "benchmarks.json": "benchmarks.json",
+    "context-windows.json": "context-windows.json",
     "templates/phase-roadmap-template.md": "phase-roadmap-template.md",
     "templates/project-roadmap-template.md": "project-roadmap-template.md",
     "templates/planning-kit-how-to-use.md": "planning-kit-how-to-use.md",

{roadmodel-0.2.71 → roadmodel-0.2.73}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roadmodel"
-version = "0.2.71"
+version = "0.2.73"
 description = "BYO-key CLI that recommends the right AI model, platform, and settings for a prompt."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -91,6 +91,7 @@ include = [
     "docs/user-context.example.md",
     "docs/catalog.json",
     "docs/benchmarks.json",
+    "docs/context-windows.json",
     "scripts/update_projects.py",
     "scripts/agent_context.py",
     "scripts/agent_rules.py",

{roadmodel-0.2.71/docs → roadmodel-0.2.73/roadmodel/data}/catalog.json

@@ -1,9 +1,9 @@
 {
   "schema_version": "4",
   "output_contract_version": 2,
-  "generated_at_utc": "2026-10-07T15:54:22Z",
+  "generated_at_utc": "2026-10-07T19:13:30Z",
   "source_doc_sha256": {
-    "model-selector.txt": "1608924122bce175e39dcf85f17cb371738164d5c5e171de2568a87ecc794395",
+    "model-selector.txt": "6a75e2265459fa7302cb80d0faf5ec2aad575034fc29866238cd1579c001cc2d",
     "model-tier-cost-scale.md": "2b3b0eb82237eb5cb5bf468a3fe971bcaf0160ad7d0bc700698d2c16640bc41d"
   },
   "models": [

roadmodel-0.2.73/roadmodel/data/context-windows.json

@@ -0,0 +1,60 @@
+{
+  "_comment": "Each catalogued model's context window in tokens: OpenRouter's context_length, the largest of its routes (update/extract_openrouter_models.py --context-windows, run by the catalog cron). A surface may cap a model lower.",
+  "source": "https://openrouter.ai/api/v1/models",
+  "models": {
+    "claude-4.5-haiku": 200000,
+    "claude-fable-5": 1000000,
+    "claude-fable-5.1": 1000000,
+    "claude-opus-5": 1000000,
+    "claude-opus-5-5": 1000000,
+    "claude-sonnet-5": 1000000,
+    "claude-sonnet-5-5": 1000000,
+    "codestral": 256000,
+    "deepseek-flash": 1048576,
+    "deepseek-v4-pro": 1048576,
+    "gemini-2.5-flash": 1048576,
+    "gemini-3-flash": 1048576,
+    "gemini-3.1-pro": 1048576,
+    "gemini-3.5-flash": 1048576,
+    "gemini-3.6-flash": 1048576,
+    "gemini-3.7-flash": 1048576,
+    "gemini-3.8-flash": 1048576,
+    "glm-4.5-air": 131072,
+    "glm-4.6": 204800,
+    "glm-5.2": 1048576,
+    "glm-5.3": 1048576,
+    "glm-5.3-flash": 1048576,
+    "gpt-5": 400000,
+    "gpt-5-mini": 400000,
+    "gpt-5.1-codex": 400000,
+    "gpt-5.1-codex-max": 400000,
+    "gpt-5.1-codex-mini": 400000,
+    "gpt-5.2": 400000,
+    "gpt-5.2-codex": 400000,
+    "gpt-5.3-codex": 400000,
+    "gpt-5.4": 1050000,
+    "gpt-5.4-mini": 400000,
+    "gpt-5.4-nano": 400000,
+    "gpt-5.5": 1050000,
+    "gpt-5.6-luna": 1050000,
+    "gpt-5.6-sol": 1050000,
+    "gpt-5.6-terra": 1050000,
+    "gpt-6-astra": 1050000,
+    "gpt-6-luna": 1050000,
+    "gpt-6-sol": 1050000,
+    "gpt-6.1-sol": 1050000,
+    "gpt-oss-120b": 131072,
+    "gpt-oss-20b": 131072,
+    "grok-4.3": 1000000,
+    "grok-4.6": 500000,
+    "grok-4.7": 500000,
+    "kimi-k2.7-code": 262144,
+    "kimi-k3": 1048576,
+    "mistral-medium-3.5": 262144,
+    "mistral-small-4": 262144,
+    "muse-spark-1.3": 1048576,
+    "opus-4.7": 1000000,
+    "opus-4.8": 1000000,
+    "sonnet-4.6": 1000000
+  }
+}

{roadmodel-0.2.71 → roadmodel-0.2.73}/roadmodel/data/model-selector.txt

@@ -469,6 +469,11 @@
       `claude agents` to a busy background session now applies right
       away. 2.1.291 is a hotfix for two regressions. Neither release
       changes the `/effort` vocabulary or the extended-thinking controls.
+      2.1.292 adds an `effort` parameter to the Agent tool, so a sub-agent
+      runs at the effort level you ask for. It also fixes cloud sessions
+      forgetting the client's thinking setting after a container restart.
+      The `/effort` vocabulary and the extended-thinking controls are
+      unchanged.
     - OpenAI (Codex, OpenAI API, ChatGPT advanced controls):
       `reasoning_effort` knob — `low`, `medium`, `high`, `xhigh`, `max`,
       `ultra`. Codex's plan-mode `plan_mode_reasoning_effort` variant

{roadmodel-0.2.71 → roadmodel-0.2.73}/src/roadmodel/__init__.py

@@ -1,2 +1,2 @@
 # src/roadmodel/__init__.py
-__version__ = "0.2.71"
+__version__ = "0.2.73"

{roadmodel-0.2.71 → roadmodel-0.2.73}/src/roadmodel/recommend.py

@@ -485,7 +485,10 @@ _SAAS_LADDER_TABLE_HEADER: Final = (
     "standard derivation) is `routine` however many steps it takes, and its "
     "complexity is how hard that known result is to reproduce. Planning, "
     "architecture, security hardening, design and refactors are `routine` at any "
-    "difficulty, as is every other task.\n"
+    "difficulty, as is every other task. When the task says how much material the "
+    "model must read (pages, words, lines of code, files), the next line is "
+    "`INPUT: <n> tokens`, your estimate of that material at about 600 tokens per "
+    "page, 1.3 per word and 10 per line of code; leave the line out otherwise.\n"
     "2. Three blocks per the <output-format> 'Ladder mode' spec: TIER: QUALITY, "
     "TIER: BALANCED and TIER: COST, in that order.\n\n"
     "Obey strictly:\n"
@@ -671,6 +674,26 @@ _CLASSIFICATION_RE: Final = re.compile(
 )
 
 
+# The table-mode ladder's optional size line, after CLASSIFICATION:
+# `INPUT: 240000 tokens` (also `~240k tokens`, `240,000 tokens`).
+_INPUT_RE: Final = re.compile(
+    r"^[ \t]*INPUT:[ \t]*~?[ \t]*(?P<n>\d[\d,_]*(?:\.\d+)?)[ \t]*(?P<unit>[km])?[ \t]*tokens?\b",
+    flags=re.IGNORECASE | re.MULTILINE,
+)
+
+
+def parse_input_tokens(text: str) -> int | None:
+    """The size in tokens of the material a table-mode response says the task
+    gives the model to read (its INPUT line), or None when it declares none."""
+    match = _INPUT_RE.search(text)
+    if not match:
+        return None
+    value = float(match.group("n").replace(",", "").replace("_", ""))
+    scale = {"k": 1_000, "m": 1_000_000}.get((match.group("unit") or "").lower(), 1)
+    tokens = int(value * scale)
+    return tokens if tokens > 0 else None
+
+
 def parse_classification(text: str) -> str | None:
     """The ladder-table key (``scoring.table_key``) a table-mode response
     declares on its CLASSIFICATION line, or None when it declares none or names
@@ -781,7 +804,9 @@ def recommend_ladder(
 
     With ``ladder_table`` (scoring.render_ladder_table) the engine copies the
     picks from the table instead of choosing them, and each base dict carries
-    the ``classification`` key the response declared, when it declared one."""
+    the ``classification`` key the response declared, when it declared one,
+    and ``input_tokens``, the size of the task's material its INPUT line
+    declared."""
     resolved_user_context = (
         user_context_text
         if user_context_text is not None
@@ -807,9 +832,12 @@ def recommend_ladder(
     )
     parsed = parse_ladder_response(raw_response)
     classification = parse_classification(raw_response) if ladder_table else None
-    if classification:
-        for base in parsed.values():
+    input_tokens = parse_input_tokens(raw_response) if ladder_table else None
+    for base in parsed.values():
+        if classification:
             base["classification"] = classification
+        if input_tokens:
+            base["input_tokens"] = str(input_tokens)
     return parsed
 
 
@@ -1450,6 +1478,38 @@ def _ladder_table_for(
         return {}
 
 
+def _fit_row_to_input(
+    row: scoring.Ladder,
+    input_tokens: int,
+    scoring_text: str,
+    unavailable_models: list[str] | None,
+) -> tuple[scoring.Ladder, dict[str, Any]]:
+    """The row with every model whose context window cannot hold the task's
+    material left out (scoring.too_small_for), and what the check found. The
+    table is computed before the engine reads the task, so the row is
+    recomputed here when a model its frontier draws on is too small. When the
+    material is larger than every known window, or none left fits, the row
+    stands and ``fits`` says so."""
+    small = set(scoring.too_small_for(input_tokens))
+    drawn = {p.candidate.model_id for p in [*row.frontier, *row.points]}
+    excluded = sorted(small & drawn)
+    report: dict[str, Any] = {"input_tokens": input_tokens, "excluded": excluded, "fits": True}
+    if scoring.nothing_fits(input_tokens):
+        # Larger than every known window: no pick holds it, and one whose
+        # window is unknown would stand only by default.
+        report["fits"] = False
+        return row, report
+    if not excluded:
+        return row, report
+    refit = scoring.ladder(
+        row.task, scoring_text, unavailable_models=[*(unavailable_models or []), *sorted(small)]
+    )
+    if refit is None:
+        report["fits"] = False
+        return row, report
+    return refit, report
+
+
 def recommend_structured_ladder(
     prompt: str,
     config: Config,
@@ -1521,10 +1581,17 @@ def recommend_structured_ladder(
         ladder_table=scoring.render_ladder_table(table) or None,
     )
     frontier_guard: dict[str, Any] | None = None
+    fitted: scoring.Ladder | None = None
     if table:
         key, found = _table_row_key(ladder, table)
         if key is not None:
             row = table[key]
+            context: dict[str, Any] | None = None
+            tokens = next(
+                (int(b["input_tokens"]) for b in ladder.values() if b.get("input_tokens")), None
+            )
+            if tokens is not None and scoring_text is not None:
+                row, context = _fit_row_to_input(row, tokens, scoring_text, unavailable_models)
             frontier_guard = {
                 "mode": "frontier",
                 "classification": key,
@@ -1538,11 +1605,14 @@ def recommend_structured_ladder(
                     if row.rungs["quality"].specialist
                     else None
                 ),
+                "context": context,
             }
+            fitted = row
         else:
             frontier_guard = {"mode": "frontier", "classification": None, "found": found}
     for base in ladder.values():
         base.pop("classification", None)
+        base.pop("input_tokens", None)
     picks = {
         tier: _base_to_payload(
             ladder[tier],
@@ -1551,9 +1621,9 @@ def recommend_structured_ladder(
         )
         for tier in _LADDER_TIERS
     }
-    if frontier_guard is not None and frontier_guard["classification"] is not None:
-        _attach_backup_plans(picks, table[frontier_guard["classification"]])
-        _mark_specialist(picks, table[frontier_guard["classification"]])
+    if fitted is not None:
+        _attach_backup_plans(picks, fitted)
+        _mark_specialist(picks, fitted)
     guard = _ladder_tier_guard(picks)
     if frontier_guard is not None:
         guard.update(frontier_guard)

{roadmodel-0.2.71 → roadmodel-0.2.73}/src/roadmodel/scoring.py

@@ -147,6 +147,15 @@ REQUIREMENT: Final[dict[str, float]] = {"low": 30.0, "medium": 50.0, "high": 70.
 REQUIREMENT_NOVEL: Final[float] = 85.0
 # Points lost per point of shortfall below the requirement (steep, but soft).
 SHORTFALL_SLOPE: Final[float] = 1.5
+# Benchmark differences within run-to-run noise, in the scaled evidence's
+# points (0–100 across the measured catalog): two candidates this close in a
+# category stand level there, and the general measure (the AA Index) decides
+# between them. Measured from the cases where AA scores a model lower at a
+# higher effort: on its long-context test (LCR) 90% of the 32 such drops fall
+# within 5.6 points (about 3 points of LCR); on the other benchmarks they stay
+# within about 4.
+TIE_BAND: Final[dict[str, float]] = {"long-context": 6.0}
+DEFAULT_TIE_BAND: Final[float] = 4.0
 # λ: the share of the market's exchange rate K this operator applies to a
 # decade of spend. λ = 1 ranks purely by value (the market-line residual, the
 # same quantity the /models Score shows); λ → 0 ranks purely by quality. It is
@@ -206,6 +215,10 @@ FUNDING_PREFERENCE: Final[dict[str, int]] = {
 BASELINE_JURISDICTIONS: Final[tuple[str, ...]] = ("us", "eu", "uk", "ca", "au", "jp", "kr")
 
 BUNDLED_BENCHMARKS_PATH = resources.files("roadmodel.data") / "benchmarks.json"
+BUNDLED_CONTEXT_PATH = resources.files("roadmodel.data") / "context-windows.json"
+# A context window must hold the task's material plus the instructions and the
+# answer: 10% above the material's own size.
+CONTEXT_HEADROOM: Final[float] = 1.1
 
 
 # --------------------------------------------------------------------------- #
@@ -257,6 +270,10 @@ class Candidate:
     # The effort AA measured the quality evidence at; this candidate runs at
     # it. None: the model's headline figure, at the posture's effort.
     evidence_level: str | None = None
+    # The category's evidence on its 0–100 scale (EvidenceScale.points), the
+    # figure ties are judged on; None when AA has not measured it there or the
+    # category has no evidence (multimodal).
+    evidence_points: float | None = None
 
     def to_dict(self) -> dict[str, Any]:
         return asdict(self)
@@ -300,6 +317,36 @@ def _load_benchmarks() -> dict[str, Any]:
     return models if isinstance(models, dict) else {}
 
 
+def context_windows() -> dict[str, int]:
+    """Each catalog model's context window in tokens (docs/context-windows.json,
+    from OpenRouter's listing); empty when the file is missing or unreadable."""
+    try:
+        raw = json.loads(BUNDLED_CONTEXT_PATH.read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, ValueError):
+        return {}
+    models = raw.get("models") if isinstance(raw, dict) else None
+    if not isinstance(models, dict):
+        return {}
+    return {str(k): v for k, v in models.items() if isinstance(v, int) and v > 0}
+
+
+def nothing_fits(input_tokens: int, windows: dict[str, int] | None = None) -> bool:
+    """True when no model with a known context window can hold
+    ``input_tokens`` of material: the material is larger than any model
+    takes, and a model whose window is unknown is no answer."""
+    known = windows if windows is not None else context_windows()
+    return bool(known) and len(too_small_for(input_tokens, known)) == len(known)
+
+
+def too_small_for(input_tokens: int, windows: dict[str, int] | None = None) -> list[str]:
+    """The catalog ids whose context window cannot hold ``input_tokens`` of
+    material with CONTEXT_HEADROOM to spare. A model with no known window is
+    kept: nothing says it cannot."""
+    known = windows if windows is not None else context_windows()
+    need = input_tokens * CONTEXT_HEADROOM
+    return sorted(mid for mid, n in known.items() if n < need)
+
+
 def with_composites(bench: dict[str, Any]) -> dict[str, Any]:
     """A copy of ``bench`` with each ``COMPOSITES`` key added to the
     evaluations of every row measured on all its parts: the mean of the row's
@@ -770,20 +817,35 @@ def _quality(
     tiers: dict[str, Any] = raw_tiers if isinstance(raw_tiers, dict) else {}
     letter = str(tiers.get(task.category, "C")).upper()
     letter_q = LETTER_QUALITY.get(letter, 30.0)
-    key = CATEGORY_EVIDENCE[task.category]
-    v = _evidence(bench, str(model.get("id", "")), key, level)
-    if v is None and level is not None and key == "median_output_tokens_per_second":
-        # Throughput is the endpoint's at any effort; AA leaves it unmeasured
-        # on most of a model's other-effort rows.
-        v = _evidence(bench, str(model.get("id", "")), key)
     if scale is None:
         # No evidence exists for this category at all (multimodal): every model
         # is on its letter, so there is nothing to discount against.
         return letter_q, "letter", letter
-    if v is None:
+    points = _evidence_points(str(model.get("id", "")), task, bench, scale, level)
+    if points is None:
         return max(0.0, letter_q - UNMEASURED_DISCOUNT), "letter", letter
-    q = EVIDENCE_WEIGHT * scale.points(v) + (1.0 - EVIDENCE_WEIGHT) * letter_q
-    return q, f"aa:{key}+letter", letter
+    q = EVIDENCE_WEIGHT * points + (1.0 - EVIDENCE_WEIGHT) * letter_q
+    return q, f"aa:{CATEGORY_EVIDENCE[task.category]}+letter", letter
+
+
+def _evidence_points(
+    model_id: str,
+    task: Task,
+    bench: dict[str, Any],
+    scale: EvidenceScale | None,
+    level: str | None = None,
+) -> float | None:
+    """The category's evidence for ``model_id`` (at ``level`` when given) on
+    its 0–100 scale, or None when unmeasured or the category has none."""
+    if scale is None:
+        return None
+    key = CATEGORY_EVIDENCE[task.category]
+    # Throughput is the endpoint's at any effort (AA leaves it unmeasured on
+    # most of a model's other-effort rows, and its figures there are noise):
+    # speed reads the headline row's.
+    at = None if key == "median_output_tokens_per_second" else level
+    v = _evidence(bench, model_id, key, at)
+    return None if v is None else scale.points(v)
 
 
 @dataclass(frozen=True)
@@ -959,6 +1021,7 @@ def rank(
             continue
         provider = _cost.model_provider(model_id) or str(model.get("provider", "unknown"))
         quality, source, letter = _quality(model, task, bench, scale)
+        points = _evidence_points(model_id, task, bench, scale)
         shortfall = max(0.0, requirement - quality)
         penalty = SHORTFALL_SLOPE * shortfall
         price = blended_price(model)
@@ -1023,6 +1086,7 @@ def rank(
                 cost_penalty=round(cost_pen, 2),
                 score=round(score, 2),
                 notes=notes,
+                evidence_points=None if points is None else round(points, 2),
             )
             # One row per model: its best reachable platform. A funded platform
             # always beats an unfunded one regardless of score; equal scores go
@@ -1242,6 +1306,35 @@ def _nearest(p: FrontierPoint) -> tuple[float, float, float, float]:
     return (-p.candidate.requirement_penalty, *_strength(p))
 
 
+def _level_with(a: Candidate, b: Candidate, category: str) -> bool:
+    """Whether ``a`` stands at least level with ``b`` in the category: its
+    evidence no more than the noise band (``TIE_BAND``) below ``b``'s, or,
+    where either is unmeasured there, its quality no lower."""
+    if a.evidence_points is None or b.evidence_points is None:
+        return a.quality >= b.quality
+    return a.evidence_points >= b.evidence_points - TIE_BAND.get(category, DEFAULT_TIE_BAND)
+
+
+def _tie_break(p: FrontierPoint, category: str) -> tuple[float, float, float]:
+    """Between points level in the category: the higher AA Index, then the
+    cheaper. On speed work the lower effort comes first: throughput is the
+    same at every effort, and more reasoning only delays the answer."""
+    slower = 0.0
+    if category == "speed":
+        level = p.candidate.evidence_level or p.candidate.effort
+        slower = -float(EFFORT_LADDER.index(level)) if level in EFFORT_LADDER else 0.0
+    return (slower, -1.0 if p.aa_index is None else p.aa_index, -p.price_usd)
+
+
+def _top(points: list[FrontierPoint], category: str) -> FrontierPoint:
+    """The strongest point for the category: of those level with its leader
+    there (:func:`_level_with`), the one ahead on :func:`_tie_break`. A
+    difference within run-to-run noise does not decide it."""
+    leader = max(points, key=_strength)
+    level = [p for p in points if _level_with(p.candidate, leader.candidate, category)]
+    return max(level, key=lambda p: _tie_break(p, category))
+
+
 # Letters from weakest to strongest.
 LETTER_ORDER: Final[str] = "DCBAS"
 # Categories whose evidence is something other than the AA Intelligence Index,
@@ -1276,6 +1369,7 @@ def _specialist(
         and c.requirement_penalty == 0
         and rank(c.letter) > rank(t.letter)
         and c.quality > t.quality
+        and not _level_with(t, c, task.category)
     ]
     if not stronger:
         return None
@@ -1325,6 +1419,7 @@ def _at_level(
     model is not up to it.
     ``scales`` are the category's evidence scale and the planning one."""
     quality, source, letter = _quality(model, task, bench, scales[0], level)
+    points = _evidence_points(c.model_id, task, bench, scales[0], level)
     general, _, _ = _quality(model, replace(task, category="planning"), bench, scales[1], level)
     penalty = SHORTFALL_SLOPE * max(0.0, c.requirement - min(quality, general))
     if level is None:
@@ -1354,6 +1449,7 @@ def _at_level(
         cost_penalty=round(cost_pen, 2),
         score=round(quality - penalty - cost_pen + nudge, 2),
         evidence_level=level,
+        evidence_points=None if points is None else round(points, 2),
     )
 
 
@@ -1448,8 +1544,9 @@ def ladder(
       COST and BALANCED stay on the frontier, BALANCED then spanning every
       adequate point above COST.
     - Each rung carries a BACKUP from another maker (:func:`_backup_for`):
-      the best adequate point on the other makers' frontier at no higher list
-      price. ``backup_warning`` says why a rung has none.
+      the cheapest point on the other makers' frontier that does the job as
+      well as the rung, else the nearest below it. ``backup_warning`` says why
+      a rung has none.
 
     None when no pool model carries an AA Index (no frontier to read)."""
     cat = catalog if catalog is not None else _cost._load_catalog()
@@ -1478,7 +1575,7 @@ def ladder(
     adequate = [p for p in points if p.candidate.requirement_penalty == 0]
     if not adequate:
         adequate = [max(points, key=_nearest)]
-    top = max(adequate, key=_strength)
+    top = _top(adequate, task.category)
     span = adequate[: adequate.index(top) + 1]
     specialist = _specialist(task, settings, points, top, bench)
     by_level = {(c.model_id, c.evidence_level): c for c in settings if c.evidence_level}
@@ -1541,11 +1638,12 @@ def ladder(
     )
     # With a specialist on QUALITY, BALANCED spans every adequate frontier point
     # above COST, the frontier's strongest included. A BALANCED point earns its
-    # higher price only by beating COST in the task's own category: the
-    # frontier is drawn on the AA Index, and a point above COST on that axis
-    # can still trail it in the category the task needs.
+    # higher price only by standing at least level with COST in the task's own
+    # category: the frontier is drawn on the AA Index, and a point above COST
+    # on that axis can still trail it in the category the task needs. A gap
+    # within run-to-run noise is level, and the AA Index then decides.
     between = span[lo + 1 :] if specialist is not None else span[lo + 1 : -1]
-    between = [p for p in between if p.candidate.quality > cost_point.candidate.quality]
+    between = [p for p in between if _level_with(p.candidate, cost_point.candidate, task.category)]
     # Like COST, BALANCED draws on what is already paid for first: a per-token
     # point stands between only when no prepaid one out-scores COST there.
     between = [p for p in between if p.candidate.scarcity < 1.0] or between
@@ -1574,8 +1672,12 @@ def ladder(
         )
     balanced_rung = settle(_below(balanced_rung, quality_rung, cat))
     cost_rung = settle(_below(cost_rung, balanced_rung, cat))
+    # General capability is level within the same noise band, read on the
+    # AA Index's own 0–100 scale (the planning evidence).
+    gscale = _evidence_scale(cat, bench, FRONTIER_INDEX)
+    aa_band = 0.0 if gscale is None else DEFAULT_TIE_BAND * (gscale.hi - gscale.lo) / 100.0
     rungs = {
-        r.tier: replace(r, backup=_backup_for(r, settings, task, headroom, bench, cat))
+        r.tier: replace(r, backup=_backup_for(r, settings, task, headroom, bench, cat, aa_band))
         for r in (cost_rung, balanced_rung, quality_rung)
     }
     warning: str | None = None
@@ -1603,23 +1705,51 @@ def _backup_for(
     headroom: str,
     bench: dict[str, Any],
     catalog: dict[str, Any],
+    aa_band: float = 0.0,
 ) -> Backup | None:
-    """The rung's backup: the best substitute from another maker the operator
-    can run, at no higher list price.
-
-    Over the pool's models from a maker other than the rung model's, draw the
-    frontier and keep its adequate points. The backup is the adequate point
-    with the highest list price at or below the rung's; else the cheapest
-    adequate point above it; else, with no adequate point, the frontier's
-    strongest for the category. It runs at the rung's posture's effort on its
-    own platform. None when the pool holds no other maker's model."""
+    """The rung's backup: the substitute from another maker that does the job
+    as well as the rung, for the least.
+
+    Over the pool's models from a maker other than the rung model's, each at
+    its measured efforts, draw the frontier and keep its adequate points,
+    those already paid for ahead of per-token ones. A point matches the rung
+    when it stands level with it in the task's category
+    (:func:`_level_with`) and in general capability (an AA Index no more than
+    ``aa_band`` below). The backup is the cheapest match; with none, the
+    substitute the QUALITY rule would pick (:func:`_top`: strongest in the
+    category, a near tie going to the higher AA Index); with no adequate
+    point, the one that falls shortest of the bar. It runs at its
+    point's measured effort, else at the rung's posture's effort, on its own
+    platform. None when the pool holds no other
+    maker's model."""
     front = frontier([c for c in pool if c.provider != rung.candidate.provider], bench)
     if not front:
         return None
     adequate = [p for p in front if p.candidate.requirement_penalty == 0]
+    r = rung.point
+
+    def paid_first(points: list[FrontierPoint]) -> list[FrontierPoint]:
+        return [p for p in points if p.candidate.scarcity < 1.0] or points
+
+    def aa(p: FrontierPoint) -> float:
+        return -1.0 if p.aa_index is None else p.aa_index
+
     if adequate:
-        within = [p for p in adequate if p.price_usd <= rung.point.price_usd]
-        chosen = within[-1] if within else adequate[0]
+        # The cheapest substitute level with the rung in the category and in
+        # general capability; with none, the one the QUALITY rule would pick
+        # among the substitutes (:func:`_top`).
+        near = paid_first(adequate)
+        matches = [
+            p
+            for p in near
+            if _level_with(p.candidate, r.candidate, task.category)
+            and (r.aa_index is None or aa(p) >= r.aa_index - aa_band)
+        ]
+        chosen = (
+            min(matches, key=lambda p: (p.price_usd, -aa(p)))
+            if matches
+            else _top(near, task.category)
+        )
     else:
         chosen = max(front, key=_nearest)
     c = chosen.candidate