AgentForge.Flow (AgentForge v0.2.1)

View Source

Provides functions for processing signals through a chain of handlers. Each handler is a function that takes a signal and state, and returns a tuple with result and new state.

Summary

Types

A flow is a handler function or a list of handler functions. Each handler takes a signal and state, and returns a tuple with result and new state.

Functions

Creates a handler that always emits a signal of the given type and data.

Creates a handler that only processes signals of a specific type. Other signal types are skipped.

Processes a signal through a list of handlers with execution limits. Supports timeout to prevent long-running processes.

Creates a handler that stores the signal data in state under the given key.

Types

flow()

@type flow() ::
  (AgentForge.Signal.t(), map() -> {term(), map()})
  | [(AgentForge.Signal.t(), map() -> {term(), map()})]

A flow is a handler function or a list of handler functions. Each handler takes a signal and state, and returns a tuple with result and new state.

Functions

always_emit(type, data)

Creates a handler that always emits a signal of the given type and data.

Examples

iex> handler = AgentForge.Flow.always_emit(:done, "success")
iex> {result, state} = handler.(nil, %{})
iex> match?({:emit, %{type: :done, data: "success"}}, result)
true

filter_type(type, handler)

Creates a handler that only processes signals of a specific type. Other signal types are skipped.

Examples

iex> inner = fn signal, state -> {AgentForge.Signal.emit(:processed, signal.data), state} end
iex> handler = AgentForge.Flow.filter_type(:test, inner)
iex> test_signal = AgentForge.Signal.new(:test, "data")
iex> {result, _} = handler.(test_signal, %{})
iex> match?({:emit, %{type: :processed}}, result)
true
iex> other_signal = AgentForge.Signal.new(:other, "data")
iex> handler.(other_signal, %{}) |> elem(0)
:skip

get_last_execution_stats()

process(handlers, signal, state)

process_handler(handler, signal, state)

process_with_limits(handlers, signal, state, opts \\ [])

Processes a signal through a list of handlers with execution limits. Supports timeout to prevent long-running processes.

Options

  • :timeout_ms - Maximum time in milliseconds to process (default: 30000)
  • :collect_stats - Whether to collect execution statistics (default: true)
  • :return_stats - Whether to return statistics in the result (default: false)

Examples

iex> handlers = [
...>   fn sig, st -> {{:emit, AgentForge.Signal.new(:echo, sig.data)}, st} end
...> ]
iex> signal = AgentForge.Signal.new(:test, "data")
iex> {:ok, result, _} = AgentForge.Flow.process_with_limits(handlers, signal, %{})
iex> result.type
:echo

With statistics:

iex> handlers = [
...>   fn sig, st -> {{:emit, AgentForge.Signal.new(:echo, sig.data)}, st} end
...> ]
iex> signal = AgentForge.Signal.new(:test, "data")
iex> {:ok, _result, _, stats} = AgentForge.Flow.process_with_limits(handlers, signal, %{}, return_stats: true)
iex> stats.steps >= 1
true

store_in_state(key)

Creates a handler that stores the signal data in state under the given key.

Examples

iex> handler = AgentForge.Flow.store_in_state(:last_message)
iex> signal = AgentForge.Signal.new(:test, "data")
iex> {result, state} = handler.(signal, %{})
iex> result
:skip
iex> state.last_message
"data"