@spec add_episode(
  GenServer.server(),
  String.t(),
  String.t(),
  String.t(),
  module() | nil,
  keyword()
) :: :ok | {:error, term()}

Ingest one episode (text content) into group_id via graphiti's add_episode. Auto-generates a unique episode name. When ontology is a module declared with use Gralkor.Ontology, its payload is materialised into graphiti's entity_types, edge_types, edge_type_map, and excluded_entity_types (cached per ontology module in the GenServer state).

Options

• :uuid — optional deterministic episode UUID. A graph-backed renewable claim serializes that UUID across application runtimes. The episode, extracted entities and edges, and durable completion marker persist in one generation-fenced graph query. A missing UUID is created, an equal marked episode succeeds without extraction, an equal unmarked episode resumes extraction, and conflicting immutable episode content returns an episode conflict.
• :lens — optional originating Lens name. It is appended to the episode's source description before the single graphiti add_episode call.
• :source_kind — :conversation, :document, or :structured_record, mapped to graphiti's message, text, or JSON episode type respectively.

@spec api_key!(atom()) :: String.t()

The credential for provider, read on the Elixir side.

Erlang's os:putenv keeps its own table and never reaches the C environment, so a credential set from Elixir — a consumer's runtime.exs, or the test helper loading .env — is invisible to the embedded interpreter's os.environ. Every client constructor therefore takes its key as an explicit argument rather than letting the Python client read the variable itself.

Raises when the variable is absent; validate_native_models!/2 has already proven it present for every provider a role selects.

@spec build_communities(GenServer.server(), String.t()) ::
  {:ok, %{communities: non_neg_integer(), edges: non_neg_integer()}}
  | {:error, term()}

Build communities for group_id.

@spec build_indices(GenServer.server()) ::
  {:ok, %{status: String.t()}} | {:error, term()}

Rebuild indices and constraints across the whole graph.

Every group is its own FalkorDB database, so "the whole graph" is every group this pool holds an instance for — rebuilding one group's database would leave every other group untouched. A group whose instance has not been created yet needs no rebuild: initialise_instance/1 builds its indices the moment it is.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec for(GenServer.server(), String.t()) :: any()

Return the Graphiti instance for group_id, creating it on first use.

Concurrent callers do not block each other once the instance is cached. Construction itself is serialised through the GenServer so two callers asking for the same group_id at the same time don't both construct it.

@spec get_episode(GenServer.server(), String.t(), String.t()) ::
  {:ok, map()} | {:error, :not_found | term()}

Returns one episode by its exact UUID.

@spec graphiti_boundary_spec(map()) :: %{optional(atom()) => term()}

Pure projection from an __ontology__/0 payload to the plain data handed across the Pythonx boundary. A graphiti add_episode kwarg (entity_types, edge_types, edge_type_map, excluded_entity_types) is populated iff its payload collection is present; the Pythonx side never re-decides inclusion, it materialises exactly what this spec carries. No Pythonx, no LLM — this is the deterministic contract the materialisation half trusts.

@spec remove_episode(GenServer.server(), String.t(), String.t()) ::
  :ok | {:error, term()}

Remove an episode and its orphaned edges/nodes from the graph.

Calls graphiti's remove_episode(uuid) which deletes the episode, its entity edges that were created by that episode, and any entity nodes referenced only by the deleted episode.

@spec search(GenServer.server(), String.t(), String.t(), pos_integer(), keyword()) ::
  {:ok, [map()]} | {:error, term()}

Run graphiti's hybrid EDGE search against group_id. Returns {:ok, [%{fact:, created_at:, valid_at:, invalid_at:, expired_at:}]} whose individual entries can be rendered by Gralkor.Format.format_fact/1.

For retrieving custom-entity nodes, use search_nodes/5 — edge search's node-label filtering matches edges by endpoint and misses standalone nodes.

@spec search_episodes(String.t(), String.t(), pos_integer()) ::
  {:ok, [map()]} | {:error, term()}

Episode search against group_id via graphiti's search_ with an episode-only config. Returns {:ok, [%{content:, source_description:}]} — the episode bodies as they were written.

This is the primitive for content Gralkor must read back verbatim. Edge and node search both return what an extractor derived from an episode, which is a different text and may be nothing at all: an episode naming one subject yields a node and no edge. Graphiti searches episodes by BM25 over their content, so retrieval here depends on the stored words rather than extraction. Internal completion-only callers may request identity convergence. Ranked results choose artefact identifiers; every completed episode carrying a selected identifier is then enumerated independently of BM25 so conflicts outside the ranked window remain visible to the caller. Mixed public episode searches may require completion only for Reflection-authored episodes while leaving ordinary historical episodes visible, or require trusted Lens or Reflection writer provenance.

@spec search_nodes(
  GenServer.server(),
  String.t(),
  String.t(),
  pos_integer(),
  keyword()
) ::
  {:ok, [map()]} | {:error, term()}

Node search against group_id via graphiti's search_ with the NODE_HYBRID_SEARCH_RRF recipe. Unlike search/4 (which returns edges and whose node_labels filter matches edges by endpoint), this returns nodes that are not reliably reachable through edge search.

Returns {:ok, [%{name:, summary:, attributes:}]} ordered by relevance.

Options

• :node_labels — optional [String.t()]. When present, a SearchFilters(node_labels: …) restricts results to nodes carrying one of those labels. When absent, all nodes are eligible.

@spec shared_client_spec(map(), map()) :: %{
  llm: map(),
  embedder: map(),
  cross_encoder: map()
}

Decide which provider builds each shared client, from the two configured model specs. Pure — no Pythonx, no credentials read — so the per-role dispatch is pinned deterministically and default_construct_shared_clients/2 is left with nothing to decide.

Each role takes its own spec's provider. The cross-encoder has no spec of its own and follows the llm role. A Google embedder carries :batch_size of 1; the OpenAI embedder takes no batch size at all, its client having no such parameter and no equivalent of the Gemini batching defect.

@spec summarise_python_error(Pythonx.Error.t()) :: String.t()

Build a compact one-line reason from a Pythonx.Error.

Exception.message/1 on a Pythonx.Error joins the entire Python traceback (every frame, every embedding vector echoed in a call line) into one multi-line blob. On a transient FalkorDB reset that blob — and the whole embedding search vector inside it — gets dumped to the log via the rescue's {:error, {:python, reason}}.

The struct's :lines field is the output of Python's traceback.format_exception(type, value, traceback): a list whose final non-blank entry is the "ExceptionClass: message" summary line. We take that one line — the error's class and message — and drop the frames entirely.