graph-agent 0.1.0

data/docs/concepts.md

@@ -0,0 +1,216 @@
+# Core Concepts
+
+## Graphs
+
+A **graph** is a directed workflow of nodes connected by edges. GraphAgent provides
+`StateGraph` as the primary graph builder and `MessageGraph` as a convenience
+subclass for chat-oriented workflows.
+
+```ruby
+graph = GraphAgent::Graph::StateGraph.new(schema)
+```
+
+A graph is built in three phases:
+
+1. **Define** — add nodes, edges, and conditional edges.
+2. **Compile** — validate the graph and produce a `CompiledStateGraph`.
+3. **Execute** — invoke or stream the compiled graph.
+
+---
+
+## State
+
+State is the shared data structure that flows through the graph. Every node
+reads state and returns updates that are applied back to it.
+
+State is defined by a **Schema** that declares fields, their types, optional
+reducers, and defaults.
+
+```ruby
+schema = GraphAgent::State::Schema.new do
+  field :messages, type: Array, reducer: GraphAgent::Reducers::ADD, default: []
+  field :count, type: Integer, default: 0
+end
+```
+
+### Last-value semantics
+
+Fields without a reducer use **last-value** semantics: the most recent write wins.
+
+```ruby
+field :status  # no reducer → last write wins
+```
+
+### Aggregation semantics
+
+Fields with a reducer **accumulate** values. The reducer is called as
+`reducer.call(current_value, new_value)` each time the field is updated.
+
+```ruby
+field :messages, reducer: GraphAgent::Reducers::ADD, default: []
+```
+
+See [State Management](state.md) for the full DSL and all built-in reducers.
+
+---
+
+## Nodes
+
+A **node** is a callable (block, lambda, method) that receives the current
+state and optionally a config hash, then returns a Hash of state updates.
+
+```ruby
+graph.add_node("greet") do |state|
+  { greeting: "Hello, #{state[:name]}!" }
+end
+```
+
+Nodes can also return `Command` or `Send` objects for advanced routing (see
+[Send & Command](send_and_command.md)).
+
+### Arity
+
+- **0 args** — `->() { { key: value } }` — no state access.
+- **1 arg** — `->(state) { ... }` — reads state.
+- **2 args** — `->(state, config) { ... }` — reads state and config.
+
+### Retry
+
+Nodes can have a `RetryPolicy` for automatic retries on failure:
+
+```ruby
+policy = GraphAgent::RetryPolicy.new(max_attempts: 3)
+graph.add_node("flaky", method(:call_api), retry_policy: policy)
+```
+
+---
+
+## Edges
+
+Edges define transitions between nodes.
+
+### Normal edges
+
+```ruby
+graph.add_edge("node_a", "node_b")
+```
+
+### Conditional edges
+
+Route dynamically based on state:
+
+```ruby
+graph.add_conditional_edges("router", ->(state) {
+  state[:route]
+})
+```
+
+### Entry and exit
+
+Every graph needs at least one entry point from `START` and typically ends at `END_NODE`:
+
+```ruby
+graph.add_edge(GraphAgent::START, "first_node")
+graph.add_edge("last_node", GraphAgent::END_NODE)
+```
+
+Convenience helpers:
+
+```ruby
+graph.set_entry_point("first_node")
+graph.set_finish_point("last_node")
+```
+
+See [Edges](edges.md) for waiting edges, sequences, conditional entry points,
+and more.
+
+---
+
+## Supersteps (Pregel Execution Model)
+
+GraphAgent executes graphs using the **Pregel** (Bulk Synchronous Parallel)
+model. Each iteration is called a **superstep**:
+
+```
+┌─────────┐
+│  PLAN   │  Determine which nodes to run based on edges/state
+└────┬────┘
+     ▼
+┌─────────┐
+│ EXECUTE │  Run all active nodes on a frozen snapshot of state
+└────┬────┘
+     ▼
+┌─────────┐
+│ UPDATE  │  Apply all node outputs atomically via reducers
+└────┬────┘
+     ▼
+┌──────────┐
+│CHECKPOINT│  Save state if a checkpointer is configured
+└────┬─────┘
+     ▼
+┌─────────┐
+│ REPEAT  │  Continue until END_NODE is reached or recursion_limit hit
+└─────────┘
+```
+
+Key properties:
+
+- Nodes within the same superstep see the **same frozen state snapshot**.
+- All updates are applied **atomically** after every node in the step finishes.
+- A **recursion limit** (default 25) prevents infinite loops.
+
+---
+
+## Channels
+
+Channels are the internal mechanism that stores individual state fields. You
+rarely interact with channels directly, but understanding them helps when
+debugging:
+
+| Channel | Behavior |
+|---------|----------|
+| `LastValue` | Stores a single value; errors if updated more than once per step |
+| `BinaryOperatorAggregate` | Applies a reducer to aggregate multiple updates |
+| `EphemeralValue` | Resets to empty between steps |
+| `Topic` | Collects multiple values; optionally accumulates across steps |
+
+See `lib/graph_agent/channels/` for implementation details.
+
+---
+
+## START and END_NODE
+
+Two sentinel constants control graph flow:
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `GraphAgent::START` | `:"__start__"` | Virtual entry node; edges from START define where execution begins |
+| `GraphAgent::END_NODE` | `:"__end__"` | Virtual terminal node; reaching END_NODE stops execution |
+
+```ruby
+graph.add_edge(GraphAgent::START, "first")
+graph.add_edge("last", GraphAgent::END_NODE)
+```
+
+---
+
+## Compilation
+
+Calling `compile` validates the graph and returns a `CompiledStateGraph`:
+
+```ruby
+app = graph.compile(
+  checkpointer: checkpointer,       # optional persistence
+  interrupt_before: ["review"],      # optional human-in-the-loop
+  interrupt_after: ["draft"],        # optional human-in-the-loop
+  debug: false                       # enable debug events
+)
+```
+
+Validation checks:
+
+- At least one entry point exists (edge from `START` or conditional entry).
+- Every edge references an existing node (or `START`/`END_NODE`).
+- Every node has at least one outgoing edge or conditional edge.
+
+If validation fails, an `InvalidGraphError` is raised at compile time.

data/docs/edges.md

@@ -0,0 +1,265 @@
+# Edges
+
+Edges define how control flows between nodes in the graph. GraphAgent supports
+several edge types for different routing patterns.
+
+---
+
+## Normal Edges
+
+A **normal edge** creates an unconditional transition from one node to another.
+
+```ruby
+graph.add_edge("node_a", "node_b")
+```
+
+After `node_a` executes, `node_b` will always execute next.
+
+`add_edge` returns `self`, so calls can be chained:
+
+```ruby
+graph.add_edge("a", "b")
+     .add_edge("b", "c")
+     .add_edge("c", GraphAgent::END_NODE)
+```
+
+---
+
+## Entry Points (from START)
+
+Every graph must have at least one entry point — an edge from `START` to a node:
+
+```ruby
+graph.add_edge(GraphAgent::START, "first_node")
+```
+
+Or use the convenience method:
+
+```ruby
+graph.set_entry_point("first_node")
+```
+
+Both are equivalent; `set_entry_point` calls `add_edge(START, node_name)`.
+
+---
+
+## Exit Points (to END_NODE)
+
+To terminate the graph, route to `END_NODE`:
+
+```ruby
+graph.add_edge("last_node", GraphAgent::END_NODE)
+```
+
+Or use the convenience method:
+
+```ruby
+graph.set_finish_point("last_node")
+```
+
+When all active nodes route to `END_NODE`, the graph stops and returns the
+final state.
+
+---
+
+## Conditional Edges
+
+A **conditional edge** routes dynamically based on the current state. Provide a
+callable (lambda, proc, or method) that receives state and returns the name of
+the next node:
+
+```ruby
+router = ->(state) do
+  if state[:score] > 0.8
+    "approve"
+  else
+    "reject"
+  end
+end
+
+graph.add_conditional_edges("evaluate", router)
+```
+
+### With a path_map
+
+A `path_map` translates the return value of the routing function to actual node
+names. This decouples your routing logic from the graph structure:
+
+```ruby
+graph.add_conditional_edges(
+  "classifier",
+  ->(state) { state[:category] },
+  {
+    "billing"   => "billing_handler",
+    "technical" => "tech_handler",
+    "other"     => "general_handler"
+  }
+)
+```
+
+If the path function returns `"billing"`, the graph transitions to
+`"billing_handler"`.
+
+A `:default` key in the path_map is used as a fallback:
+
+```ruby
+graph.add_conditional_edges(
+  "router",
+  ->(state) { state[:intent] },
+  {
+    "buy"     => "purchase_flow",
+    "return"  => "return_flow",
+    default:    "help_flow"
+  }
+)
+```
+
+### Routing to END_NODE
+
+A conditional edge can terminate the graph by returning `END_NODE`:
+
+```ruby
+graph.add_conditional_edges("check", ->(state) {
+  state[:done] ? GraphAgent::END_NODE.to_s : "process"
+})
+```
+
+### Config access
+
+The routing function can accept two arguments to access config:
+
+```ruby
+graph.add_conditional_edges("node", ->(state, config) {
+  config.dig(:configurable, :model) == "fast" ? "quick_path" : "thorough_path"
+})
+```
+
+---
+
+## Conditional Entry Points
+
+Route from `START` conditionally:
+
+```ruby
+graph.set_conditional_entry_point(
+  ->(state) { state[:type] },
+  { "chat" => "chat_node", "search" => "search_node" }
+)
+```
+
+This is equivalent to:
+
+```ruby
+graph.add_conditional_edges(GraphAgent::START, path, path_map)
+```
+
+---
+
+## Waiting Edges (Multi-Source Synchronization)
+
+A **waiting edge** fires only when **all** source nodes have executed in the
+same step. Pass an Array of source nodes:
+
+```ruby
+graph.add_edge(["fetch_a", "fetch_b"], "merge")
+```
+
+Here `"merge"` will only execute once both `"fetch_a"` and `"fetch_b"` have
+completed in the same superstep. This is useful for fan-in / join patterns.
+
+---
+
+## Sequences
+
+`add_sequence` is a shorthand for creating a chain of nodes with normal edges
+between them:
+
+```ruby
+graph.add_sequence([
+  ["step1", ->(state) { { data: "raw" } }],
+  ["step2", ->(state) { { data: state[:data] + "_cleaned" } }],
+  ["step3", ->(state) { { data: state[:data] + "_validated" } }]
+])
+```
+
+This is equivalent to:
+
+```ruby
+graph.add_node("step1", ->(state) { { data: "raw" } })
+graph.add_node("step2", ->(state) { { data: state[:data] + "_cleaned" } })
+graph.add_node("step3", ->(state) { { data: state[:data] + "_validated" } })
+graph.add_edge("step1", "step2")
+graph.add_edge("step2", "step3")
+```
+
+You still need to add entry and exit edges yourself:
+
+```ruby
+graph.add_edge(GraphAgent::START, "step1")
+graph.add_edge("step3", GraphAgent::END_NODE)
+```
+
+Sequence items can be:
+
+- `[name, action]` — a two-element array with node name and callable.
+- A callable with a `.name` method (e.g., a method reference) — the name is
+  inferred automatically.
+- A string — references an already-added node by name.
+
+---
+
+## Validation Rules
+
+At compile time, the graph validates:
+
+1. **Entry point exists** — at least one edge from `START` or a conditional
+   entry point.
+2. **Edge references are valid** — every source/target in an edge must be a
+   known node, `START`, or `END_NODE`.
+3. **No dead-end nodes** — every node must have at least one outgoing edge or
+   conditional edge.
+
+Violations raise `InvalidGraphError`.
+
+---
+
+## Complete Example
+
+```ruby
+require "graph_agent"
+
+schema = GraphAgent::State::Schema.new do
+  field :query, type: String
+  field :results, type: Array, reducer: GraphAgent::Reducers::ADD, default: []
+  field :route, type: String
+end
+
+graph = GraphAgent::Graph::StateGraph.new(schema)
+
+graph.add_node("classify") do |state|
+  route = state[:query].include?("weather") ? "weather" : "general"
+  { route: route }
+end
+
+graph.add_node("weather") do |state|
+  { results: ["Weather: sunny, 72°F"] }
+end
+
+graph.add_node("general") do |state|
+  { results: ["I can help with that!"] }
+end
+
+graph.add_edge(GraphAgent::START, "classify")
+graph.add_conditional_edges(
+  "classify",
+  ->(state) { state[:route] },
+  { "weather" => "weather", "general" => "general" }
+)
+graph.add_edge("weather", GraphAgent::END_NODE)
+graph.add_edge("general", GraphAgent::END_NODE)
+
+app = graph.compile
+result = app.invoke({ query: "What's the weather?" })
+puts result[:results]
+# => ["Weather: sunny, 72°F"]
+```

data/docs/error_handling.md

@@ -0,0 +1,241 @@
+# Error Handling
+
+GraphAgent defines a hierarchy of error classes for different failure modes.
+All errors inherit from `GraphAgent::GraphError`, which inherits from
+`StandardError`.
+
+---
+
+## Error Hierarchy
+
+```
+StandardError
+└── GraphAgent::GraphError
+    ├── GraphAgent::GraphRecursionError
+    ├── GraphAgent::InvalidUpdateError
+    ├── GraphAgent::EmptyChannelError
+    ├── GraphAgent::InvalidGraphError
+    ├── GraphAgent::NodeExecutionError
+    ├── GraphAgent::GraphInterrupt
+    ├── GraphAgent::EmptyInputError
+    └── GraphAgent::TaskNotFound
+```
+
+---
+
+## GraphRecursionError
+
+Raised when the graph exceeds its `recursion_limit` without reaching
+`END_NODE`.
+
+```ruby
+begin
+  app.invoke(input, recursion_limit: 10)
+rescue GraphAgent::GraphRecursionError => e
+  puts e.message
+  # => "Recursion limit of 10 reached without hitting END node"
+end
+```
+
+The default limit is **25** (`CompiledStateGraph::DEFAULT_RECURSION_LIMIT`).
+Increase it for graphs that legitimately need many steps:
+
+```ruby
+result = app.invoke(input, recursion_limit: 100)
+```
+
+Common causes:
+
+- A conditional edge never routes to `END_NODE`.
+- A loop's exit condition is never satisfied.
+- The limit is too low for the workload.
+
+---
+
+## InvalidUpdateError
+
+Raised when a channel receives an invalid update. The most common case is a
+`LastValue` channel receiving more than one value in a single step:
+
+```ruby
+# Two nodes both write to the same last-value field in the same step
+# => InvalidUpdateError: "At key 'status': Can receive only one value per step."
+```
+
+Also raised by `EphemeralValue` when `guard: true` (the default) and more than
+one value is written per step.
+
+---
+
+## NodeExecutionError
+
+Wraps any unhandled exception raised inside a node. Provides access to the
+node name and the original error:
+
+```ruby
+begin
+  app.invoke(input)
+rescue GraphAgent::NodeExecutionError => e
+  puts "Failed node: #{e.node_name}"
+  puts "Original error: #{e.original_error.class}: #{e.original_error.message}"
+  puts e.message
+  # => "Error in node 'fetch_data': Connection refused"
+end
+```
+
+`GraphInterrupt` and `GraphRecursionError` raised inside nodes are **not**
+wrapped — they propagate directly.
+
+---
+
+## GraphInterrupt
+
+Raised when the graph hits an interrupt point (see
+[Human-in-the-Loop](human_in_the_loop.md)). Contains an array of
+`Interrupt` objects:
+
+```ruby
+begin
+  app.invoke(input, config: config)
+rescue GraphAgent::GraphInterrupt => e
+  puts "#{e.interrupts.length} interrupt(s)"
+  e.interrupts.each do |interrupt|
+    puts "  #{interrupt.value} (id: #{interrupt.id})"
+  end
+end
+```
+
+---
+
+## EmptyChannelError
+
+Raised when reading from a channel that has no value. This is an internal
+error — you typically encounter it only if you access a state field that was
+never initialized and has no default.
+
+---
+
+## InvalidGraphError
+
+Raised at **compile time** (when calling `graph.compile`) if the graph
+structure is invalid:
+
+```ruby
+begin
+  app = graph.compile
+rescue GraphAgent::InvalidGraphError => e
+  puts e.message
+end
+```
+
+Validation checks:
+
+| Check | Error message |
+|-------|---------------|
+| No entry point | `"Graph must have an entry point..."` |
+| Edge references unknown source | `"Edge references unknown source node '...'"` |
+| Edge references unknown target | `"Edge references unknown target node '...'"` |
+| Node has no outgoing edges | `"Node '...' has no outgoing edges"` |
+| Duplicate node name | `"Node '...' already exists"` |
+| Reserved node name | `"Node name '...' is reserved"` |
+| END as start node | `"END cannot be a start node"` |
+| START as end node | `"START cannot be an end node"` |
+| Missing node action | `"Node action must be provided"` |
+| Duplicate branch name | `"Branch '...' already exists for node '...'"` |
+
+---
+
+## EmptyInputError
+
+Raised when the graph receives empty input where input is required.
+
+---
+
+## TaskNotFound
+
+Raised when referencing a task that does not exist in the checkpoint.
+
+---
+
+## RetryPolicy
+
+Configure automatic retries for individual nodes to handle transient failures:
+
+```ruby
+policy = GraphAgent::RetryPolicy.new(
+  initial_interval: 0.5,    # seconds before first retry
+  backoff_factor: 2.0,      # multiply interval each attempt
+  max_interval: 128.0,      # cap on interval
+  max_attempts: 3,           # total attempts (1 initial + 2 retries)
+  jitter: true,              # add random jitter to intervals
+  retry_on: StandardError    # which errors to retry
+)
+
+graph.add_node("api_call", method(:call_api), retry_policy: policy)
+```
+
+### retry_on options
+
+| Value | Behavior |
+|-------|----------|
+| `StandardError` (default) | Retry on any standard error |
+| `[Net::ReadTimeout, Timeout::Error]` | Retry only on specific error classes |
+| `->(e) { e.message.include?("429") }` | Custom predicate |
+
+### Retry timing
+
+For attempt `n` (0-indexed), the interval is:
+
+```
+interval = initial_interval * (backoff_factor ^ n)
+interval = min(interval, max_interval)
+interval += rand() * interval * 0.1    # if jitter enabled
+```
+
+### Example: Retrying API calls
+
+```ruby
+retry_policy = GraphAgent::RetryPolicy.new(
+  max_attempts: 5,
+  initial_interval: 1.0,
+  backoff_factor: 2.0,
+  retry_on: [Net::ReadTimeout, Net::OpenTimeout]
+)
+
+graph.add_node("call_llm", retry_policy: retry_policy) do |state|
+  response = call_openai(state[:messages])
+  { messages: [response] }
+end
+```
+
+---
+
+## Comprehensive Error Handling
+
+```ruby
+require "graph_agent"
+
+config = { configurable: { thread_id: "t1" } }
+
+begin
+  result = app.invoke(input, config: config)
+  puts "Success: #{result}"
+
+rescue GraphAgent::GraphInterrupt => e
+  puts "Human review needed"
+  snapshot = app.get_state(config)
+  puts "State: #{snapshot.values}"
+
+rescue GraphAgent::GraphRecursionError
+  puts "Graph ran too many steps — check for infinite loops"
+
+rescue GraphAgent::NodeExecutionError => e
+  puts "Node '#{e.node_name}' failed: #{e.original_error.message}"
+
+rescue GraphAgent::InvalidUpdateError => e
+  puts "State update conflict: #{e.message}"
+
+rescue GraphAgent::GraphError => e
+  puts "Graph error: #{e.message}"
+end
+```