Files

117 lines
6.2 KiB
Python

"""A routing ladder, and the rungs a task's L and E + I pick on it from the project's rung: docs/decisions.md → `routing:`."""
import dataclasses
import re
import typing
from review_rules.review_passes import ReviewedPass
# How Rung.__str__ spells a rung that names an effort, and Rung.parse reads it back.
WORDING = re.compile(r"(?P<model>\S+) at (?P<effort>\S+) effort")
# Lowest first, as Claude Code's --effort takes them.
EFFORTS = ("low", "medium", "high", "xhigh", "max")
# What a review launch reviews: such a pass, a comprehension seat or the security pass.
ReviewKind = ReviewedPass | typing.Literal["seat", "security"]
@dataclasses.dataclass(frozen=True)
class Rung:
model: str
# Empty leaves the effort to claude's settings, as for a model off the ladder.
effort: str = ""
def flags(self) -> list[str]:
return ["--model", self.model, *(["--effort", self.effort] if self.effort else [])]
def family(self) -> str:
"""The Agent tool's name for the model, such as opus for claude-opus-5-5."""
return self.model.split("-")[1]
def agent_args(self) -> str:
"""The rung in the Agent tool's words. The tool takes a family name, such as opus, and runs that family's latest model, which is the model each rung names."""
return f"model {self.family()}, effort {self.effort}"
# loop-claude hands a rung to rule-hook in environment variables in this spelling, so parse must keep reading it.
def __str__(self) -> str:
return f"{self.model} at {self.effort} effort" if self.effort else self.model
@staticmethod
def parse(text: str) -> "Rung | None":
"""The rung that names an effort, which str wrote, whether or not it is on the ladder; None for any other text, such as a bare model."""
found = WORDING.fullmatch(text)
return Rung(found["model"], found["effort"]) if found else None
# The rungs a task's L steps its worker from the project's rung.
WORKER_STEPS = {1: -1, 2: -1, 3: 1, 4: 2}
# The rungs a task's E + I steps a review up from the project's rung; an E + I under 5 steps none.
REVIEW_STEPS = {5: 1, 6: 2, 7: 3, 8: 4}
@dataclasses.dataclass(frozen=True)
class Ladder:
"""A project's rungs, least competent first. model_routing/ladder_file.py reads one, and refuses a file that holds no rung, one rung twice, since a rung's position sets every step, or two models of one family, since from_agent reads a family as one model."""
rungs: tuple[Rung, ...]
def from_agent(self, model: str, effort: str) -> Rung:
"""The rung the Agent tool's model and effort name: a family such as opus is its ladder model, at the effort given or else its cheapest. A family off the ladder, or an effort off it, gives a rung that is not on the ladder."""
family = next((rung for rung in self.rungs if rung.family() == model), None)
if family is None:
return Rung(model, effort)
return Rung(family.model, effort) if effort else family
def project_rung(self, model: str) -> "ProjectRung | None":
"""The model's cheapest rung on this ladder, which for Opus 5.5 is its default effort; None for a model off the ladder."""
rung = next((rung for rung in self.rungs if rung.model == model), None)
return ProjectRung(self, rung) if rung else None
def stepped_up(self, rung: Rung) -> Rung:
"""The rung above, or the top one; a rung off the ladder steps to the bottom one."""
return self.climbed(rung, 1)
def highest(self, *rungs: Rung) -> Rung:
"""The most competent of the rungs; one off the ladder ranks below every rung on it."""
return max(rungs, key=self.position)
def climbed(self, rung: Rung, by: int) -> Rung:
return self.rungs[max(0, min(len(self.rungs) - 1, self.position(rung) + by))]
def position(self, rung: Rung) -> int:
return self.rungs.index(rung) if rung in self.rungs else -1
@dataclasses.dataclass(frozen=True)
class ProjectRung:
"""A project's rung on the ladder it stands on, from which each task's L and E + I count their steps."""
ladder: Ladder
rung: Rung
def worker_rung(self, likelihood: int) -> Rung:
"""The rung a task's L picks for its worker, counted from the project's rung, stopping at either end of the ladder."""
return self.ladder.climbed(self.rung, WORKER_STEPS[likelihood])
def lowest_worker_rung(self) -> Rung:
"""The lowest rung any L routes a worker to, counted from the project's rung."""
return self.ladder.climbed(self.rung, min(WORKER_STEPS.values()))
def planning_rung(self, likelihood: int) -> Rung:
"""The rung of a task that files or scores todo.md items: the one its L picks, never below the project's rung."""
return self.ladder.highest(self.rung, self.worker_rung(likelihood))
def review_floor(self, escape_and_impact: int) -> Rung:
"""The rung a task's E + I picks for a review, counted up from the project's rung. An E + I of 0, for no task, picks the project's rung."""
return self.ladder.climbed(self.rung, REVIEW_STEPS.get(escape_and_impact, 0))
def review_rung(self, worker: Rung, escape_and_impact: int, kind: ReviewKind, markdown_only: bool = False) -> Rung:
"""The rung a review of this kind runs on in a chunk whose worker runs on worker and whose item has that E + I; markdown_only where the branch changes only Markdown no agent follows.
A pass's reviewer runs on reviewers_rung; no replay has qualified a lower rung for any pass, docs/decisions.md → `routing: a review pass runs below the project's rung only on a rung whose replay of its rounds finds a share of their 🔴 and 🟡 findings no more than a margin below the project's rung's own replay`. A seat and the security pass run on the project's rung, so the seats score every chunk on one rung, and the security pass spends no more than the project chose.
"""
return self.rung if kind in ("seat", "security") else self.reviewers_rung(worker, escape_and_impact, markdown_only)
def reviewers_rung(self, worker: Rung, escape_and_impact: int, markdown_only: bool = False) -> Rung:
"""The rung of each pass's reviewer: the higher of the worker's rung and review_floor's, which is never below the project's.
markdown_only means the branch changes only Markdown no agent follows. Such a branch holds no code or config for a higher rung to catch a defect in, so its reviewer runs on the project's rung: skills/larv-review/SKILL.md → "Markdown only".
"""
return self.rung if markdown_only else self.ladder.highest(worker, self.review_floor(escape_and_impact))