graph-agent 0.1.0

data/lib/graph_agent/graph/state_graph.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "mermaid_visualizer"
+
+module GraphAgent
+  module Graph
+    class StateGraph
+      attr_reader :schema, :nodes, :edges, :branches, :waiting_edges
+
+      def initialize(schema = nil, input_schema: nil, output_schema: nil)
+        @schema = _normalize_schema(schema)
+        @input_schema = input_schema ? _normalize_schema(input_schema) : nil
+        @output_schema = output_schema ? _normalize_schema(output_schema) : nil
+        @nodes = {}
+        @edges = Set.new
+        @branches = Hash.new { |h, k| h[k] = {} }
+        @waiting_edges = Set.new
+      end
+
+      def add_node(name, action = nil, metadata: nil, retry_policy: nil, cache_policy: nil, &block)
+        action = block if block && action.nil?
+        name = _get_node_name(name, action)
+
+        raise InvalidGraphError.new("Node action must be provided") if action.nil?
+        raise InvalidGraphError.new("Node '#{name}' already exists") if @nodes.key?(name)
+        raise InvalidGraphError.new("Node name '#{name}' is reserved") if [END_NODE.to_s, START.to_s].include?(name)
+
+        @nodes[name] = Node.new(
+          name, action,
+          metadata: metadata,
+          retry_policy: retry_policy,
+          cache_policy: cache_policy
+        )
+        self
+      end
+
+      def add_edge(start_key, end_key)
+        if start_key.is_a?(Array)
+          targets = start_key.map(&:to_s)
+          @waiting_edges.add([targets, end_key.to_s])
+          return self
+        end
+
+        start_key = start_key.to_s
+        end_key = end_key.to_s
+
+        raise InvalidGraphError.new("END cannot be a start node") if start_key == END_NODE.to_s
+        raise InvalidGraphError.new("START cannot be an end node") if end_key == START.to_s
+
+        @edges.add(Edge.new(start_key, end_key))
+        self
+      end
+
+      def add_conditional_edges(source, path, path_map = nil)
+        source = source.to_s
+        name = _branch_name(path)
+
+        if @branches[source].key?(name)
+          raise InvalidGraphError.new("Branch '#{name}' already exists for node '#{source}'")
+        end
+
+        @branches[source][name] = ConditionalEdge.new(source, path, path_map: path_map)
+        self
+      end
+
+      def add_sequence(nodes)
+        node_names = nodes.map do |node|
+          if node.is_a?(Array)
+            name, action = node
+            add_node(name, action)
+            name.to_s
+          elsif node.respond_to?(:call)
+            name = _get_node_name(nil, node)
+            add_node(name, node)
+            name
+          else
+            node.to_s
+          end
+        end
+
+        node_names.each_cons(2) { |a, b| add_edge(a, b) }
+        self
+      end
+
+      def set_entry_point(node_name)
+        add_edge(START, node_name)
+      end
+
+      def set_finish_point(node_name)
+        add_edge(node_name, END_NODE)
+      end
+
+      def set_conditional_entry_point(path, path_map = nil)
+        add_conditional_edges(START, path, path_map)
+      end
+
+      def compile(checkpointer: nil, interrupt_before: nil, interrupt_after: nil, debug: false)
+        validate!
+
+        CompiledStateGraph.new(
+          builder: self,
+          checkpointer: checkpointer,
+          interrupt_before: interrupt_before || [],
+          interrupt_after: interrupt_after || [],
+          debug: debug
+        )
+      end
+
+      # Generate a Mermaid diagram representation of the graph
+      def to_mermaid(options = {})
+        MermaidVisualizer.render(self, options)
+      end
+
+      # Print Mermaid diagram to stdout
+      def print_mermaid(options = {})
+        puts to_mermaid(options)
+      end
+
+      private
+
+      def _normalize_schema(schema)
+        case schema
+        when State::Schema then schema
+        when Hash          then _schema_from_hash(schema)
+        when nil           then nil
+        end
+      end
+
+      def _schema_from_hash(hash)
+        s = State::Schema.new
+        hash.each do |name, opts|
+          opts.is_a?(Hash) ? s.field(name, **opts) : s.field(name)
+        end
+        s
+      end
+
+      def _get_node_name(name, action)
+        return name.to_s if name
+
+        if action.respond_to?(:name) && !action.name.nil? && !action.name.empty?
+          action.name.split("::").last.gsub(/[^a-zA-Z0-9_]/, "_")
+        else
+          raise InvalidGraphError.new("Node name must be provided")
+        end
+      end
+
+      def _branch_name(path)
+        if path.respond_to?(:name) && path.name && !path.name.empty?
+          path.name
+        else
+          "condition_#{@branches.values.sum(&:size)}"
+        end
+      end
+
+      def validate!
+        _validate_entry_point!
+        _validate_edges!
+        _validate_outgoing_edges!
+      end
+
+      def _validate_entry_point!
+        entry_edges = @edges.any? { |e| e.source == START.to_s }
+        entry_branches = @branches[START.to_s]&.any?
+
+        return if entry_edges || entry_branches
+
+        raise InvalidGraphError.new("Graph must have an entry point. Use set_entry_point or add_edge(START, ...)")
+      end
+
+      def _validate_edges!
+        sentinel = [START.to_s, END_NODE.to_s]
+        @edges.each do |edge|
+          next if sentinel.include?(edge.source)
+
+          unless @nodes.key?(edge.source)
+            raise InvalidGraphError.new("Edge references unknown source node '#{edge.source}'")
+          end
+
+          next if edge.target == END_NODE.to_s
+
+          unless @nodes.key?(edge.target)
+            raise InvalidGraphError.new("Edge references unknown target node '#{edge.target}'")
+          end
+        end
+      end
+
+      def _validate_outgoing_edges!
+        @nodes.each_key do |name|
+          has_outgoing = @edges.any? { |e| e.source == name } ||
+                         (@branches.key?(name) && !@branches[name].empty?)
+
+          raise InvalidGraphError.new("Node '#{name}' has no outgoing edges") unless has_outgoing
+        end
+      end
+    end
+  end
+end

data/lib/graph_agent/reducers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  module Reducers
+    ADD = ->(a, b) { a + b }
+    MERGE = ->(a, b) { a.merge(b) }
+    REPLACE = ->(_, b) { b }
+    APPEND = ->(a, b) { Array(a) + Array(b) }
+
+    module_function
+
+    def add_messages(existing, new_messages)
+      existing = Array(existing)
+      new_messages = Array(new_messages)
+
+      existing_by_id = {}
+      existing.each_with_index do |msg, idx|
+        if msg.is_a?(Hash) && msg[:id]
+          existing_by_id[msg[:id]] = idx
+        end
+      end
+
+      result = existing.dup
+      new_messages.each do |msg|
+        if msg.is_a?(Hash) && msg[:id] && existing_by_id.key?(msg[:id])
+          result[existing_by_id[msg[:id]]] = msg
+        else
+          result << msg
+        end
+      end
+      result
+    end
+  end
+end

data/lib/graph_agent/state/schema.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  module State
+    class Schema
+      attr_reader :fields
+
+      Field = Data.define(:name, :type, :reducer, :default)
+
+      def initialize(&block)
+        @fields = {}
+        instance_eval(&block) if block
+      end
+
+      def field(name, type: nil, reducer: nil, default: nil)
+        @fields[name.to_sym] = Field.new(
+          name: name.to_sym,
+          type: type,
+          reducer: reducer,
+          default: default
+        )
+      end
+
+      def initial_state
+        @fields.transform_values do |f|
+          if f.default.nil?
+            nil
+          elsif f.default.respond_to?(:dup)
+            begin
+              f.default.dup
+            rescue TypeError
+              f.default
+            end
+          else
+            f.default
+          end
+        end
+      end
+
+      def apply(state, updates)
+        updates.each do |key, value|
+          key = key.to_sym
+          f = @fields[key]
+          if f&.reducer
+            state[key] = f.reducer.call(state[key], value)
+          else
+            state[key] = value
+          end
+        end
+        state
+      end
+    end
+  end
+end

data/lib/graph_agent/types/cache_policy.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  class CachePolicy
+    attr_reader :key_func, :ttl
+
+    def initialize(key_func: nil, ttl: nil)
+      @key_func = key_func
+      @ttl = ttl
+    end
+  end
+end

data/lib/graph_agent/types/command.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  class Command
+    PARENT = :__parent__
+
+    attr_reader :graph, :update, :resume, :goto
+
+    def initialize(graph: nil, update: nil, resume: nil, goto: [])
+      @graph = graph
+      @update = update
+      @resume = resume
+      @goto = Array(goto)
+    end
+
+    def to_s
+      parts = []
+      parts << "graph=#{graph.inspect}" if graph
+      parts << "update=#{update.inspect}" if update
+      parts << "resume=#{resume.inspect}" if resume
+      parts << "goto=#{goto.inspect}" unless goto.empty?
+      "Command(#{parts.join(", ")})"
+    end
+    alias inspect to_s
+  end
+end

data/lib/graph_agent/types/interrupt.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module GraphAgent
+  class Interrupt
+    attr_reader :value, :id
+
+    def initialize(value, id: nil)
+      @value = value
+      @id = id || SecureRandom.hex(16)
+    end
+
+    def ==(other)
+      other.is_a?(Interrupt) && id == other.id && value == other.value
+    end
+    alias eql? ==
+
+    def hash
+      [id, value].hash
+    end
+
+    def to_s
+      "Interrupt(value=#{value.inspect}, id=#{id.inspect})"
+    end
+    alias inspect to_s
+  end
+end

data/lib/graph_agent/types/retry_policy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  class RetryPolicy
+    attr_reader :initial_interval, :backoff_factor, :max_interval,
+                :max_attempts, :jitter, :retry_on
+
+    def initialize(
+      initial_interval: 0.5,
+      backoff_factor: 2.0,
+      max_interval: 128.0,
+      max_attempts: 3,
+      jitter: true,
+      retry_on: StandardError
+    )
+      @initial_interval = initial_interval
+      @backoff_factor = backoff_factor
+      @max_interval = max_interval
+      @max_attempts = max_attempts
+      @jitter = jitter
+      @retry_on = retry_on
+    end
+
+    def should_retry?(error)
+      case @retry_on
+      when Proc
+        @retry_on.call(error)
+      when Array
+        @retry_on.any? { |klass| error.is_a?(klass) }
+      else
+        error.is_a?(@retry_on)
+      end
+    end
+
+    def interval_for(attempt)
+      interval = @initial_interval * (@backoff_factor**attempt)
+      interval = [interval, @max_interval].min
+      interval += rand * interval * 0.1 if @jitter
+      interval
+    end
+  end
+end

data/lib/graph_agent/types/send.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  class Send
+    attr_reader :node, :arg
+
+    def initialize(node, arg)
+      @node = node.to_s
+      @arg = arg
+    end
+
+    def ==(other)
+      other.is_a?(Send) && node == other.node && arg == other.arg
+    end
+    alias eql? ==
+
+    def hash
+      [node, arg].hash
+    end
+
+    def to_s
+      "Send(node=#{node.inspect}, arg=#{arg.inspect})"
+    end
+    alias inspect to_s
+  end
+end

data/lib/graph_agent/types/state_snapshot.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  class StateSnapshot
+    attr_reader :values, :next_nodes, :config, :metadata,
+                :created_at, :parent_config, :tasks, :interrupts
+
+    def initialize(
+      values:,
+      next_nodes: [],
+      config: {},
+      metadata: nil,
+      created_at: nil,
+      parent_config: nil,
+      tasks: [],
+      interrupts: []
+    )
+      @values = values
+      @next_nodes = Array(next_nodes)
+      @config = config
+      @metadata = metadata
+      @created_at = created_at
+      @parent_config = parent_config
+      @tasks = Array(tasks)
+      @interrupts = Array(interrupts)
+    end
+  end
+end

data/lib/graph_agent/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GraphAgent
+  VERSION = '0.1.0'
+end

data/lib/graph_agent.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "graph_agent/version"
+require_relative "graph_agent/constants"
+require_relative "graph_agent/errors"
+require_relative "graph_agent/reducers"
+require_relative "graph_agent/state/schema"
+require_relative "graph_agent/channels/base_channel"
+require_relative "graph_agent/channels/last_value"
+require_relative "graph_agent/channels/binary_operator_aggregate"
+require_relative "graph_agent/channels/ephemeral_value"
+require_relative "graph_agent/channels/topic"
+require_relative "graph_agent/types/send"
+require_relative "graph_agent/types/command"
+require_relative "graph_agent/types/retry_policy"
+require_relative "graph_agent/types/cache_policy"
+require_relative "graph_agent/types/interrupt"
+require_relative "graph_agent/types/state_snapshot"
+require_relative "graph_agent/checkpoint/base_saver"
+require_relative "graph_agent/checkpoint/in_memory_saver"
+require_relative "graph_agent/graph/node"
+require_relative "graph_agent/graph/edge"
+require_relative "graph_agent/graph/conditional_edge"
+require_relative "graph_agent/graph/state_graph"
+require_relative "graph_agent/graph/compiled_state_graph"
+require_relative "graph_agent/graph/message_graph"
+
+module GraphAgent
+end

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: graph-agent
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- GraphAgent Contributors
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: Ruby port of LangGraph - build stateful, multi-actor applications with
+  LLMs using a graph-based workflow engine with Pregel execution model
+email:
+- richard.sun@ai-firstly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- Makefile
+- README.md
+- Rakefile
+- docs/README.md
+- docs/api_reference.md
+- docs/concepts.md
+- docs/edges.md
+- docs/error_handling.md
+- docs/human_in_the_loop.md
+- docs/persistence.md
+- docs/quickstart.md
+- docs/send_and_command.md
+- docs/state.md
+- docs/streaming.md
+- graph-agent.gemspec
+- lib/graph_agent.rb
+- lib/graph_agent/channels/base_channel.rb
+- lib/graph_agent/channels/binary_operator_aggregate.rb
+- lib/graph_agent/channels/ephemeral_value.rb
+- lib/graph_agent/channels/last_value.rb
+- lib/graph_agent/channels/topic.rb
+- lib/graph_agent/checkpoint/base_saver.rb
+- lib/graph_agent/checkpoint/in_memory_saver.rb
+- lib/graph_agent/constants.rb
+- lib/graph_agent/errors.rb
+- lib/graph_agent/graph/compiled_state_graph.rb
+- lib/graph_agent/graph/conditional_edge.rb
+- lib/graph_agent/graph/edge.rb
+- lib/graph_agent/graph/mermaid_visualizer.rb
+- lib/graph_agent/graph/message_graph.rb
+- lib/graph_agent/graph/node.rb
+- lib/graph_agent/graph/state_graph.rb
+- lib/graph_agent/reducers.rb
+- lib/graph_agent/state/schema.rb
+- lib/graph_agent/types/cache_policy.rb
+- lib/graph_agent/types/command.rb
+- lib/graph_agent/types/interrupt.rb
+- lib/graph_agent/types/retry_policy.rb
+- lib/graph_agent/types/send.rb
+- lib/graph_agent/types/state_snapshot.rb
+- lib/graph_agent/version.rb
+homepage: https://github.com/ai-firstly/graph-agent
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ai-firstly/graph-agent
+  source_code_uri: https://github.com/ai-firstly/graph-agent
+  changelog_uri: https://github.com/ai-firstly/graph-agent/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/graph-agent
+  bug_tracker_uri: https://github.com/ai-firstly/graph-agent/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '5.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Ruby framework for building stateful, multi-actor agent workflows
+test_files: []