mixle.task.frontier_to_native module

Frontier -> mixle-native students: distill, LNS-compress, calibrate, cascade – the loop closed.

The end-to-end pipeline the roadmap calls “J4”: take a frontier/teacher model (large, expensive, general-purpose), distill it into a SMALL, TASK-SPECIFIC student, re-execute that student’s inference in mixle.engines.lns.LogNumberSystem’s integer log-space (compact, transcendental-free), wrap it in CalibratedTaskModel for an honest answer-or-escalate decision, and compose it with the teacher into a Cascade for served, tiered inference.

This module is deliberately thin: every piece already exists –

  • mixle.task.distill.distill_structured() distills a teacher into a structured probabilistic student (a learned dependency network: kilobytes, torch-free, an exact posterior).

  • mixle.task.quantize.lns_classifier() re-executes that student’s inference in the LogNumberSystem integer log-space (the same LNS task.quantize already applies for compute quantization).

  • CalibratedTaskModel calibrates a conformal answer/escalate threshold on held-out data (CalibratedGenerator is the generative sibling – it also exposes decide(), so it drops into Cascade unmodified if the task is generative rather than classification).

  • Cascade serves the calibrated LNS student first, escalating only ambiguous/OOD requests to the teacher, and tracks realized cost.

  • mixle.task.edge.footprint() measures the LNS student’s real deployment bytes.

distill_to_lns_student() / build_served_cascade() / measure_cascade_receipt() wire those five subsystems together and report the two numbers the roadmap item’s acceptance criteria ask for: a served cascade cost/quality receipt, and the edge student’s footprint + student-teacher agreement rate.

class CascadeReceipt(n_requests, n_escalated, student_cost_per_request, teacher_cost_per_request, cascade_cost_per_request, student_quality, teacher_quality, cascade_quality, student_bytes, teacher_bytes, compression_ratio, agreement_rate)[source]

Bases: object

The served cascade’s cost/quality tradeoff, plus the edge student’s footprint and agreement.

*_cost_per_request are the per-request costs (student-only always local, teacher-only always escalates, cascade the realized mix); the whole point of cascading is that cascade_cost lands near student_cost while cascade_quality lands near (or measurably closer to) teacher_quality – see earns_its_complexity(). student_bytes/teacher_bytes are the real, measured deployment footprints (footprint() for the student); disk compression_ratio is teacher_bytes / student_bytes when a teacher footprint is supplied. agreement_rate is the fraction of the held-out test set where the LNS student’s own answer (not the cascade’s escalate-mediated answer) matches the teacher’s.

Parameters:

  • n_requests (int)

  • n_escalated (int)

  • student_cost_per_request (float)

  • teacher_cost_per_request (float)

  • cascade_cost_per_request (float)

  • student_quality (float)

  • teacher_quality (float)

  • cascade_quality (float)

  • student_bytes (int)

  • teacher_bytes (int | None)

  • compression_ratio (float | None)

  • agreement_rate (float)

earns_its_complexity(*, tol=1e-9)[source]

Whether the cascade actually beats the extremes it sits between.

Cost: cascading costs c_local + p_escalate * c_frontier per request, so it can never be cheaper than the pure-local student – but it must be strictly cheaper than always paying the teacher (tol allows the degenerate zero-escalation case, where cascade cost equals the student’s exactly). Quality: the cascade must be at least as good as the student alone (the escalations it does pay for should be net-positive, not wasted spend).

Parameters:

tol (float)

Return type:

bool

distill_to_lns_student(teacher, task_data, *, labels=None, n_components=1, min_gain=0.0, n_bins=4, max_its=30, step=1e-2, seed=0, task='', n_jobs=1)[source]

Distill teacher into a small, task-specific structured student, then LNS-compress it.

Reuses distill_structured() for the distillation (the teacher labels task_data once; the student discovers the joint dependency structure and classifies generatively) and lns_classifier() for the LNS conversion – no new quantization or distillation logic, just the existing rungs composed. The returned TaskModel runs inference as integer add/max/LUT above the leaf boundary (mixle.engines.lns) and needs no torch.

Parameters:
Return type:

TaskModel

build_served_cascade(lns_student, teacher, cal_data, cal_labels=None, *, alpha=0.1, cost=None)[source]

Calibrate the LNS student and compose it with teacher into a served Cascade.

cal_data is a held-out slice (disjoint from lns_student’s training data) used to fit the conformal answer/escalate threshold (calibrate()). If cal_labels is omitted, the teacher labels cal_data itself (one batched call) – the same “teacher is the ground truth for calibration” convention distill_for_routing() uses. The returned Cascade answers locally when the LNS student’s conformal set is a confident singleton, and escalates to teacher otherwise.

Parameters:
Return type:

Cascade

measure_cascade_receipt(cascade, test_data, truth_labels, *, teacher_bytes=None)[source]

Serve test_data through cascade and measure the real cost/quality/footprint/agreement receipt.

Reuses the machinery already built for this, rather than re-deriving it: Cascade.serve() (real serving, so cascade’s stats/realized cost are genuine, not simulated), footprint() for the student’s measured deployment bytes, and plain accuracy-vs-truth_labels for quality (the student and teacher are scored on the SAME held-out set the cascade was served, so all three numbers are directly comparable). teacher_bytes is the caller-supplied measured/declared footprint of the frontier model (opaque to mixle – it is not a mixle artifact) used only for the reported compression ratio.

Parameters:
Return type:

CascadeReceipt