Gralkor.Client behaviour (jido_gralkor v5.0.0)

Copy Markdown View Source

Public entry point and adapter port for Gralkor memory.

Named Lens operations use ingest/1 and search/1. Ingestion resolves the application-owned Lens definition and invokes its ingestion process with a Lens-bound store. Search always begins with the requesting operator's reserved "default" destination, then combines explicitly selected operator-local Lens destinations and the reserved "global" pool; a global Lens name is provenance, not a search boundary.

The compatibility surface remains recall/4, capture/5, flush/1, flush_and_await/2, and memory_add/3 or /4. Lens-aware capture uses capture/6, or capture/7 when the same turn is also routed through additional Lenses. Legacy group IDs are sanitised at their graph boundary (sanitize_group_id/1); Lens storage binds the original operator id to its selected Lens instead.

flush/1 returns :ok before the buffered turns have landed (fire-and-forget — appropriate for shutdown paths that cannot block). flush_and_await/2 returns :ok only after buffered ingestion completes, for callers that must observe completion before rotating state (for example session-id rotation in JidoGralkor.ContextRotator).

The concrete adapter is resolved from Application.get_env(:jido_gralkor, :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()
ontology()
session_id()
user_name()

Callbacks

build_communities(group_id)
build_indices()
capture(session_id, group_id, agent_name, user_name, messages)
capture(session_id, group_id, agent_name, user_name, messages, lens)
capture(session_id, group_id, agent_name, user_name, messages, lens, additional_lenses)
flush(session_id)
flush_and_await(session_id, timeout_ms)
generalise(group_id, transcript)
memory_add(group_id, content, source_description)
memory_add(group_id, content, source_description, ontology)
recall(group_id, agent_name, arg3, query)
search_generalisations(group_id, query, max_results)

Functions

impl()
ingest(request)
lens!(name)
sanitize_group_id(id)
search(search)

Types

agent_name()

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

group_id()

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

messages()

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

ontology()

@type ontology() :: module() | nil

session_id()

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

user_name()

@type user_name() :: 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, user_name, messages)

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

capture(session_id, group_id, agent_name, user_name, messages, lens)

@callback capture(
  session_id(),
  group_id(),
  agent_name(),
  user_name(),
  messages(),
  lens :: String.t()
) :: :ok | {:error, term()}

capture(session_id, group_id, agent_name, user_name, messages, lens, additional_lenses)

@callback capture(
  session_id(),
  group_id(),
  agent_name(),
  user_name(),
  messages(),
  lens :: String.t(),
  additional_lenses :: [String.t()]
) :: :ok | {:error, term()}

flush(session_id)

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

flush_and_await(session_id, timeout_ms)

@callback flush_and_await(session_id(), timeout_ms :: pos_integer()) ::
  :ok | {:error, :timeout} | {:error, term()}

generalise(group_id, transcript)

@callback generalise(group_id(), transcript :: String.t()) :: :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_add(group_id, content, source_description, ontology)

@callback memory_add(
  group_id(),
  content :: String.t(),
  source_description :: String.t() | nil,
  ontology()
) :: :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()}

search_generalisations(group_id, query, max_results)

@callback search_generalisations(
  group_id(),
  query :: String.t(),
  max_results :: pos_integer()
) ::
  {:ok, [Gralkor.Generalisation.t()]} | {:error, term()}

Functions

impl()

@spec impl() :: module()

ingest(request)

@spec ingest(Gralkor.Ingest.t()) :: :ok | {:error, term()}

lens!(name)

@spec lens!(String.t()) :: Gralkor.Lens.t()

sanitize_group_id(id)

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

search(search)

@spec search(Gralkor.Search.t()) :: {:ok, [String.t()]} | {:error, term()}