@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 name and idempotency_key. 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 episode UUID forwarded to graphiti's add_episode. When given, graphiti fetches the existing episode and re-runs extraction against it (update path). When nil (default), graphiti generates a new UUID.

@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()}

Build indices and constraints across the whole graph.

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 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()) ::
  {:ok, [map()]} | {:error, term()}

Run graphiti's hybrid EDGE search against group_id. Returns {:ok, [%{fact:, created_at:, valid_at:, invalid_at:, expired_at:}]} ready for Gralkor.Format.format_facts/1.

For retrieving custom-entity nodes (e.g. Learning for ERL recall) use search_nodes/5 — edge search's node-label filtering matches edges by endpoint and misses standalone nodes.

@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 — the right primitive for retrieving custom-entity nodes like Learning, which 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 (e.g. ["Learning"] for ERL recall). When absent, all nodes are eligible.

@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.