Gralkor.Interpret (gralkor_ex v3.1.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/3 — pure: assemble the LLM prompt from conversation messages and a formatted facts string, dropping oldest messages until the prompt fits the configured char budget. Renders role labels using agent_name.
interpret_facts/5 — call the LLM with that prompt and a structured- output schema; return the list of relevant facts the LLM selected.

See ex-interpret and ex-interpret-context in gralkor/TEST_TREES.md.

Summary

Functions

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

Assemble the LLM prompt from conversation messages and the formatted facts.

interpret_facts(messages, 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, facts_text, agent_name, opts \\ [])

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

Assemble the LLM prompt from conversation messages and the formatted facts.

Drops oldest messages until the assembled prompt fits the char budget (opts[:budget], default 8000). Raises on blank agent_name.

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

@spec interpret_facts(
  [Gralkor.Message.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 max_tokens on the provider call, 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.