langgraph_rb 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: faa20cb53b8c5f9c1ea8d740d34ea63eadfe9e07a49683dd3c090f7bb042d3fd
-  data.tar.gz: 56bfc5f8fb39473af9252caf1573f1126e30405f37ee7ac45bfde6704df20575
+  metadata.gz: 071bb22811337400b9569f90e07b50c0f7c6784b1025ce30b0502c5d321965b5
+  data.tar.gz: dad734ef3e60f76d8bf47de4c1f5f50a1b361dad8cfd7e36ed57e3cd4f998dca
 SHA512:
-  metadata.gz: 0f24fbb2f677bb13e7a8091807ff6d3f3d835b295ee691420f30b576bbd74d05eae9040d6511319eaefbc6c04170dc501101f3ff07f5a3e08c066a3d398adc3f
-  data.tar.gz: 91bdd7cf66e2c73fb5103d2fe469381bce46e889cacd6710a76c012d96296d3f0625dbc3b4e992570ef67ba3c506f8031058b3e6384304d0596e2c6f10dd8a6b
+  metadata.gz: 20c5c1c2ab980770d8ef0ca69159c1566c889c3ecd80d9185f6767b7954d92f5a15847ac50b1024dbd976670dc90d76b1bec9a95fa5d55b6123d6cdb26633bd2
+  data.tar.gz: a6edae4423708c7f807a050a9d4238d36ed188d0a0697e04eb2f21cebb3987ddf9d7f627cd6657d0b128470a58ca2a6895d02614da30341c73dbd5af1584337e

data/examples/chat_openai_tools_example.rb

@@ -1,8 +1,18 @@
 #!/usr/bin/env ruby
 require 'pry'
 require 'pry-byebug'
+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 MovieInfoTool < LangGraphRB::ToolBase
   define_function :search_movie, description: "MovieInfoTool: Search for a movie by title" do
     property :query, type: "string", description: "The movie title to search for", required: true
@@ -31,6 +41,8 @@ def run_chat_openai_tools
   chat = LangGraphRB::ChatOpenAI.new(model: ENV.fetch('OPENAI_MODEL', 'gpt-4o-mini'), temperature: 0)
   chat = chat.bind_tools(tools)
 
+  observers = [LangGraphRB::Observers::LangfuseObserver.new(name: 'chat-openai-tools-example')]
+
   graph = LangGraphRB::Graph.new do
     node :receive_input do |state|
       user_msg = { role: 'user', content: state[:input].to_s }
@@ -38,42 +50,7 @@ def run_chat_openai_tools
       { messages: existing + [user_msg] }
     end
 
-    llm_node :chat, llm_client: chat, system_prompt: "You are a movie assistant. Use tools when helpful." do |state, context|
-      messages = state[:messages] || []
-      messages = [{ role: 'system', content: context[:system_prompt] }] + messages if context[:system_prompt]
-
-      response = context[:llm_client].call(messages)
-
-      if response.is_a?(Hash) && response[:tool_calls]
-        assistant_msg = { role: 'assistant', content: nil, tool_calls: response[:tool_calls] }
-        { messages: (state[:messages] || []) + [assistant_msg], tool_call: response[:tool_calls].first }
-      else
-        assistant_msg = { role: 'assistant', content: response.to_s }
-        { messages: (state[:messages] || []) + [assistant_msg], last_response: response.to_s }
-      end
-    end    
-
-    # node :tool do |state|
-    #   tool_call = state[:tool_call]
-    #   tool_name = tool_call[:name]
-    #   tool_args = tool_call[:arguments]
-    #   tool_call_id = tool_call[:id]
-
-    #   puts "TOOL CALL #########################"
-    #   puts "tool_name: #{tool_name}"
-    #   puts "tool_args: #{tool_args}"
-    #   puts "tool_call_id: #{tool_call_id}"
-    #   puts "########################"
-    #   puts "########################"
-      
-    #   tool_method_name = tool_name.to_s.split('__').last
-
-    #   # Dispatch via ToolBase API to keep consistent interface
-    #   tool_result = tools.call({ name: tool_method_name, arguments: tool_args })
-
-    #   { messages: (state[:messages] || []) + [{ role: 'tool', content: tool_result.to_json, tool_call_id: tool_call_id, name: tool_name.to_s }],
-    #   tool_call: nil }
-    # end
+    llm_node :chat, llm_client: chat, system_prompt: "You are a movie assistant. Use tools when helpful."
 
     tool_node :tool, tools: tools
 
@@ -97,8 +74,10 @@ def run_chat_openai_tools
 
   graph.compile!
 
+  graph.draw_mermaid
+
   start = { messages: [], input: "Find details about 'The Matrix'" }
-  result = graph.invoke(start)
+  result = graph.invoke(start, observers: observers)
   puts "Messages:"
   (result[:messages] || []).each do |m|
     if m[:role] == 'assistant' && m[:tool_calls]
@@ -113,3 +92,39 @@ end
 run_chat_openai_tools
 
 
+# llm_node :chat, llm_client: chat, system_prompt: "You are a movie assistant. Use tools when helpful." do |state, context|
+    #   messages = state[:messages] || []
+    #   messages = [{ role: 'system', content: context[:system_prompt] }] + messages if context[:system_prompt]
+
+    #   response = context[:llm_client].call(messages)
+
+    #   if response.is_a?(Hash) && response[:tool_calls]
+    #     assistant_msg = { role: 'assistant', content: nil, tool_calls: response[:tool_calls] }
+    #     { messages: (state[:messages] || []) + [assistant_msg], tool_call: response[:tool_calls].first }
+    #   else
+    #     assistant_msg = { role: 'assistant', content: response.to_s }
+    #     { messages: (state[:messages] || []) + [assistant_msg], last_response: response.to_s }
+    #   end
+    # end
+
+    # node :tool do |state|
+    #   tool_call = state[:tool_call]
+    #   tool_name = tool_call[:name]
+    #   tool_args = tool_call[:arguments]
+    #   tool_call_id = tool_call[:id]
+
+    #   puts "TOOL CALL #########################"
+    #   puts "tool_name: #{tool_name}"
+    #   puts "tool_args: #{tool_args}"
+    #   puts "tool_call_id: #{tool_call_id}"
+    #   puts "########################"
+    #   puts "########################"
+      
+    #   tool_method_name = tool_name.to_s.split('__').last
+
+    #   # Dispatch via ToolBase API to keep consistent interface
+    #   tool_result = tools.call({ name: tool_method_name, arguments: tool_args })
+
+    #   { messages: (state[:messages] || []) + [{ role: 'tool', content: tool_result.to_json, tool_call_id: tool_call_id, name: tool_name.to_s }],
+    #   tool_call: nil }
+    # end

data/examples/langfuse_example.rb

@@ -12,27 +12,6 @@ Langfuse.configure do |config|
 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 "########################################################"
@@ -82,7 +61,10 @@ def langfuse_example
   
   
   graph.compile!
-  result = graph.invoke({ message: "Hello World", value:  31}, observers: [LangfuseObserver.new])
+  result = graph.invoke(
+    { message: "Hello World", value:  31},
+    observers: [LangGraphRB::Observers::LangfuseObserver.new(name: 'langfuse-example')]
+  )
   puts "Result: #{result}"
   puts "########################################################"
   puts "########################################################"

data/lib/langgraph_rb/graph.rb

@@ -214,7 +214,10 @@ module LangGraphRB
           validate_node_exists!(edge.to)
         when ConditionalEdge
           validate_node_exists!(edge.from)
-          # Path map targets will be validated at runtime
+          # If a static path_map is provided, validate mapped destinations now
+          if edge.path_map && !edge.path_map.empty?
+            edge.path_map.values.each { |dest| validate_node_exists!(dest) }
+          end
         when FanOutEdge
           validate_node_exists!(edge.from)
           edge.destinations.each { |dest| validate_node_exists!(dest) }
@@ -226,6 +229,12 @@ module LangGraphRB
         case edge
         when Edge
           [edge.to]
+        when ConditionalEdge
+          if edge.path_map && !edge.path_map.empty?
+            edge.path_map.values
+          else
+            []
+          end
         when FanOutEdge
           edge.destinations
         else
@@ -264,11 +273,17 @@ module LangGraphRB
         case edge
         when Edge
           reachable += find_reachable_nodes(edge.to, visited.dup)
+        when ConditionalEdge
+          # If a static path_map is provided, consider all mapped destinations reachable
+          if edge.path_map && !edge.path_map.empty?
+            edge.path_map.values.each do |dest|
+              reachable += find_reachable_nodes(dest, visited.dup)
+            end
+          end
         when FanOutEdge
           edge.destinations.each do |dest|
             reachable += find_reachable_nodes(dest, visited.dup)
-          end
-        # ConditionalEdge paths are dynamic, so we can't pre-validate them
+          end        
         end
       end
       

data/lib/langgraph_rb/observers/langfuse.rb

@@ -0,0 +1,205 @@
+require 'langfuse'
+
+module LangGraphRB
+  module Observers
+    # Langfuse observer that captures graph, node, and LLM events.
+    # - Creates a Langfuse trace for each graph run (thread_id)
+    # - Creates spans per node execution and links LLM generations to spans
+    # - Thread-safe and resilient to Langfuse client errors
+    class LangfuseObserver < BaseObserver
+      def initialize(name: 'langgraph-run')
+        @name = name
+        @trace = nil
+        @trace_mutex = Mutex.new
+
+        # Maintain a stack per node_name to safely handle parallel executions
+        # { Symbol(String) => [ { span: <Span>, generation: <Generation>|nil } ] }
+        @records_by_node = Hash.new { |h, k| h[k] = [] }
+        @records_mutex = Mutex.new
+      end
+
+      # Graph lifecycle
+      def on_graph_start(event)
+        ensure_trace!(event)
+      rescue => _e
+        # Swallow observer errors to avoid impacting execution
+      end
+
+      def on_graph_end(event)
+        return unless @trace
+        Langfuse.trace(id: @trace.id, output: safe_state(event.initial_state))
+      rescue => _e
+      end
+
+      # Node lifecycle
+      def on_node_start(event)
+        return if event.node_name == :__start__
+
+        trace = ensure_trace!(event)
+        return unless trace
+
+        span = Langfuse.span(
+          name: event.node_name.to_s,
+          trace_id: trace.id,
+          metadata: event.to_h
+        )
+
+        # Track record on a stack keyed by node_name
+        with_records_lock do
+          @records_by_node[event.node_name] << { span: span, generation: nil }
+        end
+
+        Langfuse.update_span(span)
+      rescue => _e
+      end
+
+      def on_node_end(event)
+        return if event.node_name == :__start__
+
+        record = with_records_lock do
+          @records_by_node[event.node_name].pop
+        end
+
+        span = record && record[:span]
+        return unless span
+
+        data = event.to_h
+        span.input = safe_state(data[:state_before])
+        span.output = safe_state(data[:state_after])
+        span.metadata = data
+        span.end_time = Time.now.utc
+        Langfuse.update_span(span)
+      rescue => _e
+      end
+
+      def on_node_error(event)
+        return if event.node_name == :__start__
+
+        record = with_records_lock do
+          @records_by_node[event.node_name].pop
+        end
+
+        span = record && record[:span]
+        return unless span
+
+        span.metadata = event.to_h
+        span.end_time = Time.now.utc
+        Langfuse.update_span(span)
+      rescue => _e
+      end
+
+      # LLM lifecycle (called directly by LLM clients)
+      def on_llm_request(data, node_name)
+        record = with_records_lock do
+          stack = @records_by_node[node_name]
+          stack.empty? ? nil : stack[-1]
+        end
+        return unless record && record[:span]
+
+        # Prefer normalized payload from LLMBase implementations (e.g., ChatOpenAI)
+        input_payload = if data.is_a?(Hash)
+          data[:input] || data[:messages] || (data[:request] && data[:request][:messages])
+        else
+          data
+        end
+
+        generation = Langfuse.generation(
+          name: "llm-request-#{node_name}",
+          trace_id: @trace&.id,
+          parent_observation_id: record[:span].id,
+          model: data[:model],
+          input: input_payload,
+          metadata: (data.respond_to?(:to_h) ? data.to_h : data)
+        )
+
+        with_records_lock do
+          record[:generation] = generation
+        end
+      rescue => _e
+      end
+
+      def on_llm_response(data, node_name)
+        record = with_records_lock do
+          stack = @records_by_node[node_name]
+          stack.empty? ? nil : stack[-1]
+        end
+        return unless record && record[:generation]
+
+        generation = record[:generation]
+
+        if data.is_a?(Hash)
+          # Prefer normalized payload keys first
+          if data.key?(:output)
+            generation.output = data[:output]
+          else
+            # Fallback to OpenAI-style response structure
+            generation.output = data.dig(:choices, 0, :message, :content)
+          end
+
+          # Usage: support both normalized top-level and OpenAI usage block
+          prompt_tokens = data[:prompt_tokens] || data.dig(:usage, :prompt_tokens)
+          completion_tokens = data[:completion_tokens] || data.dig(:usage, :completion_tokens)
+          total_tokens = data[:total_tokens] || data.dig(:usage, :total_tokens)
+
+          if prompt_tokens || completion_tokens || total_tokens
+            begin
+              generation.usage = Langfuse::Models::Usage.new(
+                prompt_tokens: prompt_tokens,
+                completion_tokens: completion_tokens,
+                total_tokens: total_tokens
+              )
+            rescue => _e
+              # best-effort usage mapping
+            end
+          end
+        else
+          generation.output = data
+        end
+
+        generation.end_time = Time.now.utc
+        Langfuse.update_generation(generation)
+
+        with_records_lock do
+          record[:generation] = nil
+        end
+      rescue => _e
+      end
+
+      private
+
+      def ensure_trace!(event)
+        return @trace if @trace
+        @trace_mutex.synchronize do
+          return @trace if @trace
+          data = event.to_h
+          @trace = Langfuse.trace(
+            name: @name,
+            thread_id: data[:thread_id],
+            metadata: data,
+            input: safe_state(data[:initial_state])
+          )
+        end
+        @trace
+      end
+
+      def with_records_lock
+        @records_mutex.synchronize do
+          yield
+        end
+      end
+
+      def safe_state(state)
+        return nil if state.nil?
+        if state.respond_to?(:to_h)
+          state.to_h
+        else
+          state
+        end
+      rescue => _e
+        nil
+      end
+    end
+  end
+end
+
+

data/lib/langgraph_rb/version.rb

@@ -1,3 +1,3 @@
 module LangGraphRB
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end 

data/lib/langgraph_rb.rb

@@ -9,6 +9,7 @@ require_relative 'langgraph_rb/stores/memory'
 require_relative 'langgraph_rb/observers/base'
 require_relative 'langgraph_rb/observers/logger'
 require_relative 'langgraph_rb/observers/structured'
+require_relative 'langgraph_rb/observers/langfuse'
 require_relative 'langgraph_rb/llm_base'
 require_relative 'langgraph_rb/chat_openai'
 require_relative 'langgraph_rb/tool_definition'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langgraph_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Julian Toro
@@ -133,7 +133,6 @@ files:
 - examples/observer_example.rb
 - examples/reducers_example.rb
 - examples/simple_test.rb
-- examples/tool_and_llm_example.rb
 - langgraph_rb.gemspec
 - lib/langgraph_rb.rb
 - lib/langgraph_rb/chat_openai.rb
@@ -143,6 +142,7 @@ files:
 - lib/langgraph_rb/llm_base.rb
 - lib/langgraph_rb/node.rb
 - lib/langgraph_rb/observers/base.rb
+- lib/langgraph_rb/observers/langfuse.rb
 - lib/langgraph_rb/observers/logger.rb
 - lib/langgraph_rb/observers/structured.rb
 - lib/langgraph_rb/runner.rb

data/examples/tool_and_llm_example.rb

@@ -1,145 +0,0 @@
-#!/usr/bin/env ruby
-
-require_relative '../lib/langgraph_rb'
-
-# Mock LLM client that can incorporate tool outputs when present
-class MockLLMClient
-  def call(messages)
-    last_user = messages&.reverse&.find { |m| m[:role] == 'user' }&.dig(:content)
-    last_tool = messages&.reverse&.find { |m| m[:role] == 'tool' }&.dig(:content)
-
-    if last_tool
-      "(mock) Based on tool result: #{last_tool} | Answering user: #{last_user}"
-    else
-      "(mock) You said: #{last_user}"
-    end
-  end
-end
-
-# Simple search tool that returns a faux result string
-class SearchTool
-  def self.call(args)
-    query = args.is_a?(Hash) ? args[:query] || args['query'] : args
-    query ||= args.to_s
-    "Results for '#{query}': [Result A, Result B, Result C]"
-  end
-end
-
-def tool_and_llm_example
-  puts "=== Tool + LLM Example ==="
-
-  mock_llm = MockLLMClient.new
-
-  graph = LangGraphRB::Graph.new(state_class: LangGraphRB::State) do
-    # 1) Capture 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
-
-    # 2) Decide whether to call a tool based on the user's request
-    # If the user says: "search <query>", produce a tool_call for SearchTool
-    llm_node :router, llm_client: mock_llm, system_prompt: "You are a helpful assistant that can decide to call tools when asked." do |state, context|
-      last_user = state[:last_user_message].to_s
-
-      if (match = last_user.match(/^\s*search\s+(.+)$/i))
-        query = match[1].strip
-        tool_call = {
-          id: "call_#{Time.now.to_i}",
-          name: 'search',
-          args: { query: query }
-        }
-
-        assistant_msg = {
-          role: 'assistant',
-          content: "Let me search for: #{query}",
-          tool_calls: [tool_call]
-        }
-
-        {
-          messages: (state[:messages] || []) + [assistant_msg],
-          tool_call: tool_call # also put it in state for convenience
-        }
-      else
-        # No tool needed; provide a direct assistant response using the LLM
-        messages = state[:messages] || []
-        messages = [{ role: 'system', content: context[:system_prompt] }] + messages if context[:system_prompt]
-        response = context[:llm_client].call(messages)
-
-        {
-          messages: (state[:messages] || []) + [{ role: 'assistant', content: response }],
-          last_response: response
-        }
-      end
-    end
-
-    # 3) Execute the tool if requested and append a tool message
-    # Use a custom block to merge the tool message with existing history
-    tool_node :use_tool, tool: SearchTool do |state|
-      # Determine the tool call (from state or messages)
-      tool_call = state[:tool_call]
-      unless tool_call
-        # Fallback: look for a message containing tool_calls
-        (state[:messages] || []).reverse.each do |msg|
-          if msg[:tool_calls] && msg[:tool_calls].first
-            tool_call = msg[:tool_calls].first
-            break
-          end
-        end
-      end
-
-      return { error: 'No tool call found' } unless tool_call
-
-      result = SearchTool.call(tool_call[:args])
-
-      tool_msg = {
-        role: 'tool',
-        content: result.to_s,
-        tool_call_id: tool_call[:id]
-      }
-
-      {
-        messages: (state[:messages] || []) + [tool_msg],
-        tool_result: result
-      }
-    end
-
-    # 4) Produce the final answer with the LLM, using any tool results
-    llm_node :final_answer, llm_client: mock_llm, system_prompt: "Use tool results if available to answer the user."
-
-    # Flow
-    set_entry_point :receive_input
-    edge :receive_input, :router
-
-    # If there is a tool_call, go to :use_tool, otherwise go directly to :final_answer
-    conditional_edge :router, ->(state) {
-      state[:tool_call] ? "use_tool" : "final_answer"
-    }, {
-      "use_tool" => :use_tool,
-      "final_answer" => :final_answer
-    }
-
-    edge :use_tool, :router
-    set_finish_point :final_answer
-  end
-
-  graph.compile!
-
-  puts graph.to_mermaid
-
-  puts "\n— Example 1: No tool needed —"
-  result1 = graph.invoke({ messages: [], input: "Tell me a joke." })
-  puts "Assistant: #{result1[:last_response]}"
-
-  puts "\n— Example 2: Tool is used —"
-  result2 = graph.invoke({ messages: [], input: "search Ruby LangGraphRB" })
-  final_message = (result2[:messages] || []).reverse.find { |m| m[:role] == 'assistant' }&.dig(:content)
-  puts "Assistant: #{final_message}"
-  tool_message = (result2[:messages] || []).reverse.find { |m| m[:role] == 'tool' }&.dig(:content)
-  puts "(Tool) #{tool_message}"
-end
-
-tool_and_llm_example 
-
-