mixle.substrate.multihop module

Planned multi-hop retrieval over substrate links and content.

Single-shot retrieve() answers “what is most relevant to this query”. But real questions chain: a symptom points to a document, the document names an entity, the entity links to a record, the record was produced by a model artifact. multihop() walks that chain – starting from the best matches, then expanding along two kinds of hop:

  • LINK hops: follow an item’s links (explicit KG edges / lineage the substrate already stores),

  • CONTENT hops: re-query the substrate with the frontier item’s own text, surfacing neighbors it is about (the “this reminds me of” step),

up to max_hops, under a per-expansion budget. The result is a HopChain: the items found and the provenance path by which each was reached. Branches that surface no new items stop early.

class HopStep(item, depth, via, parent_id, score=0.0)[source]

Bases: object

One item in the chain plus how it was reached: the provenance of a retrieval decision.

Parameters:

  • item (SubstrateItem)

  • depth (int)

  • via (str)

  • parent_id (str | None)

  • score (float)

item: SubstrateItem
depth: int
via: str
parent_id: str | None
score: float = 0.0
class HopChain(query, steps=<factory>)[source]

Bases: object

A multi-hop retrieval result: the items found and the evidence PATH to each.

Parameters:

  • query (str)

  • steps (list[HopStep])

query: str
steps: list[HopStep]
property items: list[SubstrateItem]
by_depth()[source]
Return type:

dict[int, list[SubstrateItem]]

max_depth()[source]
Return type:

int

path_to(item_id)[source]

The evidence chain from a seed to item_id – the trace the reasoner cites.

Parameters:

item_id (str)

Return type:

list[SubstrateItem]

provenance()[source]
Return type:

list[dict[str, Any]]

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

  • task (str | None)

  • assemble_kw (Any)

Return type:

Any

multihop(substrate, query, *, max_hops=2, seeds=3, branch=2, max_items=12, min_score=0.0, scope=None, telemetry=None)[source]

Chain typed hops from query across the substrate, recording the evidence path (see docstring).

Parameters:

  • max_hops (int) – how many hops out from the seeds to expand.

  • seeds (int) – how many top matches to start from (depth 0).

  • branch (int) – how many neighbors to expand per frontier item per hop.

  • max_items (int) – overall cap on the chain size.

  • min_score (float) – relevance floor for SEED and CONTENT hops – a match must score strictly above it to enter the chain (LINK hops are explicit edges and always followed). Keeps a fuzzy retriever from chaining on near-zero-similarity noise; raise it for a dense embedder.

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

  • substrate (Substrate)

  • query (str)

  • telemetry (Any)

Return type:

HopChain