168 lines
9.8 KiB
Python
168 lines
9.8 KiB
Python
"""Which ladder rung a chunk's worker and judge run on: docs/decisions.md → `routing:`.
|
|
|
|
The worker, and the session /talk opens, run on a Route (model_routing/route.py). A model off the ladder gets a route without an item, and it is never stepped.
|
|
|
|
- Start. The entry point finds the plan item that routes a fresh chunk, as loop_claude/routed_item.py does; first_route picks the worker's rung from its L, or the project's rung without an item.
|
|
- Rerun. kept decides whether a rerun resumes the route its archive last names.
|
|
- Step-up. next_route raises the route after an unfinished verdict (unfinished_route), or an interrupt or a quoted answer that carries an escalation (escalated_route); escalation_cap bounds an escalation, and agent_cycle/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
|
|
- Judge. judge_rung picks the rung of the judge of a JUDGE_REPLAYED model.
|
|
|
|
A step-up weighs five rungs:
|
|
|
|
- the project's rung: the cheapest rung of the project's model, which each L's rung is counted from, up or down;
|
|
- item_rung: the rung the chunk started on, which the routed item's L picked;
|
|
- the route's rung: where the worker runs now, at or above item_rung;
|
|
- floor_rung: the lowest rung the worker may run on next, which is the route's rung, raised where an item the worker took in has an L that picks a higher one;
|
|
- escalation_cap: ESCALATION_CAP rungs above item_rung, the highest an escalation reaches without the human's yes.
|
|
|
|
Each verdict then moves the rung by one rule, and the rung never falls. The rung changes seldom, since a model switch inside a session discards that session's prompt cache.
|
|
|
|
| Verdict | The rung goes to | Count of unfinished verdicts | Escalation mark |
|
|
|---|---|---|---|
|
|
| unfinished, not the UNFINISHED_PER_STEP-th, no escalation | floor_rung | one more | holds |
|
|
| unfinished, the UNFINISHED_PER_STEP-th since the last step | one above floor_rung | restarts | moves only with an escalation |
|
|
| unfinished with an escalation, floor_rung below the cap | one above floor_rung, once even where the count also steps | restarts | moves |
|
|
| unfinished with an escalation, floor_rung at the cap | floor_rung, unless the count steps | one more, unless it steps | holds unless the count steps |
|
|
| interrupt or quoted answer with an escalation, floor_rung below the cap | one above floor_rung | restarts | moves |
|
|
| interrupt or quoted answer with an escalation, floor_rung at the cap | floor_rung | holds | holds |
|
|
| interrupt or quoted answer without one | holds | holds | holds |
|
|
"""
|
|
import dataclasses
|
|
import typing
|
|
|
|
from agent_cycle import escalation_mark
|
|
from agent_cycle.verdicts import Interrupt, QuotedAnswer, Unfinished
|
|
from model_routing.ladder import Ladder, ProjectRung, Rung
|
|
from model_routing.route import Route
|
|
|
|
UNFINISHED_PER_STEP = 2
|
|
# How many rungs above item_rung an escalation trigger takes the worker or a task without the human's yes, as escalation_cap counts them.
|
|
ESCALATION_CAP = 2
|
|
# The models whose cheapest rung, in a `judge-replay` run, returned every interrupt the reference judge reproduced: docs/decisions.md → `routing: on a model judge-replay covered`.
|
|
JUDGE_REPLAYED = ("claude-opus-5-5",)
|
|
|
|
|
|
class Scored(typing.Protocol):
|
|
"""What routes a chunk: a plan item under loop-claude, an epic's issue under do-epic."""
|
|
@property
|
|
def id(self) -> int:
|
|
"""The number a Route keeps as its item."""
|
|
|
|
@property
|
|
def likelihood(self) -> int:
|
|
"""Its L."""
|
|
|
|
@property
|
|
def escape_and_impact(self) -> int:
|
|
"""Its E + I."""
|
|
|
|
|
|
def first_route(project: ProjectRung, item: Scored | None) -> Route:
|
|
"""The route a chunk starts on: the rung its item's L picks from the project's rung, or the project's rung without an item."""
|
|
if item is None:
|
|
return Route(project.rung)
|
|
return Route(project.worker_rung(item.likelihood), item.id, item.likelihood, item.escape_and_impact)
|
|
|
|
|
|
def kept(route: Route, project: ProjectRung) -> bool:
|
|
"""Whether a chunk keeps route: its rung is on the ladder and at or above item_rung."""
|
|
return floor_rung(project, route) == route.rung
|
|
|
|
|
|
def item_rung(project: ProjectRung, route: Route) -> Rung:
|
|
"""The rung the route's item's L picks from the project's rung, or the project's rung itself when no item routed it. The worker may run on a rung below the project's."""
|
|
return project.worker_rung(route.likelihood) if route.item else project.rung
|
|
|
|
|
|
def floor_rung(project: ProjectRung, route: Route, likelihood_taken_in: int = 0) -> Rung:
|
|
"""The lowest rung the worker may run on: the route's own, raised to item_rung where it is lower or off the ladder, and to the rung likelihood_taken_in picks from project. likelihood_taken_in is the highest L the worker took into the chunk, 0 for none."""
|
|
floor = project.ladder.highest(route.rung, item_rung(project, route))
|
|
return project.ladder.highest(floor, project.worker_rung(likelihood_taken_in)) if likelihood_taken_in else floor
|
|
|
|
|
|
def escalation_rungs(project: ProjectRung, route: Route) -> tuple[Rung, ...]:
|
|
"""The rungs an escalation trigger opens to the worker, least competent first: from one above its own up to escalation_cap; none off the ladder."""
|
|
ladder = project.ladder
|
|
if route.rung not in ladder.rungs:
|
|
return ()
|
|
return ladder.rungs[ladder.position(route.rung) + 1:ladder.position(escalation_cap(project, route)) + 1]
|
|
|
|
|
|
def escalation_cap(project: ProjectRung, route: Route) -> Rung:
|
|
"""The highest rung an escalation trigger takes the worker or a task to without the human's yes: docs/decisions.md → `routing: a worker hands a task one rung up`.
|
|
|
|
It counts from item_rung, the rung the chunk started on, so a step-up between cycles narrows what the worker may climb without a yes, and never widens it.
|
|
"""
|
|
return project.ladder.climbed(item_rung(project, route), ESCALATION_CAP)
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class StepUp:
|
|
"""A verdict changing the route's worker line: the route the worker ran on until the verdict, and the one it runs on after. The archive names both, so the figures charge each stretch of work to its own rung."""
|
|
before: Route
|
|
after: Route
|
|
|
|
|
|
def next_route(project: ProjectRung | None, route: Route, verdict: Unfinished | Interrupt | QuotedAnswer) -> Route:
|
|
"""The route the worker runs on after the judge's verdict. Off the ladder, project is None, and the route holds. The rung never falls."""
|
|
if project is None:
|
|
return route
|
|
if isinstance(verdict, Unfinished):
|
|
return unfinished_route(project, route, verdict)
|
|
return escalated_route(project, route, verdict)
|
|
|
|
|
|
def unfinished_route(project: ProjectRung, route: Route, verdict: Unfinished) -> Route:
|
|
"""The route after an unfinished verdict, as the module docstring's table says.
|
|
|
|
The rung rises to floor_rung, which the verdict's highest L taken in may raise. The verdict counts towards UNFINISHED_PER_STEP. Where steps says so, the rung steps once from the floor; the mark moves only where the verdict carries an escalation. Last, the route takes in the verdict's highest E + I, as Route.taking_in does.
|
|
"""
|
|
floor = floor_rung(project, route, verdict.taken_in.highest_likelihood)
|
|
mark = escalation_mark.moved_to(verdict)
|
|
escalates = mark is not None and below_cap(project, route, floor)
|
|
counted = route.unfinished + 1
|
|
if steps(counted, escalates):
|
|
after = one_rung_up(project.ladder, route, floor, route.escalated_at if mark is None else mark)
|
|
else:
|
|
after = dataclasses.replace(route, rung=floor, unfinished=counted)
|
|
return after.taking_in(verdict.taken_in.highest_escape_and_impact)
|
|
|
|
|
|
def escalated_route(project: ProjectRung, route: Route, verdict: Interrupt | QuotedAnswer) -> Route:
|
|
"""The route after an interrupt or a quoted answer. Without an escalation it holds, since neither is an unfinished verdict.
|
|
|
|
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. Where floor_rung lies below escalation_cap, the rung steps one up from it and the mark moves, as agent_cycle/escalation_mark.py says; at the cap the rung stays on floor_rung and the mark holds.
|
|
"""
|
|
mark = escalation_mark.moved_to(verdict)
|
|
if mark is None:
|
|
return route
|
|
floor = floor_rung(project, route, verdict.taken_in.highest_likelihood)
|
|
return one_rung_up(project.ladder, route, floor, mark) if below_cap(project, route, floor) else dataclasses.replace(route, rung=floor)
|
|
|
|
|
|
def steps(counted: int, escalates: bool) -> bool:
|
|
"""Whether an unfinished verdict steps the rung: it is the UNFINISHED_PER_STEP-th since the last step, or it escalates below escalation_cap. Where both hold, the rung still steps once."""
|
|
return counted >= UNFINISHED_PER_STEP or escalates
|
|
|
|
|
|
def below_cap(project: ProjectRung, route: Route, floor: Rung) -> bool:
|
|
"""Whether an escalation from floor may step the rung: floor lies below escalation_cap."""
|
|
return project.ladder.position(floor) < project.ladder.position(escalation_cap(project, route))
|
|
|
|
|
|
def step_up(before: Route, after: Route) -> StepUp | None:
|
|
"""The step-up from before to after; None where the worker line holds, as when only the count of unfinished verdicts changed."""
|
|
return StepUp(before, after) if after.worker_line() != before.worker_line() else None
|
|
|
|
|
|
def one_rung_up(ladder: Ladder, route: Route, rung: Rung, escalated_at: int) -> Route:
|
|
"""The route one rung above rung, with the count of unfinished verdicts restarted and the mark at escalated_at."""
|
|
return dataclasses.replace(route, rung=ladder.stepped_up(rung), unfinished=0, escalated_at=escalated_at)
|
|
|
|
|
|
def judge_rung(ladder: Ladder, judge_model: str) -> Rung:
|
|
"""The highest of the judge model's own rungs on ladder: docs/decisions.md → `routing: on a model judge-replay covered`. A model off the ladder, or not in JUDGE_REPLAYED, gets no effort flag, so claude runs it at the effort its settings give."""
|
|
if ladder.project_rung(judge_model) is None or judge_model not in JUDGE_REPLAYED:
|
|
return Rung(judge_model)
|
|
return ladder.highest(*(rung for rung in ladder.rungs if rung.model == judge_model))
|