LangEx.Graph (LangEx v0.11.3)

StateGraph builder.

Constructs a graph definition via a pipeline of add_node, add_edge, and add_conditional_edges calls, then compiles it into an executable LangEx.Graph.Compiled.

Summary

Functions

add_conditional_edges(graph, source, routing_fn, mapping \\ nil)

Adds conditional edges from source using a routing function.

add_edge(graph, from, to)

Adds a fixed edge from from to to.

add_node(graph, name, node_value, node_opts \\ [])

Adds a named node with its handler function.

add_sequence(graph, nodes)

Chains a list of node names with sequential edges.

compile(graph, opts \\ [])

Compiles the graph builder into an executable CompiledGraph.

new(schema \\ [])

Creates a new graph builder with the given state schema.

to_mermaid(compiled)

Renders the graph as a Mermaid flowchart.

Types

node_fn()

@type node_fn() :: (map() -> map() | LangEx.Command.t())

node_opt()

@type node_opt() ::
  {:retry, keyword() | true}
  | {:cache, keyword() | true}
  | {:defer, boolean()}
  | {:timeout, pos_integer()}
  | {:on_error, (Exception.t(), map() -> map() | LangEx.Command.t())}

routing_fn()

@type routing_fn() :: (map() -> atom() | String.t())

t()

@type t() :: %LangEx.Graph{
  conditional_edges: %{required(atom()) => {routing_fn(), map() | nil}},
  edges: %{required(atom()) => [atom()]},
  node_opts: %{required(atom()) => [node_opt()]},
  nodes: %{required(atom()) => node_fn() | LangEx.Graph.Compiled.t()},
  schema: keyword()
}

Functions

add_conditional_edges(graph, source, routing_fn, mapping \\ nil)

@spec add_conditional_edges(t(), atom(), routing_fn(), map() | nil) :: t()

Adds conditional edges from source using a routing function.

The routing function receives the current state and returns a node name (atom or string). An optional mapping converts return values to node names.

add_edge(graph, from, to)

@spec add_edge(t(), atom(), atom()) :: t()

Adds a fixed edge from from to to.

add_node(graph, name, node_value, node_opts \\ [])

@spec add_node(t(), atom(), node_fn() | LangEx.Graph.Compiled.t(), [node_opt()]) ::
  t()

Adds a named node with its handler function.

A compiled graph can be used as a node (subgraph). The runtime context, streaming events, and interrupts propagate through it, and its checkpoints (when it has its own checkpointer) are namespaced under "{thread_id}/{node_name}".

Execution policy options

:retry - retry the node on exceptions. true for defaults, or a keyword list — see LangEx.Graph.RetryPolicy for options (max_attempts:, initial_interval_ms:, backoff_factor:, max_interval_ms:, jitter:, retryable?:).
:cache - memoize successful results keyed by the node's input state. true for no expiry, or [ttl: milliseconds]. Cannot be combined with :on_error.
:defer - when true, the node runs only once no other (non-deferred) nodes are active — a fan-in barrier for parallel branches that converge at different depths.
:timeout - per-attempt time budget in milliseconds. A timed-out attempt raises LangEx.NodeTimeoutError, which the retry policy can retry; when exhausted it surfaces as {:error, %LangEx.NodeError{}}.
:on_error - fn exception, state -> update end invoked after the retry policy is exhausted; its return value becomes the node result (a state update map or %LangEx.Command{}). Failures inside the handler propagate.

add_sequence(graph, nodes)

@spec add_sequence(t(), [atom()]) :: t()

Chains a list of node names with sequential edges.

Graph.add_sequence(graph, [:a, :b, :c])
# equivalent to add_edge(graph, :a, :b) |> add_edge(:b, :c)

compile(graph, opts \\ [])

@spec compile(
  t(),
  keyword()
) :: LangEx.Graph.Compiled.t()

Compiles the graph builder into an executable CompiledGraph.

Options:

:name - stable graph identifier used in telemetry (:graph_id)
:checkpointer - module implementing LangEx.Checkpointer behaviour
:store - long-term memory backend, Module or {Module, config} (see LangEx.Store)
:interrupt_before - node names to pause at before execution (static breakpoints; requires a checkpointer to resume)
:interrupt_after - node names to pause at after execution
:warn_unreachable - warn about nodes not reachable via declared edges (default true; disable for graphs routed via Command goto)

new(schema \\ [])

@spec new(keyword()) :: t()

Creates a new graph builder with the given state schema.

Schema entries are key: default or key: {default, reducer_fn}.

to_mermaid(compiled)

@spec to_mermaid(t() | LangEx.Graph.Compiled.t()) :: String.t()

Renders the graph as a Mermaid flowchart.

Solid arrows are static edges; dashed arrows are conditional edges, labelled with the routing value when a mapping is given. Accepts a builder or a compiled graph.

graph |> Graph.to_mermaid() |> IO.puts()