mixle.inference.belief module

Belief states: a distribution over a latent, updated by evidence.

A belief state is the answer-side representation for reasoning: the posterior over a scientific latent given all evidence seen so far. Unlike an embedding vector it is distributional – it carries its own uncertainty – and unlike an LLM’s hidden state it updates by Bayesian conditioning, so folding in a new modality (or a retrieved datum) is a principled evidence step, not a concatenation. That makes multi-source reasoning an assimilation loop: start from the prior, fold in evidence one piece at a time, and watch the posterior entropy shrink.

This module provides the exact, canonical realization – GaussianBelief, a multivariate Gaussian over a continuous latent with a linear-Gaussian (Kalman) measurement update. Two beliefs about the same latent fuse as a product of experts (GaussianBelief.fuse()), which is the cross-modal fusion the reasoning layer is built on. Sequential updates are exact and order-independent: folding in evidence one datum at a time equals conditioning on all of it at once – the property the tests check.

Non-Gaussian belief states (mixture/HMM responsibilities, mean-field fields) already exist as LatentPosterior realizations in mixle.stats.compute.posterior; as_belief() adapts any object exposing mean/cov into this interface. Nonlinear/EKF and particle updates are future work (see notes/mixle-cross-modal-reasoning-design.md, Phase 2).

class BeliefState

Bases: ABC

A distribution over a latent, exposing a uniform query + update interface.

Realizations answer where they are defined: mean(), cov(), var(), sd(), entropy(), interval(), sample(), marginal(), and – the point of a belief state – update(), which returns a new belief conditioned on fresh evidence.

abstractmethod mean()

The posterior mean of the latent.

Return type:

ndarray

abstractmethod entropy()

The differential/Shannon entropy H[q] (nats) – watch it shrink as evidence arrives.

Return type:

float

abstractmethod sample(n=1, rng=None)

Draw n latent samples from the belief.

Parameters:

• n (int)

• rng (Any)

Return type:

ndarray

abstractmethod update(*args, **kwargs)

Return a new belief conditioned on fresh evidence (the assimilation step).

Parameters:

• args (Any)

• kwargs (Any)

Return type:

BeliefState

cov()

The posterior covariance (not defined for every realization).

Return type:

ndarray

var()

Per-coordinate posterior variance.

Return type:

ndarray

sd()

Per-coordinate posterior standard deviation.

Return type:

ndarray

interval(level=0.9)

Per-coordinate central credible interval at level – an (d, 2) array of [lo, hi].

Parameters:

level (float)

Return type:

ndarray

marginal(indices)

The belief restricted to a subset of latent coordinates.

Parameters:

indices (Any)

Return type:

BeliefState

class CategoricalBelief(probs, labels=None)

Bases: BeliefState

A belief over a finite hypothesis set – exact Bayes over K discrete alternatives.

The discrete sibling of GaussianBelief: evidence is a length-K log-likelihood vector log p(y | hypothesis k) and update() is the exact posterior (a product of experts in log space). mean returns the probability vector; entropy is Shannon (nats); map the modal hypothesis index.

Parameters:

• probs (Any)

• labels (Any)

classmethod uniform(k_or_labels)

Parameters:

k_or_labels (Any)

Return type:

CategoricalBelief

mean()

The posterior mean of the latent.

Return type:

ndarray

entropy()

The differential/Shannon entropy H[q] (nats) – watch it shrink as evidence arrives.

Return type:

float

sample(n=1, rng=None)

Draw n latent samples from the belief.

Parameters:

• n (int)

• rng (Any)

Return type:

ndarray

update(log_lik)

Exact Bayes: condition on a length-K log-likelihood vector for one observation.

Parameters:

log_lik (Any)

Return type:

CategoricalBelief

map()

The modal hypothesis label.

Return type:

Any

class GaussianBelief(mean, cov)

Bases: BeliefState

A multivariate-Gaussian belief N(mean, cov) over a continuous latent.

Evidence is a linear-Gaussian observation y = H z + noise, noise ~ N(0, R); update() applies the exact Kalman measurement update (Joseph form, so the covariance stays symmetric positive-definite). fuse() combines two beliefs about the same latent as a product of Gaussian experts. condition() does noiseless Gaussian conditioning on a coordinate subset.

Parameters:

• mean (Any)

• cov (Any)

property dim: int

mean()

The posterior mean of the latent.

Return type:

ndarray

cov()

The posterior covariance (not defined for every realization).

Return type:

ndarray

entropy()

The differential/Shannon entropy H[q] (nats) – watch it shrink as evidence arrives.

Return type:

float

interval(level=0.9)

Per-coordinate central credible interval at level – an (d, 2) array of [lo, hi].

Parameters:

level (float)

Return type:

ndarray

sample(n=1, rng=None)

Draw n latent samples from the belief.

Parameters:

• n (int)

• rng (Any)

Return type:

ndarray

update(H, y, R)

Kalman measurement update: condition on y = H z + noise, noise ~ N(0, R).

Parameters:

• H (Any) – (k, d) observation matrix (or (d,) / scalar for a single linear readout).

• y (Any) – (k,) observed value (or scalar).

• R (Any) – (k, k) observation-noise covariance (or (k,) diagonal / scalar).

Return type:

GaussianBelief

fuse(other)

Product-of-experts fusion of two beliefs about the same latent (cross-modal fusion).

Equivalent to conditioning self on other treated as a direct Gaussian observation (H = I, R = other.cov), so it reuses the exact Kalman update.

Parameters:

other (GaussianBelief)

Return type:

GaussianBelief

condition(indices, values)

Noiseless Gaussian conditioning: fix latent coordinates indices to values.

Returns the belief over the remaining coordinates. This is the exact R -> 0 limit of an observation that reads off those coordinates.

Parameters:

• indices (Any)

• values (Any)

Return type:

GaussianBelief

marginal(indices)

The belief restricted to a subset of latent coordinates.

Parameters:

indices (Any)

Return type:

GaussianBelief

as_belief(obj, node=None)

Adapt any object exposing mean/cov (a FieldPosterior node, a fitted Gaussian, a ParameterPosterior) into a GaussianBelief.

node is forwarded when the source is node-addressable (e.g. FieldPosterior.mean(node) / .cov(node)); otherwise mean/cov are called with no argument.

Parameters:

• obj (Any)

• node (Any)

Return type:

GaussianBelief