langgraph_rb 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5649cc9cef30c96380dc2ccd9a5c576af8d3efd7e02552b03d81cb45360f408
-  data.tar.gz: 3c706c127ac2fbd5e9d8a0be723575228a21d9ff91672169dc66174cd8dba3c5
+  metadata.gz: 071bb22811337400b9569f90e07b50c0f7c6784b1025ce30b0502c5d321965b5
+  data.tar.gz: dad734ef3e60f76d8bf47de4c1f5f50a1b361dad8cfd7e36ed57e3cd4f998dca
 SHA512:
-  metadata.gz: 7dd32ea2d6c98ae356596cee6ca0d697802e7107649faf63c598606f9b708a68cd7c72e72d4ad5423d136a72d74c242108c28b670f6ab2aea2cf3a18925f35d4
-  data.tar.gz: d6a30010935f797cc6ebbe3767db38c8726029956192b57cd69304d6b0238d3dd0bdb1b32d7d9b348bbc8ee4469f8b1fe62b750386834c9cb7ce52980f1f25a4
+  metadata.gz: 20c5c1c2ab980770d8ef0ca69159c1566c889c3ecd80d9185f6767b7954d92f5a15847ac50b1024dbd976670dc90d76b1bec9a95fa5d55b6123d6cdb26633bd2
+  data.tar.gz: a6edae4423708c7f807a050a9d4238d36ed188d0a0697e04eb2f21cebb3987ddf9d7f627cd6657d0b128470a58ca2a6895d02614da30341c73dbd5af1584337e

data/Gemfile

@@ -2,9 +2,12 @@ source 'https://rubygems.org'
 
 gemspec
 
+gem 'openai', '~> 0.24.0'
+
 group :development, :test do
   gem 'rspec', '~> 3.0'
   gem 'pry', '~> 0.14'
+  gem 'pry-byebug'
   gem 'rubocop', '~> 1.0'
   gem 'langfuse', '~> 0.1'
 end 

data/Gemfile.lock

@@ -1,15 +1,18 @@
 PATH
   remote: .
   specs:
-    langgraph_rb (0.1.2)
+    langgraph_rb (0.1.4)
       json (~> 2.0)
+      openai (~> 0.24.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
+    byebug (12.0.0)
     coderay (1.1.3)
     concurrent-ruby (1.3.5)
+    connection_pool (2.5.4)
     diff-lcs (1.6.2)
     json (2.13.2)
     langfuse (0.1.1)
@@ -18,6 +21,8 @@ GEM
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     method_source (1.1.0)
+    openai (0.24.0)
+      connection_pool
     parallel (1.27.0)
     parser (3.3.9.0)
       ast (~> 2.4.1)
@@ -26,6 +31,9 @@ GEM
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    pry-byebug (3.11.0)
+      byebug (~> 12.0)
+      pry (>= 0.13, < 0.16)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.0)
@@ -71,7 +79,9 @@ DEPENDENCIES
   bundler (~> 2.0)
   langfuse (~> 0.1)
   langgraph_rb!
+  openai (~> 0.24.0)
   pry (~> 0.14)
+  pry-byebug
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.0)

data/examples/basic_example.rb

@@ -123,10 +123,11 @@ def basic_example
     }
 
     # All responses go back to waiting for input (except farewell)
-    edge :handle_greeting, :receive_input
-    edge :handle_help, :receive_input  
-    edge :handle_weather, :receive_input
-    edge :general_response, :receive_input
+    set_finish_point :handle_greeting
+    set_finish_point :handle_farewell
+    set_finish_point :handle_help
+    set_finish_point :handle_weather
+    set_finish_point :general_response
   end
 
   # Compile the graph
@@ -205,7 +206,9 @@ def streaming_example
 end
 
 # Run examples
-if __FILE__ == $0
-  basic_example
-  streaming_example
-end 
+# if __FILE__ == $0
+#   basic_example
+#   streaming_example
+# end 
+
+basic_example

data/examples/chat_openai_tools_example.rb

@@ -0,0 +1,130 @@
+#!/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
+  end
+
+  define_function :get_movie_details, description: "MovieInfoTool: Get detailed information about a specific movie" do
+    property :movie_id, type: "integer", description: "The TMDb ID of the movie", required: true
+  end
+
+  def initialize(api_key: "demo")
+    @api_key = api_key
+  end
+
+  def search_movie(query:)
+    tool_response({ results: [ { id: 603, title: query, year: 1999 } ] })
+  end
+
+  def get_movie_details(movie_id:)
+    tool_response({ id: movie_id, title: "The Matrix", overview: "A computer hacker learns the truth of reality." })
+  end
+end
+
+def run_chat_openai_tools
+  tools = [MovieInfoTool.new(api_key: ENV['TMDB_API_KEY'] || 'demo')]
+
+  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 }
+      existing = state[:messages] || []
+      { messages: existing + [user_msg] }
+    end
+
+    llm_node :chat, llm_client: chat, system_prompt: "You are a movie assistant. Use tools when helpful."
+
+    tool_node :tool, tools: tools
+
+    node :final_answer do |state|
+      { **state }
+    end
+
+    set_entry_point :receive_input
+    edge :receive_input, :chat
+
+    conditional_edge :chat, ->(state) {    
+      state[:tool_call] ? "use_tool" : "final_answer"
+    }, {
+      "use_tool" => :tool,
+      "final_answer" => :final_answer
+    }
+
+    edge :tool, :chat
+    set_finish_point :final_answer
+  end
+
+  graph.compile!
+
+  graph.draw_mermaid
+
+  start = { messages: [], input: "Find details about 'The Matrix'" }
+  result = graph.invoke(start, observers: observers)
+  puts "Messages:"
+  (result[:messages] || []).each do |m|
+    if m[:role] == 'assistant' && m[:tool_calls]
+      names = m[:tool_calls].map { |tc| tc[:name] }.join(', ')
+      puts "- assistant tool_calls: #{names}"
+    else
+      puts "- #{m[:role]}: #{m[:content]}"
+    end
+  end
+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/conditional_example.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/langgraph_rb'
+
+graph = LangGraphRB::Graph.new do
+    node :greeting do |state|
+        { message: "Hello, how can I help you today?" }
+    end
+
+    node :analyze_intent do |state|
+        { intent: state[:message].downcase.include?("weather") ? "weather" : "general" }
+    end
+    
+    conditional_edge :analyze_intent, ->(state) { state[:intent] }, {
+        "weather" => :weather_response,
+        "general" => :general_response
+    }
+
+    node :weather_response do |state|
+        { message: "The weather is sunny today!" }
+    end
+
+    node :general_response do |state|
+        { message: "That's interesting! Tell me more." }
+    end
+
+    set_entry_point :greeting
+    edge :greeting, :analyze_intent
+    set_finish_point :weather_response
+    set_finish_point :general_response
+end
+    
+
+graph.compile!
+puts graph.to_mermaid
+result = graph.invoke({ message: "How's the weather?" })
+puts result[:message]  # => "The weather is sunny today!"
+

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/langgraph_rb.gemspec

@@ -33,6 +33,7 @@ Gem::Specification.new do |spec|
 
   # Runtime dependencies
   spec.add_dependency "json", "~> 2.0"
+  spec.add_dependency "openai", "~> 0.24.0"
 
   # Development dependencies
   spec.add_development_dependency "bundler", "~> 2.0"

data/lib/langgraph_rb/chat_openai.rb

@@ -0,0 +1,197 @@
+require 'openai'
+require_relative 'llm_base'
+
+module LangGraphRB
+  # ChatOpenAI wrapper compatible with LLMBase, supporting tool binding
+  class ChatOpenAI < LLMBase
+    def initialize(model:, temperature: 0.0, api_key: ENV['OPENAI_API_KEY'])
+      super(model: model, temperature: temperature)
+      @client = OpenAI::Client.new(api_key: api_key)
+    end
+
+    # Returns a new instance with tools bound (non-destructive)
+    def bind_tools(tools)
+      dup_instance = self.class.new(model: @model, temperature: @temperature)      
+      dup_instance.instance_variable_set(:@client, @client)
+      dup_instance.instance_variable_set(:@bound_tools, Array(tools))
+      dup_instance
+    end
+
+    # messages: array of { role: 'system'|'user'|'assistant'|'tool', content: string, tool_calls?: [...] }
+    # tools: optional array of tool definitions (objects responding to .to_openai_tool_schema)
+    # Returns assistant text string or a tool-call envelope hash when tool calls are produced
+    def call(messages, tools: nil)
+      raise ArgumentError, 'messages must be an Array' unless messages.is_a?(Array)
+
+      tool_definitions = (tools || @bound_tools)
+      tool_schemas = Array(tool_definitions).flat_map do |tool|
+        if tool.respond_to?(:to_openai_tool_schema)
+          Array(tool.to_openai_tool_schema)
+        else
+          [tool]
+        end
+      end
+
+      request_payload = {
+        model: @model,
+        temperature: @temperature,
+        messages: normalize_messages(messages)
+      }
+
+      if tool_schemas && !tool_schemas.empty?
+        request_payload[:tools] = tool_schemas
+        request_payload[:tool_choice] = 'auto'
+      end
+
+      notify_llm_request({
+        name: 'OpenAI::ChatCompletion',
+        model: @model,
+        model_parameters: { temperature: @temperature },
+        input: request_payload[:messages]
+      })
+
+      # openai 0.24.0 uses client.chat.completions.create(params)
+      response = @client.chat.completions.create(request_payload)
+
+      message = extract_message_from_response(response)
+      tool_calls = message[:tool_calls]
+      text_content = message[:content] 
+
+      usage = extract_usage_from_response(response)
+      notify_llm_response({
+        output: tool_calls ? { tool_calls: tool_calls } : text_content,
+        prompt_tokens: usage[:prompt_tokens],
+        completion_tokens: usage[:completion_tokens],
+        total_tokens: usage[:total_tokens]
+      })
+
+      if tool_calls && !tool_calls.empty?
+        normalized_calls = tool_calls.map do |tc|
+          {
+            id: tc[:id],
+            name: tc[:function][:name],
+            arguments: parse_tool_arguments(tc[:function][:arguments])
+          }
+        end
+        { tool_calls: normalized_calls }
+      else
+        text_content
+      end
+    end
+
+    private
+
+    def normalize_messages(messages)
+      messages.map do |m|
+        role = (m[:role] || m['role'])
+        content = m[:content] || m['content']
+
+        normalized = { role: role }
+
+        if content.is_a?(Array)
+          normalized[:content] = content
+        elsif content.nil?
+          normalized[:content] = nil
+        else
+          normalized[:content] = content.to_s
+        end
+
+        # Preserve assistant tool_calls; convert internal format back to OpenAI shape
+        tool_calls = m[:tool_calls] || m['tool_calls']
+        if tool_calls && role.to_s == 'assistant'
+          normalized[:tool_calls] = Array(tool_calls).map do |tc|
+            # Already OpenAI shape
+            if tc[:function] || tc['function']
+              fn = tc[:function] || tc['function']
+              raw_args = fn[:arguments] || fn['arguments']
+              args_str = raw_args.is_a?(String) ? raw_args : JSON.dump(raw_args || {})
+              {
+                id: (tc[:id] || tc['id']),
+                type: 'function',
+                function: {
+                  name: (fn[:name] || fn['name']).to_s,
+                  arguments: args_str
+                }
+              }
+            else
+              # Internal normalized shape { id:, name:, arguments: Hash|String }
+              raw_args = tc[:arguments] || tc['arguments']
+              args_str = raw_args.is_a?(String) ? raw_args : JSON.dump(raw_args || {})
+              {
+                id: (tc[:id] || tc['id']),
+                type: 'function',
+                function: {
+                  name: (tc[:name] || tc['name']).to_s,
+                  arguments: args_str
+                }
+              }
+            end
+          end
+        end
+
+        # Preserve tool message linkage
+        if role.to_s == 'tool'
+          tool_call_id = m[:tool_call_id] || m['tool_call_id']
+          name = m[:name] || m['name']
+          normalized[:tool_call_id] = tool_call_id if tool_call_id
+          normalized[:name] = name if name
+        end
+
+        normalized
+      end
+    end
+
+    def parse_tool_arguments(raw)
+      return {} if raw.nil?
+      case raw
+      when String
+        JSON.parse(raw) rescue {}
+      when Hash
+        raw
+      else
+        {}
+      end
+    end
+
+    def extract_message_from_response(response)
+      # Handles both Hash responses and typed OpenAI::Models::* objects
+      if response.respond_to?(:choices)
+        first_choice = response.choices.first
+        if first_choice.respond_to?(:[])
+          first_choice[:message] || first_choice['message'] || {}
+        else
+          # In some versions, choices elements are structs with #message
+          first_choice.message
+        end
+      else
+        (response['choices'] || []).dig(0, 'message') || {}
+      end
+    end
+
+    def extract_usage_from_response(response)
+      usage = if response.respond_to?(:usage)
+        response.usage
+      else
+        response['usage']
+      end
+
+      return { prompt_tokens: nil, completion_tokens: nil, total_tokens: nil } unless usage
+
+      if usage.respond_to?(:[]) || usage.is_a?(Hash)
+        {
+          prompt_tokens: usage[:prompt_tokens] || usage['prompt_tokens'],
+          completion_tokens: usage[:completion_tokens] || usage['completion_tokens'],
+          total_tokens: usage[:total_tokens] || usage['total_tokens']
+        }
+      else
+        {
+          prompt_tokens: usage.prompt_tokens,
+          completion_tokens: usage.completion_tokens,
+          total_tokens: usage.total_tokens
+        }
+      end
+    end
+  end
+end
+
+

data/lib/langgraph_rb/graph.rb

@@ -42,11 +42,11 @@ module LangGraphRB
       @nodes[name] = LLMNode.new(name, llm_client: llm_client, system_prompt: system_prompt, &block)
     end
 
-    def tool_node(name, tool:, &block)
+    def tool_node(name, tools:, &block)
       name = name.to_sym
       raise GraphError, "Node '#{name}' already exists" if @nodes.key?(name)
       
-      @nodes[name] = ToolNode.new(name, tool: tool, &block)
+      @nodes[name] = ToolNode.new(name, tools: tools, &block)
     end
 
     def edge(from, to)
@@ -149,7 +149,15 @@ module LangGraphRB
         when Edge
           lines << "    #{edge.from} --> #{edge.to}"
         when ConditionalEdge
-          lines << "    #{edge.from} --> |condition| #{edge.from}_decision{condition}"
+          decision_name = "#{edge.from}_decision"
+          # Connect source to decision node with a label
+          lines << "    #{edge.from} -- condition --> #{decision_name}{\"condition\"}"
+          # Add labeled branches from decision to each mapped destination
+          if edge.path_map && !edge.path_map.empty?
+            edge.path_map.each do |label, destination|
+              lines << "    #{decision_name} -- #{label} --> #{destination}"
+            end
+          end
         when FanOutEdge
           edge.destinations.each do |dest|
             lines << "    #{edge.from} --> #{dest}"
@@ -206,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) }
@@ -218,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
@@ -256,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/llm_base.rb

@@ -0,0 +1,60 @@
+require 'json'
+
+module LangGraphRB
+  # Abstract base for chat LLM clients.
+  # Implementations must provide #call(messages, tools: nil) and may support #bind_tools.
+  class LLMBase
+    attr_reader :model, :temperature
+
+    def initialize(model:, temperature: 0.0)
+      @model = model
+      @temperature = temperature
+      @bound_tools = []
+      @observers = []
+      @node_name = nil
+    end
+
+    # Called by runtime to allow LLM client to emit tracing/telemetry events
+    def set_observers(observers, node_name)
+      @observers = Array(observers)
+      @node_name = node_name
+    end
+
+    def bind_tools(tools)
+      @bound_tools = Array(tools)
+      self
+    end
+
+    def bound_tools
+      @bound_tools
+    end
+
+    def call(_messages, tools: nil)
+      raise NotImplementedError, "Subclasses must implement #call(messages, tools: nil)"
+    end
+
+    protected
+
+    def notify_llm_request(payload)
+      @observers.each do |observer|
+        begin
+          observer.on_llm_request(payload, @node_name)
+        rescue => _e
+          # Ignore observer errors
+        end
+      end
+    end
+
+    def notify_llm_response(payload)
+      @observers.each do |observer|
+        begin
+          observer.on_llm_response(payload, @node_name)
+        rescue => _e
+          # Ignore observer errors
+        end
+      end
+    end
+  end
+end
+
+

data/lib/langgraph_rb/node.rb

@@ -81,19 +81,32 @@ module LangGraphRB
 
       response = (context[:llm_client] || @llm_client).call(messages)
 
-      {
-        messages: [{ role: 'assistant', content: response }],
-        last_response: response
-      }
+      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
   end
 
   # Specialized node for tool calls
   class ToolNode < Node
-    attr_reader :tool
+    attr_reader :tools
 
-    def initialize(name, tool:, &block)
-      @tool = tool
+    def initialize(name, tools:, &block)
+      @tools = tools
       super(name, &(block || method(:default_tool_call)))
     end
 
@@ -105,15 +118,22 @@ module LangGraphRB
       
       return { error: "No tool call found" } unless tool_call
 
-      result = @tool.call(tool_call[:args])
+      # Normalize expected structure for tool dispatch
+      normalized = normalize_tool_call(tool_call)
+      tool = @tools.find { |t| t.class.name == normalized[:class_name] }
+      result = tool.call(normalized)
       
+      tool_message = {
+        role: 'tool',
+        content: result.to_s,
+        tool_call_id: normalized[:id],
+        name: normalized[:name]
+      }
+
       {
-        messages: [{
-          role: 'tool',
-          content: result.to_s,
-          tool_call_id: tool_call[:id]
-        }],
-        tool_result: result
+        **state,
+        messages: (state[:messages] || []) + [tool_message],
+        tool_call: nil
       }
     end
 
@@ -128,5 +148,34 @@ module LangGraphRB
       
       nil
     end
+
+    def normalize_tool_call(call)
+      # Supports shapes from OpenAI and our internal format
+      if call.is_a?(Hash)
+        if call[:name] && call[:arguments]
+          class_name = call[:name].to_s.split('__').first
+          name = call[:name].to_s.split('__').last
+          return {
+            id: call[:id],
+            name: name.to_sym,
+            class_name: class_name,
+            arguments: call[:arguments]
+          }
+        elsif call[:function]
+          return {
+            id: call[:id],
+            name: (call.dig(:function, :name) || call.dig('function', 'name')).to_sym,
+            arguments: call.dig(:function, :arguments) || call.dig('function', 'arguments')
+          }
+        elsif call[:args]
+          return {
+            id: call[:id],
+            name: (call[:name] || call['name']).to_sym,
+            arguments: call[:args]
+          }
+        end
+      end
+      call
+    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/tool_definition.rb

@@ -0,0 +1,97 @@
+require 'json'
+
+module LangGraphRB
+  # Mixin to declare tool functions compatible with OpenAI tool/function calling
+  module ToolDefinition
+    def self.extended(base)
+      base.instance_variable_set(:@__tool_functions, {})
+    end
+
+    def define_function(name, description: "", &block)
+      class_name = self.name
+      fn_name = "#{class_name}__#{name}".to_sym
+      @__tool_functions ||= {}
+      @__tool_functions[fn_name] = {
+        name: fn_name,
+        description: description,
+        parameters: { type: 'object', properties: {}, required: [] }
+      }
+
+      # Evaluate the DSL inside a builder to collect properties
+      if block
+        builder = FunctionSchemaBuilder.new(@__tool_functions[fn_name][:parameters])
+        builder.instance_eval(&block)
+      end
+    end
+
+    def tool_functions
+      @__tool_functions || {}
+    end
+
+    def to_openai_tool_schema
+      # One class may expose multiple functions; return an array of tool entries
+      tool_functions.values.map do |fn|
+        {
+          type: 'function',
+          function: {
+            name: fn[:name].to_s,
+            description: fn[:description],
+            parameters: fn[:parameters]
+          }
+        }
+      end
+    end
+
+    class FunctionSchemaBuilder
+      def initialize(parameters)
+        @parameters = parameters
+      end
+
+      def property(name, type:, description: "", required: false)
+        @parameters[:properties][name.to_sym] = { type: type, description: description }
+        if required
+          @parameters[:required] ||= []
+          @parameters[:required] << name.to_sym
+        end
+      end
+    end
+  end
+
+  # Base class for tools using the ToolDefinition mixin
+  class ToolBase
+    extend ToolDefinition
+
+    def call(call_args)
+      # call_args: { name:, arguments: {} } or OpenAI-like hash
+      name = call_args[:name] || call_args['name']
+      args = call_args[:arguments] || call_args['arguments'] || {}
+      raise ArgumentError, 'Tool call missing name' if name.nil?
+
+      method_name = name.to_sym
+      unless respond_to?(method_name)
+        raise ArgumentError, "Undefined tool function: #{name}"
+      end
+
+      result = public_send(method_name, **symbolize_keys(args))
+      tool_response(result)
+    end
+
+    # Standardize tool responses; can be overridden by subclasses
+    def tool_response(payload)
+      payload
+    end
+
+    def to_openai_tool_schema
+      self.class.to_openai_tool_schema
+    end
+
+    private
+
+    def symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+      hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+    end
+  end
+end
+
+

data/lib/langgraph_rb/version.rb

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

data/lib/langgraph_rb.rb

@@ -9,6 +9,10 @@ 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'
 
 module LangGraphRB
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langgraph_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Julian Toro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-16 00:00:00.000000000 Z
+date: 2025-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.24.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.24.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -111,6 +125,8 @@ files:
 - SUMMARY.md
 - examples/advanced_example.rb
 - examples/basic_example.rb
+- examples/chat_openai_tools_example.rb
+- examples/conditional_example.rb
 - examples/initial_state_example.rb
 - examples/langfuse_example.rb
 - examples/llmnode_example.rb
@@ -119,16 +135,20 @@ files:
 - examples/simple_test.rb
 - langgraph_rb.gemspec
 - lib/langgraph_rb.rb
+- lib/langgraph_rb/chat_openai.rb
 - lib/langgraph_rb/command.rb
 - lib/langgraph_rb/edge.rb
 - lib/langgraph_rb/graph.rb
+- 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
 - lib/langgraph_rb/state.rb
 - lib/langgraph_rb/stores/memory.rb
+- lib/langgraph_rb/tool_definition.rb
 - lib/langgraph_rb/version.rb
 - test_runner.rb
 homepage: https://github.com/fulit103/langgraph_rb