mixle.reason.store module

Cross-modal retrieval that can condition on raw evidence.

Embedding-only retrieval can lose information for modalities that are too structured to compress safely, such as spectra, images, or spatial volumes. This store treats retrieval as evidence selection for Bayesian assimilation:

1. index the corpus by a low-cost embedding key (an approximate router, not the answer);

2. for a query, retrieve the nearest items by embedding;

3. for each, run a sufficiency test: would the raw payload reduce the query’s uncertainty materially more than its lossy embedding? If not, use the embedding evidence; if so, fetch the raw payload and condition the belief on it through its precise evidence;

4. fuse each choice into the belief (a product-of-experts update), recording provenance;

5. optionally retrieve actively by selecting the corpus item that most reduces query entropy.

Domain-neutral: the store knows nothing about seismic or spectra. The application supplies two callables: coarse(payload) -> Evidence for embedding fidelity and fine(payload) -> Evidence for raw fidelity. The same machinery can serve a document corpus or a spatially indexed volume when the application supplies the appropriate evidence functions.

class RetrievalStep(index, fidelity, gain)

Bases: object

Provenance for one assimilated item: which corpus index, at what fidelity, and the nats it removed.

Parameters:

• index (int)

• fidelity (str)

• gain (float)

class CrossModalStore(keys, payloads, *, coarse, fine, metric='euclidean')

Bases: object

A corpus indexed by embedding keys, with raw payloads conditioned on when embeddings fall short.

Parameters:

• keys (Any) – (N, d_key) embedding vectors used as the retrieval index.

• payloads (Sequence[Any]) – length-N sequence of raw items (arbitrary; passed to coarse/fine).

• coarse (Callable[[Any], LinearGaussianEvidence]) – payload -> LinearGaussianEvidence at embedding fidelity (low-cost, lossy).

• fine (Callable[[Any], LinearGaussianEvidence]) – payload -> LinearGaussianEvidence at raw fidelity (precise, “expensive”).

• metric (str) – "euclidean" (default) or "cosine" for retrieval.

retrieve(query_key, k=8)

Return indices of the nearest k embedding keys to query_key.

Parameters:

• query_key (Any)

• k (int)

Return type:

list[int]

assimilate(belief, query_key, *, k=8, query=None, epsilon=0.0)

Retrieve neighbors and fold selected evidence into belief.

For each retrieved item the sufficiency test compares how much raw evidence would reduce query entropy relative to embedding evidence. If the surplus exceeds epsilon the raw payload is used, else the embedding evidence is. Returns the updated belief and a per-item provenance trail.

Parameters:

• belief (GaussianBelief)

• query_key (Any)

• k (int)

• query (Any)

• epsilon (float)

Return type:

tuple[GaussianBelief, list[RetrievalStep]]

next_evidence(belief, *, query=None, candidates=None, fidelity='fine')

Active retrieval: the corpus item whose evidence most reduces the query entropy (EIG).

Returns (index, expected_gain_nats). fidelity selects the fine (raw) or coarse (embedding) evidence builder for the look-ahead.

Parameters:

• belief (GaussianBelief)

• query (Any)

• candidates (Sequence[int] | None)

• fidelity (str)

Return type:

tuple[int, float]