Gralkor.Client behaviour (jido_gralkor v7.0.0)

Copy Markdown View Source

Public entry point and adapter port for Gralkor memory.

Named Lens operations use ingest/1 and replace/1; search/1 selects registered Destinations. Ingestion resolves an appending Lens and invokes its ingestion process with a Lens-bound store. Replacement validates and stores the complete graph for a replaceable Lens. Lenses and Reflections reference first-class Destinations, whose addresses resolve graph placement and whose ontologies govern extraction. Destination search runs every distinct selection concurrently, defaults an empty selection to packaged operator memory, and can return facts, nodes, episodes, or Reflection artefacts.

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. The internal capture/8 form also carries the host tools and tool context made available to subsequent Reflections. 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()
search_result()
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)
capture( session_id, group_id, agent_name, user_name, messages, lens, additional_lenses, reflection_context )
flush(session_id)
flush_and_await(session_id, timeout_ms)
memory_add(group_id, content, source_description)
recall(group_id, agent_name, arg3, query)

Functions

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

Types

agent_name()

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

group_id()

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

messages()

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

search_result()

@type search_result() :: map()

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

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

@callback capture(
  session_id(),
  group_id(),
  agent_name(),
  user_name(),
  messages(),
  lens :: String.t(),
  additional_lenses :: [String.t()],
  reflection_context :: map()
) :: :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()}

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

ingest(request)

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

lens!(name)

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

replace(request)

@spec replace(Gralkor.Replace.t()) :: :ok | {:error, term()}

sanitize_group_id(id)

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

search(request)

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