117 lines
6.2 KiB
Python
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))
|