Gralkor.Client behaviour (gralkor v1.2.0)

Port for talking to a Gralkor backend from Elixir.

Six operations — recall, capture, end_session, memory_search, memory_add, health_check. 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 Gralkor's RediSearch constraint.

The concrete adapter is resolved from Application.get_env(:gralkor, :client); defaults to Gralkor.Client.HTTP. Tests swap in Gralkor.Client.InMemory.

Summary

Types

group_id()

session_id()

turn()

Callbacks

build_communities(group_id)

build_indices()

capture(session_id, group_id, turn)

end_session(session_id)

health_check()

memory_add(group_id, content, source_description)

memory_search(group_id, session_id, query)

recall(group_id, session_id, query)

Functions

impl()

sanitize_group_id(id)

Types

group_id()

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

session_id()

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

turn()

@type turn() :: %{
  user_query: String.t(),
  assistant_answer: String.t(),
  events: [map()]
}

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, turn)

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

end_session(session_id)

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

health_check()

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

memory_search(group_id, session_id, query)

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

recall(group_id, session_id, query)

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

Functions

impl()

@spec impl() :: module()

sanitize_group_id(id)

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