langgraph_rb 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5649cc9cef30c96380dc2ccd9a5c576af8d3efd7e02552b03d81cb45360f408
-  data.tar.gz: 3c706c127ac2fbd5e9d8a0be723575228a21d9ff91672169dc66174cd8dba3c5
+  metadata.gz: faa20cb53b8c5f9c1ea8d740d34ea63eadfe9e07a49683dd3c090f7bb042d3fd
+  data.tar.gz: 56bfc5f8fb39473af9252caf1573f1126e30405f37ee7ac45bfde6704df20575
 SHA512:
-  metadata.gz: 7dd32ea2d6c98ae356596cee6ca0d697802e7107649faf63c598606f9b708a68cd7c72e72d4ad5423d136a72d74c242108c28b670f6ab2aea2cf3a18925f35d4
-  data.tar.gz: d6a30010935f797cc6ebbe3767db38c8726029956192b57cd69304d6b0238d3dd0bdb1b32d7d9b348bbc8ee4469f8b1fe62b750386834c9cb7ce52980f1f25a4
+  metadata.gz: 0f24fbb2f677bb13e7a8091807ff6d3f3d835b295ee691420f30b576bbd74d05eae9040d6511319eaefbc6c04170dc501101f3ff07f5a3e08c066a3d398adc3f
+  data.tar.gz: 91bdd7cf66e2c73fb5103d2fe469381bce46e889cacd6710a76c012d96296d3f0625dbc3b4e992570ef67ba3c506f8031058b3e6384304d0596e2c6f10dd8a6b

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,115 @@
+#!/usr/bin/env ruby
+require 'pry'
+require 'pry-byebug'
+require_relative '../lib/langgraph_rb'
+
+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)
+
+  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." 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
+
+    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!
+
+  start = { messages: [], input: "Find details about 'The Matrix'" }
+  result = graph.invoke(start)
+  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
+
+

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/tool_and_llm_example.rb

@@ -0,0 +1,145 @@
+#!/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 
+
+

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}"

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/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.5"
 end 

data/lib/langgraph_rb.rb

@@ -9,6 +9,9 @@ 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/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.5
 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,17 +125,22 @@ 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
 - 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
 - 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/logger.rb
@@ -129,6 +148,7 @@ files:
 - 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