@spec merge_usage(map() | nil, map()) :: map()

Reducer that accumulates token usage maps by summing numeric fields.

Use as the schema reducer for the usage key:

Graph.new(llm_usage: {%{}, &ChatModel.merge_usage/2})

@spec node(keyword()) :: (map() -> map())

Returns a node function that calls an LLM provider.

Options

• :provider - module implementing LangEx.LLM (explicit)
• :model - model string like "gpt-4o" or "claude-sonnet-4-20250514" (auto-resolves provider)
• :messages_key - state key holding the message list (default: :messages)
• :usage_key - state key accumulating token usage (default: :llm_usage); only written when the key exists in the graph state schema
• :tools - list of %LangEx.Tool{} definitions for function calling
• :resilient - route calls through LangEx.LLM.Resilient for retries with backoff. true for defaults, or a keyword list of Resilient options (:max_retries, :retry_base_ms, :fallback, ...)
• All other opts forwarded to provider.chat/2 (:api_key, :temperature, etc.)

Either :provider or :model must be given. When :model is a string and :provider is absent, the provider is resolved via LangEx.LLM.Registry.init_chat_model/2.

Tool execution is handled by a separate LangEx.Tool.Node in the graph, not by the LLM node itself.

Token usage accounting

When the provider implements chat_with_usage/2, token counts are attached to the [:lang_ex, :llm, :chat, :stop] telemetry event as :usage metadata. To also accumulate usage in graph state, declare the usage key in the schema with merge_usage/2 as the reducer:

Graph.new(
  messages: {[], &Message.add_messages/2},
  llm_usage: {%{}, &ChatModel.merge_usage/2}
)

Examples

Graph.add_node(:llm, ChatModel.node(model: "gpt-4o"))
Graph.add_node(:llm, ChatModel.node(model: "gpt-4o",
  tools: [%LangEx.Tool{name: "search", ...}]
))