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.

exception CapabilityUnavailable

Bases: LookupError

Typed, intentional decline from a capability implementation.

Predicate implementations may raise this when the capability is genuinely unavailable. Other exceptions are implementation defects and deliberately propagate instead of being converted into a false “unsupported” answer.

class Conditionable(*args, **kwargs)

Bases: Protocol

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

condition(observed)

Return the conditional distribution after fixing the indexed coordinates in 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)

Return the distribution over the coordinates or fields identified by 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)

Return the inferred latent-state posterior for observation 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)

Return the posterior-predictive distribution or sample representation for the supplied context.

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)

Update sufficient statistics from encoded data resident on engine.

Parameters:

• enc (Any)

• weights (Any)

• estimate (Any)

• engine (Any)

Return type:

None

class Transform(*args, **kwargs)

Bases: Protocol

A contract-declared invertible change of variables with a tractable Jacobian.

forward(x)

Map values from the base space into the transformed space.

Parameters:

x (Any)

Return type:

Any

inverse(y)

Map values from the transformed space back into the base space.

Parameters:

y (Any)

Return type:

Any

log_abs_det_inverse_jacobian(y)

Return log |det d inverse(y) / dy| for density correction.

Parameters:

y (Any)

Return type:

float

invalid_inverse_value()

Return an in-domain fill value used to encode rejected observations safely.

Return type:

Any

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)

Return per-row log densities for encoded data already resident on 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)

Return per-row, per-component log densities on 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)

Pack homogeneous component parameters into an engine-native stacked representation.

Parameters:

• dists (Any)

• engine (Any)

Return type:

Any

backend_stacked_log_density(x, params, engine)

Score encoded data against a stacked parameter representation on 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)

Return the conditional event intensity at time t given the observed history.

Parameters:

• t (float)

• times (Any)

• marks (Any)

Return type:

Any

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

Return the integrated intensity over [t_start, t_end] given the observed history.

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)

Return whether obj satisfies this capability predicate.

Parameters:

obj (Any)

Return type:

bool

class Enumerable

Bases: PredicateCapability

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

classmethod check(obj)

Return whether obj exposes a supported enumerator.

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)

Return whether obj reports a finite, non-negative support size.

A Boolean is not a support count even though bool subclasses int: support_size() returning True used to certify a one-point support, so an object answering a yes/no question was routed as an enumerable finite distribution.

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)

Return whether obj can be unranked by finite support index.

Parameters:

obj (Any)

Return type:

bool

class Shardable

Bases: PredicateCapability

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

The low-cost string predicate gates planning; the rich Decomposition is built only when a node is actually sharded.

classmethod check(obj)

Return whether obj declares a shardable decomposition axis.

Parameters:

obj (Any)

Return type:

bool

class ExponentialFamily

Bases: PredicateCapability

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

classmethod check(obj)

Return whether obj declares an exponential-family form.

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)

Return whether obj has a registered closed-form conjugate update.

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)

Return whether obj reports exact density semantics.

Parameters:

obj (Any)

Return type:

bool

class SetValued

Bases: PredicateCapability

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

classmethod check(obj)

Return whether obj exposes set-valued membership metadata.

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)

Return whether obj provides both CDF and quantile operations.

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)

Return whether obj provides at least mean and variance methods.

Parameters:

obj (Any)

Return type:

bool

class HasEntropy

Bases: PredicateCapability

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

classmethod check(obj)

Return whether obj exposes an entropy method.

Parameters:

obj (Any)

Return type:

bool

class Discrete

Bases: PredicateCapability

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

classmethod check(obj)

Return whether obj has countable or explicitly finite support.

Parameters:

obj (Any)

Return type:

bool

class Continuous

Bases: PredicateCapability

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

classmethod check(obj)

Return whether obj looks continuous by capability predicates.

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)

Return whether obj can provide an estimator.

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)

Return whether obj exposes solve and top-k optimization methods.

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)

Return whether obj is a recognized null or identity value.

Parameters:

obj (Any)

Return type:

bool

supports(obj, capability)

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

capability may be the capability class itself or the catalogued NAME STRING that capabilities() / describe() report (supports(x, "HasMoments")), so the query surface round-trips its own vocabulary.

For a runtime_checkable Protocol, isinstance establishes attribute presence only, not callable shape – an object with condition = 3 cleared supports(obj, Conditionable) and therefore require(), and the routing failure surfaced later as a TypeError inside the operation. These are authoritative dispatch declarations, so every declared protocol method must at least be callable on obj.

Parameters:

• obj (Any)

• capability (type | str)

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.

Accepts the capability class or its catalogued name string, exactly like supports().

Parameters:

• obj (Any)

• capability (type | str)

• 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)

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. Two closed forms are DERIVED when the methods are absent: a finite mixture’s mean/variance from its component moments (law of total variance), and exact mean/variance/std/entropy/median/mode for a small finite enumerable support by summing the whole support. Keys absent from the result are not available in closed form for obj – and the _status receipt names each core statistic that could not be produced and why – so summarize never raises on a partially-featured distribution and never returns a bare empty report.

Parameters:

obj (Any)

Return type:

dict[str, Any]

what_supports(capability, among)

Return the names of entries 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