mixle.task.deploy_family module

F11: deployment of the family – the trained checkpoint family served through the existing stack.

Scope, read this first. F11 is, per the roadmap, thin composition over machinery that already exists and is already receipted:

  • J2 (mixle.task.checkpoint_family_ladder) builds the family itself: a headline causal LM plus a ladder of decreasing-size rungs, each with its own real eval report.

  • I1 (mixle.models.unified_quantizer) turns a torch model’s real parameter tensors into “I-quantized artifacts” – per-tensor auto-picked quantization with a measured bytes/error receipt.

  • J4 (mixle.task.frontier_to_native) builds the edge tier: a frontier-distilled, LNS-compressed, calibrated student served behind a Cascade, with its own cost/quality receipt.

  • Economics (mixle.task.economics) supplies CostModel, the unit costs a per-request dollar figure is built from.

This module does not re-derive compression, quantization, distillation, calibration, or cost arithmetic; it takes J2’s family, I1-quantizes every rung (plus the headline) into a real measured artifact, and reports a cost/quality frontier across those artifacts – the roadmap’s “end-to-end serve receipt (cost/quality frontier plot)” acceptance criterion – next to J4’s own served-cascade receipt for the edge tier.

A real constraint this discovered, not glossed over: two receipted “quality” axes don’t share units, so this module does not force them onto one line. J2’s family rungs are causal LMs scored by F10’s synthetic eval suite (mixle.models.eval_harness) – perplexity plus three accuracy-style tasks. J4’s edge student is a distilled classifier scored by held-out label accuracy on whatever task it was trained for. Both are real, receipted quality numbers, but they measure different capabilities on different tasks; averaging them into one scalar would manufacture a false equivalence the underlying receipts do not support. So deploy_family() reports two things side by side instead: a same-axis cost/quality frontier across the J2 family + headline (comparable, because every point is the SAME eval suite on the SAME task), and J4’s own CascadeReceipt as the edge tier’s cost/quality trade on ITS task, unmerged. ServeReceipt.summary() prints both.

Why this does not build a full :class:`~mixle.task.router.Router` across the whole family. Router requires every non-final tier to expose decide(x) (a CalibratedTaskModel shape returning a label or ESCALATE); J2’s family rungs are plain causal LMs with no calibrated decision boundary, and building one would mean inventing an eval-suite-specific classifier wrapper this task does not ask for. J4’s own 2-tier Cascade (student, calibrated; frontier, a callable) already IS the calibrated-routing piece this module reuses unmodified via build_served_cascade() – what’s genuinely new here is turning J2’s causal-LM family into comparable priced artifacts, which is a quantization/costing question, not a routing one.

Cost model. Every artifact’s per-request cost is priced off ONE CostModel, scaled by real measured artifact bytes relative to the most expensive (headline/frontier) artifact: cost_per_request = cost.c_frontier * (artifact_bytes / headline_artifact_bytes). This is an honest, declared proxy (inference cost tracks model size, not size-independent) rather than a literal cloud price list – the real number in the receipt is artifact_bytes (I1’s measured quantized footprint); the dollar figure is a transparent, reproducible scaling of it through the SAME CostModel the rest of the stack (J4’s cascade) already uses for its own tier’s cost.

class ArtifactReceipt(name, n_tensors, dense_bytes, quantized_bytes, compression_ratio, mean_reconstruction_error, method_counts)[source]

Bases: object

One model’s I1-quantized deployment artifact: real measured bytes/error rolled up over every parameter tensor – I1’s own QuantizationReceipt per tensor, summed/averaged here, not re-derived.

Parameters:
class FrontierPoint(name, real_target, artifact, cost_per_request, quality)[source]

Bases: object

One priced, quality-scored point on the family’s cost/quality frontier.

Parameters:

  • name (str)

  • real_target (str)

  • artifact (ArtifactReceipt)

  • cost_per_request (float)

  • quality (float)

class ServeReceipt(points, edge_cascade=None)[source]

Bases: object

F11’s end-to-end serve receipt: the J2-family cost/quality frontier, plus J4’s own edge-tier served-cascade receipt reported alongside it (see the module docstring for why the two axes are kept separate rather than merged).

Parameters:

  • points (list[FrontierPoint])

  • edge_cascade (CascadeReceipt | None)

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

Real, checkable claim: walking the family points cheapest-first, quality never DROPS below tolerance – i.e. paying more for a bigger rung is never strictly worse on the eval suite.

Parameters:

tol (float)

Return type:

bool

frontier_plot(*, width=40)[source]

A deterministic, dependency-free ASCII cost/quality scatter (no matplotlib in this repo’s dependency set) – x = cost_per_request (log-scaled across the family’s real span), y = quality. This is a real, reproducible rendering of the receipted numbers below, not decoration.

Parameters:

width (int)

Return type:

str

quantize_family_artifacts(model, *, name, bits=8, seed=0)[source]

I1: quantize_tensor(method="auto") over every real, non-empty parameter tensor of model.

Rolls I1’s per-tensor receipts (chosen method, measured bytes, measured reconstruction error) into one per-model ArtifactReceipt – real totals over real per-tensor measurements, never a single assumed bits-per-parameter constant. seed is offset per tensor (seed + i) so the auto-pick bandit’s tie-breaking is deterministic but not identical across tensors of the same shape.

Parameters:
Return type:

ArtifactReceipt

deploy_family(family, headline_model, *, edge_cascade_receipt=None, cost=None, bits=8, seed=0)[source]

Build F11’s end-to-end serve receipt from a J2 FamilyLadderResult plus its own headline_model.

Every rung (and the headline) is I1-quantized into a real measured ArtifactReceipt (quantize_family_artifacts()); each artifact’s per-request cost is priced off cost (a CostModel, CostModel(c_frontier=1.0) by default) scaled by real measured bytes relative to the headline’s own artifact (see module docstring); quality is J2’s own real EvalReport for that rung/headline, reduced to _quality_score(). edge_cascade_receipt (optional) is J4’s own CascadeReceipt for the edge tier, carried through unmodified and reported alongside the family frontier rather than merged into it.

Parameters:

  • family (FamilyLadderResult)

  • headline_model (Any)

  • edge_cascade_receipt (CascadeReceipt | None)

  • cost (CostModel | None)

  • bits (int)

  • seed (int)

Return type:

ServeReceipt