Package Map¶

mixle is broad because it is meant to keep heterogeneous modeling work in a single composable environment. The package is easier to navigate if you think of it as seven layers:

the user-facing lifecycle and recommendation surface;
composable probability distributions and estimators;
inference, enumeration, uncertainty, and operations over those models;
applied neural, LLM, task, reasoning, design, and evolution workflows built on the same contracts where practical;
substrate, skill, pool, and telemetry surfaces around local applications;
compute, serialization, data, and parallel runtime support;
optional assembled applications such as mixle.scientist.

The generated API reference is available at mixle. This page is a human map for choosing where to start.

Top-Level Facade¶

Use the top-level package when you want discoverability:

import mixle

model = mixle.Model().fit(rows)
print(model.evaluate(holdout))
print(mixle.describe(model.fitted))

Important top-level exports include:

mixle.Model: Lifecycle wrapper for fit, evaluation, posterior queries, distillation, artifact handling, and explanation. See Model Lifecycle.
mixle.propose: Builds a verified candidate frontier from automatic recommendation, an independence baseline, and optionally an LLM-designed model. Treat it as an exploratory helper and validate the result on held-out data.
mixle.describe / mixle.capabilities / mixle.supports: Capability inspection. Use these before assuming that a model can enumerate, condition, marginalize, produce exact densities, expose latent posteriors, or run on a backend. See Capabilities And Contracts.
mixle.stats: High-level distribution and estimator namespace. This is the first import location for most probabilistic modeling code.

Distribution And Model Objects¶

mixle.stats contains the composable probability model substrate:

Namespace	Use it for
`mixle.stats`	Common distribution, estimator, sampler, encoder, and combinator imports.
`mixle.stats.univariate`	Continuous and discrete scalar families.
`mixle.stats.bayes`	Conjugate priors and Bayesian estimators.
`mixle.stats.compute`	The protocol and vectorized compute layer beneath the public families.
`mixle.models`	Incubating applied helpers: neural leaves, Transformer helpers, random forests, GPs, graphs, grammars, DPMs, POMDPs, and related utilities.

Use Distribution Families, Univariate Families, Structured Statistical Families, and Latent, Bayesian, And Nonparametric Families for the stable family catalog. Use Model Families when you specifically need an applied helper that is not an ordinary distribution family.

Inference And Probability Operations¶

Inference is split by kind of question rather than by data type:

Namespace	Use it for
`mixle.inference`	`optimize`, EM, streaming estimation, priors, calibration, conformal prediction, MCMC, model comparison, forecasting, diagnostics, certified model creation, simulation, verified synthesis, reproducibility receipts, skills, placement plans, and UQ dispatch.
`mixle.enumeration`	Top-k, rank, seek, nucleus traversal, HMM paths, assignments, graph structures, and quantized support traversal.
`mixle.ops`	Conditioning, marginalization, projections, transforms, mixtures, quantization, products of experts, and distribution algebra.
`mixle.ppl`	Symbolic random-variable expressions that lower to Mixle estimators, distributions, and inference targets.

The main guides are Automatic Inference, Inference, Inference Toolkit, Enumeration and Ranking, Operations, Local Reasoning Ecosystem, and Probabilistic Programming.

Applied Neural, LLM, And Task Workflows¶

The neural and LLM-facing layers reuse the same model vocabulary where practical. They are newer and more uneven than the core distribution layer, but they are part of the main Mixle story rather than miscellaneous extras:

Namespace	Use it for
`mixle.models`	Incubating Transformer leaves, direct language models, DPO leaves, neural leaves, learned embeddings, and applied model helpers.
`mixle.task`	LLM labelers, task distillation, one-call replacement for label, numeric, multi-label, and structured-output functions, active learning, local students, cascades, routers, edge search, quantization, tool calling, planning, artifacts, and scorecards.
`mixle.reason`	LLM uncertainty, semantic entropy, claim reliability, finite-hypothesis reasoning, graph-producing LLMs, typed ontologies, and cross-modal latent evidence.
`mixle.represent`	Segmenters, embeddings, heterogeneous encoders, vector quantizers, and cross-modal representations, including posterior-affinity retrieval.

Use Neural and LLM Models, Task Distillation, Task Serving, Routing, And Edge Deployment, Uncertainty, Reasoning Systems, and Representation Layer for the narrative guides. Use Project Maturity to decide how much validation each surface needs.

Local Application Runtime¶

Version 0.6.2 adds local application surfaces around fitted models:

Namespace	Use it for
`mixle.substrate`	Typed, scoped, provenanced storage for documents, records, artifacts, traces, context packets, graph facts, retrieval, multi-hop evidence, factuality checks, lineage audits, secret scans, sharing, and governance.
`mixle.inference.skill`	Packaging a fitted model, created artifact, or callable as a named reusable capability with certificate/provenance metadata.
`mixle.pool`	Local-or-pool job submission, budget checks, explicit confirmation for billable backends, and artifact return.
`mixle.telemetry`	Local JSONL decision events for fits, placement, routing, context, reasoning, escalation, pool jobs, and drift.
`mixle.scientist`	Optional assembled local scientific workflow using cached open-weight encoders, certified heads, substrate-backed reasoning, and edge distillation receipts.

Use Local Reasoning Ecosystem for the narrative guide and mixle.substrate package, mixle.pool package, mixle.telemetry package, and mixle.scientist module for API reference.

Scientific Design And Analysis¶

Mixle also includes scientific modeling support:

Namespace	Use it for
`mixle.process`	Temporal point processes, renewal processes, Hawkes processes, birth-death processes, continuous-time Markov chains, and random partitions.
`mixle.relations`	Assignment, shortest path, edit distance, Viterbi path, spanning tree, subset, and ranking relation solvers.
`mixle.analysis`	Coverage, extremes, KDE, kriging, spatial mixtures, rank aggregation, covariance shrinkage, and related diagnostics.
`mixle.doe`	Design of experiments, Bayesian optimization, active design, multi-fidelity design, sensitivity, propagation, and constrained optimization.
`mixle.evolve`	Objective-led model improvement, structure search, verification, and anti-regression ledgers.

Use Temporal And Stochastic Processes, Relations, Analysis Utilities, Design of Experiments, and Evolution And Search when the modeling task is closer to scientific design, structured optimization, or repeated model improvement.

Data, Engines, And Runtime¶

The lower layers keep model code independent from storage location, array library, and deployment format:

Namespace	Use it for
`mixle.data`	Schemas, validation, exchangeability checks, hashes, encoded IO, structured data sources, and stream token sources.
`mixle.engines`	NumPy, Torch, JAX, symbolic, bit-packed, high-precision, LNS, and precision-planning engines.
`mixle.stats.compute`	Protocol classes, encoded data, generated kernels, backend scoring, sufficient statistics, and decomposition metadata.
`mixle.utils`	Automatic model typing, serialization, optional dependency gates, metrics, vector utilities, HVIS embeddings, and runtime helpers.
`mixle.utils.parallel`	Encoded-data backends, resource planning, model sharding, distributed folding, and model-parallel estimators.

Use Data Layer, Compute Engines, Compute Layer, and Utilities And Parallelism when performance, persistence, or deployment boundaries matter.

Experimental Surface¶

mixle.experimental contains exploratory APIs that are useful for research but are not the stable entry point for new production code. The current program surface is documented in Experimental Program API. Prefer stable surfaces in mixle.stats and mixle.inference when possible. Use mixle.ppl, mixle.models, and mixle.task deliberately when their higher-level or applied workflow is the reason for the code.

Choosing An Entry Point¶

Situation	Start with
You know the estimator tree	`mixle.inference.optimize` and Core Concepts.
You have heterogeneous raw rows and want a first model	`mixle.propose` or `mixle.task.recommend_model`.
You need a lifecycle object for a demo or application boundary	`mixle.Model` and Model Lifecycle.
You need to replace an LLM or rule with a local model	`mixle.task.solve` and Task Serving, Routing, And Edge Deployment.
You need uncertainty-aware LLM behavior	`mixle.reason` and Uncertainty.
You need a local knowledge/reasoning application shell	`mixle.substrate`, `mixle.inference.skill`, `mixle.pool`, `mixle.telemetry`, and Local Reasoning Ecosystem.
You need speed or scale	Compute Layer, Compute Engines, and Utilities And Parallelism.