Examples

Runnable examples live in examples/. They are plain Python scripts, so the fastest way to learn a workflow is to run the script under the same environment you use for tests.

Start with the base-install examples. Move to Torch, task, or real-data workflows only after the core distribution and inference path is clear.

Recommended First Runs

Script	What it demonstrates	Needs
gallery_univariate_example.py	Scalar continuous and discrete families.	Base install
gallery_combinators_example.py	Records, tuples, sequences, optional fields, and transforms.	Base install
gallery_structured_example.py	Mixtures, HMMs, LDA, and latent-variable models.	Base install
auto_example.py	Automatic estimator selection for mixed Python records.	Base install
structured_hmm_example.py	Low-rank, sparse, Kronecker, duration, terminal, and input-output HMMs.	Base install
production_example.py	Provenance, registry, serving, drift, and checkpoints.	Base install

Run them directly:

python examples/gallery_univariate_example.py
python examples/gallery_combinators_example.py
python examples/gallery_structured_example.py
python examples/auto_example.py
python examples/structured_hmm_example.py
python examples/production_example.py

Choose By Workflow

Workflow	Start with	Related guides
Heterogeneous records	auto_example.py, gallery_combinators_example.py	Quickstart, Fitting Heterogeneous Records
Mixtures and latent state models	gallery_structured_example.py, structured_hmm_example.py	HMMs and Latent Structure, Latent, Bayesian, And Nonparametric Families
Mixture compression and projection	mixture_reduction_benchmark.py, project_neural_to_structured.py	Inference Toolkit, Operations
Distribution family discovery	gallery_univariate_example.py, gallery_multivariate_example.py, gallery_directional_example.py	Univariate Families, Structured Statistical Families
Graphs, rankings, trees, and sets	gallery_graphs_example.py, gallery_rankings_example.py	Structured Statistical Families, Relations
Temporal and point processes	gallery_processes_example.py	Temporal And Stochastic Processes
Probabilistic programming	ppl_example.py	Probabilistic Programming, PPL Mixture Workflow
Exact support traversal	enumeration_example.py, enumeration_showcase_example.py	Enumeration and Ranking, Enumeration and Ranking
Scaling and engines	scaling_example.py, engine_benchmark_example.py	Compute Engines, Utilities And Parallelism
Neural or representation workflows	shared_embedding_example.py, heterogeneous_representation_example.py, cross_modal_fit_receipt.py	Neural and LLM Models, Representation Layer
Local reasoning ecosystem	frontier_ecosystem_demo.py, reasoner_investigation_demo.py, flagship_triage_app.py, flagship_kg_agent.py	Local Reasoning Ecosystem, Reasoning Systems
Local scientist and edge distillation	laptop_scientist.py, foundation_to_edge.py, vision_edge_distillation/	Local Reasoning Ecosystem, Task Distillation
Scientific inverse problems	flagship_physics_inverse.py, skeptic_challenge_example.py	Inference, Probabilistic Programming, Uncertainty
LLM/task replacement	task_distill_example.py, task_llm_active_example.py, task_cascade_economics_example.py	Task Distillation, Task Serving, Routing, And Edge Deployment
Extraction and agent-style task behavior	task_extraction_example.py, win_demo_example.py	Task Serving, Routing, And Edge Deployment, Agentic Task Distillation
Real-data task workflow	real_receipt_banking77.py	Task Serving, Routing, And Edge Deployment, Project Maturity

Dependency Notes

Most examples use only the base package dependencies. Examples that train neural students, neural leaves, representation models, or neural-density teachers generally need mixle[torch]. The real-data Banking77 receipt additionally needs the Hugging Face datasets package and downloads the dataset on first run. The laptop_scientist.py and foundation_to_edge.py workflows need the scientist extra and local Hugging Face model weights where noted by the scripts.

pip install -e .
pip install -e ".[torch]"
pip install -e ".[scientist]"
pip install datasets

Use mixle[all] only when you deliberately want the full optional surface. For most examples, a smaller extra is easier to debug.

Complete Inventory

Script	Category	Purpose
auto_example.py	Automatic inference	Infer an estimator shape for mixed Python records.
cross_modal_fit_receipt.py	Cross-modal inference	Fit a heterogeneous Bayesian network over categorical, image-vector, signal-vector, and continuous fields.
doe_example.py	Design of experiments	Latin hypercube designs, Bayesian optimization, and sensitivity.
engine_benchmark_example.py	Engines	Compare NumPy and Torch engine paths honestly across workloads.
enumeration_example.py	Enumeration	Exact top-k support traversal.
enumeration_showcase_example.py	Enumeration	Broader ranking, seek, and structured-support examples.
extensibility_seams_example.py	Extension	Show where new families and backends attach.
flagship_kg_agent.py	Reasoning ecosystem	Ontology-constrained graph facts, KG completion, and cited KG-RAG.
flagship_physics_inverse.py	Scientific inference	Bayesian inverse problem with coverage-oriented uncertainty checks.
flagship_triage_app.py	Reasoning ecosystem	Support triage over substrate, skills, pool-style jobs, monitoring, and grounded answering.
foundation_to_edge.py	Edge distillation	Distill a foundation-model capability into a smaller local artifact and report retained accuracy.
frontier_ecosystem_demo.py	Local reasoning ecosystem	End-to-end tour of substrate, creation, simulation, skills, reasoning, telemetry, and governance surfaces.
gallery_combinators_example.py	Distribution gallery	Composite, record, sequence, optional, and transformed families.
gallery_directional_example.py	Distribution gallery	Circular and spherical directional families.
gallery_graphs_example.py	Distribution gallery	Graph and tree distributions.
gallery_multivariate_example.py	Distribution gallery	Vector and matrix families.
gallery_processes_example.py	Distribution gallery	Temporal and point-process families.
gallery_rankings_example.py	Distribution gallery	Ranking and permutation families.
gallery_structured_example.py	Distribution gallery	Mixtures, HMMs, LDA, and latent models.
gallery_univariate_example.py	Distribution gallery	Scalar continuous and discrete families.
heterogeneous_correctness_example.py	Validation	Correctness checks across heterogeneous components.
heterogeneous_representation_example.py	Representation	Segmenters, embeddings, and shared heterogeneous encoders.
hidden_association_example.py	Latent models	Association models with hidden structure.
hierarchical_mixture_example.py	Latent models	Hierarchical mixture variants.
joint_mixture_example.py	Latent models	Joint mixture variants.
laptop_scientist.py	Local scientist	Optional assembled workflow for cached encoders, local answering, and verified scientific responses.
latent_variable_models_example.py	Latent models	Latent families beyond the first HMM path.
lookback_hmm_example.py	Latent models	HMMs with longer history.
mixture_reduction_benchmark.py	Projection/compression	Compare closed-form Gaussian-mixture reduction with sample-and-refit projection.
project_neural_to_structured.py	Projection/compression	Project a trained neural density onto a structured Gaussian-mixture student and measure size, latency, and likelihood tradeoffs.
ppl_example.py	PPL	free parameters, mixtures, sequences, and moments.
production_example.py	Production	Provenance, registry, serving, drift, and checkpoints.
real_receipt_banking77.py	Real-data task workflow	Banking77 intent classification through the solve loop.
reasoner_investigation_demo.py	Reasoning ecosystem	Evidence acquisition over retrieve, compute, simulate, and delegate actions with abstention.
scaling_example.py	Parallelism	Same optimize call on local and multiprocessing backends.
semi_supervised_mixture_example.py	Latent models	Partially labeled mixture fitting.
shared_embedding_example.py	Neural leaf	Mixture of language-model experts with one shared embedding.
skeptic_challenge_example.py	Verification workflow	Stress-check claims and examples against explicit evidence.
structure_learning_example.py	Applied models	Dependency and structure learning before modeling.
structured_hmm_example.py	HMMs	Structured transition variants and duration behavior.
structured_leaves_example.py	Structured models	Structured emissions and leaves.
task_cascade_economics_example.py	Task workflow	Cascade cost accounting, harvesting, and retraining.
task_distill_example.py	Task workflow	Distill a slow teacher into a local callable artifact.
task_extraction_example.py	Task workflow	Distill LLM field extraction into a local sequence tagger.
task_llm_active_example.py	Task workflow	LLM teacher, active labeling, local student, and calibrated cascade.
vision_edge_distillation/	Edge distillation	Train and verify a compact vision student from cached or reproduced foundation-model features.
win_demo_example.py	End-to-end workflow	Replace a ticket router and invoice extractor with calibrated models.

Benchmark and distributed-stress harnesses that were previously under examples/ have been moved to gitignored benchmark areas. The tracked examples page now focuses on scripts intended to be read and run as documentation.

Representative Source

Structured HMMs:

examples/structured_hmm_example.py

"""Composable / structured HMMs — a tour of mixle.stats.latent.structured_hmm.

A standard HMM is a dense K x K transition + per-state emissions. mixle factors the transition behind a
small TransitionOperator interface (forward: alpha @ A, backward: A @ v, plus an expected-mass M-step), so
rich structure plugs into ONE forward-backward / EM: low-rank transitions, block / factorial (Kronecker)
combinators, sparse (left-to-right) transitions, sticky / Dirichlet priors. On top sit decoding (Viterbi /
posterior), enumeration (top-k / rank / nucleus over sequences), terminal (absorbing) states, an
input-output HMM, an explicit-duration HMM (HSMM) with segment decoding, forgetting-based parallel
Baum-Welch, and a JAX fast path.

Run: ``python examples/structured_hmm_example.py``
"""

from __future__ import annotations

import numpy as np

import mixle.stats as S
from mixle.inference import optimize
from mixle.stats.latent.structured_hmm import (
    DenseTransition,
    ExplicitDurationHMM,
    InputOutputHMM,
    KroneckerTransition,
    LowRankTransition,
    SparseTransition,
    StructuredHMM,
    _row_normalize,
    left_to_right_edges,
    sticky_transition,
)


def gaussians(centers, sd=1.0):
    return [S.GaussianDistribution(float(c), sd) for c in centers]


def low_rank():
    rng = np.random.RandomState(0)
    k, r = 8, 2
    gen = StructuredHMM(
        gaussians(range(0, 4 * k, 4)),
        np.ones(k) / k,
        LowRankTransition(_row_normalize(rng.rand(k, r)), _row_normalize(rng.rand(r, k))),
    )
    seqs = [gen.sampler(seed=s).sample(50) for s in range(60)]
    init = StructuredHMM(
        gaussians([4 * i + rng.uniform(-1, 1) for i in range(k)]),
        np.ones(k) / k,
        LowRankTransition(_row_normalize(rng.rand(k, r)), _row_normalize(rng.rand(r, k))),
    )
    fit = optimize(seqs, init.estimator(), prev_estimate=init, max_its=40, out=None)
    print(
        f"1. Low-rank HMM (K={k}, rank={r}): transition params {2 * k * r} vs dense {k * k}; "
        f"recovered means {sorted(round(e.mu, 1) for e in fit.emissions)[:4]}..."
    )


def factorial():
    rng = np.random.RandomState(0)
    a1, a2 = _row_normalize(rng.rand(3, 3)), _row_normalize(rng.rand(4, 4))
    kt = KroneckerTransition(DenseTransition(a1), DenseTransition(a2))
    print(
        f"2. Factorial (Kronecker) HMM: state=(s1,s2), {kt.n_states}=3x4 joint states, A=A1(x)A2 "
        f"(forward O(K1 K2 (K1+K2)) not O((K1K2)^2))"
    )


def sticky_and_sparse():
    sp = SparseTransition(5, left_to_right_edges(5, skip=1))
    a = sp.as_matrix()
    st = sticky_transition(np.full((3, 3), 1 / 3), kappa=10.0)
    print(
        f"3. Sparse left-to-right (5 states): lower-triangle zero={np.allclose(np.tril(a, -1), 0)}; "
        f"sticky prior biases self-transitions (segmentation)"
    )


def decode_and_enumerate():
    a = np.array([[0.92, 0.08], [0.08, 0.92]])
    cat = [S.CategoricalDistribution({0: 0.8, 1: 0.2}), S.CategoricalDistribution({0: 0.2, 1: 0.8})]
    hmm = StructuredHMM(cat, [0.5, 0.5], DenseTransition(a), len_dist=S.CategoricalDistribution({2: 0.5, 3: 0.5}))
    en = hmm.enumerator()
    print(
        f"4. Decoding + enumeration: Viterbi works for any operator; top-3 most-probable sequences "
        f"{[seq for seq, _ in en.top_k(3)]}, nucleus(0.9) covers {en.nucleus_size(0.9).covered_mass:.2f}"
    )


def terminal():
    a = _row_normalize(np.array([[0.6, 0.3, 0.1], [0.2, 0.6, 0.2], [0, 0, 1.0]]))
    hmm = StructuredHMM(gaussians([-3, 0, 3]), [0.7, 0.3, 0.0], DenseTransition(a), terminal_states={2})
    lengths = [len(hmm.sampler(seed=s).sample(50)) for s in range(20)]
    print(
        f"5. Terminal (absorbing) states: state 2 stops the sequence -> variable lengths "
        f"{min(lengths)}..{max(lengths)} (length is a stopping time)"
    )


def hsmm():
    d = 6
    dur = np.zeros((2, d))
    dur[0, 3] = 1.0
    dur[1, 1] = 1.0
    gen = ExplicitDurationHMM(gaussians([-6, 6], 0.4), [1.0, 0.0], np.array([[0, 1.0], [1.0, 0]]), dur, d)
    rng = np.random.RandomState(0)
    true = [0] * 4 + [1] * 2 + [0] * 4 + [1] * 2
    seq = [float(rng.normal([-6, 6][s], 0.4)) for s in true]
    segs = gen.viterbi_segments(seq)
    print(
        f"6. Explicit-duration HMM (HSMM): non-geometric durations; decoded segments "
        f"{[(s, dd) for s, _, dd in segs]} (state, duration)"
    )


def iohmm():
    a0, a1 = np.array([[0.95, 0.05], [0.05, 0.95]]), np.array([[0.05, 0.95], [0.95, 0.05]])
    io = InputOutputHMM(gaussians([-5, 5], 0.5), [0.5, 0.5], [DenseTransition(a0), DenseTransition(a1)])
    print(
        "7. Input-output HMM: an exogenous input selects the transition each step (input 0=sticky, "
        "1=flip) -- a controlled Markov model"
    )


def main():
    print("# Composable / structured HMMs in mixle\n")
    low_rank()
    factorial()
    sticky_and_sparse()
    decode_and_enumerate()
    terminal()
    hsmm()
    iohmm()
    print(
        "\nAll of these share one TransitionOperator interface: the operator's structure makes FITTING "
        "cheaper (O(K r) low-rank, O(edges) sparse, factorial Kronecker), while as_matrix() feeds decoding "
        "and enumeration. Forgetting-parallel Baum-Welch (fit_chunked) and a JAX fast path "
        "(jit_forward_loglik) round out the toolkit."
    )


if __name__ == "__main__":
    main()

Active LLM distillation and cascade:

examples/task_llm_active_example.py

"""LLM teacher + active labeling: pay a frontier model for the fewest labels, then serve locally for ~free.

The two differentiators in one run:

  * the teacher is an **LLM** (here a local ``CallableLLM``; swap in ``OpenAICompatLLM(base_url, model)``
    to use Ollama / vLLM / a hosted endpoint unchanged);
  * **active labeling** (DoE applied to the labeling decision) queries that LLM only for the most informative
    examples, reaching the same student quality as random labeling for far fewer paid calls.

Then the distilled student is wrapped in a calibrated cascade and the realized savings are reported. Run:
``python task_llm_active_example.py``  (needs ``pip install "mixle[torch]"``).
"""

from __future__ import annotations

import numpy as np

from mixle.task import (
    CalibratedTaskModel,
    CallableLLM,
    Cascade,
    CostModel,
    active_distill,
    llm_labeler,
)

SPAM = ["free", "winner", "prize", "buy", "cheap", "offer", "click", "loan", "casino"]
HAM = ["meeting", "lunch", "project", "report", "schedule", "team", "review", "invoice"]
FILLER = ["the", "a", "today", "please", "thanks", "we", "you", "and", "to"]


def pool(seed, n_per_class=300):
    r = np.random.RandomState(seed)
    out = []
    for words in (SPAM, HAM):
        for _ in range(n_per_class):
            toks = list(r.choice(words, size=2)) + list(r.choice(FILLER, size=r.randint(3, 8)))
            r.shuffle(toks)
            out.append(" ".join(toks))
    r.shuffle(out)
    return out


def local_llm(prompt, system=None):
    """Deterministic local teacher with the same callable shape as an LLM endpoint."""
    text = prompt.split("Text:", 1)[-1].lower()
    return "spam" if any(w in text.split() for w in SPAM) else "ham"


def main() -> None:
    # the teacher is an LLM, constrained to the label set
    teacher = llm_labeler(CallableLLM(local_llm), ["spam", "ham"], instruction="Classify the email as spam or ham.")
    recipe = {"n": 4, "dim": 512, "hidden": [64], "epochs": 200, "lr": 1e-2}

    p, val = pool(1), pool(seed=900)[:300]
    truth = teacher(val)

    def acc(model):
        pred = model.batch(val)
        return float(np.mean([a == b for a, b in zip(pred, truth)]))

    budget = 60
    print(f"label budget: {budget} LLM calls (out of {len(p)} unlabeled)")
    active = active_distill(teacher, p, budget=budget, seed_size=20, rounds=4, acquisition="margin", recipe=recipe)
    rand = active_distill(teacher, p, budget=budget, seed_size=20, rounds=4, acquisition="random", recipe=recipe)
    print(f"   active labeling : {acc(active.model):.3f} accuracy with {active.labels_used} labels")
    print(f"   random labeling : {acc(rand.model):.3f} accuracy with {rand.labels_used} labels")

    print("\nwrap the active student in a calibrated cascade and serve")
    cal = pool(seed=2)
    model = CalibratedTaskModel(active.model, alpha=0.1).calibrate(cal, teacher(cal))
    casc = Cascade(model, teacher, cost=CostModel(c_frontier=0.01, c_local=0.00001))
    casc.serve(pool(seed=901))
    rep = casc.report()
    print(f"   served {rep['n_requests']} requests, escalated {rep['realized_escalation_rate']:.1%} to the LLM")
    print(f"   saved ${rep['savings_vs_frontier']:.2f} vs paying the LLM for every request")


if __name__ == "__main__":
    main()