Mnemosyne.Pipeline.HopControl (mnemosyne v0.2.0)

LLM-driven control of the multi-hop retrieval loop.

At each hop, an LLM controller assesses whether the accumulated candidates are sufficient to answer the query. When they are, retrieval stops early. When they are not, the controller selects a small focus set of candidates whose content drives the next-hop query, and the retrieval tags are regenerated conditioned on what has been retrieved so far. Tag refinement is capped by the configured refinement budget to bound LLM cost.

Summary

Functions

assess(state, query, candidates, hop, ctx)

Assesses whether retrieval can stop at the current hop.

init(config, max_hops)

Initializes control state from config and the pipeline's max hop count. The refinement budget is capped at max_hops to avoid exceeding the traversal depth. Without config, refinement is disabled but the sufficiency controller still runs.

node_content(arg1)

Extracts the primary text content of a node for prompt display.

refine(state, query, candidates, hop, ctx)

Regenerates retrieval tags conditioned on the query and candidates retrieved so far. Runs whenever refinement budget remains.

Functions

assess(state, query, candidates, hop, ctx)

@spec assess(
  Mnemosyne.Pipeline.HopControl.State.t(),
  String.t(),
  [Mnemosyne.Pipeline.Retrieval.TaggedCandidate.t()],
  non_neg_integer(),
  map()
) ::
  {:stop, Mnemosyne.Pipeline.HopControl.State.t()}
  | {:continue, [Mnemosyne.Pipeline.Retrieval.TaggedCandidate.t()],
     Mnemosyne.Pipeline.HopControl.State.t()}

Assesses whether retrieval can stop at the current hop.

Returns {:stop, state} when the controller judges the candidates sufficient, or {:continue, focus_candidates, state} with up to 2 focus candidates selected to drive the next hop. Degrades to {:continue, [], state} on any LLM or parse failure so retrieval never breaks on controller errors.

init(config, max_hops)

@spec init(Mnemosyne.Config.t() | nil, non_neg_integer()) ::
  Mnemosyne.Pipeline.HopControl.State.t()

Initializes control state from config and the pipeline's max hop count. The refinement budget is capped at max_hops to avoid exceeding the traversal depth. Without config, refinement is disabled but the sufficiency controller still runs.

node_content(arg1)

@spec node_content(struct()) :: String.t()

Extracts the primary text content of a node for prompt display.

refine(state, query, candidates, hop, ctx)

@spec refine(
  Mnemosyne.Pipeline.HopControl.State.t(),
  String.t(),
  [Mnemosyne.Pipeline.Retrieval.TaggedCandidate.t()],
  non_neg_integer(),
  map()
) ::
  {:refined, [String.t()], [[float()]], Mnemosyne.Pipeline.HopControl.State.t()}
  | {:skip, Mnemosyne.Pipeline.HopControl.State.t()}

Regenerates retrieval tags conditioned on the query and candidates retrieved so far. Runs whenever refinement budget remains.

Returns {:refined, tags, vectors, new_state} on success, or {:skip, new_state} when the budget is exhausted or refinement fails.