langgraph_rb 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c2d260c430ce9be20fea65d6dff4d8013a535a6db46cdd89e15b19200c8b6dd
-  data.tar.gz: a5213444bbf90954158836c6e73237752ecc2d689e0e4de4807621edb2460f44
+  metadata.gz: 7629f7f9d5f4778ec860440939aa791d896fe0db95dc4d2b454aa06b4f6e6986
+  data.tar.gz: 1e607cbc2ea8238f8d06228572e8fc782d61fc68a1999310e0180da1e490a36a
 SHA512:
-  metadata.gz: ce7b663fb858e5c2adea131d21682df32eddc0cbb72b324773fa0b1cf932338c105d155e7b7b046556748e9f5d60342b9171537a21e1f41c7f7e4933499968cb
-  data.tar.gz: e30e5ad223be3a455361f753b44ba928054eff285429ca0a8c73474eb851eb9c6c59c627357010032d5133d8ba9d891669225e3640aea5873017910724766536
+  metadata.gz: 3bb81a69fbe5288500d87b7d166365f4fbebd6469c234ba3772e06e22ce685e1bd5aa07a649931e01b2799132071c69e9afb319781c5c0c5da7a7ba86424a197
+  data.tar.gz: 83f0fc66a0309602c334be73ab07d3352cc537f82b5942c23983bc4b0ea343f4f50f81c5e1055b7cad32f5dbea69bc5a3654dd8a4229e71cbd3b13383c9faaf8

data/.gitignore

@@ -7,4 +7,5 @@ vendor/bundle/
 .ruby-version
 .byebug_history
 coverage/
-*.log
+*.log
+.env

data/Gemfile

@@ -6,4 +6,5 @@ group :development, :test do
   gem 'rspec', '~> 3.0'
   gem 'pry', '~> 0.14'
   gem 'rubocop', '~> 1.0'
+  gem 'langfuse', '~> 0.1'
 end 

data/Gemfile.lock

@@ -0,0 +1,80 @@
+PATH
+  remote: .
+  specs:
+    langgraph_rb (0.1.2)
+      json (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.5)
+    diff-lcs (1.6.2)
+    json (2.13.2)
+    langfuse (0.1.1)
+      concurrent-ruby (~> 1.2)
+      sorbet-runtime (~> 0.5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    method_source (1.1.0)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.11.1)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    rubocop (1.79.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.46.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    sorbet-runtime (0.6.12534)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+
+PLATFORMS
+  arm64-darwin-22
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  langfuse (~> 0.1)
+  langgraph_rb!
+  pry (~> 0.14)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.0)
+
+BUNDLED WITH
+   2.6.7

data/examples/langfuse_example.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+require 'langfuse'
+require_relative '../lib/langgraph_rb'
+
+url = 'https://us.cloud.langfuse.com'
+
+Langfuse.configure do |config|
+    config.public_key = ENV['LANGFUSE_PUBLIC_KEY']  # e.g., 'pk-lf-...'
+    config.secret_key = ENV['LANGFUSE_SECRET_KEY']  # e.g., 'sk-lf-...'
+    config.host = url
+    config.debug = true # Enable debug logging
+end
+
+
+class LangfuseObserver < LangGraphRB::Observers::BaseObserver
+
+    def on_graph_start(event)
+        @trace ||= Langfuse.trace(
+            name: "graph-start2",
+            thread_id: event.thread_id,
+            metadata: event.to_h
+        )
+    end
+
+    def on_node_end(event)
+        span = Langfuse.span(
+            name: "node-#{event.node_name}",
+            trace_id: @trace.id,
+            input: event.to_h,            
+        )
+        Langfuse.update_span(span)        
+    end
+end
+
+
+def langfuse_example
+  puts "########################################################"
+  puts "########################################################"
+  puts "########################################################"
+  puts "=== Langfuse Example ==="
+  
+  # Create a simple graph for demonstration
+
+  graph = LangGraphRB::Graph.new(state_class: LangGraphRB::State) do
+    node :process_message do |state|
+        sleep(Random.rand(0.1..0.5))
+      { message: "Processed: #{state[:message]}" }
+    end
+    
+    conditional_edge :process_message, -> (state) { 
+        sleep(Random.rand(0.1..0.5))
+      if state[:value] > 0 and state[:value] < 10
+        puts "Processed between 0 and 10"
+        return :process_between_0_and_10
+      elsif state[:value] > 10
+        puts "Processed greater than 10"
+        return :process_greater_than_10
+      else
+        puts "Processed less than 0"
+        return :process_less_than_0
+      end
+    }
+
+    node :process_between_0_and_10 do |state|
+      { message: "Processed between 0 and 10: #{state[:message]}" }      
+    end
+
+    node :process_greater_than_10 do |state|
+      { message: "Processed greater than 10: #{state[:message]}" }
+    end
+
+    node :process_less_than_0 do |state|
+      { message: "Processed less than 0: #{state[:message]}" }
+    end
+
+    set_entry_point :process_message    
+    set_finish_point :process_between_0_and_10
+    set_finish_point :process_greater_than_10
+    set_finish_point :process_less_than_0
+  end
+
+  
+  
+  graph.compile!
+  result = graph.invoke({ message: "Hello World", value:  31}, observers: [LangfuseObserver.new])
+  puts "Result: #{result}"
+  puts "########################################################"
+  puts "########################################################"
+  puts "########################################################"
+  puts "########################################################"
+end
+
+langfuse_example
+

data/examples/llmnode_example.rb

@@ -0,0 +1,210 @@
+#!/usr/bin/env ruby
+require 'langfuse'
+require_relative '../lib/langgraph_rb'
+
+url = 'https://us.cloud.langfuse.com'
+
+puts "LANGFUSE_PUBLIC_KEY: #{ENV['LANGFUSE_PUBLIC_KEY']}"
+puts "LANGFUSE_SECRET_KEY: #{ENV['LANGFUSE_SECRET_KEY']}"
+puts "LANGFUSE_HOST: #{url}"
+puts "LANGFUSE_DEBUG: #{true}"
+
+Langfuse.configure do |config|
+    config.public_key = ENV['LANGFUSE_PUBLIC_KEY']  # e.g., 'pk-lf-...'
+    config.secret_key = ENV['LANGFUSE_SECRET_KEY']  # e.g., 'sk-lf-...'
+    config.host = url
+    config.debug = true # Enable debug logging
+end
+
+# Very simple mock LLM client. Bring your own real client instead.
+class MockLLMClient
+
+    def set_observers(observers, node_name)
+        @observers = observers
+        @node_name = node_name
+    end
+
+    def call(messages)
+
+        data = {
+            name: "MockLLMClient",
+            model: "MockLLM",
+            model_parameters: {
+                temperature: 0.5,
+                max_tokens: 1000
+            },
+            input: messages,
+        }
+
+        log_llm_request(data)
+
+        last_user_message = messages.reverse.find { |m| m[:role] == 'user' }&.dig(:content)
+        "(mock) You said: #{last_user_message}"
+
+        data = {
+            output: "(mock) You said: #{last_user_message}",
+            prompt_tokens: 100,
+            completion_tokens: 100,
+            total_tokens: 200,
+        }
+
+        log_llm_response(data)
+    end
+
+    def log_llm_request(data)
+        @observer&.each do |observer|
+            observer.on_llm_request(data, @node_name)
+        end
+    end
+  
+    def log_llm_response(data)
+        @observers&.each do |observer|
+            observer.on_llm_response(data, @node_name)
+        end
+    end
+end
+
+class LangfuseObserver < LangGraphRB::Observers::BaseObserver
+
+    def initialize
+        @trace = nil
+        @spans_by_node = {}
+    end
+
+    def on_graph_start(event)
+        @trace ||= Langfuse.trace(
+            name: "llm-graph",
+            thread_id: event.thread_id,            
+            metadata: event.to_h
+        )
+    end
+
+    def on_node_start(event)
+        @spans_by_node[event.node_name] ||= {
+            span: Langfuse.span(
+                name: "node-#{event.node_name}",
+                trace_id: @trace.id,
+                input: event.to_h,            
+            ),
+            generation: nil
+        }
+        Langfuse.update_span(@spans_by_node[event.node_name][:span])        
+    end
+
+    def on_node_end(event)
+        # @spans_by_node[event.node_name] ||= {
+        #     span: Langfuse.span(
+        #         name: "node-#{event.node_name}",
+        #         trace_id: @trace.id,
+        #         input: event.to_h,            
+        #     ),
+        #     generation: nil
+        # }
+        # Langfuse.update_span(@spans_by_node[event.node_name][:span])        
+    end
+
+    def on_llm_request(event, node_name)
+        puts "########################################################"
+        puts "on_llm_request: #{event}"
+        puts "node_name: #{node_name}"
+        puts "spans_by_node: #{@spans_by_node}"
+        puts "$$$$--------------------------------------------------------$$$$"
+        span = @spans_by_node[node_name][:span]
+        generation = Langfuse.generation(
+            name: event[:name],
+            trace_id: @trace.id,
+            parent_observation_id: span.id,
+            model: event[:model],
+            model_parameters: event[:model_parameters],
+            input: event[:input]
+        )
+
+        @spans_by_node[node_name.to_sym][:generation] = generation        
+    end
+
+    def on_llm_response(event, node_name)
+        puts "########################################################"
+        puts "on_llm_response: #{event}"
+        puts "node_name: #{node_name}"
+        puts "spans_by_node: #{@spans_by_node}"
+        puts "$$$$--------------------------------------------------------$$$$"
+
+        generation = @spans_by_node[node_name][:generation]
+
+        return if generation.nil?
+
+        generation.output = event[:output]
+        generation.usage = Langfuse::Models::Usage.new(
+            prompt_tokens: event[:prompt_tokens],
+            completion_tokens: event[:completion_tokens], 
+            total_tokens: event[:total_tokens]
+        )
+        Langfuse.update_generation(generation)
+
+        @spans_by_node[node_name.to_sym][:generation] = nil
+    end
+end
+
+def llmnode_example
+  puts "=== LLMNode Example ==="
+
+  mock_llm = MockLLMClient.new
+
+  # Build a minimal chat graph using an LLM node.
+  graph = LangGraphRB::Graph.new(state_class: LangGraphRB::State) do
+    # Collect user input into the message history
+    node :receive_input do |state|
+      user_msg = { role: 'user', content: state[:input].to_s }
+      existing = state[:messages] || []
+      { messages: existing + [user_msg], last_user_message: state[:input].to_s }
+    end
+
+    # LLM node – uses a custom block to call the provided client via context
+    # Note: The default LLM behavior can be used once the core library wires a default callable.
+    llm_node :chat, llm_client: mock_llm, system_prompt: "You are a helpful assistant." do |state, context|
+      messages = state[:messages] || []
+
+      puts "########################################################"
+      puts "########################################################"
+
+      puts "context: #{context}"
+
+      puts "########################################################"
+      puts "########################################################"
+
+      # Optionally prepend a system prompt
+      if context[:system_prompt]
+        messages = [{ role: 'system', content: context[:system_prompt] }] + messages
+      end
+
+      response = context[:llm_client].call(messages)
+
+      assistant_msg = { role: 'assistant', content: response }
+      { messages: (state[:messages] || []) + [assistant_msg], last_response: response }
+    end
+
+    set_entry_point :receive_input
+    edge :receive_input, :chat
+    set_finish_point :chat
+  end
+
+  graph.compile!
+
+  # Single-turn example
+  result = graph.invoke({ messages: [], input: "Hello there!" }, observers: [LangfuseObserver.new])
+
+  puts "Assistant: #{result[:last_response]}"
+  puts "Messages:" 
+  (result[:messages] || []).each { |m| puts "  - #{m[:role]}: #{m[:content]}" }
+
+  # Multi-turn example (reuse message history)
+  second = graph.invoke({ messages: result[:messages], input: "What's the weather like?" })
+
+  puts "\nAssistant (turn 2): #{second[:last_response]}"
+  puts "Messages (after 2 turns):"
+  (second[:messages] || []).each { |m| puts "  - #{m[:role]}: #{m[:content]}" }
+end
+
+llmnode_example
+
+

data/lib/langgraph_rb/node.rb

@@ -40,27 +40,47 @@ module LangGraphRB
     def initialize(name, llm_client:, system_prompt: nil, &block)
       @llm_client = llm_client
       @system_prompt = system_prompt
-      
-      super(name, &block)
+
+      # Use default LLM behavior if no custom block provided
+      super(name, &(block || method(:default_llm_call)))
     end
 
-    def call(state, context: nil)
-      # If no custom block provided, use default LLM behavior
-      if @callable.nil? || @callable == method(:default_llm_call)
-        default_llm_call(state, context)
+    def call(state, context: nil, observers: [])
+      # Auto-inject LLM config into the context for both default and custom blocks
+      merged_context = (context || {}).merge(
+        llm_client: @llm_client,
+        system_prompt: @system_prompt
+      )
+
+      begin
+        @llm_client&.set_observers(observers, @name) if observers.any?
+      rescue => e
+        raise NodeError, "Error setting observers for LLM client: #{e.message}"
+      end
+
+      # Delegate to Node's dispatcher so arity (0/1/2) is handled uniformly
+      case @callable.arity
+      when 0
+        @callable.call
+      when 1
+        @callable.call(state)
       else
-        super(state, context: context)
+        @callable.call(state, merged_context)
       end
+    rescue => e
+      raise NodeError, "Error executing node '#{@name}': #{e.message}"
     end
 
     private
 
     def default_llm_call(state, context)
       messages = state[:messages] || []
-      messages = [@system_prompt] + messages if @system_prompt && !messages.empty?
-      
-      response = @llm_client.call(messages)
-      
+      if context && context[:system_prompt]
+        messages = [{ role: 'system', content: context[:system_prompt] }] + messages
+      end
+
+      response = (context[:llm_client] || @llm_client).call(messages)
+
       {
         messages: [{ role: 'assistant', content: response }],
         last_response: response

data/lib/langgraph_rb/observers/base.rb

@@ -60,6 +60,16 @@ module LangGraphRB
         # Override in subclasses if cleanup needed
       end
 
+      # Called when LLM requests occur
+      def on_llm_request(event)
+        # Override in subclasses
+      end
+
+      # Called when LLM responses occur
+      def on_llm_response(event)
+        # Override in subclasses
+      end
+
       protected
 
       # Helper method to create standardized event structure
@@ -117,11 +127,11 @@ module LangGraphRB
 
     class NodeEvent
       attr_reader :type, :node_name, :node_class, :state_before, :state_after, 
-                  :context, :thread_id, :step_number, :duration, :error, :result, :timestamp
+                  :context, :thread_id, :step_number, :duration, :error, :result, :timestamp, :from_node
 
       def initialize(type:, node_name:, node_class: nil, state_before: nil, state_after: nil,
                      context: nil, thread_id: nil, step_number: nil, duration: nil, 
-                     error: nil, result: nil)
+                     error: nil, result: nil, from_node: nil)
         @type = type
         @node_name = node_name
         @node_class = node_class
@@ -133,6 +143,7 @@ module LangGraphRB
         @duration = duration
         @error = error
         @result = result
+        @from_node = from_node
         @timestamp = Time.now.utc
       end
 
@@ -141,6 +152,7 @@ module LangGraphRB
           type: @type,
           node_name: @node_name,
           node_class: @node_class&.name,
+          from_node: @from_node,
           state_before: @state_before,
           state_after: @state_after,
           context: @context,

data/lib/langgraph_rb/runner.rb

@@ -64,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
@@ -78,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
@@ -87,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
@@ -96,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]
@@ -193,7 +193,7 @@ module LangGraphRB
       notify_observers(:on_graph_end, event)
     end
 
-    def notify_node_start(node, state, context)
+    def notify_node_start(node, state, context, from_node: nil)
       event = Observers::NodeEvent.new(
         type: :start,
         node_name: node.name,
@@ -201,12 +201,13 @@ module LangGraphRB
         state_before: state,
         context: context,
         thread_id: @thread_id,
-        step_number: @step_number
+        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)
+    def notify_node_end(node, state_before, state_after, result, duration, from_node: nil)
       event = Observers::NodeEvent.new(
         type: :end,
         node_name: node.name,
@@ -216,12 +217,13 @@ module LangGraphRB
         result: result,
         duration: duration,
         thread_id: @thread_id,
-        step_number: @step_number
+        step_number: @step_number,
+        from_node: from_node
       )
       notify_observers(:on_node_end, event)
     end
 
-    def notify_node_error(node, state, error)
+    def notify_node_error(node, state, error, from_node: nil)
       event = Observers::NodeEvent.new(
         type: :error,
         node_name: node.name,
@@ -229,7 +231,8 @@ module LangGraphRB
         state_before: state,
         error: error,
         thread_id: @thread_id,
-        step_number: @step_number
+        step_number: @step_number,
+        from_node: from_node
       )
       notify_observers(:on_node_error, event)
     end
@@ -251,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
@@ -267,12 +270,12 @@ module LangGraphRB
     end
 
     # Safely execute a single node
-    def execute_node_safely(node, state, context, step)
-      notify_node_start(node, state, context)
+    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)
+        result = node.call(state, context: context, observers: @observers)
         duration = Time.now - start_time
         
         processed_result = process_node_result(node.name, state, result, step)
@@ -285,11 +288,11 @@ module LangGraphRB
                        state
                      end
         
-        notify_node_end(node, state, final_state, result, duration)
+        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)
+        notify_node_error(node, state, error, from_node: from_node)
         
         {
           type: :error,
@@ -421,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.1"
+  VERSION = "0.1.3"
 end 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langgraph_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Julian Toro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-05 00:00:00.000000000 Z
+date: 2025-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -106,11 +106,14 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - Gemfile
+- Gemfile.lock
 - README.md
 - SUMMARY.md
 - examples/advanced_example.rb
 - examples/basic_example.rb
 - examples/initial_state_example.rb
+- examples/langfuse_example.rb
+- examples/llmnode_example.rb
 - examples/observer_example.rb
 - examples/reducers_example.rb
 - examples/simple_test.rb