Gralkor.Interpret (jido_gralkor v7.0.0)

Filter retrieved graph facts down to those relevant to the conversation, using the configured LLM.

Two responsibilities, each its own tree:

build_interpretation_context/5 — pure: assemble the LLM prompt from conversation messages, the request being answered, and a formatted facts string, dropping oldest messages until the prompt fits the configured char budget. Renders role labels using agent_name.
interpret_facts/6 — call the LLM with that prompt and a structured- output schema; return the list of relevant facts the LLM selected.

The request travels separately from the conversation because a recall may be made from a session that never carried it — a fresh session, or a memory search whose query is not the last thing the user said. Without it the model has nothing to judge relevance against.

See test-trees/unit/interpret_TEST_TREES.md.

Summary

Types

interpret_fn()

Functions

build_interpretation_context(messages, query, facts_text, agent_name, opts \\ [])

Assemble the LLM prompt from conversation messages, the request being answered, and the formatted facts.

interpret_facts(messages, query, facts_text, interpret_fn, agent_name, opts \\ [])

Run the LLM over the conversation context + facts text, returning the filtered list of relevant facts.

interpret_schema()

Schema for the structured-output response the LLM returns.

Types

interpret_fn()

@type interpret_fn() :: (String.t(), pos_integer() ->
                     {:ok, [String.t()]} | {:error, term()})

Functions

build_interpretation_context(messages, query, facts_text, agent_name, opts \\ [])

@spec build_interpretation_context(
  [Gralkor.Message.t()],
  String.t(),
  String.t(),
  String.t(),
  keyword()
) :: String.t()

Assemble the LLM prompt from conversation messages, the request being answered, and the formatted facts.

Drops oldest messages until the assembled prompt fits the char budget (opts[:budget], default 8000). The request and the facts are never dropped. Raises on blank agent_name.

interpret_facts(messages, query, facts_text, interpret_fn, agent_name, opts \\ [])

@spec interpret_facts(
  [Gralkor.Message.t()],
  String.t(),
  String.t(),
  interpret_fn(),
  String.t(),
  keyword()
) :: [String.t()]

Run the LLM over the conversation context + facts text, returning the filtered list of relevant facts.

opts[:output_token_budget] (default 2000) is passed to interpret_fn so the LLM-side wiring can set the provider's output token limit, and is also rendered into the prompt as a self-limit instruction.

Raises Gralkor.InterpretParseFailed if the LLM returns a response that can't be parsed against the schema (truncation, schema mismatch). Raises RuntimeError if the call returns {:error, _} (upstream LLM failure). Raises ArgumentError if agent_name is blank or the output token budget is non-positive/non-integer.

interpret_schema()

@spec interpret_schema() :: keyword()

Schema for the structured-output response the LLM returns.