mixle.capability module

Capability-based feature detection for mixle objects.

Determine what an object supports rather than what class it is, so callers can dispatch on behaviour instead of concrete class names. This generalises the pattern the engine layer already uses (DistributionCapabilities.supports_engine / intersect_engine_ready) to every capability facet in the type hierarchy (see docs/ABSTRACTIONS.md).

Two flavours of capability:

• Method-presence capabilities are runtime_checkable Protocol``s, so they work with ``isinstance and with static typing/autocomplete: Conditionable, Marginalizable, LatentStructured, PosteriorPredictive, EngineResidentEStep.

• Declaration / derived capabilities cannot be expressed by a method name (they inspect the declaration or compose other capabilities); they subclass PredicateCapability and carry a check(obj) classmethod: Enumerable, FiniteSupport, RankableByIndex, ExponentialFamily, Neutral.

supports(obj, cap) / capabilities(obj) / require(obj, cap) are the uniform query surface for both flavours. All mixle imports are deferred into the check methods so this module stays a dependency-free leaf that any layer can import without cycles.

exception CapabilityError

Bases: TypeError

Raised by require() when an object lacks a needed capability.

class Conditionable(*args, **kwargs)

Bases: Protocol

Supports conditioning on a subset of coordinates: condition(observed) -> distribution.

condition(observed)

Parameters:

observed (dict[int, float])

Return type:

Any

class Marginalizable(*args, **kwargs)

Bases: Protocol

Supports marginalising to a subset of coordinates: marginal(keep) -> distribution.

marginal(keep)

Parameters:

keep (Any)

Return type:

Any

class LatentStructured(*args, **kwargs)

Bases: Protocol

Exposes an explicit latent posterior q(z|x): latent_posterior(x) -> LatentPosterior.

latent_posterior(x)

Parameters:

x (Any)

Return type:

Any

class PosteriorPredictive(*args, **kwargs)

Bases: Protocol

Can draw/score new data conditioned on an observation’s inferred latent state.

posterior_predictive(*args, **kwargs)

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

class EngineResidentEStep(*args, **kwargs)

Bases: Protocol

An accumulator that can run its E-step on the active compute engine without leaving it.

seq_update_engine(enc, weights, estimate, engine)

Parameters:

• enc (Any)

• weights (Any)

• estimate (Any)

• engine (Any)

Return type:

None

class Transform(*args, **kwargs)

Bases: Protocol

An invertible change of variables with a tractable Jacobian (combinator/transform.py).

forward(x)

Parameters:

x (Any)

Return type:

Any

inverse(y)

Parameters:

y (Any)

Return type:

Any

log_abs_det_inverse_jacobian(y)

Parameters:

y (Any)

Return type:

float

class SupportsBackendScoring(*args, **kwargs)

Bases: Protocol

A distribution that can score a batch directly on the active engine (backend_seq_log_density).

backend_seq_log_density(x, engine)

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

class SupportsBackendComponentScoring(*args, **kwargs)

Bases: Protocol

A distribution that exposes per-component engine scoring (backend_seq_component_log_density).

backend_seq_component_log_density(x, engine)

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

class SupportsStackedBackend(*args, **kwargs)

Bases: Protocol

A component type that can score/parameterise a homogeneous stack on the engine.

backend_stacked_params(dists, engine)

Parameters:

• dists (Any)

• engine (Any)

Return type:

Any

backend_stacked_log_density(x, params, engine)

Parameters:

• x (Any)

• params (Any)

• engine (Any)

Return type:

Any

class TemporalPointProcess(*args, **kwargs)

Bases: Protocol

An event-time point process exposing its conditional intensity and compensator.

intensity(t, times, marks=None) is the conditional rate lambda(t) given the history; the univariate Hawkes / inhomogeneous-Poisson leaves return a float, the multivariate variant a per-mark vector. expected_count(t_start, t_end, times, marks=None) is the integrated intensity (compensator) over the window. (Birth-death is a population process, not an intensity-based point process, and is intentionally excluded.)

intensity(t, times, marks=None)

Parameters:

• t (float)

• times (Any)

• marks (Any)

Return type:

Any

expected_count(t_start, t_end, times, marks=None)

Parameters:

• t_start (float)

• t_end (float)

• times (Any)

• marks (Any)

Return type:

Any

class PredicateCapability

Bases: object

Base for capabilities determined by inspecting the object rather than a method name.

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class Enumerable

Bases: PredicateCapability

Its support can be iterated in descending-probability order (enumerator() works).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class FiniteSupport

Bases: PredicateCapability

Has a finite number of distinct support points (support_size() is an int).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class RankableByIndex

Bases: PredicateCapability

Supports random access by integer rank (unranking) via the count-budget seek index.

Finite-support enumerables are rankable by index through the count-DP semiring; the implication edge finite ==> enumerable ==> rankable is exactly this composition. (Decomposable combinators over infinite-but-countable children are also rankable structurally; this conservative check covers the finite-leaf case used by the dispatch layers.)

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class Shardable

Bases: PredicateCapability

Declares a non-atomic model-parallel decomposition axis (decomposition().is_shardable).

The cheap string predicate gates planning; the rich Decomposition is built only when a node is actually sharded. See ~/codex/notes/model-parallel-design.md.

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class ExponentialFamily

Bases: PredicateCapability

Declares an exponential-family form (generated stacked kernels + conjugate estimation).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class ConjugateUpdatable

Bases: PredicateCapability

Has a closed-form conjugate Bayesian update (the top tier of the inference ladder).

supports(x, ConjugateUpdatable) is True iff conjugate_posterior(x, data) returns an exact closed-form posterior; otherwise Bayesian inference falls back to the numerical fitters (MAP / Laplace / MCMC / VI). Detection is the single conjugate_posterior registry.

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class ExactDensity

Bases: PredicateCapability

log_density returns the exact log p(x), not a bound or an approximation.

False for models whose log_density is a variational lower bound (e.g. LDA / LLDA return a per-document ELBO) or a plug-in / Monte-Carlo estimate (e.g. HDPM, IBP). supports(x, ExactDensity) lets code that needs an exact likelihood require it instead of silently trusting a bound. Detection: x.density_semantics() (default DensitySemantics.EXACT).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class SetValued

Bases: PredicateCapability

A distribution over sets with forced/required membership (required / num_required).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class HasCDF

Bases: PredicateCapability

Exposes an exact cumulative distribution function and its inverse (cdf and quantile).

The CDF/quantile pair is what lets a continuous family answer probability-ordered / rank queries through the inverse transform (the continuous analogue of enumeration).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class HasMoments

Bases: PredicateCapability

Exposes closed-form moments (mean and variance at least; optionally skewness/kurtosis).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class HasEntropy

Bases: PredicateCapability

Exposes a closed-form (differential or Shannon) entropy() in nats.

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class Discrete

Bases: PredicateCapability

Countable support: the distribution is enumerable or has explicit finite support.

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class Continuous

Bases: PredicateCapability

Continuous support: has a CDF/quantile but no countable (enumerable) support.

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class Fittable

Bases: PredicateCapability

Can be fit from data: exposes an estimator() (the M-step / MLE entry point).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class Optimizable

Bases: PredicateCapability

Exposes a ranked objective over a structured space – the Relation surface (solve / top).

Optimization-as-distribution: the object can return its optimum (solve) and the k-best members (top / enumerator), so optimization is a first-class, capability-gated operation rather than a property of a specific class.

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

class Neutral

Bases: PredicateCapability

The identity / no-op element of a combinator (a Null distribution, accumulator, or encoder).

classmethod check(obj)

Parameters:

obj (Any)

Return type:

bool

supports(obj, capability)

Return whether obj provides capability (a Protocol or a PredicateCapability).

Parameters:

• obj (Any)

• capability (type)

Return type:

bool

capabilities(obj)

Return the set of capability names obj provides — “what can I do with this?”.

Parameters:

obj (Any)

Return type:

frozenset[str]

require(obj, capability, op=None)

Raise CapabilityError (early, with a clear message) if obj lacks capability.

Parameters:

• obj (Any)

• capability (type)

• op (str | None)

Return type:

None

intersect_capabilities(children, caps=FACET_PRESERVING)

Capabilities shared by EVERY child — what a decomposable combinator over them preserves.

Parameters:

• children (Any)

• caps (tuple[type, ...])

Return type:

frozenset[str]

top_k(dist, k)

Return the k highest-probability (value, log_prob) pairs.

Dispatches on capability, not class: a RankableByIndex distribution could random-access by rank, but every Enumerable distribution can stream its support in descending probability — so one implementation covers all of them, including user-defined ones. Raises a clear CapabilityError for distributions that support neither.

Parameters:

• dist (Any)

• k (int)

Return type:

list[tuple[Any, float]]

class CapabilitySpec(name, summary, kind, backed_by, home)

Bases: object

One row of the capability vocabulary: what it means, what backs it, where it lives.

Parameters:

• name (str)

• summary (str)

• kind (str)

• backed_by (str)

• home (str)

name: str

summary: str

kind: str

backed_by: str

home: str

catalog()

Return the full capability vocabulary (every facet/contract/role), as data.

Return type:

tuple[CapabilitySpec, …]

describe(obj)

Return a plain-English summary of what obj is and what you can do with it.

The one-call answer to “what can this do?”: its category, the capabilities it has and notably lacks, the engines it runs on, and how to fit it. Works on any object; richest for distributions.

Parameters:

obj (Any)

Return type:

str

summarize(obj)

Return every closed-form summary statistic obj exposes, selected by its capabilities.

The numeric companion to describe() (which says what an object can do): mean/variance/std (plus skewness/kurtosis when present) for a HasMoments distribution, entropy for HasEntropy, and the median for HasCDF. Keys absent from the result are not available in closed form for obj – so summarize never raises on a partially-featured distribution.

Parameters:

obj (Any)

Return type:

dict[str, float]

what_supports(capability, among)

Return the names of the objects in among that provide capability.

among is an iterable of instances (or classes for method-presence protocols) — e.g. what_supports(Conditionable, [mvn, gaussian, mixture]).

Parameters:

• capability (type)

• among (Any)

Return type:

list[str]

render_catalog_markdown()

Render CAPABILITY_CATALOG as a markdown table (the source for docs/CAPABILITIES.md).

Return type:

str