Example Execution Manifest¶
This page is the release-facing execution manifest for scripts shipped under
examples/. The examples guide describes what each script teaches; this
manifest records what must be executed, skipped, or marked blocked before a
public release.
Current Inventory¶
The core package currently ships 57 Python example scripts (the count was 64 before the 2026-08-04 removal of the direct-dataset flagships, and this line had not caught up – the execution status in “Release Execution Status” below and the tree both say 57):
Group |
Examples |
Release tier |
|---|---|---|
Base distribution galleries |
|
smoke/validation |
Latent and structured models |
HMM, mixture, association, and structure-learning examples |
validation |
DOE, enumeration, production, and scaling |
DOE, enumeration (including |
validation/manual |
Model comparison, dependence structure, symbolic export, and combinatorial scheduling |
|
validation ( |
Task and distillation workflows |
task distillation, active labeling, extraction, cascade economics |
validation/manual |
Reasoning, cross-modal, and scientist workflows |
frontier ecosystem, KG agent, scientist, physics inverse, receipts |
manual unless dependencies are provisioned |
Release Execution Status¶
2026-08-10 re-verification. All 57 examples were re-executed against the current
release/0.8.0 tip (7f0c7bd1), because the 2026-08-07 pass below predates an adversarial
statistical-review campaign (passes 2-23, 2026-08-08..10) that changed public behavior on several
mixle.inference, mixle.ppl, mixle.reason, and mixle.task surfaces – including one
this pass found the campaign itself had not touched: cross_modal_fit_receipt.py exercises the
CrossModal transactional-fit repair (D-0171/D-0172) directly. Same method as 2026-08-07: source
tree, Python 3.12.12, one script at a time in its own process under a resident-memory and
free-disk watchdog (debounced against transient readings from other concurrent work on a shared
machine). 57 passed, 0 failed – 355.5s total, slowest script (skeptic_challenge_example.py)
16.2s, both faster than the 2026-08-07 figures (439s / 24.3s) and consistent with normal run-to-run
variance rather than a real change. One environment gap, unrelated to mixle: peft was
missing from the execution venv despite being declared in the examples extras group
(pyproject.toml); installed at the declared bound (peft>=0.11,<1), after which
peft_lora_grad_leaf.py passes. Zero regressions from the review campaign reached this corpus.
2026-08-07 pass (superseded environment identity; narrative below still current). All 57
examples were executed against release/0.8.0, from the source tree on
Python 3.12.12, one at a time in its own process session under a resident-memory watchdog. All 57
completed successfully: 439s in total, peak 2.3 GB, and the slowest single script
project_neural_to_structured.py at 24.3s.
57 passed, 0 failed.
Environment: every optional extra provisioned – scikit-learn, torch, transformers, datasets, pyspark, mpi4py and dask were all importable. That is what the number means and what it does not. It says every script EXECUTES TO COMPLETION with exit code 0 against this candidate: no import breaks, no API drift, no crash. It is not proof the printed numbers are scientifically correct – an example can run clean and still demonstrate the wrong thing, which only the per-example assertions and the review gates can speak to – and it says nothing about a base install. The per-example
blockedclassifications in the Inventory below are a separate axis and remain accurate for a minimal environment –skeptic_challenge_example.pypasses here only because scikit-learn is present, and still fails without it.
This supersedes the 2026-08-04 pass, which measured only the 23 base-install scripts and predates the library repairs below. Two of its statements no longer hold: the remaining 34 examples were recorded as “not executed in this pass” and all of them execute when their prerequisites exist, and the slowest script was recorded at 46s against 24.3s now.
This run also stands as regression evidence for eight library defects fixed on 2026-08-05/06 –
parameter tying (keys=) unusable for the LDA/pLSI/PCFG families, BernoulliSetDistribution
and MarkovChainDistribution unpicklable at every protocol, and the automatic type-detection
path building models the library then refused, among others. Those fixes touch the key validator
that every estimator walks, sequence length handling, Dirichlet-process component priors, and
pickling; 57 examples and the 131-notebook corpus both execute clean on top of them.
This supersedes the 2026-07-17 pass, which is no longer accurate in three respects.
hierarchical_mixture_example.pywas recorded as not completing even under a 15-minute allowance, and was flagged as the more likely of two candidates to be a real behaviour change from the EM-monotonicity work in #435. It now completes in 50 seconds. The earlier measurement was taken while the execution host was under load averages of roughly 140-175 against 10 cores.lookback_hmm_example.pywas recorded as exceeding a 90s budget and then completing at 86s on re-run. It now completes in 39 seconds, consistent with the same host-load explanation. It still callsoptimize(..., max_its=1000, delta=None), so it always runs the full thousand EM iterations by design; that is a fixed amount of work, not a convergence problem.win_demo_example.pywas reclassified to blocked for needingtorch. It passes when torch is present, so it is blocked only on the base install, not unconditionally.
semi_supervised_mixture_example.py was listed among the 19 that passed in July and did not.
It built its estimator from SequenceEstimator(CategoricalEstimator(...)), whose default
len_estimator=NullEstimator() yields a sequence law with no distribution over length – a law
conditional on the length it is handed, which mixle reports as a LIKELIHOOD_FACTOR and a
generative mixture refuses as a component. The ground truth it samples from draws lengths from
CategoricalDistribution({seq_samp: 1.0}), so the estimator was also fitting a different family
than the one that produced the data. With a length estimator supplied it recovers the generating
parameters: weights 0.598/0.296/0.106 against a true 0.6/0.3/0.1.
Real-data flagship demonstrations (Banking77, UCI Adult, sunspots) were removed from this repository on 2026-08-04: the repository carries no direct dataset usage, and real-data demonstrations live in notebooks outside it. Their historical execution evidence remains in this page’s git history.
``hierarchical_mixture_example.py`` follow-up (2026-07-17). A later
re-verification pass flagged this example as exceeding its 90s budget against
current 0.8.0 source, and – after it still had not finished with a
15-minute allowance – raised the EM-monotonicity fix in #435 (2026-07-13,
mixle/stats/latent/hierarchical_mixture.py) as the plausible cause, since
that commit changed how the outer-mixture weights are derived. Investigated
directly with a per-iteration log-likelihood/delta trace
(optimize(..., on_step=...)) of the example’s exact model/data/seed,
captured on three points in history: v0.7.0, the commit immediately
before #435 (2ed006ca), and current release/0.8.0.
Not a #435 regression.
mixle/stats/latent/hierarchical_mixture.pyis byte-identical betweenv0.7.0and2ed006ca(git diffconfirms zero changes), and the iteration-indexed trajectories for all three points agree closely throughout: e.g. log-likelihood at iteration 3 is -22681.620149 on bothv0.7.0and2ed006ca, -22681.620138 after #435; at iteration 10000, delta is 3.07e-6 before #435 vs. 8.63e-6 after – same order of magnitude, no widening gap. The slow-convergence shape below predates #435 by at least back tov0.7.0; #435’s outer-weight fix did not change it.Root cause: this configuration has always converged very slowly against the estimator’s exact ``delta=1.0e-9`` default. It is weakly identified – 4 outer mixture components (3 near-degenerate single-topic, one blended) over only 3 mildly-skewed categorical symbols, 8-10 tokens per document. A direct trace to the example’s
max_its=10000shows log-likelihood plateaus near -22681.6 for ~1000 iterations, jumps to ~-22510 between iterations 1000-1500 (EM escaping a saddle), then creeps from -22510 to -22508.1 over the remaining 8500 iterations without ever satisfyingdelta<1e-9– delta is still ~8.6e-6 at iteration 10000, and does not drop below1e-4for good until iteration ~7095. It was always going to run the fullmax_its=10000rather than stop early on genuine convergence; that run took ~262s under this pass’s load (uptimeload averages ~20-40 against 10 cores), plausibly several times that under the ~140-175 load of the prior pass. No non-monotonicity, oscillation, or hang was observed at any point (mixle/tests/latent_readout_correctness_test.pygained a newHierarchicalMixtureBoundedConvergenceTestcovering this gap on a small, fast, well-separated corpus).Resolution. The example’s
max_itswas reduced from 10000 to 2000 – comfortably past the iteration-1000-1500 escape – capturing log-likelihood -22509.97 vs. the 10000-iteration run’s -22508.13 (over 99.99% of the total achievable improvement). The re-budgeted example now completes in approximately 20s. The estimator’s actual default convergence tolerance (delta=1.0e-9) is unchanged for real callers; only this example’s requestedmax_itsmoved.
2026-07-21 re-verification. All 19 previously-passed examples plus both
previously-resolved timed-out cases (hierarchical_mixture_example.py,
lookback_hmm_example.py) were re-run against current release-prep/0.8.0
source (roughly 40 additional bug-fix commits landed since the 2026-07-17 pass,
none in these examples’ own code paths) and still pass. This pass also:
Confirmed
auto_example.pyandenumeration_showcase_example.py– both inventoried “Execute.” but absent from the 2026-07-17 evidence above – pass cleanly and quickly (0.55s and 0.68s respectively). Recorded here as the evidence that was previously missing; not a live concern.Corrected the
lookback_hmm_example.pymechanism claim above: an instrumented per-iteration trace shows only about 480 of the requested 1000 iterations actually execute, not the full 1000 as previously stated.delta=Nonedoes disable thedelta-gated convergence check, but a separate,delta-independent monotonicity guard in_fused_em_loop(mixle/inference/estimation.py:738-741, added by a commit predating even the 2026-07-17 baseline) breaks the loop when a per-iteration log-likelihood delta goes slightly negative – which happens near convergence here. The bottom-linepassedstatus and the ~86s runtime are unaffected; only the stated reason was wrong.Documented, in the Inventory table below, a previously-unrecorded
torchhard dependency (no classical fallback) fordoe_example.py(viaGaussianProcessRegressor) and fortask_cascade_economics_example.py,task_distill_example.py,task_extraction_example.py, andtask_llm_active_example.py(all viamixle.task.distill._fit_mlpormixle.task.extract’s distillation path) – the same shape of blocker already documented forwin_demo_example.py. This is why these five, despite being policy-required by the Minimum Release Run below, had no recorded execution evidence: a base install cannot run them at all, and the Inventory entries did not say so.Confirmed
geoscience_inversion_report.py– also absent from the 2026-07-17 evidence despite exercisingmixle.task.inverse– passes its execution contract. The script’s calibration layer detected a poorly calibrated candidate and abstained. Exact measurements belong in the content-addressed receipt, not in this mutable narrative. Superseded in 0.8.2: that abstention was the simulator defect P09-F04 – the forward model handed tolearn_inversewas noise-free, so the learned posterior was near-deterministic against a noisy measurement and the SBC and coverage checks rightly failed – and on the repaired script those checks pass and the report serves a depth interval that contains the true depth. Like the three othertorch-backed rows above, it cannot run in a base install at all.
2026-07-23 addition. quickstart_example.py was added to close a
coverage gap: neither mixle.describe() (the package docstring’s own
“start here”) nor mixle.propose() (headlined in the README’s Package
highlights, paired with optimize()) had a runnable example calling them
directly. Passes in a base install, no optional dependencies, 3.4s.
2026-07-23 addition (batch 2). Six more scripts closed the remaining README-headlined coverage gaps identified in the same audit. All were run directly (not just imported) and their printed output checked against an independent hand or brute-force calculation, not just “exited zero”:
precedence_scheduling_example.py–mixle.precedence_scheduling(maximum-weight closure, time-phased MILP scheduling), on a software-release dependency DAG rather than the test suite’s mine-planning framing, to show the module’s generality is real. Base install, 2.3s. The script’s own in-line assertions verify the returned schedule against the raw capacity and precedence arrays.capability_layer_example.py– the rest ofmixle.capability(capabilities,supports,require,catalog,what_supports,summarize) beyonddescribe(). Base install, 2.2s.symbolic_export_example.py–mixle.engines.symbolic_engine/symbolic_export(LaTeX / SymPy / optional Sage). Needsmixle[sympy]; 3.5s. Differentiates each of two families’ closed-form log-density to its score function and confirms Gaussian’s score grows without bound as an observation moves further from the mean, while Student-t’s saturates back toward zero – checked against the textbook closed forms by hand, not just printed. Separately found (not fixed; see below): constants likepirender as decimals rather than staying symbolic underSYMBOLIC_ENGINE– correct value, not textbook-pretty LaTeX.autoregressive_enumeration_example.py–mixle.enumeration.AutoregressiveEnumerableover a small synthetic prefix-dependent logit table (base install, no torch, no network – a real LM plugs into the samenext_logprobsinterface). 2.2s. Instruments the model callable itself to show the number of distinct prefixes actually queried stays far below the full sequence-space size. Separately found and since fixed (see below):nucleus_size()was wrong for this class.model_comparison_example.py–mixle.ppl’swaic/loo/compare(), ranking a deliberately-wrong unimodal fit against a 2-component mixture and a second wrong (Student-t) fit on genuinely bimodal data. The script reports the measured ranking and diagnostics; this narrative does not preserve a result from an unbound historical run.copula_vine_example.py– directCopulaDistribution/RVineCopulaDistributionfitting on Clayton-generated lower-tail-dependent heterogeneous-marginal data, contrasted against a Gaussian-copula core fit to the same data. The script checks its measured tail diagnostics; exact results belong in the candidate-bound receipt.
Two real, non-blocking issues were found incidentally while building these
(not introduced by them), both since fixed – see the 2026-07-23 follow-ups
below: SYMBOLIC_ENGINE’s constants not staying symbolic, and
AutoregressiveEnumerable.nucleus_size() returning an incorrect size
(size_lower=size_upper=0 when the correct answer is 5, confirmed against
brute force) while its covered_mass field stayed correct.
2026-07-23 follow-up: pi fixed. Root cause: GaussianDistribution /
LogGaussianDistribution / MultivariateGaussianDistribution got pi
via from mixle.engines.arithmetic import * (StudentTDistribution used
math.pi directly); both are ordinary Python import/reference semantics –
the value is bound once, at each family module’s own import time, against
whichever engine was the default THEN. Passing an explicit
engine=SYMBOLIC_ENGINE to a backend_log_density_from_params /
backend_seq_log_density / exp_family_log_partition call never
revisited that binding, so the LaTeX output always showed a decimal literal
regardless of which engine was requested. Fixed by reading engine.pi off
the actual passed-in engine at each of the 8 confirmed call sites across the
4 affected families (every ComputeEngine already exposes .pi); no
numeric change on the ordinary numpy path (engine.pi is the same
math.pi value), confirmed by the full backend_scoring_test.py suite
(264 subtests) plus a dedicated regression test. Checked every other family
using the same import pattern for the same bug – diagonal_gaussian.py
and von_mises_fisher.py’s pi hits were false positives (a docstring
formula and plain-float __init__ setup respectively), and
markov_chain.py / hidden_markov.py / lookback_hidden_markov_model.py’s
were the unrelated HMM initial-state-distribution variable of the same name.
MultivariateGaussianDistribution’s fix is verified correct but its full
symbolic export still hits a separate, pre-existing array-conversion
limitation in the symbolic engine, unrelated to this bug and not fixed here.
2026-07-23 follow-up: nucleus_size() fixed. Root cause: nucleus_size()
delegated to the generic density_rank.count_dp_top_p, which assumes its
exact per-item mass histogram (bucketed by the floor of the EXACT total
log-density) and the count index share one bucket numbering – true for
Composite/Record/Sequence, false for AutoregressiveEnumerable, whose
quantized_count_index buckets a sequence by the SUM of its per-step
floor-quantized buckets (floor(a) + floor(b) <= floor(a + b), so the
structural bucket is systematically <= the exact one, confirmed both
theoretically and empirically – a 0-1 bucket gap per real sequence at
oversample=64, L=3). Fixed by giving nucleus_size() its own
implementation (mirroring mass_above’s existing fix for the identical
discrepancy) that derives every quantity from the structural count index
alone, rather than delegating to count_dp_top_p; also fixed
nucleus_size() silently ignoring the instance’s own oversample /
bin_width_bits. mixture_cross_rank and the other
quantized_count_index call sites in density_rank.py were checked for
the same coupling assumption and found unaffected – each builds and reads
one self-consistent histogram rather than mixing two independently-bucketed
ones. Verified against the exact repro (previously 0, now matches
brute-force truth of 5) across a full sweep of targets on both a
fixed-length and a terminating (eos) model; a naive fix that always
searched for a fully-certified bracket was correct but required exponential
search depth on the terminating model (steps_bound scales with the
model’s max_depth safety cap, not the depth of sequences actually
relevant to a given target) – the shipped fix instead uses a fast,
bounded search and reports truncated=True (a documented, pre-existing
part of CountDPTopPResult’s contract: size_upper is a floor, not a
cover, when truncated) rather than searching indefinitely for a certificate.
Execution status should be recorded as evidence, not inferred from import success or from an earlier notebook run. If an example writes an artifact, the artifact path and any cleanup policy should be captured with the status.
Execution state and claim state are separate. Every attempted example receives one execution state:
passedThe script completed from a clean install with the documented command. This proves runnability only; it does not verify any advertised result.
failedThe script exited non-zero. Record the first meaningful exception.
timed_outThe script exceeded the declared runtime budget.
blockedA required dataset, credential, GPU, model weight, external service, or optional dependency was unavailable.
skippedThe release configuration intentionally omitted the script with a recorded reason.
Do not merge blocked and skipped. A blocked example needs an external
prerequisite; a skipped example was deliberately left out of the release gate.
That distinction matters when deciding whether documentation can claim the
workflow is healthy.
An evidence-class example additionally receives claim state verified only
when a machine-readable acceptance contract checks the advertised behavior and
the process fails if that contract is absent or false. Publication’s
mixle.example_execution_manifest/v2 therefore records
execution_status, claim_status, and acceptance_contract separately.
The exact-output and JSON assertions in
release-checklists/0.8.2-repro-bundle.json are the release claim oracles.
Inventory entries below that merely say “Execute” are runnability targets, not
claim evidence.
Minimum Release Run¶
The minimum release run should include:
all base-install examples listed in Examples;
every example referenced by README files or Sphinx pages;
every example touching public APIs changed in the current release scope;
task-distillation examples because the current release scope includes task and DOE-distillation surfaces;
DOE examples because the current release scope includes pool-based DOE for distillation and cross-modal training; and
vision or reasoning examples only when their optional dependencies are installed, otherwise mark them blocked with the missing prerequisite.
Example command shape:
python examples/gallery_univariate_example.py
python examples/task_distill_example.py
python examples/doe_example.py
When release validation uses a timeout wrapper, record the timeout and whether the script is expected to be short, long, or manual.
Timeouts should be chosen before execution. A script that times out under the
declared budget should be recorded as timed_out even if it might finish
eventually on a warmer machine.
Inventory¶
Path |
Expected status before release |
|---|---|
|
Execute or record failure. |
|
Execute. Base install (numpy only; synthetic toy model, no torch/network). |
|
Blocked on |
|
Execute. Base install. |
|
Execute. Base install. |
|
Execute as a synthetic multi-vector feature tutorial. It is not real cross-modal evidence because it has no raw modality inputs or encoders. |
|
Blocked on |
|
Manual/benchmark or bounded smoke run. |
|
Execute. |
|
Execute or classify as long-running. |
|
Execute. |
|
Manual unless KG/RAG prerequisites are provisioned. |
|
Execute or mark blocked on PDE/scientific dependencies. |
|
Manual unless local reasoning prerequisites are provisioned. |
|
Manual/integration. |
|
Blocked on |
|
Manual/integration. |
|
Execute. |
|
Execute. |
|
Execute. |
|
Execute. |
|
Execute. |
|
Execute. |
|
Execute. |
|
Execute. |
|
Execute. |
|
Blocked on |
|
Execute. |
|
Execute. |
|
Execute. |
|
Execute with optional-dependency status recorded. |
|
Execute. |
|
Execute. |
|
Manual/benchmark or bounded smoke run. |
|
Execute. Base install. |
|
Execute with optional-dependency status recorded. |
|
Execute with optional-dependency status recorded (needs |
|
Execute. |
|
Execute. Base install. |
|
Execute with artifact-output path recorded. |
|
Execute with optional-dependency status recorded. |
|
Execute. |
|
Manual/integration. |
|
Execute or classify by backend availability. |
|
Execute. |
|
Execute with optional-dependency status recorded. |
|
Blocked on |
|
Execute. |
|
Execute. |
|
Execute. |
|
Blocked on |
|
Blocked on |
|
Blocked on |
|
Blocked on |
|
Blocked on |
|
Execute with optional-dependency status recorded. |
|
Blocked on |
Evidence to Record¶
For each executed example, record:
command;
package version or wheel filename installed;
optional extras installed;
timeout;
status;
claim status and its machine acceptance contract, if used as evidence;
first error or output artifact path; and
whether network or external data was used.
For blocked or skipped examples, record:
the missing prerequisite or release-scope reason;
whether the example is referenced by a public guide;
the owner of the follow-up decision; and
the condition that would move it back into the release gate.
The manifest should make it clear which examples are evidence for the release and which examples remain illustrative but unexecuted.