llm_chain 0.5.5 → 0.6.0

data/examples/tools_example.rb

@@ -5,11 +5,9 @@ require_relative '../lib/llm_chain'
 puts "🛠️  LLMChain Tools Demo"
 puts "=" * 40
 
-# 1. Individual Tool Usage
 puts "\n1. 🧮 Calculator Tool"
 calculator = LLMChain::Tools::Calculator.new
 
-# Test mathematical expressions
 examples = [
   "15 * 7 + 3",
   "sqrt(144)",
@@ -21,7 +19,6 @@ examples.each do |expr|
   puts "📊 #{result[:formatted]}"
 end
 
-# 2. Web Search Tool
 puts "\n2. 🔍 Web Search Tool"
 search = LLMChain::Tools::WebSearch.new
 
@@ -45,15 +42,12 @@ search_queries.each do |query|
   end
 end
 
-# 3. Code Interpreter Tool
 puts "\n3. 💻 Code Interpreter Tool"
 interpreter = LLMChain::Tools::CodeInterpreter.new
 
-# Test Ruby code execution
 ruby_examples = [
   <<~RUBY,
     ```ruby
-    # Simple Fibonacci calculation
     a, b = 0, 1
     result = [a, b]
     8.times do
@@ -69,7 +63,6 @@ ruby_examples = [
   
   <<~RUBY
     ```ruby
-    # Data analysis example
     numbers = [23, 45, 67, 89, 12, 34, 56, 78]
     
     puts "Dataset: \#{numbers}"
@@ -97,159 +90,4 @@ ruby_examples.each_with_index do |code, i|
   rescue => e
     puts "❌ Execution error: #{e.message}"
   end
-end
-
-# 4. Tool Manager Usage
-puts "\n4. 🎯 Tool Manager"
-tool_manager = LLMChain::Tools::ToolManagerFactory.create_default_toolset
-
-puts "Registered tools: #{tool_manager.list_tools.map(&:name).join(', ')}"
-
-# Test tool matching
-test_prompts = [
-  "What is 25 squared?",
-  "Find information about Ruby gems",
-  "Run this code: puts 'Hello World'"
-]
-
-test_prompts.each do |prompt|
-  puts "\n🎯 Testing: \"#{prompt}\""
-  matched_tools = tool_manager.list_tools.select { |tool| tool.match?(prompt) }
-  
-  if matched_tools.any?
-    puts "   Matched tools: #{matched_tools.map(&:name).join(', ')}"
-    
-    # Execute with first matched tool
-    tool = matched_tools.first
-    result = tool.call(prompt)
-    puts "   Result: #{result[:formatted] || result.inspect}"
-  else
-    puts "   No tools matched"
-  end
-end
-
-# 5. LLM Chain with Tools
-puts "\n5. 🤖 LLM Chain with Tools"
-
-begin
-  # Create chain with tools (but without retriever for local testing)
-  chain = LLMChain::Chain.new(
-    model: "qwen3:1.7b",
-    tools: tool_manager,
-    retriever: false  # Disable RAG for this example
-  )
-  
-  # Test queries that should trigger tools
-  test_queries = [
-    "Calculate the area of a circle with radius 5 (use pi = 3.14159)",
-    "What's the latest news about Ruby programming?",
-    "Execute this Ruby code: puts (1..100).select(&:even?).sum"
-  ]
-  
-  test_queries.each_with_index do |query, i|
-    puts "\n🤖 Query #{i+1}: #{query}"
-    puts "🔄 Processing..."
-    
-    response = chain.ask(query)
-    puts "📝 Response: #{response}"
-    puts "-" * 40
-  end
-  
-rescue => e
-  puts "❌ Error with LLM Chain: #{e.message}"
-  puts "💡 Make sure Ollama is running with qwen3:1.7b model"
-end
-
-# 6. Custom Tool Example
-puts "\n6. 🔧 Custom Tool Example"
-
-# Create a simple DateTime tool
-class DateTimeTool < LLMChain::Tools::BaseTool
-  def initialize
-    super(
-      name: "datetime",
-      description: "Gets current date and time information",
-      parameters: {
-        format: { 
-          type: "string", 
-          description: "Date format (optional)" 
-        }
-      }
-    )
-  end
-
-  def match?(prompt)
-    contains_keywords?(prompt, ['time', 'date', 'now', 'current', 'today'])
-  end
-
-  def call(prompt, context: {})
-    now = Time.now
-    
-    # Try to detect desired format from prompt
-    format = if prompt.match?(/iso|standard/i)
-               now.iso8601
-             elsif prompt.match?(/human|readable/i)
-               now.strftime("%B %d, %Y at %I:%M %p")
-             else
-               now.to_s
-             end
-    
-    {
-      timestamp: now.to_i,
-      formatted_time: format,
-      timezone: now.zone,
-      formatted: "Current time: #{format} (#{now.zone})"
-    }
-  end
-end
-
-# Test custom tool
-datetime_tool = DateTimeTool.new
-time_queries = [
-  "What time is it now?",
-  "Give me current date in human readable format",
-  "Show me the current time in ISO format"
-]
-
-time_queries.each do |query|
-  puts "\n🕐 Query: #{query}"
-  if datetime_tool.match?(query)
-    result = datetime_tool.call(query)
-    puts "   #{result[:formatted]}"
-  else
-    puts "   Query didn't match datetime tool"
-  end
-end
-
-# 7. Configuration-based Tool Setup
-puts "\n7. ⚙️  Configuration-based Tools"
-
-tools_config = [
-  { 
-    class: 'calculator' 
-  },
-  { 
-    class: 'web_search',
-    options: { 
-      search_engine: :duckduckgo 
-    }
-  },
-  { 
-    class: 'code_interpreter',
-    options: { 
-      timeout: 30,
-      allowed_languages: ['ruby', 'python'] 
-    }
-  }
-]
-
-config_tool_manager = LLMChain::Tools::ToolManagerFactory.from_config(tools_config)
-puts "Tools from config: #{config_tool_manager.list_tools.map(&:name).join(', ')}"
-
-# Test configuration-based setup
-config_result = config_tool_manager.execute_tool('calculator', 'What is 99 * 99?')
-puts "Config test result: #{config_result[:formatted]}" if config_result
-
-puts "\n" + "=" * 40
-puts "✨ Tools demo completed!"
-puts "\nTry running the chain with: ruby -I lib examples/quick_demo.rb" 
+end 

data/lib/llm_chain/agents/agent_factory.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative '../interfaces/agent'
+
+module LLMChain
+  module Agents
+    # Factory for creating different types of agents
+    # 
+    # Provides a centralized way to instantiate agents with proper configuration.
+    # Supports dependency injection and easy extension for new agent types.
+    #
+    # @example Basic usage
+    #   agent = AgentFactory.create(type: :react, model: "qwen3:1.7b")
+    #   result = agent.run("Analyze this data")
+    #
+    # @example With custom tools and memory
+    #   agent = AgentFactory.create(
+    #     type: :react,
+    #     model: "gpt-4",
+    #     tools: custom_tool_manager,
+    #     memory: redis_memory
+    #   )
+    #
+    # @example Registering custom agent
+    #   class MyCustomAgent < LLMChain::Interfaces::Agent
+    #     # implementation
+    #   end
+    #   
+    #   AgentFactory.register(:my_custom, MyCustomAgent)
+    #   agent = AgentFactory.create(type: :my_custom)
+    class AgentFactory
+      @registry = {}
+      @descriptions = {}
+
+      # Register a custom agent class
+      # @param type [Symbol] agent type identifier
+      # @param agent_class [Class] agent class that implements LLMChain::Interfaces::Agent
+      # @param description [String] human-readable description of the agent
+      # @return [void]
+      def self.register(type, agent_class, description: nil)
+        unless agent_class.ancestors.include?(LLMChain::Interfaces::Agent)
+          raise ArgumentError, "Agent class must implement LLMChain::Interfaces::Agent"
+        end
+        
+        @registry[type.to_sym] = agent_class
+        @descriptions[type.to_sym] = description || "Custom agent: #{agent_class.name}"
+      end
+
+      # Create an agent instance by type
+      # @param type [Symbol] the type of agent to create
+      # @param model [String] LLM model identifier
+      # @param tools [LLMChain::Interfaces::ToolManager] tool manager
+      # @param memory [LLMChain::Interfaces::Memory] memory backend
+      # @param max_iterations [Integer] maximum reasoning iterations (for ReAct)
+      # @param client_options [Hash] additional client options
+      # @return [LLMChain::Interfaces::Agent] agent instance
+      # @raise [ArgumentError] when agent type is unknown
+      def self.create(
+        type:,
+        model: nil,
+        tools: nil,
+        memory: nil,
+        max_iterations: 5,
+        **client_options
+      )
+        type_sym = type.to_sym
+        
+        # Get registered agent class
+        agent_class = @registry[type_sym]
+        unless agent_class
+          raise ArgumentError, "Unknown agent type: #{type}. Supported types: #{supported_types.join(', ')}"
+        end
+
+        # Create agent instance with standard parameters
+        agent_class.new(
+          model: model || LLMChain.configuration.default_model,
+          tools: tools || LLMChain::Tools::ToolManagerFactory.create_default_toolset,
+          memory: memory || LLMChain::Memory::Array.new,
+          max_iterations: max_iterations,
+          **client_options
+        )
+      end
+
+      # Get list of supported agent types
+      # @return [Array<Symbol>] supported agent types
+      def self.supported_types
+        @registry.keys
+      end
+
+      # Check if agent type is supported
+      # @param type [Symbol] agent type to check
+      # @return [Boolean] whether the type is supported
+      def self.supported?(type)
+        supported_types.include?(type.to_sym)
+      end
+
+      # Get description of available agent types
+      # @return [Hash<Symbol, String>] agent type descriptions
+      def self.agent_descriptions
+        @descriptions
+      end
+
+      # Unregister a custom agent
+      # @param type [Symbol] agent type to unregister
+      # @return [void]
+      def self.unregister(type)
+        type_sym = type.to_sym
+        @registry.delete(type_sym)
+        @descriptions.delete(type_sym)
+      end
+
+      # Get registered agent class
+      # @param type [Symbol] agent type
+      # @return [Class, nil] agent class or nil if not registered
+      def self.get_registered_agent(type)
+        @registry[type.to_sym]
+      end
+    end
+  end
+end 

data/lib/llm_chain/agents/composite_agent.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require_relative '../interfaces/agent'
+require_relative 'agent_factory'
+require_relative 'planner_agent'
+require_relative 'react_agent'
+
+module LLMChain
+  module Agents
+    # Composite agent that combines planning and execution capabilities.
+    #
+    # This agent uses a PlannerAgent to decompose complex tasks into atomic steps,
+    # then uses a ReActAgent to execute each step. This provides better handling
+    # of multi-step tasks compared to using ReActAgent alone.
+    #
+    # @example Basic usage
+    #   agent = LLMChain::Agents::CompositeAgent.new(
+    #     model: "qwen3:1.7b",
+    #     tools: tool_manager
+    #   )
+    #   result = agent.run("Find the president of the US and the capital of France")
+    class CompositeAgent < LLMChain::Interfaces::Agent
+      attr_reader :model, :tools, :memory, :planner, :executor
+
+      # Initialize the composite agent with planning and execution capabilities.
+      # @param model [String] LLM model identifier
+      # @param tools [LLMChain::Interfaces::ToolManager] tool manager
+      # @param memory [LLMChain::Interfaces::Memory] memory backend
+      # @param max_iterations [Integer] maximum reasoning iterations for executor
+      # @param client_options [Hash] additional client options
+      def initialize(model:, tools:, memory: nil, max_iterations: 3, **client_options)
+        @model = model
+        @tools = tools
+        @memory = memory || LLMChain::Memory::Array.new
+        @max_iterations = max_iterations
+        
+        # Create planner and executor agents through factory
+        @planner = AgentFactory.create(
+          type: :planner,
+          model: @model,
+          **client_options
+        )
+        @executor = AgentFactory.create(
+          type: :react,
+          model: @model,
+          tools: @tools,
+          memory: @memory,
+          max_iterations: @max_iterations,
+          **client_options
+        )
+      end
+
+      # Execute a task using planning and execution methodology.
+      # @param task [String] the task to accomplish
+      # @param stream [Boolean] whether to stream reasoning steps
+      # @yield [Hash] reasoning step information
+      # @return [Hash] final result with reasoning trace
+      def run(task, stream: false, &block)
+        # Step 1: Determine if task needs planning
+        use_planner = should_use_planner?(task)
+        
+        if use_planner
+          # Use planning approach for complex tasks
+          run_with_planning(task, stream: stream, &block)
+        else
+          # Use direct execution for simple tasks
+          execute_directly(task, stream: stream, &block)
+        end
+      end
+
+      # Check if this agent can handle the given task.
+      # @param task [String] task description
+      # @return [Boolean] whether this agent can handle the task
+      def can_handle?(task)
+        # Composite agent can handle any task that the planner or executor can handle
+        @planner.can_handle?(task) || @executor.can_handle?(task)
+      end
+
+      # Get description of agent capabilities.
+      # @return [String] agent description
+      def description
+        "Composite agent with intelligent planning and execution capabilities for complex multi-step tasks"
+      end
+
+      private
+
+      # Determine if task should use planning approach
+      # @param task [String] the task to analyze
+      # @return [Boolean] whether to use planning
+      def should_use_planner?(task)
+        # Simple tasks that don't need planning
+        simple_patterns = [
+          /\bcalculate\s+\d+\s*[\+\-\*\/]\s*\d+\b/i,
+          /\bwhat\s+is\s+\d+\s*[\+\-\*\/]\s*\d+\b/i,
+          /\b\d+\s*[\+\-\*\/]\s*\d+\b/,
+          /\bwhat\s+time\s+is\s+it\b/i,
+          /\bcurrent\s+time\b/i,
+          /\bwhat\s+year\s+is\s+it\b/i,
+          /\bcurrent\s+date\b/i,
+          /\bwhat\s+time\b/i,
+          /\bcurrent\s+date\b/i
+        ]
+        
+        # Complex patterns that need planning
+        complex_patterns = [
+          /\band\b/i,
+          /\bthen\b/i,
+          /\bnext\b/i,
+          /\bfind\b.*\band\b/i,
+          /\bsearch\b.*\band\b/i,
+          /\bget\b.*\band\b/i,
+          /\bcalculate\b.*\band\b/i,
+          /\bwhat\s+is\b.*\band\b/i
+        ]
+        
+        # Check if task matches simple patterns
+        return false if simple_patterns.any? { |pattern| task.match?(pattern) }
+        
+        # Check if task matches complex patterns
+        return true if complex_patterns.any? { |pattern| task.match?(pattern) }
+        
+        # Default to planning for tasks longer than 50 characters
+        task.length > 50
+      end
+
+      # Run task with planning approach
+      # @param task [String] the task to accomplish
+      # @param stream [Boolean] whether to stream reasoning steps
+      # @yield [Hash] reasoning step information
+      # @return [Hash] final result with reasoning trace
+      def run_with_planning(task, stream: false, &block)
+        # Step 1: Plan - Decompose the task into atomic steps
+        planning_result = @planner.run(task, stream: stream, &block)
+        steps = planning_result[:steps] || [task]
+        
+        # Step 2: Execute - Run each step with the executor
+        execution_results = []
+        validated_answers = []
+        
+        steps.each_with_index do |step, index|
+          step_result = @executor.run(step, stream: stream, &block)
+          execution_results << step_result
+          
+          # Validate and process the result
+          validated_answer = validate_and_process_result(step_result, step, index + 1)
+          validated_answers << validated_answer if validated_answer
+          
+          # Yield step completion if streaming
+          if block_given? && stream
+            yield({
+              step: index + 1,
+              total_steps: steps.length,
+              current_step: step,
+              step_result: step_result,
+              validated_answer: validated_answer,
+              type: "step_completion"
+            })
+          end
+        end
+        
+        # Step 3: Compile final result with smart aggregation
+        final_answer = smart_aggregate_results(validated_answers, task)
+        
+        {
+          task: task,
+          final_answer: final_answer,
+          reasoning_trace: [
+            {
+              step: 1,
+              action: "plan",
+              action_input: task,
+              observation: "Decomposed into #{steps.length} steps: #{steps.join(', ')}"
+            },
+            *execution_results.flat_map { |result| result[:reasoning_trace] }
+          ],
+          iterations: execution_results.sum { |result| result[:iterations] || 0 },
+          success: validate_overall_success(execution_results, validated_answers, task),
+          planning_result: planning_result,
+          execution_results: execution_results,
+          validated_answers: validated_answers
+        }
+      end
+
+      # Execute task directly without planning
+      # @param task [String] the task to accomplish
+      # @param stream [Boolean] whether to stream reasoning steps
+      # @yield [Hash] reasoning step information
+      # @return [Hash] final result with reasoning trace
+      def execute_directly(task, stream: false, &block)
+        result = @executor.run(task, stream: stream, &block)
+        
+        {
+          task: task,
+          final_answer: result[:final_answer],
+          reasoning_trace: result[:reasoning_trace],
+          iterations: result[:iterations],
+          success: result[:success],
+          planning_result: { steps: [task] },
+          execution_results: [result],
+          validated_answers: [],
+          approach: "direct"
+        }
+      end
+
+      # Validate and process execution result
+      # @param result [Hash] execution result
+      # @param step [String] step description
+      # @param step_number [Integer] step number
+      # @return [Hash, nil] validated and processed result
+      def validate_and_process_result(result, step, step_number)
+        return nil unless result[:success] && result[:final_answer]
+        
+        answer = result[:final_answer]
+        
+        # Check for error indicators
+        error_indicators = [
+          "unable to complete",
+          "insufficient data",
+          "error",
+          "failed",
+          "please provide",
+          "no results found"
+        ]
+        
+        return nil if error_indicators.any? { |indicator| answer.downcase.include?(indicator) }
+        
+        # Extract meaningful information based on step type
+        processed_answer = extract_meaningful_info(answer, step)
+        
+        {
+          step_number: step_number,
+          step: step,
+          original_answer: answer,
+          processed_answer: processed_answer,
+          quality_score: calculate_quality_score(answer, step)
+        }
+      end
+
+      # Extract meaningful information from answer
+      # @param answer [String] original answer
+      # @param step [String] step description
+      # @return [String] processed answer
+      def extract_meaningful_info(answer, step)
+        # For mathematical calculations, extract the result
+        if step.match?(/\b(calculate|add|multiply|divide|subtract)\b/i)
+          # Look for numbers in the answer
+          numbers = answer.scan(/\d+/).map(&:to_i)
+          return numbers.last.to_s if numbers.any?
+        end
+        
+        # For time/date queries, extract the formatted time
+        if step.match?(/\b(time|date|year)\b/i) && answer.include?("formatted")
+          # Extract the formatted time from JSON
+          if match = answer.match(/"formatted":\s*"([^"]+)"/)
+            return match[1]
+          end
+        end
+        
+        # For web search results, extract the most relevant snippet
+        if answer.include?("Search results") && answer.include?("snippet")
+          # Extract first meaningful snippet
+          if match = answer.match(/"snippet":\s*"([^"]+)"/)
+            return match[1].gsub(/\.\.\./, '').strip
+          end
+        end
+        
+        # Default: return first 100 characters
+        answer.length > 100 ? answer[0..100] + "..." : answer
+      end
+
+      # Calculate quality score for answer
+      # @param answer [String] answer to score
+      # @param step [String] step description
+      # @return [Integer] quality score (0-10)
+      def calculate_quality_score(answer, step)
+        score = 5 # Base score
+        
+        # Penalize error indicators
+        error_indicators = ["unable to complete", "insufficient data", "error", "failed"]
+        score -= 3 if error_indicators.any? { |indicator| answer.downcase.include?(indicator) }
+        
+        # Reward meaningful content
+        score += 2 if answer.length > 20
+        score += 1 if answer.match?(/\d+/)
+        score += 1 if answer.match?(/[A-Za-z]+/)
+        
+        # Reward specific content types
+        score += 2 if step.match?(/\b(calculate|add|multiply)\b/i) && answer.match?(/\d+/)
+        score += 2 if step.match?(/\b(time|date)\b/i) && answer.include?("formatted")
+        score += 2 if step.match?(/\b(search|find)\b/i) && answer.include?("results")
+        
+        [score, 10].min # Cap at 10
+      end
+
+      # Smart aggregation of results
+      # @param validated_answers [Array] validated answers
+      # @param original_task [String] original task
+      # @return [String] aggregated result
+      def smart_aggregate_results(validated_answers, original_task)
+        return "Task could not be completed successfully." if validated_answers.empty?
+        
+        # For single answer, return it directly
+        if validated_answers.length == 1
+          return validated_answers.first[:processed_answer]
+        end
+        
+        # For multiple answers, create a structured response
+        parts = []
+        validated_answers.each_with_index do |answer, index|
+          parts << "Part #{index + 1}: #{answer[:processed_answer]}"
+        end
+        
+        # Add summary if it's a complex task
+        if original_task.match?(/\band\b/i)
+          parts << "\nSummary: All requested information has been gathered."
+        end
+        
+        parts.join("\n\n")
+      end
+
+      # Validate overall success
+      # @param execution_results [Array] execution results
+      # @param validated_answers [Array] validated answers
+      # @param task [String] original task
+      # @return [Boolean] overall success
+      def validate_overall_success(execution_results, validated_answers, task)
+        # Check if we have any valid answers
+        return false if validated_answers.empty?
+        
+        # For simple tasks, one good answer is enough
+        return true unless task.match?(/\band\b/i)
+        
+        # For complex tasks, we need at least 50% of expected parts
+        expected_parts = task.scan(/\band\b/i).length + 1
+        actual_parts = validated_answers.length
+        
+        actual_parts >= (expected_parts * 0.5).ceil
+      end
+    end
+  end
+end