Architecture Notes

mixle is organized around a small set of contracts and a larger set of capability facets. The concrete modules are numerous, but the mental model stays compact:

  • Objects implement contracts: distributions, samplers, estimators, encoders, accumulators, enumerators, relations, engines, and data handles.

  • Capabilities describe what those objects can do: enumerate, rank by index, condition, marginalize, expose latent posteriors, run on an engine, or update conjugately.

  • Concerns own algorithms: inference fits models, enumeration ranks supports, operations transform distributions, engines execute array math, and data sources feed encoders.

Contract stack

The core distribution cast lives in mixle.stats.compute.pdist:

ProbabilityDistribution

Scalar scoring, sampler creation, estimator creation, and optional support queries.

SequenceEncodableProbabilityDistribution

Vectorized scoring over encoded batches, with optional engine support.

DistributionSampler and ConditionalSampler

Seeded draw surfaces for unconditional and conditional sampling.

DistributionEnumerator

Descending-probability support iteration.

StatisticAccumulator and ParameterEstimator

Mergeable sufficient statistics and M-step estimation.

Capability layer

The capability helpers in mixle.capability make behavior inspectable at runtime. mixle.describe(x) is the front door for users; supports and require are the front door for implementation code.

The most important capability groups are:

  • support queries: Enumerable, FiniteSupport, RankableByIndex;

  • statistical form: ExponentialFamily, ConjugateUpdatable;

  • transformations: Conditionable, Marginalizable, Transform;

  • latent models: LatentStructured, PosteriorPredictive;

  • backend execution: SupportsBackendScoring, EngineResidentEStep.

Concern modules

mixle.inference

Owns fitting, EM strategies, objective optimization, posterior objects, diagnostics, model comparison, and production-facing inference utilities.

mixle.enumeration

Owns k-best search, quantized indexes, structural count DPs, rank/seek queries, and HMM path enumeration.

mixle.ops

Owns operations that transform model capability sets, such as quantize, project, condition, marginalize, mixture, transform, and tilt.

mixle.engines

Owns backend-neutral computation, precision tools, generated kernels, and symbolic export.

mixle.data

Owns typed schemas, sources, validation, hashing, and encoded-data IO.

Object modules

Distribution families stay under mixle.stats and its support-oriented subpackages. Top-level aliases such as mixle.dist and mixle.process provide discoverable object namespaces without changing serialization type IDs for existing models.

The architecture favors additive shims and re-exports over breaking moves: stable import paths matter because serialized models store fully-qualified class names.