LLMAgent.Handlers (llm_agent v0.1.1)

View Source

Provides standard handlers for processing LLM-specific signals.

This module implements signal handlers for the various LLM agent signal types, following AgentForge's handler pattern. Each handler takes a signal and state, processes the signal, and returns a tuple with a result and a new state.

Summary

Functions

Handles error signals.

Handles user message signals.

Handles response signals.

Handles task state signals.

Handles thinking step signals.

Handles tool call signals.

Handles tool result signals.

Functions

error_handler(signal, state)

Handles error signals.

Processes errors and may implement recovery strategies.

Parameters

  • signal - The error signal
  • state - The current store state

Returns

A tuple containing the result and updated state.

Examples

iex> signal = LLMAgent.Signals.error("API unavailable", "get_weather")
iex> state = LLMAgent.Store.new()
iex> {result, new_state} = LLMAgent.Handlers.error_handler(signal, state)
iex> is_tuple(result) and is_map(new_state)
true

message_handler(signal, state)

Handles user message signals.

Takes a user message, adds it to history, and generates the appropriate next signal (thinking, tool call, or response) based on the message content and available tools.

Parameters

  • signal - The user message signal
  • state - The current store state

Returns

A tuple containing the result and updated state.

Examples

iex> signal = LLMAgent.Signals.user_message("Hello")
iex> state = LLMAgent.Store.new()
iex> {result, new_state} = LLMAgent.Handlers.message_handler(signal, state)
iex> match?({:emit, %{type: :thinking}}, result) or match?({:emit, %{type: :response}}, result)
true

response_handler(signal, state)

Handles response signals.

Formats the final response and may trigger notifications or other side effects.

Parameters

  • signal - The response signal
  • state - The current store state

Returns

A tuple containing the result and updated state.

Examples

iex> signal = LLMAgent.Signals.response("AAPL is trading at $200")
iex> state = LLMAgent.Store.new()
iex> {result, new_state} = LLMAgent.Handlers.response_handler(signal, state)
iex> is_tuple(result) and is_map(new_state)
true

task_handler(signal, state)

Handles task state signals.

Updates the state of a task and generates a notification if necessary.

Parameters

  • signal - The task state signal
  • state - The current store state

Returns

A tuple containing the result and updated state.

Examples

iex> signal = LLMAgent.Signals.task_state("task_123", "completed")
iex> state = LLMAgent.Store.new()
iex> {result, new_state} = LLMAgent.Handlers.task_handler(signal, state)
iex> is_tuple(result) and is_map(new_state)
true

thinking_handler(signal, state)

Handles thinking step signals.

Processes a thinking step, adds it to state, and determines the next action (continue thinking, call a tool, or generate a response).

Parameters

  • signal - The thinking signal
  • state - The current store state

Returns

A tuple containing the result and updated state.

Examples

iex> signal = LLMAgent.Signals.thinking("I need stock data", 1)
iex> state = LLMAgent.Store.new()
iex> {result, new_state} = LLMAgent.Handlers.thinking_handler(signal, state)
iex> is_tuple(result) and is_map(new_state)
true

tool_handler(signal, state)

Handles tool call signals.

Executes the specified tool with the provided arguments and generates a tool result signal. Includes parameter validation based on tool schema and detailed error handling.

Parameters

  • signal - The tool call signal
  • state - The current store state

Returns

A tuple containing the result and updated state.

Examples

iex> signal = LLMAgent.Signals.tool_call("get_weather", %{city: "New York"})
iex> state = LLMAgent.Store.new()
iex> {result, new_state} = LLMAgent.Handlers.tool_handler(signal, state)
iex> is_tuple(result) and is_map(new_state)
true

tool_result_handler(signal, state)

Handles tool result signals.

Processes the result of a tool execution and generates the next signal based on the result.

Parameters

  • signal - The tool result signal
  • state - The current store state

Returns

A tuple containing the result and updated state.

Examples

iex> signal = LLMAgent.Signals.tool_result("get_weather", %{temp: 72})
iex> state = LLMAgent.Store.new()
iex> {result, new_state} = LLMAgent.Handlers.tool_result_handler(signal, state)
iex> is_tuple(result) and is_map(new_state)
true