mixle.task.router module

Calibrated N-tier model routing.

Router generalizes Cascade from one local tier plus a teacher to several calibrated tiers. Each local tier answers only when its conformal set is a confident singleton and, if a density gate is configured, the input is in distribution. Otherwise the request falls through to the next tier, ending at a teacher/frontier callable that always answers. Reports carry realized traffic and cost:

router = Router.from_solutions([fast, accurate], teacher=frontier, costs=[0.0001, 0.001, 0.03])
router(x)                     # answered by the lowest-cost confident tier
router.report()               # per-tier traffic, realized $/req, savings vs all-teacher serving
router.harvested()            # the frontier's answers on hard inputs = training data for the tiers

Every request the teacher answers is harvested as targeted training data for the lower-cost tiers.

class TierStats(name, cost_per_request, answered=0)[source]

Bases: object

Traffic counter and request cost for one router tier.

Parameters:
class RouterStats(tiers=<factory>, harvested_inputs=<factory>, harvested_labels=<factory>, degraded=<factory>)[source]

Bases: object

Mutable accounting for routed requests, harvested labels, and degraded tier calls.

Parameters:

  • tiers (list[TierStats])

  • harvested_inputs (list[Any])

  • harvested_labels (list[Any])

  • degraded (list[DegradedResult])

property n_requests: int

Return the total number of requests answered across all tiers.

class Router(tiers)[source]

Bases: object

Route each request to the lowest-cost tier whose calibrated model is confident.

Parameters:

tiers (list[tuple[str, Any, float]])

classmethod from_solutions(solutions, teacher, *, costs, names=None)[source]

Build from Solution objects ordered by cost plus the teacher callable.

costs has one entry per solution plus one for the teacher (per-request).

Parameters:
Return type:

Router

serve(xs)[source]

Route a batch of requests and return the tier-selected answers.

Parameters:

xs (Any)

Return type:

list[Any]

harvested()[source]

Return teacher-answered (inputs, labels) for retraining lower-cost tiers.

Return type:

tuple[list[Any], list[Any]]

report()[source]

Return per-tier traffic and realized economics.

Return type:

dict[str, Any]

summary()[source]

Render a compact human-readable traffic and cost summary.

Return type:

str

route_stack(solutions, teacher, *, costs)[source]

Convenience: Router.from_solutions() with tiers sorted by ascending cost.

Parameters:
Return type:

Router

class HarvestResolveResult(accepted, n_harvested, escalation_before, escalation_after, escalation_drop, agreement, router=None, tier_name='')[source]

Bases: object

Receipt from resolve_from_harvest().

escalation_before is exactly 1.0: every harvested input, by definition, escalated all the way to the teacher under the current router. escalation_after is the new tier’s own calibrated escalation rate on a held-out split of that same harvested set; escalation_drop is the difference. router is the new stack with the tier inserted (None when nothing was accepted because there is too little harvested data to fit/calibrate or the new tier does not escalate measurably less often than always-escalate, in which case it buys nothing and is rejected).

Parameters:

  • accepted (bool)

  • n_harvested (int)

  • escalation_before (float)

  • escalation_after (float)

  • escalation_drop (float)

  • agreement (float)

  • router (Router | None)

  • tier_name (str)

resolve_from_harvest(router, *, cost_per_request, name='resolved', alpha=0.1, holdout=0.25, min_drop=0.05, distill_kw=None, seed=0)[source]

Train a new router tier from harvested teacher labels.

Every harvested input escalated through the existing tiers, so the baseline escalation rate on that set is 1.0. A new tier is fit and calibrated on a held-out split of the same harvested set without re-calling the teacher. It is inserted only if its calibrated escalation rate drops by at least min_drop below 1.0 on that split.

Parameters:
Return type:

HarvestResolveResult