Raxol.Agent.AIBackend behaviour (Raxol Agent v2.6.0)

Behaviour for pluggable AI model integration.

Agents are backend-agnostic -- they call complete/2 or stream/2 and the backend handles the model-specific HTTP/inference details.

Implementations:

Raxol.Agent.Backend.HTTP -- Req-based client for Claude, GPT, Ollama, Kimi, OpenRouter
Raxol.Agent.Backend.Lumo -- Proton Lumo with U2L encryption (or lumo-tamer proxy)
Raxol.Agent.Backend.Mock -- Deterministic responses for testing

Summary

Callbacks

available?()

Check if the backend is currently available.

capabilities()

List of supported capabilities.

complete(list, opts)

Send messages and receive a complete response.

handles_tools_internally?()

Whether the backend runs its own internal tool-call loop.

max_context_tokens()

Maximum context window in tokens, or nil when unknown.

name()

Human-readable name of the backend.

stream(list, opts)

Send messages and receive a stream of events.

Functions

handles_tools_internally?(backend)

Query whether a backend handles tools internally, defaulting to false.

max_context_tokens(backend)

Query a backend's max context window, defaulting to nil.

Types

message()

@type message() :: %{role: :system | :user | :assistant, content: String.t()}

response()

@type response() :: %{content: String.t(), usage: map(), metadata: map()}

stream_event()

@type stream_event() :: {:chunk, String.t()} | {:done, response()} | {:error, term()}

Callbacks

available?()

@callback available?() :: boolean()

Check if the backend is currently available.

capabilities()

@callback capabilities() :: [:completion | :streaming | :tool_use | :vision]

List of supported capabilities.

complete(list, opts)

@callback complete([message()], opts :: keyword()) :: {:ok, response()} | {:error, term()}

Send messages and receive a complete response.

handles_tools_internally?()

(optional)

@callback handles_tools_internally?() :: boolean()

Whether the backend runs its own internal tool-call loop.

When true, the vendor owns the agent loop (e.g. a wrapped Claude Code or Codex CLI) and the framework must NOT drive tool dispatch itself -- it injects its tools into the vendor instead. When false (the default), the framework's ReAct loop drives tool calls. Defaults to false for backends that omit it.

max_context_tokens()

(optional)

@callback max_context_tokens() :: pos_integer() | nil

Maximum context window in tokens, or nil when unknown.

name()

@callback name() :: String.t()

Human-readable name of the backend.

stream(list, opts)

(optional)

@callback stream([message()], opts :: keyword()) ::
  {:ok, Enumerable.t()} | {:error, term()}

Send messages and receive a stream of events.

Functions

handles_tools_internally?(backend)

@spec handles_tools_internally?(module()) :: boolean()

Query whether a backend handles tools internally, defaulting to false.

Safe to call on any backend module: backends that do not implement the optional callback are treated as framework-driven.

max_context_tokens(backend)

@spec max_context_tokens(module()) :: pos_integer() | nil

Query a backend's max context window, defaulting to nil.