mixle.substrate.retrieve module

Cross-kind retrieval over substrate items.

retrieve() queries the substrate across selected item kinds, applies per-kind weights, and diversifies results so evidence can span documents, records, artifacts, traces, and other modalities. The returned Retrieval preserves merged relevance order, per-kind grouping, scores, and provenance.

class RetrievedHit(item, score)[source]

Bases: object

One retrieved item immutably paired with its relevance score (MXR-080-0248).

Retrieval used to carry items/scores as two independently-settable parallel lists, re-paired on demand via zip(self.items, self.scores) wherever a caller needed both – nothing enforced they stayed the same length, so Retrieval.provenance()’s zip could silently drop whichever tail was longer instead of raising, quietly omitting real evidence from a citation list. A RetrievedHit is the unit of construction instead: an item can never exist in a Retrieval without a validated, finite score attached, and – being frozen – the pairing itself cannot drift out of sync after the fact.

Parameters:

  • item (SubstrateItem)

  • score (float)

class Retrieval(query, items=None, scores=None)[source]

Bases: object

A planned, cross-kind retrieval result: items in merged relevance order, grouped by kind.

Construction contract (MXR-080-0248): built from aligned, validated (item, score) pairs (see RetrievedHit) – not independently-settable parallel lists. items/scores stay available as read-only derived views for every existing reader (r.items, r.scores, zip(r.items, r.scores), r.scores[0]); what changed is that a Retrieval can no longer be constructed into a state where they disagree on length, or where a score is NaN/inf.

Parameters:
property items: list[SubstrateItem]

Retrieved items in merged relevance order (a read-only derived view of hits).

property scores: list[float]

1 with items (a read-only derived view of hits).

Type:

Scores aligned 1

by_kind()[source]

Group retrieved items by substrate kind.

Return type:

dict[str, list[SubstrateItem]]

kinds()[source]

Return the sorted substrate kinds present in the result.

Return type:

list[str]

top(n)[source]

Return the top n retrieved items.

n shares Substrate.search()’s exact-non-negative-integer contract (MXR-080-0236) – no bool, no fractional value, no negative-indexing trick.

Parameters:

n (int)

Return type:

list[SubstrateItem]

provenance()[source]

Return compact provenance records for retrieved items.

Return type:

list[dict[str, Any]]

to_context(task=None, **assemble_kw)[source]

Budget THIS retrieval’s own ordered, weighted hits into a ContextPacket (MXR-080-0249).

Previously this copied self.items into a throwaway Substrate and called assemble_context(), which ran ITS OWN fresh, unweighted search over that tiny shard – discarding this retrieval’s cross-kind weights, diversification order, and scores entirely, and substituting whatever a brand-new lexical/cosine fit over just these few items happened to produce instead. A weighted retrieval that had ranked an artifact above a text item (scores 50 and 1) came back from that fresh search reordered text-before-artifact, rescored 1 and 0.5 – the weighting had silently vanished.

This instead packs self.hits – already in this retrieval’s own decided order, at their own decided scores – directly against the budget, with the same greedy, fit-checked packing assemble_context() itself uses (built on the same public ContextPacket/ContextBudget/compress_text surface, so the fit guarantee – the default rendering is always checked against its TRUE length, never an estimate – holds here too), but never re-scoring, re-ordering, or re-searching.

Accepts the same budget/compress/telemetry keywords assemble_context did. kind/scope are no longer accepted: there is no fresh search left for them to filter – restrict kinds=/scope= on the original retrieve() call instead.

Parameters:

  • task (str | None)

  • assemble_kw (Any)

Return type:

Any

retrieve(substrate, query, *, k=8, kinds=None, weights=None, diversify=True, scope=None, telemetry=None)[source]

Plan a cross-kind retrieval for query (see module docstring).

Parameters:

  • k (int) – total items to return. Must be an exact, non-negative int (MXR-080-0236, see _require_count()) – bool and fractional values are rejected, and a negative k raises rather than silently slicing from the end. Validated once, up front, before any per-kind search runs, and used identically by both the diversified and flat merge paths below so a given k means the same thing regardless of diversify.

  • kinds (list[str] | None) – restrict to these substrate kinds (default: every kind present).

  • weights (dict[str, float] | None) – per-kind score multipliers (e.g. {"artifact": 1.2} to favor deployable models). Every weight must be finite and non-negative (MXR-080-0248) – a negative weight would silently reverse that kind’s relevance ordering, and a NaN/infinite weight would destabilize the merged order; both are rejected up front, before any score is multiplied.

  • diversify (bool) – when True (default), interleave the top hits of each kind so the result spans modalities; when False, take a flat merged top-k (whichever kind scores highest wins).

  • scope (str | None) – restrict to a team/access scope.

  • substrate (Substrate)

  • query (str)

  • telemetry (Any)

Return type:

Retrieval