mixle.task.regress module

solve_regression for calibrated replacement of numeric task functions.

The regression shape of the solve loop. teacher(x) -> float is the scorer/pricer/estimator being replaced; a small student learns it, and calibration is split conformal for regression: on a held-out slice the absolute-residual quantile qhat is set so the interval [yhat - qhat, yhat + qhat] covers the teacher’s answer with probability >= 1 - alpha (finite-sample, distribution-free, exchangeable inputs). The escalate-or-answer rule becomes a precision rule: answer locally only when the guaranteed interval is tight enough for the caller’s purpose (qhat <= tol); otherwise run the real code. So a locally answered value is covered by the calibrated interval; if the student cannot achieve that precision, every request escalates.

def price(item): … # the rigid pricing routine sol = solve_regression(price, items, tol=5.0) # dataset <- price(i); train; calibrate sol(item) # a float: local (±tol guaranteed) or teacher sol.interval(item) # (yhat, lo, hi) with 1 - alpha coverage sol.improve(); sol.report() # the same compounding loop

qhat is one global width, as in standard split conformal regression.

class RecordRegressionFeaturizer(dim=256, seed=0)

Bases: object

Record featurizer for regression tasks.

HashedRecord (built for classification) squashes numerics through tanh, which saturates and erases the magnitude signal a regressor needs. Here numeric keys (learned from the fit sample) map to dedicated standardized columns; everything else uses hashing.

Parameters:

• dim (int)

• seed (int)

fit(records)

Learn numeric-key normalization statistics from sample records.

Parameters:

records (list[Any])

Return type:

RecordRegressionFeaturizer

transform(records)

Transform records into standardized numeric columns plus hashed categorical features.

Parameters:

records (list[Any])

Return type:

ndarray

to_spec()

Serialize numeric-key statistics and hashing settings.

Return type:

dict[str, Any]

classmethod from_spec(spec)

Reconstruct a regression featurizer from an artifact spec.

Parameters:

spec (dict[str, Any])

Return type:

RecordRegressionFeaturizer

featurizer_spec(f)

Tagged, artifact-ready spec for the featurizers the solve shapes use.

Parameters:

f (Any)

Return type:

dict[str, Any]

featurizer_from_spec(spec)

Reconstruct a task featurizer from a tagged artifact spec.

Parameters:

spec (dict[str, Any])

Return type:

Any

class RegressionSolution(net, featurizer, teacher, qhat, alpha, tol, holdout_mae, y_mean, y_scale, train_inputs=<factory>, train_ys=<factory>, cal_inputs=<factory>, cal_ys=<factory>, hidden=(64, ), epochs=300, lr=0.01, seed=0, n_requests=0, n_escalated=0, harvested_inputs=<factory>, harvested_ys=<factory>)

Bases: object

A calibrated numeric student in front of the routine it replaces.

Parameters:

• net (Any)

• featurizer (Any)

• teacher (Callable[[...], Any])

• qhat (float)

• alpha (float)

• tol (float)

• holdout_mae (float)

• y_mean (float)

• y_scale (float)

• train_inputs (list)

• train_ys (list)

• cal_inputs (list)

• cal_ys (list)

• hidden (tuple)

• epochs (int)

• lr (float)

• seed (int)

• n_requests (int)

• n_escalated (int)

• harvested_inputs (list)

• harvested_ys (list)

interval(x)

Return (yhat, lo, hi) with calibrated teacher-answer coverage.

Parameters:

x (Any)

Return type:

tuple[float, float, float]

property answers_locally: bool

Whether the calibrated precision meets the tolerance at all (else everything escalates).

decide(x)

Return the calibrated point estimate when local precision is sufficient.

If answers_locally is false, return None to signal escalation. Unlike __call__, this method never falls through to the teacher itself, so a Router tier can decide whether to escalate to the next tier.

Parameters:

x (Any)

Return type:

float | None

report()

Return calibration, precision, request, and harvest metrics.

Return type:

dict[str, Any]

save(path)

Persist the network, featurizer, and calibration metadata.

Parameters:

path (str)

Return type:

str

classmethod load(path, teacher, *, device='cpu')

Reconstitute a serving RegressionSolution (no training/calibration data; improve() raises).

Parameters:

• path (str)

• teacher (Callable[[...], Any])

• device (str)

Return type:

RegressionSolution

improve()

Re-fit with harvested pairs; promote only if the calibrated width shrinks (anti-regression).

Return type:

bool

solve_regression(teacher, inputs, *, tol, alpha=0.1, holdout=0.25, kind=None, hidden=(64,), epochs=300, lr=1e-2, dim=256, prelabeled=None, seed=0)

Replace a numeric routine with a conformally-calibrated student (see module docstring).

Parameters:

• teacher (Callable[[...], Any]) – the numeric routine (teacher(x) -> float); labels the dataset, remains the fallback.

• inputs (Sequence[Any]) – example inputs (text or dict/tuple records).

• tol (float) – the caller’s precision requirement — answer locally only when the calibrated qhat <= tol.

• alpha (float) – interval miscoverage level (1 - alpha coverage of the teacher’s answer).

• prelabeled (tuple[Sequence[Any], Sequence[float]] | None) – already-teacher-labeled (inputs, values) — typically harvested escalations from a serving deployment — folded into the TRAINING split only, never calibration (which stays a fresh split of inputs, so qhat keeps its finite-sample guarantee). The re-solve half of the serving loop.

• holdout (float)

• kind (str | None)

• hidden (Sequence[int])

• epochs (int)

• lr (float)

• dim (int)

• seed (int)

Return type:

RegressionSolution