Gralkor.Client behaviour (gralkor_ex v2.1.3)

Copy Markdown View Source

Port for talking to a Gralkor backend from Elixir.

Operations — recall, capture, end_session, memory_add, build_indices, build_communities. Every failure is reported as {:error, reason} so callers can decide how to fail open. Group IDs are sanitised at the edge (sanitize_group_id/1) to satisfy FalkorDB's RediSearch constraint.

The concrete adapter is resolved from Application.get_env(:gralkor_ex, :client); defaults to Gralkor.Client.Native (in-process via Pythonx). Tests swap in Gralkor.Client.InMemory.

No health_check/0 — the embedded runtime is ready by the time Application.start/2 returns; runtime failures surface from the next call.

Summary

Types

agent_name()
group_id()
messages()
session_id()

Callbacks

build_communities(group_id)
build_indices()
capture(session_id, group_id, agent_name, messages)
end_session(session_id)
memory_add(group_id, content, source_description)
recall(group_id, agent_name, arg3, query)

Functions

impl()
sanitize_group_id(id)

Types

agent_name()

@type agent_name() :: String.t()

group_id()

@type group_id() :: String.t()

messages()

@type messages() :: [Gralkor.Message.t()]

session_id()

@type session_id() :: String.t()

Callbacks

build_communities(group_id)

@callback build_communities(group_id()) ::
  {:ok, %{communities: non_neg_integer(), edges: non_neg_integer()}}
  | {:error, term()}

build_indices()

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

capture(session_id, group_id, agent_name, messages)

@callback capture(session_id(), group_id(), agent_name(), messages()) ::
  :ok | {:error, term()}

end_session(session_id)

@callback end_session(session_id()) :: :ok | {:error, term()}

memory_add(group_id, content, source_description)

@callback memory_add(
  group_id(),
  content :: String.t(),
  source_description :: String.t() | nil
) ::
  :ok | {:error, term()}

recall(group_id, agent_name, arg3, query)

@callback recall(group_id(), agent_name(), session_id() | nil, query :: String.t()) ::
  {:ok, String.t()} | {:error, term()}

Functions

impl()

@spec impl() :: module()

sanitize_group_id(id)

@spec sanitize_group_id(String.t()) :: String.t()