roadmodel 0.2.62__tar.gz → 0.2.63__tar.gz

{roadmodel-0.2.62 → roadmodel-0.2.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roadmodel
-Version: 0.2.62
+Version: 0.2.63
 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.62 → roadmodel-0.2.63}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roadmodel"
-version = "0.2.62"
+version = "0.2.63"
 description = "BYO-key CLI that recommends the right AI model, platform, and settings for a prompt."
 readme = "README.md"
 requires-python = ">=3.11"

{roadmodel-0.2.62 → roadmodel-0.2.63}/src/roadmodel/__init__.py

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

{roadmodel-0.2.62 → roadmodel-0.2.63}/src/roadmodel/recommend.py

@@ -501,8 +501,10 @@ _SAAS_LADDER_TABLE_HEADER: Final = (
     "gives both the same settings because a lower effort saves this user nothing or "
     "the dial has no lower level; say which in that block's RATIONALE, and never "
     "invent another difference.\n"
-    "- BACKUP obeys the Step 7 HARD cross-provider rule and names a model this user "
-    "can reach.\n"
+    "- Each block's BACKUP is the model the row names after `backup` in that tier's "
+    "cell, copied verbatim; code checks it against the row and replaces one that "
+    "differs. Where a cell names no backup, BACKUP obeys the Step 7 HARD "
+    "cross-provider rule and names a model this user can reach.\n"
     "- Each RATIONALE is three labelled segments (TASK: / PICK: / EFFORT:), one crisp "
     "sentence each. PICK says why the row's model fits its tier in the table's terms "
     "(where it sits on the user's frontier, its AA Index); EFFORT says why the setting "
@@ -1331,6 +1333,48 @@ def _enforce_table_row(ladder: dict[str, dict[str, str]], row: scoring.Ladder) -
     return rewritten
 
 
+def _enforce_table_backup(ladder: dict[str, dict[str, str]], row: scoring.Ladder) -> list[str]:
+    """Make every rung's BACKUP the row's: the best model from another maker
+    the user can run at no higher list price (scoring._backup_for). A rung
+    whose row names no backup (no other maker funded) keeps the engine's,
+    under the Step 7 guard. Returns the tiers whose backup it set."""
+    adjusted: list[str] = []
+    for tier in _LADDER_TIERS:
+        backup = row.rungs[tier].backup
+        if backup is None:
+            continue
+        b = backup.candidate
+        written = ladder[tier].get("backup", "")
+        if written and (
+            cost.model_id_of(written) == b.model_id
+            or _model_key(written) in {_model_key(b.model_id), _model_key(b.model_name)}
+        ):
+            continue
+        ladder[tier]["backup"] = b.model_name
+        adjusted.append(tier)
+    return adjusted
+
+
+def _attach_backup_plans(picks: dict[str, dict[str, Any]], row: scoring.Ladder) -> None:
+    """Give each pick whose BACKUP is the row's a ``backup_plan``: the
+    platform and effort the row runs that backup at, so a caller can show the
+    backup on the surface the scorer chose (the user's subscription surface
+    where one reaches it) instead of guessing one. A backup the guard replaced
+    gets none."""
+    for tier in _LADDER_TIERS:
+        backup = row.rungs[tier].backup
+        if backup is None:
+            continue
+        b = backup.candidate
+        if picks[tier].get("backup") != cost.canonical_model_name(b.model_name):
+            continue
+        picks[tier]["backup_plan"] = {
+            "model": picks[tier]["backup"],
+            "platform": b.platform_name,
+            "effort": _effort_word(backup.level),
+        }
+
+
 # Claude Code's Ultracode is a session setting above its Max level: it stands
 # where the row says max.
 _ULTRACODE_PLATFORM: Final = "claude-code"
@@ -1410,10 +1454,13 @@ def recommend_structured_ladder(
     ladder table (scoring.ladder_table) goes into the prompt, the engine
     classifies the task and copies its row, and every rung is then made the
     row's (:func:`_enforce_table_row`), effort included on every surface
-    whose dial the catalog documents (:func:`_enforce_table_effort`). ``guard``
-    then reports ``mode: "frontier"``, the row, how it was found, the tiers
-    rewritten and the tiers whose effort was set, and is healthy: two rungs on
-    one model are the table's answer, not a collapse.
+    whose dial the catalog documents (:func:`_enforce_table_effort`), and
+    BACKUP included where the row names one (:func:`_enforce_table_backup`;
+    such a pick also carries a ``backup_plan`` with the backup's platform and
+    effort). ``guard`` then reports ``mode: "frontier"``, the row, how it was
+    found, the tiers rewritten, the tiers whose effort was set and the tiers
+    whose backup was set, and is healthy: two rungs on one model are the
+    table's answer, not a collapse.
     Without a table, or a response the table cannot place, the engine's own
     picks stand under the tier-distinctness guard as before.
 
@@ -1460,6 +1507,7 @@ def recommend_structured_ladder(
                 "found": found,
                 "rewritten": _enforce_table_row(ladder, row),
                 "effort_set": _enforce_table_effort(ladder, row),
+                "backup_set": _enforce_table_backup(ladder, row),
                 "frontier": [p.candidate.model_name for p in row.frontier],
             }
         else:
@@ -1474,6 +1522,8 @@ 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"]])
     guard = _ladder_tier_guard(picks)
     if frontier_guard is not None:
         guard.update(frontier_guard)

{roadmodel-0.2.62 → roadmodel-0.2.63}/src/roadmodel/scoring.py

@@ -56,7 +56,7 @@ from __future__ import annotations
 import json
 import math
 import re
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass, field, replace
 from datetime import datetime, timedelta, timezone
 from importlib import resources
 from typing import Any, Final
@@ -1024,6 +1024,24 @@ class FrontierPoint:
     price_usd: float
 
 
+@dataclass(frozen=True)
+class Backup:
+    """A rung's cross-maker substitute, read off the frontier of the other
+    makers' models (see :func:`ladder`)."""
+
+    point: FrontierPoint
+    effort: str
+    native: str | None = None
+
+    @property
+    def candidate(self) -> Candidate:
+        return self.point.candidate
+
+    @property
+    def level(self) -> str:
+        return self.native or self.effort
+
+
 @dataclass(frozen=True)
 class Rung:
     tier: str
@@ -1033,6 +1051,9 @@ class Rung:
     # The same level as the platform's own dial names it (native_level), or
     # None when the catalog documents no dial for the platform and model.
     native: str | None = None
+    # The best cross-maker substitute at no higher list price; None when the
+    # pool holds no other maker's model.
+    backup: Backup | None = None
 
     @property
     def candidate(self) -> Candidate:
@@ -1052,6 +1073,8 @@ class Ladder:
     # complexity's requirement, cheapest first.
     adequate: list[FrontierPoint]
     rungs: dict[str, Rung]
+    # Why a rung has no backup: the pool holds no other maker's model.
+    backup_warning: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         def point(p: FrontierPoint) -> dict[str, Any]:
@@ -1072,9 +1095,23 @@ class Ladder:
             "frontier": [point(p) for p in self.frontier],
             "adequate": [p.candidate.model_id for p in self.adequate],
             "rungs": {
-                t: {**point(r.point), "effort": r.effort, "native_effort": r.native}
+                t: {
+                    **point(r.point),
+                    "effort": r.effort,
+                    "native_effort": r.native,
+                    "backup": (
+                        {
+                            **point(r.backup.point),
+                            "effort": r.backup.effort,
+                            "native_effort": r.backup.native,
+                        }
+                        if r.backup is not None
+                        else None
+                    ),
+                }
                 for t, r in self.rungs.items()
             },
+            "backup_warning": self.backup_warning,
         }
 
 
@@ -1129,6 +1166,9 @@ def ladder(
       level they may converge. On an `uncapped` pool every free rung runs at
       the top effort and two rungs on one model converge: a lower effort saves
       that operator nothing.
+    - 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.
 
     None when no pool model carries an AA Index (no frontier to read)."""
     cat = catalog if catalog is not None else _cost._load_catalog()
@@ -1183,8 +1223,52 @@ def ladder(
         )
     balanced_rung = _below(balanced_rung, quality_rung, cat)
     cost_rung = _below(cost_rung, balanced_rung, cat)
-    rungs = {"cost": cost_rung, "balanced": balanced_rung, "quality": quality_rung}
-    return Ladder(task=base, frontier=front, adequate=adequate, rungs=rungs)
+    pool = funded or ranking.candidates
+    rungs = {
+        r.tier: replace(r, backup=_backup_for(r, pool, task, headroom, bench, cat))
+        for r in (cost_rung, balanced_rung, quality_rung)
+    }
+    warning: str | None = None
+    if any(r.backup is None for r in rungs.values()):
+        makers = sorted({c.provider for c in pool})
+        warning = (
+            f"No cross-provider backup: the models this user can run come from "
+            f"{', '.join(makers) or 'no maker'} only. Add a second maker's subscription or "
+            "API key so an outage or an exhausted pool has somewhere to go."
+        )
+    return Ladder(task=base, frontier=front, adequate=adequate, rungs=rungs, backup_warning=warning)
+
+
+def _backup_for(
+    rung: Rung,
+    pool: list[Candidate],
+    task: Task,
+    headroom: str,
+    bench: dict[str, Any],
+    catalog: dict[str, Any],
+) -> 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."""
+    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]
+    if adequate:
+        within = [p for p in adequate if p.price_usd <= rung.point.price_usd]
+        chosen = within[-1] if within else adequate[0]
+    else:
+        chosen = max(front, key=lambda p: (p.candidate.quality, p.aa_index, -p.price_usd))
+    t = Task(task.category, task.complexity, task.novel, TIER_BUDGET[rung.tier])
+    c = chosen.candidate
+    effort = effort_for(t, headroom, c.scarcity)
+    return Backup(chosen, effort, native_level(c.platform_id, c.model_id, effort, catalog=catalog))
 
 
 def _below(lower: Rung, upper: Rung, catalog: dict[str, Any]) -> Rung:
@@ -1271,14 +1355,19 @@ def render_ladder_table(table: dict[str, Ladder]) -> str:
             for p in any_ladder.frontier
         ),
         "Rows: <category>/<complexity>[/novel]: COST | BALANCED | QUALITY, each "
-        "<model> @ <platform> · <effort>, the effort in the platform's own level words.",
+        "<model> @ <platform> · <effort>, the effort in the platform's own level words, "
+        "then `backup <model> @ <platform>`: that pick's BACKUP.",
     ]
+
+    def cell(t: str, r: Rung) -> str:
+        text = f"{t.upper()} = {r.candidate.model_name} @ {r.candidate.platform_name} · {r.level}"
+        if r.backup is not None:
+            b = r.backup.candidate
+            text += f", backup {b.model_name} @ {b.platform_name}"
+        return text
+
     for key, lad in table.items():
-        cells = " | ".join(
-            f"{t.upper()} = {r.candidate.model_name} @ {r.candidate.platform_name} · {r.level}"
-            for t in LADDER_TIERS
-            for r in [lad.rungs[t]]
-        )
+        cells = " | ".join(cell(t, lad.rungs[t]) for t in LADDER_TIERS)
         lines.append(f"{key}: {cells}")
     lines.append("</ladder-table>")
     return "\n".join(lines)