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 Retrieval(query, items=<factory>, scores=<factory>)[source]

Bases: object

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

Parameters:
query: str
items: list[SubstrateItem]
scores: list[float]
by_kind()[source]
Return type:

dict[str, list[SubstrateItem]]

kinds()[source]
Return type:

list[str]

top(n)[source]
Parameters:

n (int)

Return type:

list[SubstrateItem]

provenance()[source]
Return type:

list[dict[str, Any]]

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

Assemble a ContextPacket from this retrieval (over an in-memory shard of its items).

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.

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

  • 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