graph-agent 0.1.0

data/docs/human_in_the_loop.md

@@ -0,0 +1,231 @@
+# Human-in-the-Loop
+
+GraphAgent supports pausing graph execution so a human can inspect the state,
+approve actions, provide input, or modify state before resuming.
+
+---
+
+## Overview
+
+The human-in-the-loop pattern works in three steps:
+
+1. **Interrupt** — the graph pauses before or after a specific node.
+2. **Inspect / Modify** — the human reads the state, optionally modifies it.
+3. **Resume** — the graph continues from where it left off.
+
+This requires a **checkpointer** to persist state across the pause.
+
+---
+
+## interrupt_before and interrupt_after
+
+Specify which nodes should trigger interrupts at compile time:
+
+```ruby
+checkpointer = GraphAgent::Checkpoint::InMemorySaver.new
+
+app = graph.compile(
+  checkpointer: checkpointer,
+  interrupt_before: ["human_review"],  # pause BEFORE this node runs
+  interrupt_after: ["draft"]           # pause AFTER this node runs
+)
+```
+
+- `interrupt_before` — pauses **before** the node executes. The node has not
+  yet seen or modified state.
+- `interrupt_after` — pauses **after** the node executes and its updates are
+  applied.
+
+Both accept an array of node name strings or symbols.
+
+---
+
+## Catching GraphInterrupt
+
+When an interrupt fires, the graph raises `GraphAgent::GraphInterrupt`:
+
+```ruby
+config = { configurable: { thread_id: "review-1" } }
+
+begin
+  result = app.invoke(input, config: config)
+  puts "Completed: #{result}"
+rescue GraphAgent::GraphInterrupt => e
+  puts "Paused with #{e.interrupts.length} interrupt(s)"
+  e.interrupts.each do |interrupt|
+    puts "  #{interrupt.value}"
+  end
+end
+```
+
+Each interrupt in the `interrupts` array is a `GraphAgent::Interrupt` object:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `value` | Object | Description of the interrupt (typically a String) |
+| `id` | String | Unique identifier for this interrupt |
+
+---
+
+## Inspecting State with get_state
+
+After an interrupt, inspect the saved state:
+
+```ruby
+snapshot = app.get_state(config)
+
+puts "Current state: #{snapshot.values}"
+puts "Next nodes: #{snapshot.next_nodes}"
+puts "Step: #{snapshot.metadata[:step]}"
+```
+
+This lets the human review what the graph has computed so far and decide
+whether to approve, modify, or reject.
+
+---
+
+## Modifying State with update_state
+
+The human can modify state before resuming:
+
+```ruby
+app.update_state(config, {
+  approved: true,
+  reviewer_notes: "Looks good, proceed"
+})
+```
+
+Updates respect reducers — if a field has a reducer, the update is merged
+through it.
+
+---
+
+## Resuming Execution
+
+Resume by calling `invoke` with `nil` input and the same config:
+
+```ruby
+result = app.invoke(nil, config: config)
+```
+
+The graph picks up from the last checkpoint and continues execution.
+
+---
+
+## Wildcard Interrupts
+
+Use `"*"` to interrupt before or after **every** node:
+
+```ruby
+app = graph.compile(
+  checkpointer: checkpointer,
+  interrupt_before: ["*"]
+)
+```
+
+This is useful for step-by-step debugging or approval workflows where every
+action needs human review.
+
+---
+
+## Full Example
+
+```ruby
+require "graph_agent"
+
+schema = GraphAgent::State::Schema.new do
+  field :messages, type: Array, reducer: GraphAgent::Reducers::ADD, default: []
+  field :draft, type: String
+  field :approved, type: :boolean, default: false
+end
+
+graph = GraphAgent::Graph::StateGraph.new(schema)
+
+graph.add_node("generate_draft") do |state|
+  topic = state[:messages].last[:content]
+  { draft: "Draft response about: #{topic}" }
+end
+
+graph.add_node("human_review") do |state|
+  if state[:approved]
+    { messages: [{ role: "ai", content: state[:draft] }] }
+  else
+    { messages: [{ role: "ai", content: "Draft was rejected." }] }
+  end
+end
+
+graph.add_edge(GraphAgent::START, "generate_draft")
+graph.add_edge("generate_draft", "human_review")
+graph.add_edge("human_review", GraphAgent::END_NODE)
+
+checkpointer = GraphAgent::Checkpoint::InMemorySaver.new
+app = graph.compile(
+  checkpointer: checkpointer,
+  interrupt_before: ["human_review"]
+)
+
+config = { configurable: { thread_id: "review-session-1" } }
+
+# Step 1: Start execution — will pause before human_review
+begin
+  app.invoke(
+    { messages: [{ role: "user", content: "Write about Ruby" }] },
+    config: config
+  )
+rescue GraphAgent::GraphInterrupt => e
+  puts "Interrupted: #{e.interrupts.first.value}"
+end
+
+# Step 2: Inspect the draft
+snapshot = app.get_state(config)
+puts "Draft: #{snapshot.values[:draft]}"
+
+# Step 3: Approve and resume
+app.update_state(config, { approved: true })
+result = app.invoke(nil, config: config)
+puts "Final: #{result[:messages].last[:content]}"
+```
+
+---
+
+## Patterns
+
+### Approval Gate
+
+```ruby
+graph.add_node("propose_action") do |state|
+  { proposed_action: "Delete 50 records" }
+end
+
+graph.add_node("execute_action") do |state|
+  if state[:approved]
+    { result: "Deleted 50 records" }
+  else
+    { result: "Action cancelled" }
+  end
+end
+
+graph.add_edge(GraphAgent::START, "propose_action")
+graph.add_edge("propose_action", "execute_action")
+graph.add_edge("execute_action", GraphAgent::END_NODE)
+
+app = graph.compile(
+  checkpointer: checkpointer,
+  interrupt_before: ["execute_action"]
+)
+```
+
+### Human Input Collection
+
+```ruby
+graph.add_node("ask_question") do |state|
+  { question: "What is your preferred language?" }
+end
+
+graph.add_node("process_answer") do |state|
+  { result: "You chose: #{state[:human_input]}" }
+end
+
+# After interrupt, the human provides input via update_state:
+# app.update_state(config, { human_input: "Ruby" })
+```

data/docs/persistence.md

@@ -0,0 +1,276 @@
+# Persistence & Checkpointing
+
+Persistence enables multi-turn conversations, fault recovery, and
+human-in-the-loop workflows by saving graph state between invocations.
+
+---
+
+## Why Persistence Matters
+
+Without persistence, every `invoke` starts from scratch. With a checkpointer:
+
+- **Multi-turn conversations** — state accumulates across calls using the same
+  `thread_id`.
+- **Fault tolerance** — if a graph fails mid-execution, the last checkpoint is
+  available to resume from.
+- **Human-in-the-loop** — interrupts pause execution; the state is saved so a
+  human can inspect, modify, and resume.
+- **Time travel** — list past checkpoints to replay or debug execution history.
+
+---
+
+## InMemorySaver
+
+`GraphAgent::Checkpoint::InMemorySaver` stores checkpoints in a Ruby Hash. It
+is suitable for development, testing, and single-process applications.
+
+```ruby
+checkpointer = GraphAgent::Checkpoint::InMemorySaver.new
+app = graph.compile(checkpointer: checkpointer)
+```
+
+> **Note:** Data is lost when the process exits. For production, implement a
+> custom saver backed by a database (see below).
+
+---
+
+## Thread-Based Conversations
+
+A **thread** is identified by `thread_id` in the config. All invocations with
+the same `thread_id` share state:
+
+```ruby
+config = { configurable: { thread_id: "user-42" } }
+
+# First turn
+result1 = app.invoke(
+  { messages: [{ role: "user", content: "Hi, I'm Alice" }] },
+  config: config
+)
+
+# Second turn — state includes messages from the first turn
+result2 = app.invoke(
+  { messages: [{ role: "user", content: "What's my name?" }] },
+  config: config
+)
+# result2[:messages] contains all messages from both turns
+```
+
+Different `thread_id` values create independent conversations:
+
+```ruby
+config_a = { configurable: { thread_id: "thread-a" } }
+config_b = { configurable: { thread_id: "thread-b" } }
+
+# These are completely independent
+app.invoke({ messages: [{ role: "user", content: "Hello" }] }, config: config_a)
+app.invoke({ messages: [{ role: "user", content: "Bonjour" }] }, config: config_b)
+```
+
+---
+
+## Checkpoint Lifecycle
+
+During execution, checkpoints are saved at specific points with a `source`
+metadata field:
+
+| Source | When |
+|--------|------|
+| `:input` | After initializing state from input, before any nodes run |
+| `:loop` | After each superstep completes |
+| `:interrupt` | When an interrupt fires (before or after a node) |
+| `:exit` | After the graph finishes (reaches `END_NODE`) |
+| `:update` | After a manual `update_state` call |
+
+Each checkpoint stores:
+
+- `channel_values` — the full state at that point.
+- `next_nodes` — which nodes would execute next.
+- `id` — a UUID identifying this checkpoint.
+
+---
+
+## get_state
+
+Retrieve the current state snapshot for a thread:
+
+```ruby
+snapshot = app.get_state(config)
+```
+
+Returns a `GraphAgent::StateSnapshot` with:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `values` | Hash | Current state values |
+| `next_nodes` | Array | Nodes that would execute next |
+| `config` | Hash | Config including `checkpoint_id` |
+| `metadata` | Hash | Step number, source, etc. |
+| `parent_config` | Hash/nil | Config of the previous checkpoint |
+| `tasks` | Array | Pending tasks |
+| `interrupts` | Array | Active interrupts |
+
+```ruby
+snapshot = app.get_state(config)
+puts snapshot.values[:messages]
+puts "Next: #{snapshot.next_nodes}"
+puts "Step: #{snapshot.metadata[:step]}"
+```
+
+Returns `nil` if no checkpoint exists for the given config.
+
+---
+
+## update_state
+
+Manually modify the state of a thread:
+
+```ruby
+app.update_state(config, { approved: true, reviewer: "Alice" })
+```
+
+This creates a new checkpoint with the updated state. The metadata `source` is
+set to `:update`.
+
+`update_state` respects reducers: if a field has a reducer, the update value is
+merged via that reducer, not replaced.
+
+```ruby
+# If :messages has an ADD reducer:
+app.update_state(config, {
+  messages: [{ role: "system", content: "Human approved this action" }]
+})
+# The new message is appended, not replaced
+```
+
+Returns the new checkpoint config (with the new `checkpoint_id`), or `nil` if
+no checkpoint exists.
+
+---
+
+## StateSnapshot
+
+`GraphAgent::StateSnapshot` is a read-only object returned by `get_state`:
+
+```ruby
+snapshot = app.get_state(config)
+
+snapshot.values       # => { messages: [...], count: 5 }
+snapshot.next_nodes   # => ["process"]
+snapshot.config       # => { configurable: { thread_id: "t1", checkpoint_id: "..." } }
+snapshot.metadata     # => { source: :loop, step: 3 }
+snapshot.parent_config # => { configurable: { ... } } or nil
+snapshot.created_at   # => Time or nil
+snapshot.tasks        # => []
+snapshot.interrupts   # => []
+```
+
+---
+
+## Listing Checkpoints
+
+`InMemorySaver#list` returns all checkpoints for a thread (most recent first):
+
+```ruby
+checkpoints = checkpointer.list(config)
+
+checkpoints.each do |tuple|
+  puts "ID: #{tuple.config.dig(:configurable, :checkpoint_id)}"
+  puts "Step: #{tuple.metadata[:step]}"
+  puts "Source: #{tuple.metadata[:source]}"
+  puts "---"
+end
+```
+
+Options:
+
+```ruby
+# Filter by metadata
+checkpointer.list(config, filter: { source: :loop })
+
+# Limit results
+checkpointer.list(config, limit: 5)
+
+# Before a specific checkpoint
+checkpointer.list(config, before: {
+  configurable: { checkpoint_id: "some-uuid" }
+})
+```
+
+---
+
+## Deleting Threads
+
+Remove all checkpoints and writes for a thread:
+
+```ruby
+checkpointer.delete_thread("user-42")
+```
+
+---
+
+## Implementing a Custom CheckpointSaver
+
+Subclass `GraphAgent::Checkpoint::BaseSaver` and implement four methods:
+
+```ruby
+class PostgresSaver < GraphAgent::Checkpoint::BaseSaver
+  def get_tuple(config)
+    thread_id = config.dig(:configurable, :thread_id)
+    checkpoint_id = config.dig(:configurable, :checkpoint_id)
+
+    # Query your database for the checkpoint
+    row = db_query(thread_id, checkpoint_id)
+    return nil unless row
+
+    GraphAgent::Checkpoint::CheckpointTuple.new(
+      config: config,
+      checkpoint: row[:checkpoint],
+      metadata: row[:metadata],
+      parent_config: row[:parent_config],
+      pending_writes: row[:pending_writes] || []
+    )
+  end
+
+  def list(config, filter: nil, before: nil, limit: nil)
+    # Return an array of CheckpointTuple, newest first
+  end
+
+  def put(config, checkpoint, metadata, new_versions)
+    thread_id = config.dig(:configurable, :thread_id)
+    checkpoint_id = checkpoint[:id]
+
+    # Insert into your database
+    db_insert(thread_id, checkpoint_id, checkpoint, metadata)
+
+    # Return the new config
+    {
+      configurable: {
+        thread_id: thread_id,
+        checkpoint_ns: config.dig(:configurable, :checkpoint_ns) || "",
+        checkpoint_id: checkpoint_id
+      }
+    }
+  end
+
+  def put_writes(config, writes, task_id)
+    # Store pending writes
+  end
+
+  def delete_thread(thread_id)
+    # Delete all data for the thread
+  end
+end
+```
+
+### CheckpointTuple
+
+`GraphAgent::Checkpoint::CheckpointTuple` is a `Data.define` with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `config` | Hash | Config with `thread_id`, `checkpoint_ns`, `checkpoint_id` |
+| `checkpoint` | Hash | Serialized state (`channel_values`, `id`, etc.) |
+| `metadata` | Hash/nil | Step, source, parents |
+| `parent_config` | Hash/nil | Config pointing to the previous checkpoint |
+| `pending_writes` | Array | Pending writes as `[task_id, channel, value]` triples |

data/docs/quickstart.md

@@ -0,0 +1,154 @@
+# Quickstart
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "graph-agent"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install graph-agent
+```
+
+Requires Ruby >= 3.1.0.
+
+---
+
+## Hello World
+
+The simplest possible graph: one node, in → out.
+
+```ruby
+require "graph_agent"
+
+graph = GraphAgent::Graph::StateGraph.new({ greeting: {} })
+
+graph.add_node("greet") do |state|
+  { greeting: "Hello, #{state[:name]}!" }
+end
+
+graph.add_edge(GraphAgent::START, "greet")
+graph.add_edge("greet", GraphAgent::END_NODE)
+
+app = graph.compile
+result = app.invoke({ name: "World" })
+
+puts result[:greeting]
+# => "Hello, World!"
+```
+
+**What happened:**
+
+1. We defined a state with a single field `:greeting` (last-value semantics — no reducer).
+2. We added a node `"greet"` that reads `:name` from state and writes `:greeting`.
+3. We wired `START → greet → END_NODE`.
+4. We compiled and invoked.
+
+---
+
+## Calculator Agent
+
+A more realistic example: a loop that processes arithmetic operations until there are none left.
+
+```ruby
+require "graph_agent"
+
+schema = GraphAgent::State::Schema.new do
+  field :operations, type: Array, reducer: GraphAgent::Reducers::REPLACE, default: []
+  field :results, type: Array, reducer: GraphAgent::Reducers::ADD, default: []
+  field :done, type: :boolean, default: false
+end
+
+graph = GraphAgent::Graph::StateGraph.new(schema)
+
+graph.add_node("compute") do |state|
+  op = state[:operations].first
+  remaining = state[:operations][1..]
+
+  answer = case op[:op]
+           when "+" then op[:a] + op[:b]
+           when "-" then op[:a] - op[:b]
+           when "*" then op[:a] * op[:b]
+           when "/" then op[:a].to_f / op[:b]
+           end
+
+  {
+    operations: remaining,
+    results: [{ expression: "#{op[:a]} #{op[:op]} #{op[:b]}", answer: answer }],
+    done: remaining.empty?
+  }
+end
+
+should_continue = ->(state) do
+  state[:done] ? GraphAgent::END_NODE.to_s : "compute"
+end
+
+graph.add_edge(GraphAgent::START, "compute")
+graph.add_conditional_edges("compute", should_continue)
+
+app = graph.compile
+
+result = app.invoke({
+  operations: [
+    { op: "+", a: 2, b: 3 },
+    { op: "*", a: 4, b: 5 },
+    { op: "-", a: 10, b: 7 }
+  ]
+})
+
+result[:results].each do |r|
+  puts "#{r[:expression]} = #{r[:answer]}"
+end
+# 2 + 3 = 5
+# 4 * 5 = 20
+# 10 - 7 = 3
+```
+
+---
+
+## Running with Streaming
+
+Instead of waiting for the final result, stream intermediate states:
+
+```ruby
+app.stream(
+  { operations: [{ op: "+", a: 1, b: 2 }, { op: "*", a: 3, b: 4 }] },
+  stream_mode: :updates
+) do |updates|
+  puts "Step updates: #{updates}"
+end
+```
+
+Or use an `Enumerator` (no block):
+
+```ruby
+events = app.stream(
+  { operations: [{ op: "+", a: 1, b: 2 }] },
+  stream_mode: :values
+)
+
+events.each do |state|
+  puts "Results so far: #{state[:results]}"
+end
+```
+
+---
+
+## Where to Go Next
+
+- [Core Concepts](concepts.md) — understand graphs, state, nodes, edges, and supersteps.
+- [State Management](state.md) — deep dive into schemas, reducers, and defaults.
+- [Edges](edges.md) — all edge types including conditional and waiting edges.
+- [Persistence](persistence.md) — checkpointing and multi-turn conversations.
+- [Human-in-the-Loop](human_in_the_loop.md) — interrupt, inspect, modify, resume.
+- [API Reference](api_reference.md) — every class and method.