mixle.reason.store module

Cross-modal RAG with a raw-data fallback: retrieve by embedding, condition on raw evidence.

Embedding-only retrieval (embed everything, fetch top-k, stuff the vectors in) loses information twice for modalities too lossy to compress – a full spectrum, a thin-section image, a seismic sub-volume. This store treats retrieval as evidence selection for Bayesian assimilation instead:

1. index the corpus by a cheap 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 cheap embedding evidence; if so, fetch the raw payload and condition the belief on it through its full (precise) evidence;

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

5. optionally retrieve actively – fetch the corpus item that most reduces the query entropy.

Domain-neutral: the store knows nothing about seismic or spectra. The application supplies two callables – coarse(payload) -> Evidence (embedding fidelity) and fine(payload) -> Evidence (raw fidelity) – so the same machinery serves a document corpus or one spatially-indexed volume (see the mixle_pde spatial-store application).

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)

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 – the retrieval index (routers, not answers).

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

• coarse (Callable[[Any], LinearGaussianEvidence]) – payload -> LinearGaussianEvidence at embedding fidelity (cheap, 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)

Indices of the k corpus items whose embedding keys are nearest query_key.

Parameters:

• query_key (Any)

• k (int)

Return type:

list[int]

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

Retrieve k neighbors and fold each into belief, fetching raw payloads when the embedding is too lossy for the query.

For each retrieved item the sufficiency test compares how much the raw evidence would reduce the query entropy versus the embedding evidence; if the surplus exceeds epsilon the raw payload is used, else the cheap embedding 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]