mixle.task.deploy_family module

F11: deployment of an accepted checkpoint family 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 accepted 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.

Artifact and cost contracts. A family point is emitted only for a rung that passed J2’s quality gate. Each point retains the exact per-parameter quantized payload, an executable model materialized from that payload, a canonical state payload, and a SHA-256 content address. The receipt therefore identifies something that can actually be served and independently verified, rather than summarizing temporary arrays that have already been discarded.

Every deployable is executed on the caller’s declared probe_inputs under PyTorch’s FLOP profiler. Per-request cost is priced from those measured operations relative to the headline: cost_per_request = cost.c_frontier * (inference_flops / headline_inference_flops). Storage bytes remain separately receipted and use each source tensor’s real dtype width.

class ArtifactReceipt(name, n_tensors, dense_bytes, quantized_bytes, compression_ratio, mean_reconstruction_error, method_counts, content_digest)

Bases: object

One model’s I1-quantized deployment artifact: real measured bytes/error rolled up over every parameter tensor. Tensors whose encoding overhead would exceed their dense source are retained exactly and reported as dense rather than being made larger in the name of compression.

Parameters:

• name (str)

• n_tensors (int)

• dense_bytes (int)

• quantized_bytes (int)

• compression_ratio (float)

• mean_reconstruction_error (float)

• method_counts (dict[str, int])

• content_digest (str)

class DenseParameter(array)

Bases: object

Exact fallback for a tensor whose quantized payload plus metadata would be larger.

Parameters:

array (ndarray)

class DeployableArtifact(name, model, parameters, state, receipt)

Bases: object

Content-addressed executable model plus the exact payload that produced its served weights.

Parameters:

• name (str)

• model (Any)

• parameters (tuple[QuantizedParameter, ...])

• state (tuple[StateTensor, ...])

• receipt (ArtifactReceipt)

verify()

Return whether the executable model still matches its immutable content address.

Return type:

bool

serve(*args, **kwargs)

Execute the verified artifact; mutation after publication fails closed.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

class FrontierPoint(name, real_target, artifact, inference_flops, cost_per_request, quality)

Bases: object

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

Parameters:

• name (str)

• real_target (str)

• artifact (DeployableArtifact)

• inference_flops (int)

• cost_per_request (float)

• quality (float)

class QuantizedParameter(name, tensor)

Bases: object

A named compressed or exact-dense payload retained by a deployable artifact.

Parameters:

• name (str)

• tensor (QuantizedTensor | DenseParameter)

class ServeReceipt(points, probe_digest, edge_cascade=None)

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])

• probe_digest (str)

• edge_cascade (CascadeReceipt | None)

is_monotone_frontier(*, tol=1e-9)

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)

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

class StateTensor(name, dtype, shape, data)

Bases: object

Canonical bytes for one tensor in the executable artifact state.

Parameters:

• name (str)

• dtype (str)

• shape (tuple[int, ...])

• data (bytes)

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

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

Retains I1’s selected payload for each parameter and uses an exact dense fallback when no encoding fits the literal byte budget. The per-model receipt contains real totals over the source dtypes, never a single assumed bits-per-parameter constant. seed is offset per tensor (seed + i).

Parameters:

• model (Any)

• name (str)

• bits (int)

• seed (int)

Return type:

DeployableArtifact

deploy_family(family, headline_model, *, probe_inputs, edge_cascade_receipt=None, cost=None, bits=8, seed=0)

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

Every accepted rung (and the headline) is I1-quantized into a real DeployableArtifact (quantize_family_artifacts()); each artifact’s per-request cost is priced off cost (a CostModel, CostModel(c_frontier=1.0) by default) scaled by measured inference work 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)

• probe_inputs (Any)

• edge_cascade_receipt (CascadeReceipt | None)

• cost (CostModel | None)

• bits (int)

• seed (int)

Return type:

ServeReceipt