langgraph_rb 0.1.0 → 0.1.2

data/lib/langgraph_rb/observers/logger.rb

@@ -0,0 +1,71 @@
+require 'logger'
+
+module LangGraphRB
+  module Observers
+    # File and stdout logging observer
+    class LoggerObserver < BaseObserver
+      def initialize(logger: nil, level: :info, format: :text)
+        @logger = logger || Logger.new($stdout)
+        @level = level
+        @format = format
+        @logger.level = Logger.const_get(level.to_s.upcase)
+      end
+
+      def on_graph_start(event)
+        log(:info, "Graph execution started", event.to_h)
+      end
+
+      def on_graph_end(event)
+        log(:info, "Graph execution completed", event.to_h)
+      end
+
+      def on_node_start(event)
+        log(:debug, "Node execution started: #{event.node_name}", event.to_h)
+      end
+
+      def on_node_end(event)
+        duration_ms = event.duration ? (event.duration * 1000).round(2) : 'unknown'
+        log(:info, "Node completed: #{event.node_name} (#{duration_ms}ms)", event.to_h)
+      end
+
+      def on_node_error(event)
+        log(:error, "Node error: #{event.node_name} - #{event.error&.message}", event.to_h)
+      end
+
+      def on_step_complete(event)
+        log(:debug, "Step #{event.step_number} completed with #{event.completed_nodes.length} nodes", event.to_h)
+      end
+
+      def on_interrupt(event)
+        log(:warn, "Execution interrupted: #{event[:message]}", event)
+      end
+
+      private
+
+      def log(level, message, data)
+        case @format
+        when :json
+          @logger.send(level, { message: message, data: sanitize_data(data) }.to_json)
+        else
+          @logger.send(level, "#{message} | #{format_data(data)}")
+        end
+      end
+
+      def format_data(data)
+        relevant_fields = data.select { |k, v| [:thread_id, :step_number, :node_name, :duration_ms].include?(k) && v }
+        relevant_fields.map { |k, v| "#{k}=#{v}" }.join(" ")
+      end
+
+      def sanitize_data(data)
+        data.transform_values do |value|
+          case value
+          when Hash
+            sanitize_state(value, max_size: 500)
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end 

data/lib/langgraph_rb/observers/structured.rb

@@ -0,0 +1,111 @@
+require 'json'
+
+module LangGraphRB
+  module Observers
+    # Structured data observer for APM/monitoring integration
+    class StructuredObserver < BaseObserver
+      def initialize(sink: nil, format: :json, include_state: false, async: false)
+        @sink = sink || $stdout
+        @format = format
+        @include_state = include_state
+        @async = async
+        @event_queue = async ? Queue.new : nil
+        @worker_thread = start_worker_thread if async
+      end
+
+      def on_graph_start(event)
+        emit_event(:graph_start, event.to_h)
+      end
+
+      def on_graph_end(event)
+        emit_event(:graph_end, event.to_h)
+      end
+
+      def on_node_start(event)
+        emit_event(:node_start, sanitize_event(event.to_h))
+      end
+
+      def on_node_end(event)
+        emit_event(:node_end, sanitize_event(event.to_h))
+      end
+
+      def on_node_error(event)
+        emit_event(:node_error, sanitize_event(event.to_h))
+      end
+
+      def on_step_complete(event)
+        emit_event(:step_complete, sanitize_event(event.to_h))
+      end
+
+      def on_command_processed(event)
+        emit_event(:command_processed, event)
+      end
+
+      def shutdown
+        if @async && @worker_thread
+          @event_queue << :shutdown
+          @worker_thread.join
+        end
+      end
+
+      private
+
+      def emit_event(type, data)
+        event = {
+          event_type: type,
+          timestamp: Time.now.utc.iso8601,
+          **data
+        }
+
+        if @async
+          @event_queue << event
+        else
+          write_event(event)
+        end
+      end
+
+      def write_event(event)
+        case @format
+        when :json
+          @sink.puts(JSON.generate(event))
+        when :ndjson
+          @sink.puts(JSON.generate(event))
+        else
+          @sink.puts(event.inspect)
+        end
+        
+        @sink.flush if @sink.respond_to?(:flush)
+      end
+
+      def sanitize_event(event_data)
+        result = event_data.dup
+        
+        unless @include_state
+          result.delete(:state_before)
+          result.delete(:state_after)
+          result.delete(:state)
+        else
+          result[:state_before] = sanitize_state(result[:state_before]) if result[:state_before]
+          result[:state_after] = sanitize_state(result[:state_after]) if result[:state_after]
+          result[:state] = sanitize_state(result[:state]) if result[:state]
+        end
+        
+        result
+      end
+
+      def start_worker_thread
+        Thread.new do
+          loop do
+            event = @event_queue.pop
+            break if event == :shutdown
+            
+            write_event(event)
+          rescue => e
+            # Log error but continue processing
+            $stderr.puts "Observer error: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end 

data/lib/langgraph_rb/runner.rb

@@ -1,16 +1,19 @@
 require 'thread'
+require 'json'
+require 'time'
 
 module LangGraphRB
   class Runner
     attr_reader :graph, :store, :thread_id
 
-    def initialize(graph, store:, thread_id:)
+    def initialize(graph, store:, thread_id:, observers: [])
       @graph = graph
       @store = store
       @thread_id = thread_id
       @step_number = 0
       @execution_queue = Queue.new
       @interrupt_handler = nil
+      @observers = Array(observers)
     end
 
     # Synchronous execution
@@ -26,6 +29,8 @@ module LangGraphRB
 
     # Streaming execution with optional block for receiving intermediate results
     def stream(initial_state, context: nil, &block)
+      notify_graph_start(initial_state, context)
+      
       @step_number = 0
       current_state = initial_state
       
@@ -59,7 +64,7 @@ module LangGraphRB
               if dest_name == Graph::FINISH
                 final_state = dest_state
               else
-                next_active << ExecutionFrame.new(dest_name, dest_state, @step_number)
+                next_active << ExecutionFrame.new(dest_name, dest_state, @step_number, from_node: result[:node_name])
               end
             else
               # Use normal edge routing
@@ -73,7 +78,7 @@ module LangGraphRB
                 if dest_name == Graph::FINISH
                   final_state = dest_state
                 else
-                  next_active << ExecutionFrame.new(dest_name, dest_state, @step_number)
+                  next_active << ExecutionFrame.new(dest_name, dest_state, @step_number, from_node: result[:node_name])
                 end
               end
             end
@@ -82,7 +87,7 @@ module LangGraphRB
             # Handle Send commands (map-reduce)
             result[:sends].each do |send_cmd|
               payload_state = result[:state].merge_delta(send_cmd.payload)
-              next_active << ExecutionFrame.new(send_cmd.to, payload_state, @step_number)
+              next_active << ExecutionFrame.new(send_cmd.to, payload_state, @step_number, from_node: result[:node_name])
             end
             
           when :interrupt
@@ -91,7 +96,7 @@ module LangGraphRB
               user_input = @interrupt_handler.call(result[:interrupt])
               # Continue with user input merged into state
               updated_state = result[:state].merge_delta(user_input || {})
-              next_active << ExecutionFrame.new(result[:node_name], updated_state, @step_number)
+              next_active << ExecutionFrame.new(result[:node_name], updated_state, @step_number, from_node: result[:node_name])
             else
               # No interrupt handler, treat as completion
               final_state = result[:state]
@@ -124,11 +129,17 @@ module LangGraphRB
         break if final_state
       end
       
-      {
+      result = {
         state: current_state,
         step_number: @step_number,
         thread_id: @thread_id
       }
+      
+      notify_graph_end(current_state)
+      result
+    rescue => error
+      notify_graph_end(current_state || initial_state)
+      raise
     end
 
     # Resume from checkpoint
@@ -150,6 +161,82 @@ module LangGraphRB
 
     private
 
+    def notify_observers(method, event)
+      @observers.each do |observer|
+        begin
+          observer.send(method, event)
+        rescue => e
+          # Log observer errors but don't fail execution
+          $stderr.puts "Observer error in #{observer.class}##{method}: #{e.message}"
+        end
+      end
+    end
+
+    def notify_graph_start(initial_state, context)
+      event = Observers::GraphEvent.new(
+        type: :start,
+        graph: @graph,
+        initial_state: initial_state,
+        context: context,
+        thread_id: @thread_id
+      )
+      notify_observers(:on_graph_start, event)
+    end
+
+    def notify_graph_end(final_state)
+      event = Observers::GraphEvent.new(
+        type: :end,
+        graph: @graph,
+        initial_state: final_state,
+        thread_id: @thread_id
+      )
+      notify_observers(:on_graph_end, event)
+    end
+
+    def notify_node_start(node, state, context, from_node: nil)
+      event = Observers::NodeEvent.new(
+        type: :start,
+        node_name: node.name,
+        node_class: node.class,
+        state_before: state,
+        context: context,
+        thread_id: @thread_id,
+        step_number: @step_number,
+        from_node: from_node
+      )
+      notify_observers(:on_node_start, event)
+    end
+
+    def notify_node_end(node, state_before, state_after, result, duration, from_node: nil)
+      event = Observers::NodeEvent.new(
+        type: :end,
+        node_name: node.name,
+        node_class: node.class,
+        state_before: state_before,
+        state_after: state_after,
+        result: result,
+        duration: duration,
+        thread_id: @thread_id,
+        step_number: @step_number,
+        from_node: from_node
+      )
+      notify_observers(:on_node_end, event)
+    end
+
+    def notify_node_error(node, state, error, from_node: nil)
+      event = Observers::NodeEvent.new(
+        type: :error,
+        node_name: node.name,
+        node_class: node.class,
+        state_before: state,
+        error: error,
+        thread_id: @thread_id,
+        step_number: @step_number,
+        from_node: from_node
+      )
+      notify_observers(:on_node_error, event)
+    end
+
     # Execute all nodes in the current super-step in parallel
     def execute_super_step(active_executions, context)
       return [] if active_executions.empty?
@@ -167,7 +254,7 @@ module LangGraphRB
         # Execute each frame for this node
         executions.each do |frame|
           thread = Thread.new do
-            execute_node_safely(node, frame.state, context, frame.step)
+            execute_node_safely(node, frame.state, context, frame.step, from_node: frame.from_node)
           end
           threads << thread
         end
@@ -183,11 +270,30 @@ module LangGraphRB
     end
 
     # Safely execute a single node
-    def execute_node_safely(node, state, context, step)
+    def execute_node_safely(node, state, context, step, from_node: nil)
+      notify_node_start(node, state, context, from_node: from_node)
+      
+      start_time = Time.now
       begin
         result = node.call(state, context: context)
-        process_node_result(node.name, state, result, step)
+        duration = Time.now - start_time
+        
+        processed_result = process_node_result(node.name, state, result, step)
+        
+        # Extract final state from processed result
+        final_state = case processed_result[:type]
+                     when :completed
+                       processed_result[:state]
+                     else
+                       state
+                     end
+        
+        notify_node_end(node, state, final_state, result, duration, from_node: from_node)
+        processed_result
       rescue => error
+        duration = Time.now - start_time
+        notify_node_error(node, state, error, from_node: from_node)
+        
         {
           type: :error,
           node_name: node.name,
@@ -318,16 +424,17 @@ module LangGraphRB
 
     # Execution frame for tracking active node executions
     class ExecutionFrame
-      attr_reader :node_name, :state, :step
+      attr_reader :node_name, :state, :step, :from_node
 
-      def initialize(node_name, state, step)
+      def initialize(node_name, state, step, from_node: nil)
         @node_name = node_name.to_sym
         @state = state
         @step = step
+        @from_node = from_node
       end
 
       def to_s
-        "#<ExecutionFrame node: #{@node_name}, step: #{@step}>"
+        "#<ExecutionFrame node: #{@node_name}, step: #{@step}, from: #{@from_node}>"
       end
     end
   end

data/lib/langgraph_rb/version.rb

@@ -1,3 +1,3 @@
 module LangGraphRB
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end 

data/lib/langgraph_rb.rb

@@ -6,10 +6,14 @@ require_relative 'langgraph_rb/command'
 require_relative 'langgraph_rb/graph'
 require_relative 'langgraph_rb/runner'
 require_relative 'langgraph_rb/stores/memory'
+require_relative 'langgraph_rb/observers/base'
+require_relative 'langgraph_rb/observers/logger'
+require_relative 'langgraph_rb/observers/structured'
 
 module LangGraphRB
   class Error < StandardError; end
   class GraphError < Error; end
   class NodeError < Error; end
   class StateError < Error; end
+  class ObserverError < Error; end
 end 

data/test_runner.rb

@@ -67,18 +67,18 @@ routing_graph = LangGraphRB::Graph.new do
     { message: "Number #{state[:number]} is positive!" }
   end
   
-  node :negative_handler do |state|
+  node :generate_sql do |state|
     { message: "Number #{state[:number]} is negative or zero!" }
   end
   
   set_entry_point :check_number
   
   conditional_edge :check_number, ->(state) {
-    state[:is_positive] ? :positive_handler : :negative_handler
+    state[:is_positive] ? :positive_handler : :generate_sql
   }
   
   set_finish_point :positive_handler
-  set_finish_point :negative_handler
+  set_finish_point :generate_sql
 end
 
 routing_graph.compile!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langgraph_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Julian Toro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-29 00:00:00.000000000 Z
+date: 2025-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -104,11 +104,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
 - Gemfile
 - README.md
 - SUMMARY.md
 - examples/advanced_example.rb
 - examples/basic_example.rb
+- examples/initial_state_example.rb
+- examples/observer_example.rb
+- examples/reducers_example.rb
 - examples/simple_test.rb
 - langgraph_rb.gemspec
 - lib/langgraph_rb.rb
@@ -116,6 +120,9 @@ files:
 - lib/langgraph_rb/edge.rb
 - lib/langgraph_rb/graph.rb
 - lib/langgraph_rb/node.rb
+- lib/langgraph_rb/observers/base.rb
+- lib/langgraph_rb/observers/logger.rb
+- lib/langgraph_rb/observers/structured.rb
 - lib/langgraph_rb/runner.rb
 - lib/langgraph_rb/state.rb
 - lib/langgraph_rb/stores/memory.rb