API Overview

The generated reference under mixle is exhaustive. This page is the human map: where to import the thing you are probably looking for.

Fit a model

Task	Import	Notes
Fit an estimator or prototype distribution	from mixle.inference import optimize	Main EM/MLE entry point.
Initialize or estimate directly	from mixle.inference import initialize, estimate	Useful when you want explicit control over one E/M pass.
Try multiple random starts	from mixle.inference import best_of	Common for mixtures and HMMs.
Stream updates	from mixle.inference import StreamingEstimator	Online or mini-batch estimation.
Create a certified artifact	from mixle.inference import create	Fits a model and attaches certificate, optional calibration, UQ, and provenance.
Simulate from a fitted model	from mixle.inference import simulate	Packages a model as a baseline/scenario simulator.
Build a verified synthetic dataset	from mixle.inference import synthesize	Draws inputs, optionally labels them, and keeps rows that verify.
Record and replay a fit	from mixle.inference import record_fit, verify_reproducible	Stores and checks data/parameter fingerprints.
Certify and place estimation blocks	from mixle.inference import certify, plan_placement	Reports estimation guarantees and local/pool placement.
Use gradient MAP/MLE	from mixle.inference.gradient_fit import fit_map, fit_mle	For differentiable parameter objectives.

Build distributions and estimators

Family group	Common imports
Scalar families	GaussianDistribution, PoissonDistribution, CategoricalDistribution
Estimators	GaussianEstimator, PoissonEstimator, CategoricalEstimator
Records and tuples	CompositeDistribution, CompositeEstimator, RecordDistribution
Sequences	SequenceDistribution, SequenceEstimator
Latent models	MixtureDistribution, MixtureEstimator, HiddenMarkovModelDistribution
Bayesian families	mixle.stats.bayes and mixle.inference.priors

Most high-level distribution symbols are re-exported from mixle.stats:

from mixle.stats import GaussianEstimator, MixtureEstimator, SequenceEstimator

Use the implementation submodules when you want a narrower import or source location, for example mixle.stats.univariate.continuous.gaussian.

For the full narrative catalog, use Univariate Families, Structured Statistical Families, and Latent, Bayesian, And Nonparametric Families.

Use neural and language-model leaves

The symbols in this section live in mixle.models, an incubating applied helper namespace. Use them when a neural likelihood really belongs inside a larger model. For ordinary distribution work, prefer mixle.stats first.

Task	Import	Notes
Fit a small causal LM directly	from mixle.models import LM	LM.fit trains token sequences; generate and nll query it.
Put a Transformer inside a distribution	from mixle.models import StreamingTransformer	Wraps a Torch module as an estimator-compatible neural leaf.
Use a ready LM estimator	from mixle.models import TransformerLMEstimator	Fits (context, next_token) observations as a generative leaf.
Tie token embeddings across experts	from mixle.models import CategoricalEmbedding	Reuse one embedding in several LM estimators.
Preference optimization	from mixle.models import DPOModel	A DPO-trained preference leaf over (x, chosen, rejected) triples.
Neural Gaussian/categorical leaves	from mixle.models import NeuralGaussian, NeuralCategorical	Conditional Torch-backed regression and classification likelihoods.
Unconditional neural density	from mixle.models import NeuralDensity, build_maf, build_coupling_flow	Wrap exact-density Torch modules as Mixle leaves.
Constructible neural density families	from mixle.models import VAE, Flow, MAF, DiscreteAR	Use common neural-density families directly as distribution objects.
Conditional neural density	from mixle.models import NeuralConditionalDensity, build_mdn, build_conditional_flow	Model p(y | x) with an MDN or exact conditional flow.
Energy-based density	from mixle.models import EnergyModel, build_energy_net	Approximate normalized density from NCE-trained energy functions.
Autoregressive categorical density	from mixle.models import build_autoregressive_categorical	Exact neural density over discrete vectors.
Conditional autoregressive categorical density	from mixle.models import build_conditional_autoregressive_categorical	Exact neural p(y | x) over discrete target vectors.

Use other model families

These helpers also live in mixle.models. They share Mixle conventions where practical, but they do not all have the same maturity as the core distribution families.

Task	Import	Notes
Gaussian-process regression	from mixle.models import GaussianProcessRegressor	Exact GP regression with stationary kernels and predictive uncertainty.
Random forest conditional leaf	from mixle.models import RandomForestEstimator	Fits p(y | x) as a Mixle-compatible conditional distribution.
Truncated Dirichlet-process mixture	from mixle.models import fit_truncated_dpm	Variational finite truncation with ordinary Mixle component estimators.
Dependence discovery	from mixle.models import learn_pc_skeleton, orient_v_structures	Conditional-independence structure discovery for tabular data.
Induced grammars	from mixle.models import fit_induced_pcfg, viterbi_parse	Heterogeneous PCFG learning and parse extraction.
Knowledge graphs	from mixle.models import TransEKnowledgeGraphModel	Embedding model for entity-relation triples.
Random graphs	from mixle.models import ErdosRenyiGraphModel, StochasticBlockGraphModel	Graph-valued likelihoods and block structure.
POMDPs	from mixle.models import PartiallyObservableMarkovDecisionProcessModel	Action-conditioned hidden-state model.

Represent heterogeneous inputs

from mixle.represent import (
    ByteSegmenter,
    FeatureEmbedding,
    HeterogeneousEncoder,
    VectorQuantizer,
    WindowSegmenter,
)
from mixle.represent.posterior import PosteriorRetriever

Use mixle.represent when the front end of the model must handle multiple modalities. Segmenters cut raw data into units, embeddings map units into a shared vector space, and VectorQuantizer optionally learns a discrete codebook in that space. PosteriorRetriever uses a fitted mixture’s posterior affinity to retrieve or rerank heterogeneous records by what the model believes is similar.

For deterministic image and signal baselines:

from mixle.represent.modality import image_features, signal_features, vectorize

Design and distill tasks

Task	Import	Notes
Recommend a generative model from data	from mixle.task import recommend_model	Returns an estimator plus confidence gaps and dependency hints.
Let an LLM propose a model spec	from mixle.task import design_model	Builds only allowlisted specs and fit-validates before trusting them.
Distill a teacher into a local model	from mixle.task import distill	Teacher can be a slow model, human-facing function, or LLM labeler.
Distill a generative text student	from mixle.task import distill_text_generative	Fits per-class token models so the student exposes label posteriors and text evidence.
Replace a classification or routing function	from mixle.task import solve	Trains a calibrated local student and escalates uncertain cases.
Replace a numeric scoring or pricing function	from mixle.task import solve_regression	Uses split-conformal intervals and answers locally only when the calibrated width meets tol.
Replace a multi-label tagger	from mixle.task import solve_multilabel	Decides each label as present or absent and escalates if any label is ambiguous.
Replace a dict-valued enrichment function	from mixle.task import solve_structured	Splits a stable output schema into calibrated categorical and numeric field solvers, then escalates if any field is uncertain.
Actively choose LLM labels	from mixle.task import active_distill	Queries the teacher on the most informative pool items.
Calibrate and cascade	from mixle.task import CalibratedTaskModel, Cascade	Local answer when reliable; escalate to the teacher otherwise.
Route and score deployed students	from mixle.task import Router, scorecard	Measure escalation, local agreement, cost, and route behavior.
Distill extraction	from mixle.task import llm_extractor, distill_extractor	Turns LLM field extraction into a local sequence tagger.
Distill tool calling	from mixle.task import ToolSpec, distill_tool_caller	Local tool selector plus per-tool argument extractors.
Distill planning	from mixle.task import distill_planner, sft_planner	Stepwise next-tool planner or trace-SFT generative planner.
Train from agent history	from mixle.task import harvest_agent_traces	Build deterministic teachers from stored tool-use traces.
Distill one Torch module into another	from mixle.task.distill_methods import response_distill, hint_distill	Classic KD, feature matching, attention transfer, relational KD, and sequence-level distillation.

Build a local reasoning application

Task	Import	Notes
Store and retrieve typed knowledge	from mixle.substrate import Substrate, retrieve	Local scoped store for documents, records, artifacts, traces, and context packets.
Ask over evidence and skills	from mixle.substrate import Reasoner, investigate	Fires retrieve/compute/simulate/create/delegate actions under a budget.
Package a model as a capability	from mixle.inference import skill, SkillRegistry	Named callable with provenance and inherited certificate metadata.
Check answer factuality	from mixle.substrate import check_factuality	Claim-level support from substrate evidence.
Apply ontology constraints	from mixle.reason.ontology import Ontology	Typed relation constraints and graph-fact auditing.
Submit local-or-pool work	from mixle.pool import PoolJob, submit	Budgeted job abstraction with local fallback.
Record decision telemetry	from mixle.telemetry import Telemetry, record	JSONL events for routing, placement, reasoning, pool jobs, and drift.

Quantify LLM and reasoning uncertainty

Task	Import	Notes
Semantic-entropy LLM UQ	from mixle.reason import LLMUncertainty	Wraps any generate(prompt) -> str callable.
Claim-level reliability	from mixle.reason import sentence_claims, information_corroborator	Checks whether response claims recur across independent samples.
Cross-modal evidence fusion	from mixle.reason import Latent, Evidence, reason	Exact linear-Gaussian latent assimilation with attribution.
Epistemic/aleatoric splits	from mixle.inference.uncertainty import decompose_entropy	Used by LLM and scientific reasoning surfaces.

Transform distributions

Task	Import	Notes
Quantize a distribution	from mixle.ops import quantize	Turns a continuous distribution into finite support for enumeration.
Condition or marginalize	from mixle.ops import condition, marginalize	Requires the model to expose the relevant capability.
Build a latent mixture	from mixle.ops import mixture	Convenience constructor for weighted mixtures.
Project into a simpler family	from mixle.ops import project	Sample-based forward-KL projection into a fittable target family.
Collapse or reduce Gaussian mixtures exactly	from mixle.inference import collapse_mixture, reduce_mixture	Closed-form moment projection and Runnalls mixture reduction.
Merge parameter estimates by Fisher information	from mixle.inference import fisher_merge	Precision-weighted parameter merge for Laplace/Fisher summaries.
Pool experts	from mixle.ops import product_of_experts	Exact for supported tractable families such as shared categoricals and Gaussians.

Solve structured relations

from mixle.relations import Assignment, EditDistance, ShortestPath, ViterbiPath

Relations enumerate feasible structured objects in objective order. Use them for k-best assignments, paths, edit neighborhoods, spanning trees, constrained subsets, and graph decisions.

Model temporal processes

from mixle.process import (
    ContinuousTimeMarkovChainDistribution,
   HawkesProcessDistribution,
   InhomogeneousPoissonProcessDistribution,
   RenewalProcessDistribution,
)

The process namespace collects event-time, renewal, self-exciting, birth-death, CTMC, and random-partition families.

Analyze diagnostics and data structure

from mixle.analysis import gpd_fit, kde, ordinary_kriging, chao1, borda_count

mixle.analysis contains applied routines for extreme values, KDE, coverage, kriging, rank aggregation, spatial mixtures, max-stable processes, and covariance shrinkage.

Improve and search models

from mixle.evolve import improve, search, Space, Real, Integer, Categorical, nll_objective

mixle.evolve provides anti-regression improvement loops, typed search spaces, objective builders, operator registries, promotion verdicts, and evolution ledgers.

Use the broader inference toolkit

from mixle.inference import (
    collapse_mixture,
    laplace_posterior,
    log_score,
    reliability_curve,
    select_best,
    split_conformal,
    vuong_test,
)

Use Inference Toolkit for scoring rules, calibration, conformal prediction, cross-validation, model comparison, multiple testing, regression, survival, resampling, robust covariance, posterior helpers, closed-form projection/compression, verifier-based selection, and decision utilities.

Serve task models

from mixle.task import (
    DeviceSpec,
    Router,
    quantize_mlp,
    scorecard,
    solve,
    solve_multilabel,
    solve_regression,
    solve_structured,
)

Use Task Serving, Routing, And Edge Deployment for one-call task replacement, multi-tier routing, numeric, multi-label, and structured-output task replacement, edge-device search, quantized students, scorecards, and harnesses for replacing legacy extractors, alert rules, and matchers.

Build reasoning systems

from mixle.reason import reason_discrete, GraphLLM, CrossModalStore, CrossModalModel

Use Reasoning Systems for finite-hypothesis reasoning, graph-producing LLMs, cross-modal retrieval, evidence acquisition, amortized encoders, and learned multimodal latent models.

Inspect capabilities

import mixle

mixle.describe(model)
mixle.capabilities(model)
mixle.supports(model, mixle.capability.Enumerable)

The capability layer is the right way to ask what an object can do. It is more stable than checking concrete classes. See Capabilities And Contracts for the full behavior catalog.

Use the lifecycle facade

import mixle

m = mixle.propose(rows, fit=True)
print(m.evaluate(holdout))
print(m.explain())

mixle.Model and mixle.propose provide a high-level lifecycle around proposal, fitting, evaluation, posterior queries, distillation, deployment, and explanation. See Model Lifecycle.

Understand automatic modeling internals

from mixle.utils.automatic import analyze_structure, get_estimator

profile = analyze_structure(rows)
for line in profile.explain():
    print(line)

Use Automatic Modeling Internals when you need to inspect the profiling objects, model-family score gaps, dependency hints, validation notes, and factory functions behind recommend_model and get_estimator.

Use the PPL surface

from mixle.ppl import Normal, Poisson, Mix, Markov, Field, Group, free

PPL constructors build symbolic random variables. Calling .fit(...) lowers them to ordinary mixle.stats distributions and estimators.

Enumerate structured supports

from mixle.enumeration import top_k, density_rank, supports_enumeration

top_k and supports_enumeration are the usual first calls. Use density_rank when you need rank or cumulative-mass information for a value.

Run on engines and backends

from mixle.engines import TorchEngine, NumpyEngine, SymbolicEngine
from mixle.inference import optimize

optimize(data, estimator, engine=TorchEngine(device="cuda"))
optimize(data, estimator, backend="mp", num_workers=4)

engine= controls array math and devices. backend= controls where encoded data is folded: local process, multiprocessing, Spark, Dask, MPI, and related adapters.

Use lower-level compute surfaces

from mixle.stats.compute.sequence import seq_encode, seq_log_density_sum
from mixle.stats.compute.kernel import kernel_for

The compute layer contains the distribution contracts, encoded-data helpers, sequence drivers, declaration metadata, generated kernels, backend scoring, and stacked mixture paths that support the public APIs. See Compute Layer.

Use utility and parallel helpers

from mixle.utils.serialization import to_json, from_json
from mixle.utils.parallel import Resources, encoded_data, plan

Use Utilities And Parallelism for safe serialization, optional dependency gates, metrics, HVIS helpers, encoded-data backends, resource planning, and model-parallel estimators.

Work with data sources

from mixle.data import Schema, Field, Real, Text, check_dataset, dataset_hash

The data layer is optional. Plain Python sequences remain accepted by the encoder contract.