Troubleshooting

This page collects the problems that usually mean the model shape, dependency set, or capability expectation is mismatched.

Torch Import or Neural Leaf Failure

Install the Torch extra:

pip install "mixle[torch]"

Then verify:

python - <<'PY'
from mixle.models import TransformerLMEstimator
print(TransformerLMEstimator)
PY

Use device="cpu" first. Move to device="cuda" after the shape works.

Estimator Does Not Match Data

Symptom: an encoder, unpacking, or shape error during optimize.

Check one observation and the estimator side by side:

row = data[0]
print(row)
print(estimator)

For tuples, use CompositeEstimator. For dictionaries or named records, use record-shaped estimators. For variable-length lists, use SequenceEstimator. For next-token neural leaves, the field should look like (context, target).

Mixture Results Change Across Runs

Mixtures and HMMs have local optima. Use multiple starts:

import numpy as np
from mixle.inference import best_of

score, model = best_of(
    train,
    valid,
    estimator,
    trials=8,
    max_its=100,
    init_p=0.1,
    delta=1e-8,
    rng=np.random.RandomState(0),
    out=None,
)

Set rng= when you need reproducibility.

For release evidence, compare the selected mixture against a simpler baseline on held-out data and keep the rejected restart scores. A single improved run does not prove that the latent structure is stable.

Unexpected NaN or -inf Scores

NaN inputs, impossible observations, and missing fields should not be quietly rewritten by troubleshooting code. First identify which case you have:

• NaN as source data means the data pipeline or model-specific missing-data policy must decide what it represents;

• -inf usually means the observation is impossible under the fitted support;

• NaN produced during fitting or scoring usually means a numerical or validation bug that should be reproduced with a minimal row; and

• masked, optional, or marginalized fields should be represented with the explicit missing-data surface documented for the model.

Do not replace non-finite values with zeros to keep a workflow running. That changes the statistical meaning of the observation and can hide the issue that the model needs to report.

A Capability Is Missing

Not every model can enumerate, condition, marginalize, or expose latent posteriors. Ask the model:

import mixle

print(mixle.describe(model))
print(mixle.capabilities(model))

If a workflow needs enumeration, choose a family with enumerable support. If it needs latent paths, choose a latent-structured family that exposes posterior or decoding methods.

Automatic Recommendation Looks Weak

recommend_model reports low-confidence fields when the best family does not beat the runner-up by much.

rec = recommend_model(data)
print(rec.low_confidence_fields())

Treat those as data collection or modeling decisions. Add more data, constrain the family explicitly, or compare the recommended model with a hand-built alternative.

LLM-Designed Model Falls Back

design_model falls back when the LLM returns invalid JSON, uses a non-allowlisted family, builds an incompatible estimator, or fails fit-validation.

designed = design_model(data, llm)
print(designed.source)
print(designed.note)

Fallback is intentional. The LLM proposes; mixle validates.

Conformal Cascade Escalates Too Often

High escalation can mean:

• the local student is too weak;

• calibration data are small or harder than training data;

• alpha is too strict for the business tradeoff;

• the density gate is marking traffic as OOD;

• live traffic differs from training traffic.

Inspect conformal sets, OOD flags, and harvested examples. Retrain with the harvested escalation labels before loosening calibration.

For solve_regression, a high escalation rate usually means the calibrated interval width qhat is larger than the requested tol. Check whether tol is actually the application tolerance, whether the examples span the live input range, and whether the target function is noisy or discontinuous. Do not increase tol solely to force local answers.

For solve_multilabel, one ambiguous label escalates the whole request. Inspect labels with too few positive or negative calibration examples first: under-calibrated labels are deliberately treated as ambiguous. Add examples for rare labels or split the task if one hard label is preventing otherwise stable tags from being served locally.

For solve_structured, every output field must be locally decided before the dictionary is returned. Check the per-field report: categorical fields fail for the same reasons as solve; numeric fields fail for the same qhat versus tol reason as solve_regression. A missing tolerance for a numeric field is a setup error rather than a calibration result.

Spark or Distributed Backend Fails

Start with backend="local" and the same estimator. Then try backend="mp". Move to Spark/Dask/MPI only after the local shape works.

For Spark, make sure the driver and workers use the same Python environment and that Java is installed.

Documentation Build Fails

Use the same strict verification command:

make -C docs html SPHINXOPTS="-W --keep-going"

Warnings are treated as errors. Common causes are stale :doc: links, missing optional dependencies during autodoc, or generated API files that need to be refreshed with make -C docs apidoc. If the working tree build passes but a clean checkout fails, check for untracked docs/api/*.rst pages that were generated locally but never included in the documentation PR.