mixle.task.model module

Callable task-model wrapper for serialized local models.

The artifact contract (mixle.task.artifact) makes a model durable. TaskModel makes it directly usable by pairing a fitted model with an I/O adapter that converts raw application inputs into model features and converts model outputs into application results. The adapter is serialized in the artifact manifest, so TaskModel.load(path) reconstructs the full raw_input -> result callable in a fresh process.

Adapters self-describe and rebuild through a registry (register_adapter / IOAdapter.from_spec). The built-in TextClassifierIO supports the distillation path with a dependency-free hashed character n-gram featurizer, a small classifier, and a stored label map.

class HashedNGram(n=3, dim=256, seed=0)[source]

Bases: object

Map a string to a fixed-width float vector by hashing its character n-grams into dim buckets.

The featurizer is deterministic and dependency-free. It serializes as three scalar settings and rebuilds without a fitted vocabulary or external tokenizer. Counts are L2-normalized per row.

Parameters:
transform(texts)[source]

Return L2-normalized hashed n-gram feature rows for texts.

Parameters:

texts (list[str])

Return type:

ndarray

to_spec()[source]

Return the serializable featurizer configuration.

Return type:

dict[str, Any]

classmethod from_spec(spec)[source]

Rebuild a featurizer from to_spec() output.

Parameters:

spec (dict[str, Any])

Return type:

HashedNGram

class HashedRecord(dim=256, seed=0)[source]

Bases: object

Map a heterogeneous record to a fixed-width hashed feature vector.

Each tuple position or dictionary key owns a hashed namespace. Categorical, string, and boolean values contribute an indicator feature; numeric values contribute a bounded value feature and a presence feature. The transform is stateless and deterministic, so it serializes as two scalar settings and rebuilds without a fitted encoder or vocabulary.

Parameters:
transform(records)[source]

Return L2-normalized hashed feature rows for heterogeneous records.

Parameters:

records (list[Any])

Return type:

ndarray

to_spec()[source]

Return the serializable record-featurizer configuration.

Return type:

dict[str, Any]

classmethod from_spec(spec)[source]

Rebuild a record featurizer from to_spec() output.

Parameters:

spec (dict[str, Any])

Return type:

HashedRecord

register_adapter(kind, from_spec)[source]

Register an adapter’s from_spec factory under kind so a saved io block can rebuild it.

Parameters:
Return type:

None

adapter_from_spec(spec)[source]

Rebuild an adapter from its io spec (the kind field selects the factory).

Parameters:

spec (dict[str, Any])

Return type:

Any

class TextClassifierIO(featurizer, labels)[source]

Bases: _ClassifierIO

str -> label: hashed character n-gram features into a small classifier.

Parameters:

  • featurizer (HashedNGram)

  • labels (list[str])

class RecordClassifierIO(featurizer, labels)[source]

Bases: _ClassifierIO

record -> label: hashed-record features into a small classifier (tuples/dicts of mixed fields).

Parameters:

  • featurizer (HashedRecord)

  • labels (list[str])

class StructuredClassifierIO(field_keys, label_index, labels)[source]

Bases: object

record -> label through a structured probabilistic model instead of a neural net.

The model is a fitted joint over (field_1, ..., field_m, label) – a DependencyTreeDistribution (or mixture) discovered by mixle.inference.structure.learn_structure(). Classification is the generative rule argmax_label P(features, label): score each candidate label and pick the best. Because softmax_label log P(features, label) = P(label | features) exactly (the feature evidence is a shared constant across labels), proba_batch() returns the true posterior – not a softmax over arbitrary logits – so conformal calibration (mixle.task.calibrate) and the density gate operate on a real probability.

The student is interpretable (model.edges() shows the discovered dependencies), kilobytes on disk, and round-trips through the json artifact path. It assumes a fixed schema: every record exposes the same fields (field_keys for dicts, positional for tuples) – the variable set a Bayesian network is defined over.

Parameters:
logits_batch(model, raw_inputs)[source]

Per-label log-joint log P(features, label) as an (m, K) score matrix (the classifier logits).

Parameters:
Return type:

ndarray

proba_batch(model, raw_inputs)[source]

The exact posterior P(label | features) – softmax of the per-label log-joints (shared evidence cancels).

Parameters:
Return type:

ndarray

predict_batch(model, raw_inputs)[source]

Predict labels for raw inputs by maximizing the per-label joint score.

Parameters:
Return type:

list[str]

predict(model, raw_input)[source]

Predict the label for one raw input.

Parameters:
Return type:

str

to_spec()[source]

Return the serializable structured-classifier adapter specification.

Return type:

dict[str, Any]

classmethod from_spec(spec)[source]

Rebuild a structured-classifier adapter from its artifact io specification.

Parameters:

spec (dict[str, Any])

Return type:

StructuredClassifierIO

class TaskModel(model, adapter, *, builder=None, config=None, payload='torch', task='', meta=None)[source]

Bases: object

A fitted small model plus its I/O adapter, callable as task(raw) -> result and saveable to a directory.

Parameters:

  • model (Any)

  • adapter (Any)

  • builder (str | None)

  • config (dict[str, Any] | None)

  • payload (str)

  • task (str)

  • meta (dict[str, Any] | None)

batch(raw_inputs)[source]

Run the wrapped model on a batch of raw inputs through its adapter.

Parameters:

raw_inputs (list[Any])

Return type:

list[Any]

save(path)[source]

Persist as a task artifact: the model payload plus the adapter’s io spec and metadata.

Parameters:

path (str)

Return type:

str

classmethod load(path, *, device='cpu')[source]

Rebuild a TaskModel (model + adapter) from a saved artifact directory.

Parameters:
Return type:

TaskModel