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, attempted=0, answered=0, failed=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.

property n_attempts: int

Return every paid tier invocation, including escalation and failure.

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='', n_train=0, n_calibration=0, n_evaluation=0, escalation_drop_lower=0.0, local_accuracy=0.0, local_accuracy_lower=0.0, evaluation_confidence=0.0, reason='')[source]

Bases: object

Receipt from resolve_from_harvest().

escalation_before is one on the reserved evaluation subset because every member is a recorded frontier escalation under the current router. escalation_after and local_accuracy are measured only after the candidate tier is frozen. Their one-sided simultaneous lower bounds gate insertion. router remains None when either bound is insufficient.

Parameters:

  • accepted (bool)

  • n_harvested (int)

  • escalation_before (float)

  • escalation_after (float)

  • escalation_drop (float)

  • agreement (float)

  • router (Router | None)

  • tier_name (str)

  • n_train (int)

  • n_calibration (int)

  • n_evaluation (int)

  • escalation_drop_lower (float)

  • local_accuracy (float)

  • local_accuracy_lower (float)

  • evaluation_confidence (float)

  • reason (str)

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

Train a new router tier from harvested teacher labels.

The harvest is split before fitting into training, calibration, and an untouched post-selection evaluation set. The new tier is selected using only training/calibration data. It is inserted only when simultaneous one-sided exact-binomial lower bounds on evaluation interception and local accuracy clear min_drop and 1 - alpha respectively.

Parameters:
Return type:

HarvestResolveResult