# `Gralkor.Client`
[🔗](https://github.com/elimydlarz/jido_gralkor/blob/main/lib/gralkor/client.ex#L1)

Port for talking to a Gralkor backend from Elixir.

Operations — recall, capture, flush, flush_and_await, 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.

`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 the episode is queryable via
`recall/4`, for callers that must observe completion before rotating
state (e.g. session-id rotation in `JidoGralkor.ContextRotator`).

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.

# `agent_name`

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

# `group_id`

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

# `messages`

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

# `session_id`

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

# `user_name`

```elixir
@type user_name() :: String.t()
```

# `build_communities`

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

# `build_indices`

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

# `capture`

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

# `flush`

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

# `flush_and_await`

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

# `memory_add`

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

# `recall`

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

# `impl`

```elixir
@spec impl() :: module()
```

# `sanitize_group_id`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*