graph-agent 0.1.0

data/docs/send_and_command.md

@@ -0,0 +1,218 @@
+# Send & Command
+
+GraphAgent provides two types for advanced routing beyond simple edges:
+`Send` for fan-out/fan-in (map-reduce) patterns, and `Command` for combining
+state updates with routing decisions.
+
+---
+
+## Send
+
+`GraphAgent::Send` dispatches work to a specific node with custom input. It is
+primarily used inside conditional edge functions to create **map-reduce**
+patterns.
+
+### Constructor
+
+```ruby
+GraphAgent::Send.new(node, arg)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `node` | String/Symbol | Target node name |
+| `arg` | Hash | State updates to apply before executing the target node |
+
+### Fan-Out (Map)
+
+Return an array of `Send` objects from a conditional edge to fan out work
+across multiple invocations of the same (or different) nodes:
+
+```ruby
+schema = GraphAgent::State::Schema.new do
+  field :subjects, type: Array, default: []
+  field :jokes, type: Array, reducer: GraphAgent::Reducers::ADD, default: []
+end
+
+graph = GraphAgent::Graph::StateGraph.new(schema)
+
+graph.add_node("get_subjects") do |state|
+  { subjects: ["cats", "dogs", "programming"] }
+end
+
+graph.add_node("generate_joke") do |state|
+  subject = state[:subjects].first
+  { jokes: ["Why did the #{subject} cross the road? ..."] }
+end
+
+fan_out = ->(state) do
+  state[:subjects].map do |subject|
+    GraphAgent::Send.new("generate_joke", { subjects: [subject] })
+  end
+end
+
+graph.add_edge(GraphAgent::START, "get_subjects")
+graph.add_conditional_edges("get_subjects", fan_out)
+graph.add_edge("generate_joke", GraphAgent::END_NODE)
+
+app = graph.compile
+result = app.invoke({})
+puts result[:jokes]
+```
+
+Each `Send` triggers a separate execution of `"generate_joke"` with a different
+subject. All results are aggregated back via the `:jokes` reducer.
+
+### Fan-In (Reduce)
+
+Fan-in happens automatically: all `Send` targets write to the same shared
+state, and reducers aggregate the results. You can also use
+[waiting edges](edges.md#waiting-edges-multi-source-synchronization) to
+synchronize before a downstream node.
+
+---
+
+## Command
+
+`GraphAgent::Command` combines a **state update** with a **routing decision**
+in a single return value from a node.
+
+### Constructor
+
+```ruby
+GraphAgent::Command.new(
+  graph: nil,        # reserved for subgraph routing
+  update: nil,       # Hash of state updates to apply
+  resume: nil,       # resume value (for interrupt workflows)
+  goto: []           # String, Symbol, Send, or Array thereof — next node(s)
+)
+```
+
+### Basic Usage
+
+Return a `Command` from a node to update state and route simultaneously:
+
+```ruby
+graph.add_node("router") do |state|
+  target = state[:intent] == "buy" ? "purchase" : "browse"
+  GraphAgent::Command.new(
+    update: { routed: true, route: target },
+    goto: target
+  )
+end
+```
+
+### Goto with Multiple Targets
+
+`goto` accepts an array to route to multiple nodes in the next step:
+
+```ruby
+graph.add_node("fork") do |state|
+  GraphAgent::Command.new(
+    goto: ["analyze", "log"]
+  )
+end
+```
+
+### Goto with Send
+
+You can mix `Send` objects in `goto` for dynamic fan-out:
+
+```ruby
+graph.add_node("dispatch") do |state|
+  sends = state[:tasks].map do |task|
+    GraphAgent::Send.new("worker", { current_task: task })
+  end
+  GraphAgent::Command.new(goto: sends)
+end
+```
+
+### Update Without Routing
+
+If you only need state updates (with routing handled by normal edges), use a
+plain Hash return instead of `Command`. Use `Command` specifically when you
+need the node to **control routing**.
+
+---
+
+## When to Use Command vs Conditional Edges
+
+| Use Case | Recommended |
+|----------|-------------|
+| Route based on state, node doesn't modify state | Conditional edge |
+| Route based on state **and** modify state atomically | `Command` |
+| Fan-out to multiple instances of the same node | `Send` via conditional edge |
+| Fan-out with per-instance state modifications | `Command` with `Send` in `goto` |
+| Simple sequential flow | Normal edge |
+
+### Command vs Conditional Edge Example
+
+**Conditional edge** — routing logic is separate from the node:
+
+```ruby
+graph.add_node("classify") do |state|
+  { category: detect_category(state[:input]) }
+end
+
+graph.add_conditional_edges("classify", ->(state) {
+  state[:category]
+}, { "a" => "handler_a", "b" => "handler_b" })
+```
+
+**Command** — routing logic is inside the node:
+
+```ruby
+graph.add_node("classify") do |state|
+  category = detect_category(state[:input])
+  GraphAgent::Command.new(
+    update: { category: category },
+    goto: "handler_#{category}"
+  )
+end
+
+# Still need outgoing edges for validation — use conditional edges
+# that won't actually be reached, or structure so that Command targets
+# are valid node names.
+```
+
+---
+
+## Complete Map-Reduce Example
+
+```ruby
+require "graph_agent"
+
+schema = GraphAgent::State::Schema.new do
+  field :urls, type: Array, default: []
+  field :pages, type: Array, reducer: GraphAgent::Reducers::ADD, default: []
+  field :summary, type: String
+end
+
+graph = GraphAgent::Graph::StateGraph.new(schema)
+
+graph.add_node("plan") do |state|
+  { urls: ["https://example.com/a", "https://example.com/b"] }
+end
+
+graph.add_node("fetch") do |state|
+  url = state[:urls].first
+  { pages: ["Content from #{url}"] }
+end
+
+graph.add_node("summarize") do |state|
+  { summary: "Summarized #{state[:pages].length} pages" }
+end
+
+fan_out_fetches = ->(state) do
+  state[:urls].map { |url| GraphAgent::Send.new("fetch", { urls: [url] }) }
+end
+
+graph.add_edge(GraphAgent::START, "plan")
+graph.add_conditional_edges("plan", fan_out_fetches)
+graph.add_edge("fetch", "summarize")
+graph.add_edge("summarize", GraphAgent::END_NODE)
+
+app = graph.compile
+result = app.invoke({})
+puts result[:summary]
+```

data/docs/state.md

@@ -0,0 +1,181 @@
+# State Management
+
+## Overview
+
+State is the shared data structure that every node reads from and writes to.
+GraphAgent applies updates atomically after each superstep using **reducers**.
+
+---
+
+## Defining State with Schema DSL
+
+Use `GraphAgent::State::Schema` with a block:
+
+```ruby
+schema = GraphAgent::State::Schema.new do
+  field :messages,   type: Array,   reducer: GraphAgent::Reducers::ADD, default: []
+  field :count,      type: Integer, reducer: GraphAgent::Reducers::ADD, default: 0
+  field :status,     type: String
+  field :metadata,   type: Hash,    reducer: GraphAgent::Reducers::MERGE, default: {}
+end
+```
+
+Each `field` call accepts:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | Symbol/String | Field name (converted to Symbol) |
+| `type:` | Class/nil | Optional type annotation (not enforced at runtime) |
+| `reducer:` | Proc/nil | Callable `(current, new) → merged`; nil means last-value semantics |
+| `default:` | Object/nil | Initial value; duplicated per invocation to avoid shared state |
+
+---
+
+## Defining State with Hash Shorthand
+
+Pass a Hash directly to `StateGraph.new` instead of a `Schema` object:
+
+```ruby
+graph = GraphAgent::Graph::StateGraph.new({
+  messages: { type: Array, reducer: ->(a, b) { a + b }, default: [] },
+  count: { type: Integer, reducer: ->(a, b) { a + b }, default: 0 },
+  status: {}  # last-value semantics, no default
+})
+```
+
+Each key becomes a field name. Values can be:
+
+- A **Hash** with `:type`, `:reducer`, `:default` keys (all optional).
+- Any non-Hash value is treated as a field with no options.
+
+---
+
+## Built-in Reducers
+
+Defined in `GraphAgent::Reducers`:
+
+| Reducer | Lambda | Behavior |
+|---------|--------|----------|
+| `ADD` | `(a, b) → a + b` | Concatenates arrays, adds numbers, joins strings |
+| `APPEND` | `(a, b) → Array(a) + Array(b)` | Wraps both sides in arrays then concatenates |
+| `MERGE` | `(a, b) → a.merge(b)` | Shallow-merges hashes |
+| `REPLACE` | `(_, b) → b` | Always replaces with the new value |
+
+### `add_messages`
+
+A special reducer for chat message lists. It matches messages by `:id` and
+replaces existing messages in-place; new messages (without matching IDs) are
+appended:
+
+```ruby
+field :messages, reducer: GraphAgent::Reducers.method(:add_messages), default: []
+```
+
+Example:
+
+```ruby
+existing = [
+  { id: "1", role: "user", content: "Hi" },
+  { id: "2", role: "ai", content: "Hello" }
+]
+
+new_msgs = [
+  { id: "2", role: "ai", content: "Hello! How can I help?" },  # updates id "2"
+  { id: "3", role: "user", content: "Tell me a joke" }          # appended
+]
+
+result = GraphAgent::Reducers.add_messages(existing, new_msgs)
+# => [
+#   { id: "1", role: "user", content: "Hi" },
+#   { id: "2", role: "ai", content: "Hello! How can I help?" },
+#   { id: "3", role: "user", content: "Tell me a joke" }
+# ]
+```
+
+---
+
+## Custom Reducers
+
+Any callable that takes two arguments works as a reducer:
+
+```ruby
+# Keep only the last N messages
+keep_last_10 = ->(existing, new_msgs) do
+  (Array(existing) + Array(new_msgs)).last(10)
+end
+
+schema = GraphAgent::State::Schema.new do
+  field :messages, reducer: keep_last_10, default: []
+end
+```
+
+```ruby
+# Union of sets
+set_union = ->(a, b) { (Array(a) | Array(b)) }
+
+schema = GraphAgent::State::Schema.new do
+  field :tags, reducer: set_union, default: []
+end
+```
+
+---
+
+## Initial State and Defaults
+
+When a graph is invoked, `Schema#initial_state` produces the starting state by
+duplicating each field's default value:
+
+```ruby
+schema = GraphAgent::State::Schema.new do
+  field :items, default: []
+  field :count, default: 0
+end
+
+schema.initial_state
+# => { items: [], count: 0 }
+```
+
+- Defaults are `.dup`'d to prevent shared mutation between invocations.
+- Fields without a default start as `nil`.
+- Input values passed to `invoke` are merged on top of the initial state.
+
+---
+
+## How Updates Are Applied
+
+After each superstep, the compiled graph calls `Schema#apply` (or the internal
+`_apply_updates` method) for every update returned by the nodes:
+
+```ruby
+# Pseudocode for one superstep:
+# 1. All nodes run on a frozen snapshot
+# 2. Collect updates: { "node_a" => { count: 1 }, "node_b" => { count: 2 } }
+# 3. For each update hash, for each key:
+#      if field has a reducer  → state[key] = reducer.call(state[key], value)
+#      else                    → state[key] = value   (last-value)
+```
+
+This means:
+
+- **With a reducer** (`ADD`), two nodes returning `{ count: 1 }` and `{ count: 2 }`
+  produce `count = 0 + 1 + 2 = 3` (assuming default 0).
+- **Without a reducer**, the last update wins (order depends on iteration of
+  the updates hash).
+
+---
+
+## Private / Input / Output Schemas
+
+`StateGraph` accepts `input_schema:` and `output_schema:` parameters:
+
+```ruby
+graph = GraphAgent::Graph::StateGraph.new(
+  full_schema,
+  input_schema: input_only_schema,
+  output_schema: output_only_schema
+)
+```
+
+These are stored on the builder for future use (e.g., input validation and
+output filtering) but are not yet enforced at runtime. The main `schema`
+parameter defines all fields the graph operates on.

data/docs/streaming.md

@@ -0,0 +1,172 @@
+# Streaming
+
+GraphAgent supports streaming intermediate results as the graph executes,
+instead of waiting for the final output.
+
+---
+
+## Stream Modes
+
+The `stream` method accepts a `stream_mode` parameter:
+
+| Mode | Yields | Description |
+|------|--------|-------------|
+| `:values` | Full state Hash | Emits the complete state after each superstep |
+| `:updates` | Per-node updates Hash | Emits only the changes each node produced |
+| `:debug` | Raw event Hash | Emits all internal events with type, step, state, and updates |
+
+---
+
+## stream_mode: :values
+
+Yields the full state after each superstep. This is the default mode.
+
+```ruby
+app.stream({ query: "hello" }, stream_mode: :values) do |state|
+  puts "Messages: #{state[:messages].length}"
+  puts "Status: #{state[:status]}"
+end
+```
+
+The final yield contains the complete output state (same as what `invoke`
+would return).
+
+---
+
+## stream_mode: :updates
+
+Yields only the updates produced by each node in the step:
+
+```ruby
+app.stream({ query: "hello" }, stream_mode: :updates) do |updates|
+  updates.each do |node_name, node_updates|
+    puts "#{node_name} produced: #{node_updates}"
+  end
+end
+```
+
+The updates hash maps node names (strings) to the Hash each node returned.
+
+---
+
+## stream_mode: :debug
+
+Yields raw event hashes with full internal detail:
+
+```ruby
+app.stream({ query: "hello" }, stream_mode: :debug) do |event|
+  case event[:type]
+  when :values
+    puts "Step #{event[:step]}: state = #{event[:state]}"
+  when :updates
+    puts "Step #{event[:step]}: updates = #{event[:updates]}"
+  end
+end
+```
+
+Event structure:
+
+```ruby
+{
+  type: :values | :updates,
+  step: Integer,
+  state: Hash,      # present for :values events
+  updates: Hash     # present for :updates events
+}
+```
+
+---
+
+## Using Block Form
+
+Pass a block to `stream` to process events as they arrive:
+
+```ruby
+app.stream(input, config: config, stream_mode: :values) do |state|
+  render_state(state)
+end
+```
+
+---
+
+## Using Enumerator (No Block)
+
+When called without a block, `stream` returns an `Enumerator`:
+
+```ruby
+events = app.stream(input, stream_mode: :values)
+
+events.each do |state|
+  puts state[:messages].last
+end
+```
+
+The `Enumerator` is lazy — events are produced as the graph executes. You can
+use standard Enumerable methods:
+
+```ruby
+# Get the first 3 states
+first_three = app.stream(input, stream_mode: :values).take(3)
+
+# Find the first state where processing is complete
+done = app.stream(input, stream_mode: :values).find { |s| s[:done] }
+```
+
+---
+
+## Streaming with Config
+
+All `stream` options from `invoke` are available:
+
+```ruby
+app.stream(
+  input,
+  config: { configurable: { thread_id: "t1" } },
+  recursion_limit: 50,
+  stream_mode: :updates
+) do |updates|
+  puts updates
+end
+```
+
+---
+
+## Complete Example
+
+```ruby
+require "graph_agent"
+
+schema = GraphAgent::State::Schema.new do
+  field :numbers, type: Array, default: []
+  field :sum, type: Integer, reducer: GraphAgent::Reducers::ADD, default: 0
+  field :step_name, type: String
+end
+
+graph = GraphAgent::Graph::StateGraph.new(schema)
+
+graph.add_node("add_evens") do |state|
+  evens = state[:numbers].select(&:even?)
+  { sum: evens.sum, step_name: "add_evens" }
+end
+
+graph.add_node("add_odds") do |state|
+  odds = state[:numbers].select(&:odd?)
+  { sum: odds.sum, step_name: "add_odds" }
+end
+
+graph.add_edge(GraphAgent::START, "add_evens")
+graph.add_edge("add_evens", "add_odds")
+graph.add_edge("add_odds", GraphAgent::END_NODE)
+
+app = graph.compile
+
+puts "=== :values mode ==="
+app.stream({ numbers: [1, 2, 3, 4, 5] }, stream_mode: :values) do |state|
+  puts "sum=#{state[:sum]} step=#{state[:step_name]}"
+end
+
+puts "\n=== :updates mode ==="
+app.stream({ numbers: [1, 2, 3, 4, 5] }, stream_mode: :updates) do |updates|
+  updates.each { |node, u| puts "#{node}: #{u}" }
+end
+```

data/graph-agent.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "lib/graph_agent/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "graph-agent"
+  spec.version       = GraphAgent::VERSION
+  spec.authors       = ["GraphAgent Contributors"]
+  spec.email         = ["richard.sun@ai-firstly.com"]
+  spec.summary       = "A Ruby framework for building stateful, multi-actor agent workflows"
+  spec.description   = "Ruby port of LangGraph - build stateful, multi-actor applications " \
+                       "with LLMs using a graph-based workflow engine with Pregel execution model"
+  spec.homepage      = "https://github.com/ai-firstly/graph-agent"
+  spec.license       = "MIT"
+  spec.required_ruby_version = [">= 3.1.0", "< 5.0"]
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ai-firstly/graph-agent"
+  spec.metadata["changelog_uri"] = "https://github.com/ai-firstly/graph-agent/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/graph-agent"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/ai-firstly/graph-agent/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    if File.exist?(".git")
+      `git ls-files -z`.split("\x0").reject do |f|
+        f.match(%r{\A(?:test|spec|features)/})
+      end
+    else
+      Dir.glob("**/*").reject do |f|
+        File.directory?(f) ||
+          f.match(%r{\A(?:test|spec|features)/}) ||
+          f.match(/\A\./) ||
+          f.match(/\.gem$/)
+      end
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "concurrent-ruby", "~> 1.2"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+end

data/lib/graph_agent/channels/base_channel.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  module Channels
+    class BaseChannel
+      MISSING = Object.new.freeze
+
+      attr_accessor :key
+
+      def initialize(key: "")
+        @key = key
+      end
+
+      def get
+        raise NotImplementedError.new("#{self.class}#get must be implemented")
+      end
+
+      def update(values)
+        raise NotImplementedError.new("#{self.class}#update must be implemented")
+      end
+
+      def checkpoint
+        get
+      rescue EmptyChannelError
+        MISSING
+      end
+
+      def from_checkpoint(checkpoint)
+        raise NotImplementedError.new("#{self.class}#from_checkpoint must be implemented")
+      end
+
+      def available?
+        get
+        true
+      rescue EmptyChannelError
+        false
+      end
+
+      def consume
+        false
+      end
+
+      def finish
+        false
+      end
+
+      def copy
+        from_checkpoint(checkpoint)
+      end
+    end
+  end
+end