AgentSea.Provider behaviour (agentsea_core v0.1.0)

Copy Markdown

A chat-completion backend (Anthropic, OpenAI, a local model, …).

Every LLM integration implements this behaviour. Streaming is optional and, where supported, returns a lazy Stream of normalized chunks built from an SSE body — there is no async-generator plumbing.

Summary

Types

message()

A single conversation message. role is required; extra keys (e.g. tool_calls, tool_call_id) are allowed.

opts()

Provider options (model, api_key, system_prompt, tools, …).

stream_event()

A streamed event from stream/2.

Callbacks

complete(list, opts)

Run a single (non-streaming) completion.

model_info(model)

Static capabilities for a model id; nil for unknown models.

stream(list, opts)

Run a streaming completion, returning a lazy stream of stream_event/0.

Types

message()

@type message() :: %{
  :role => :system | :user | :assistant | :tool,
  :content => term(),
  optional(atom()) => term()
}

A single conversation message. role is required; extra keys (e.g. tool_calls, tool_call_id) are allowed.

opts()

@type opts() :: keyword()

Provider options (model, api_key, system_prompt, tools, …).

stream_event()

@type stream_event() ::
  {:content, String.t()} | {:thinking, String.t()} | {:tool_call, map()} | :done

A streamed event from stream/2.

Callbacks

complete(list, opts)

@callback complete([message()], opts()) :: {:ok, AgentSea.Response.t()} | {:error, term()}

Run a single (non-streaming) completion.

model_info(model)

@callback model_info(model :: String.t()) :: AgentSea.ModelInfo.t() | nil

Static capabilities for a model id; nil for unknown models.

stream(list, opts)

(optional) 
@callback stream([message()], opts()) :: Enumerable.t()

Run a streaming completion, returning a lazy stream of stream_event/0.