mixle package

mixle — a capability-oriented probability/statistics library.

The structure (see docs/ARCHITECTURE.md and docs/CAPABILITIES.md):

  • Objects — the families: mixle.dist (the umbrella over every distribution, including the graph / ranking / set / Markov families), mixle.process (stochastic processes), mixle.models (generic / applied models — GPs, neural nets, random forests, knowledge graphs, POMDPs — which aren’t full Distribution-contract families but still participate in some concerns), and mixle.relations.

  • Concerns — what you can do, each its own module: mixle.enumeration, mixle.inference, mixle.ops. (Drawing from a model is intrinsic behavior, not a separate concern: mixle.stats.sample() is the verb, and the Posterior hierarchy that inference produces lives in mixle.stats.compute.posterior / mixle.inference.posterior.)

  • Kernel — mixle.contracts (every ABC/Protocol in one import) and the capability meta-layer re-exported here (supports(), capabilities(), describe(), catalog(), what_supports(), require()).

Start with mixle.describe(x) to see what any object can do.

class Model(spec=None, *, notes=None)[source]

Bases: object

One object over the model lifecycle: build / fit / evaluate / enumerate / distill / deploy / use.

Parameters:

  • spec (Any)

  • notes (list[str] | None)

fit(data, *, restarts='auto', calibrate=False, **optimize_kw)[source]

Fit via mixle.inference.optimize(); the algorithm follows from the model’s structure.

restarts="auto" (default) makes latent-variable fitting genuinely automatic: after the plain fit, a family-agnostic saddle check runs (a mixture stuck at the symmetric saddle gives every observation a ~uniform component posterior), and on suspicion the fit silently reruns as multi-restart EM (mixle.inference.best_of()), keeping the better log-likelihood and recording what happened in notes. Pass an int to force that many restarts up front, or restarts=None for the raw single fit.

calibrate (opt-in, default off): reserve a holdout slice (a fraction, or True for 25%), fit on the rest, and attach a CalibrationReport on self.calibration measuring whether the model’s uncertainty is honest on the held-out data (PIT test + held-out log-density). Off by default because it costs training data.

Parameters:
Return type:

Model

evaluate(data)[source]

Held-out fit quality: total and mean log-density over data.

Parameters:

data (Any)

Return type:

dict[str, Any]

sample(size=None, *, seed=None)[source]
Parameters:

  • size (int | None)

  • seed (int | None)

Return type:

Any

enumerate()[source]

The fitted distribution’s enumerator (top-k / top-p / rank / seek), where supported.

Return type:

Any

posterior(x)[source]

Latent posterior for one observation (mixtures, HMMs, …), where supported.

Parameters:

x (Any)

Return type:

Any

distill(teacher=None, inputs=None, **solve_kw)[source]

Distill a tiny deployable student via mixle.task.solve().

With teacher=None the fitted model itself teaches: inputs are labeled by their most-probable latent component (posterior argmax), so a fitted mixture becomes a fast, calibrated classifier of its own clusters. Returns a mixle.task.Solution (call it, report(), improve()).

Parameters:
deploy(path)[source]

Persist a durable artifact directory (model + manifest); Model.load() restores it.

Parameters:

path (str)

Return type:

str

classmethod load(path)[source]
Parameters:

path (str)

Return type:

Model

explain_prediction(x)[source]

Exact per-part attribution of log p(x) — mixle.inference.explain().

Parameters:

x (Any)

forecast(history, horizon, **kw)[source]

Horizon predictions with honest intervals — mixle.inference.forecast() (HMMs).

Parameters:
do(interventions, **kw)[source]

Graph-surgery intervention — mixle.inference.do() (learned Bayesian networks).

Parameters:
explain()[source]

What this model is, what it supports, and how it was proposed.

Return type:

str

propose(data, *, fit=False, llm=None, holdout=0.25, seed=0, max_its=25, **recommend_kw)[source]

Propose a model for data from a verified frontier of candidates and return the winner.

Candidates come from every proposer the library has — the heuristic recommendation (mixle.task.recommend.recommend_model(), dependency-aware), the plain independence baseline (mixle.utils.automatic.get_estimator()), and, when an llm handle is given, an LLM-designed structure (mixle.task.design.design_model(), allowlisted-spec, fit-validated). Each candidate is fitted on a train split and scored on held-out data, so the ranking is out-of-sample, not a guess. The winner becomes the returned Model; the full ranking lands in Model.frontier and the per-field confidence / dependency / candidate notes in Model.notes (shown by explain()). Pass fit=True to also fit the winner to all of data before returning.

Parameters:
Return type:

Model

supports(obj, capability)[source]

Return whether obj provides capability (a Protocol or a PredicateCapability).

Parameters:
Return type:

bool

capabilities(obj)[source]

Return the set of capability names obj provides — “what can I do with this?”.

Parameters:

obj (Any)

Return type:

frozenset[str]

describe(obj)[source]

Return a plain-English summary of what obj is and what you can do with it.

The one-call answer to “what can this do?”: its category, the capabilities it has and notably lacks, the engines it runs on, and how to fit it. Works on any object; richest for distributions.

Parameters:

obj (Any)

Return type:

str

summarize(obj)[source]

Return every closed-form summary statistic obj exposes, selected by its capabilities.

The numeric companion to describe() (which says what an object can do): mean/variance/std (plus skewness/kurtosis when present) for a HasMoments distribution, entropy for HasEntropy, and the median for HasCDF. Keys absent from the result are not available in closed form for obj – so summarize never raises on a partially-featured distribution.

Parameters:

obj (Any)

Return type:

dict[str, float]

catalog()[source]

Return the full capability vocabulary (every facet/contract/role), as data.

Return type:

tuple[CapabilitySpec, …]

what_supports(capability, among)[source]

Return the names of the objects in among that provide capability.

among is an iterable of instances (or classes for method-presence protocols) — e.g. what_supports(Conditionable, [mvn, gaussian, mixture]).

Parameters:
Return type:

list[str]

require(obj, capability, op=None)[source]

Raise CapabilityError (early, with a clear message) if obj lacks capability.

Parameters:
Return type:

None

Subpackages

Submodules