Production Workflows¶

Production support lives primarily in mixle.inference.production and mixle.task. The goal is not to replace deployment infrastructure. The goal is to make fitted probabilistic models self-describing, versionable, monitorable, and callable behind a service or cascade.

This page describes practical helpers, not a full production platform. Validate serialization, scoring latency, drift thresholds, rollback behavior, and runtime dependencies in the environment where the model will actually run.

Production concerns are grouped into five areas:

provenance headers;
verifiable training lineage;
registry and alias promotion;
scoring services with activity logs;
drift detection and retrain/swap monitoring.
reproducibility receipts and local telemetry where the broader runtime layer is used.

Fit with Provenance¶

fit_with_provenance fits a model and attaches a structured Header.

from mixle.inference.production import fit_with_provenance, verify_lineage
from mixle.stats import GaussianEstimator

model, header = fit_with_provenance(
    data,
    GaussianEstimator(),
    max_its=30,
    seed=1,
)

print(header.dataset_hash)
print(header.model_hash)
print(header.final_loglik)
print(verify_lineage(header))

The header records:

model type and summary;
inferred schema when available;
record count and dataset hash;
final log likelihood;
model hash;
training settings and convergence trace;
timing, resource usage, environment, and git commit when available.

Build Headers Explicitly¶

Use build_header when fitting happened elsewhere but you still want a provenance record.

from mixle.inference.production import build_header

header = build_header(
    model,
    data,
    training={"source": "external-fit"},
    final_loglik="auto",
)

Headers are plain serializable records through Header.to_dict().

Registry¶

Registry stores models by name and version. It also supports aliases such as production so serving code can load the currently promoted version.

from mixle.inference.production import Registry

registry = Registry("/tmp/mixle-registry")
version = registry.register(model, "events", header=header)

print(registry.names())
print(registry.versions("events"))

registry.promote("events", version, alias="production")
prod_model, prod_header = registry.current("events", alias="production")

The registry is filesystem-backed and serializes models through mixle’s serialization registry. Model names, versions, and aliases are constrained to single path components. An unsafe name such as "../model" raises ValueError, and unknown names or versions raise clear KeyError messages rather than leaking store paths.

Reproducibility Receipts¶

Use record_fit when the fit itself must be replayable, not merely stored.

from mixle.inference import record_fit, verify_reproducible

receipt = record_fit(model, data, seed=1, estimator=estimator)
check = verify_reproducible(estimator, data, receipt, seed=1)

print(receipt.as_dict())
print(check["reproducible"])

The receipt records a data fingerprint, seed, estimator type, and parameter fingerprint. It complements provenance headers: the header describes the training run, while the reproducibility receipt checks whether the same fit can be recovered.

Checkpointing Long Fits¶

Registry checkpointers can snapshot a model during optimization:

from mixle.inference import optimize
from mixle.inference.production import Registry

registry = Registry("/tmp/mixle-checkpoints")
model = optimize(
    data,
    estimator,
    max_its=100,
    on_step=registry.checkpointer("run-2026-07-01", every=5),
    out=None,
)

print(registry.verify_chain("run-2026-07-01"))

Each checkpoint can carry lineage metadata, making interruption and audit workflows explicit.

Service¶

Service wraps a fitted model and scores batches while recording activity.

from mixle.inference.production import Service

service = Service(model, name="events", reference=reference_data)
log_probs = service.score(current_batch)
print(service.health())

Activity logs include record count, wall time, mean log likelihood, and the number of unscorable records. A JSONL log path can be supplied for persistent activity records.

For application-level route, placement, context, pool, and reasoning events, use mixle.telemetry and the workflow in Local Reasoning Ecosystem.

Load from a Registry Alias¶

service = Service.from_registry(registry, "events", alias="production")
scores = service.score(records)

This is the handoff point for deployment systems: promote a version in the registry, and serving code reads the alias.

Drift Detection¶

detect_drift compares reference data to current data using both model-native score drift and per-feature shift.

from mixle.inference.production import detect_drift

report = detect_drift(
    model,
    reference_data,
    current_data,
    psi_threshold=0.25,
    ks_threshold=0.2,
    loglik_shift_threshold=-0.5,
)

print(report.drift)
print(report.score)
print(report.per_feature)

Score drift looks at the model’s log-density distribution. Feature drift uses population stability index, Kolmogorov-Smirnov, and related summary statistics where applicable.

Task Artifacts and Cascades¶

mixle.task models are production-oriented artifacts for local task serving. They can be saved, loaded, calibrated, and placed behind a Cascade that escalates uncertain inputs to a teacher.

Use Task Distillation when the production object is a classifier, extractor, or local LLM-distilled model rather than a density model.

Practical Deployment Shape¶

Fit with provenance.
Register the model.
Promote a version to an alias.
Serve through Service or a task Cascade.
Log scoring activity.
Run drift checks against a reference sample.
Retrain and promote a new version when drift or quality thresholds fail.

API Map¶

Import	Purpose
`fit_with_provenance`	fit and produce a provenance header
`Header`, `build_header`, `environment_info`	provenance records and environment capture
`verify_lineage`	verify convergence/model-hash lineage
`Registry`	versioned model store and alias promotion with safe path components
`Service`	batch scoring with activity logging and health summaries
`detect_drift`, `score_drift`, `DriftReport`	drift detection from model scores and feature shifts
`Monitor`	drift-triggered retrain/swap loop
`record_fit`, `verify_reproducible`, `ReproReceipt`	replay and verify fitted parameter recovery
`Telemetry`, `record`	local decision events for reasoning, routing, placement, and pool jobs