@type content() ::
  String.t()
  | {:text, String.t()}
  | {:image_url, String.t()}
  | {:audio_url, String.t()}
  | {:document_url, String.t()}

Message content - can be text or multi-modal.

Examples

"Just text"
{:text, "Formatted text"}
{:image_url, "https://example.com/image.png"}

@type message() :: model_request() | model_response()

Any message type

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

Model identifier - provider:model string

@type model_request() :: %{parts: [request_part()], timestamp: DateTime.t()}

Model request message.

A message we send to the model.

@type model_response() :: %{
  parts: [response_part()],
  usage: Nous.Usage.t(),
  model_name: String.t(),
  timestamp: DateTime.t()
}

Model response message.

A message we receive from the model, including usage information.

@type output_type() ::
  :string
  | module()
  | %{required(atom()) => atom()}
  | map()
  | {:regex, String.t()}
  | {:grammar, String.t()}
  | {:choice, [String.t()]}
  | {:one_of, [module()]}

Output type specification.

Controls how agent output is parsed and validated:

• :string — raw text (default)
• module() — Ecto schema module → JSON schema + changeset validation
• %{atom() => atom()} — schemaless Ecto types (e.g. %{name: :string, age: :integer})
• %{String.t() => map()} — raw JSON schema map (string keys, passed through as-is)
• {:regex, String.t()} — regex-constrained output (vLLM/SGLang)
• {:grammar, String.t()} — EBNF grammar-constrained output (vLLM)
• {:choice, [String.t()]} — choice-constrained output (vLLM/SGLang)
• {:one_of, [module()]} — multi-schema selection: LLM chooses which schema to use

@type request_part() :: system_prompt_part() | user_prompt_part() | tool_return_part()

Message parts that can appear in requests to the model

@type response_part() :: text_part() | tool_call_part() | thinking_part()

Message parts that can appear in responses from the model

@type stream_event() ::
  {:text_delta, String.t()}
  | {:thinking_delta, String.t()}
  | {:tool_call_delta, any()}
  | {:finish, String.t()}
  | {:complete, map()}
  | {:error, term()}

Stream event types emitted by run_stream/3.

On successful streams, events typically arrive in this order:

• {:text_delta, text} — incremental text content
• {:thinking_delta, text} — incremental reasoning/thinking content
• {:tool_call_delta, calls} — tool call information (list for OpenAI, map/string for others)
• {:finish, reason} — stream finished, reason is a string like "stop" or "length"
• {:complete, result} — final aggregated result with %{output: text, finish_reason: reason}

{:error, reason} indicates a stream error (HTTP error, timeout, etc.) and may be emitted at any point in the stream. When an error occurs, {:finish, _} and {:complete, _} may not be emitted.

@type system_prompt_part() :: {:system_prompt, String.t()}

System prompt message part

@type text_part() :: {:text, String.t()}

Text response part from model

@type thinking_part() :: {:thinking, String.t()}

Thinking/reasoning part from model

@type tool_call() :: %{id: String.t(), name: String.t(), arguments: map()}

Tool call information from the model.

The model requests to call a tool with these parameters.

@type tool_call_part() :: {:tool_call, tool_call()}

Tool call part from model

@type tool_return() :: %{call_id: String.t(), result: any()}

Tool return information sent back to the model.

The result of executing a tool call.

@type tool_return_part() :: {:tool_return, tool_return()}

Tool return message part

@type user_prompt_part() :: {:user_prompt, String.t() | [content()]}

User prompt message part