llm_chain 0.5.5 → 0.6.0

data/lib/llm_chain/agents/planner_agent.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative '../interfaces/agent'
+require_relative '../client_registry'
+
+module LLMChain
+  module Agents
+    # Agent that decomposes a complex user request into a sequence of atomic steps.
+    #
+    # The agent uses the same model system as other agents in the framework.
+    # It creates a client through the ClientRegistry based on the provided model.
+    #
+    # @example Basic usage
+    #   planner = LLMChain::Agents::PlannerAgent.new(model: "qwen3:1.7b")
+    #   steps = planner.plan("Find the president of the US and the capital of France")
+    #   # => ["Find the president of the US", "Find the capital of France"]
+    class PlannerAgent < LLMChain::Interfaces::Agent
+      attr_reader :model, :client
+
+      # Initialize the planner agent with a model identifier.
+      # @param model [String] LLM model identifier
+      # @param client_options [Hash] additional client options
+      def initialize(model:, **client_options)
+        @model = model
+        @client = LLMChain::ClientRegistry.client_for(@model, **client_options)
+      end
+
+      # Decompose a complex user task into a sequence of atomic steps.
+      # @param task [String] The complex user request to decompose.
+      # @return [Array<String>] The list of atomic steps (one per string).
+      # @example
+      #   planner = PlannerAgent.new(client: my_llm_client)
+      #   steps = planner.plan("Find the president of the US and the capital of France")
+      #   # => ["Find the president of the US", "Find the capital of France"]
+      def plan(task)
+        prompt = <<~PROMPT
+          Decompose the following user request into a minimal sequence of atomic steps.
+          Return only the steps, one per line, no explanations, *no numbering*.
+
+          User request:
+          #{task}
+
+          Steps:
+        PROMPT
+
+        response = @client.chat(prompt)
+        response.lines.map(&:strip).reject(&:empty?)
+      end
+
+      # Check if this agent can handle the given task
+      # @param task [String] The user request
+      # @return [Boolean] Whether this agent can handle the task
+      def can_handle?(task)
+        !task.nil? && !task.strip.empty?
+      end
+
+      # Execute a task using the agent's capabilities
+      # @param task [String] the task to accomplish
+      # @param stream [Boolean] whether to stream reasoning steps
+      # @yield [Hash] reasoning step information (when streaming)
+      # @return [Hash] execution result with reasoning trace
+      def run(task, stream: false, &block)
+        steps = plan(task)
+        
+        result = {
+          task: task,
+          steps: steps,
+          result: steps.join("\n\n"),
+          reasoning_trace: [
+            {
+              step: 1,
+              action: "plan",
+              action_input: task,
+              observation: "Decomposed into #{steps.length} steps: #{steps.join(', ')}"
+            }
+          ]
+        }
+        
+        yield(result) if block_given? && stream
+        result
+      end
+
+      # Get the model identifier used by this agent
+      # @return [String] model name
+      def model
+        @model
+      end
+
+      # Get the tool manager available to this agent
+      # @return [LLMChain::Interfaces::ToolManager] tool manager
+      def tools
+        nil # Planner doesn't use tools directly
+      end
+
+      # Get the memory system used by this agent
+      # @return [LLMChain::Interfaces::Memory] memory backend
+      def memory
+        nil # Planner doesn't use memory
+      end
+
+      # Get description of agent capabilities
+      # @return [String] Agent description
+      def description
+        "Planner agent that decomposes complex tasks into atomic steps."
+      end
+    end
+  end
+end 

data/lib/llm_chain/agents/react_agent.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require_relative '../interfaces/agent'
+require_relative '../client_registry'
+
+module LLMChain
+  module Agents
+    # ReAct Agent implements the Reasoning + Acting paradigm
+    # 
+    # The agent follows this cycle:
+    # 1. **Reasoning**: Analyze the task and plan steps
+    # 2. **Acting**: Execute tools based on the plan
+    # 3. **Observing**: Evaluate results and adjust plan
+    # 4. **Repeating**: Continue until task completion
+    #
+    # @example Basic usage
+    #   agent = ReActAgent.new(
+    #     model: "qwen3:1.7b",
+    #     tools: ToolManagerFactory.create_default_toolset,
+    #     max_iterations: 5
+    #   )
+    #   
+    #   result = agent.run("Find the weather in Moscow and calculate the average temperature for the week")
+    class ReActAgent < LLMChain::Interfaces::Agent
+
+      attr_reader :model, :tools, :memory, :max_iterations, :client
+
+      # Initialize ReAct agent
+      # @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
+      # @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
+        @client = LLMChain::ClientRegistry.client_for(@model, **client_options)
+      end
+
+      # Execute a task using ReAct 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)
+        # Special case: if asking about available tools, return immediately
+        if task.downcase.include?("tools") && (task.downcase.include?("available") || task.downcase.include?("which"))
+          return {
+            task: task,
+            final_answer: "Available tools: #{@tools.list_tools.map(&:name).join(', ')}",
+            reasoning_trace: [],
+            iterations: 0,
+            success: true
+          }
+        end
+        
+        reasoning_trace = []
+        current_state = { task: task, observations: [] }
+        failed_actions = {}  # Track failed actions to avoid repetition
+        
+        @max_iterations.times do |iteration|
+          # Step 1: Reasoning - Analyze current state and plan next action
+          reasoning_step = reason(current_state, reasoning_trace, failed_actions)
+          reasoning_trace << reasoning_step
+          
+          yield reasoning_step if block_given? && stream
+          
+          # Step 2: Acting - Execute planned action
+          action_result = act(reasoning_step)
+          reasoning_trace.last[:action_result] = action_result
+          
+          # Step 3: Observing - Update state with results
+          current_state[:observations] << action_result
+          
+          # Track failed actions
+          if !action_result[:success] || action_result[:formatted].include?("error")
+            action_key = "#{reasoning_step[:action]}:#{reasoning_step[:action_input]}"
+            failed_actions[action_key] = (failed_actions[action_key] || 0) + 1
+          end
+          
+          # Step 4: Check if task is complete
+          if reasoning_step[:thought].include?("FINAL ANSWER") || 
+             reasoning_step[:thought].include?("Task completed") ||
+             (action_result[:success] && !action_result[:formatted].include?("error") && 
+              action_result[:formatted].length > 100 && !action_result[:formatted].include?("timezone"))
+            break
+          end
+          
+          # Stop if too many failures
+          if failed_actions.values.any? { |count| count >= 3 }
+            break
+          end
+        end
+        
+        # Extract final answer from reasoning trace
+        final_answer = extract_final_answer(reasoning_trace)
+        
+        {
+          task: task,
+          final_answer: final_answer,
+          reasoning_trace: reasoning_trace,
+          iterations: reasoning_trace.length,
+          success: !final_answer.nil? && !final_answer.empty? && !final_answer.include?("error")
+        }
+      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)
+        # ReAct agent can handle complex multi-step tasks
+        task.include?("analyze") || 
+        task.include?("find") && task.include?("and") ||
+        task.include?("calculate") && task.include?("and") ||
+        task.length > 50  # Long tasks likely need reasoning
+      end
+
+      # Get description of agent capabilities
+      # @return [String] agent description
+      def description
+        "ReAct agent with reasoning and acting capabilities for complex multi-step tasks"
+      end
+
+      private
+
+      # Generate reasoning step based on current state
+      # @param state [Hash] current state including task and observations
+      # @param trace [Array] previous reasoning steps
+      # @param failed_actions [Hash] tracking of failed actions
+      # @return [Hash] reasoning step with thought and action
+      def reason(state, trace, failed_actions)
+        prompt = build_reasoning_prompt(state, trace, failed_actions)
+        response = @client.chat(prompt)
+        parsed = parse_reasoning_response(response)
+        
+        {
+          iteration: trace.length + 1,
+          thought: parsed[:thought],
+          action: parsed[:action],
+          action_input: parsed[:action_input],
+          timestamp: Time.now
+        }
+      end
+
+      # Execute the planned action using available tools
+      # @param reasoning_step [Hash] the reasoning step with action details
+      # @return [Hash] action execution result
+      def act(reasoning_step)
+        action = reasoning_step[:action]
+        action_input = reasoning_step[:action_input]
+        
+        return { success: false, error: "No action specified" } unless action
+        
+        tool = @tools.get_tool(action)
+        return { success: false, error: "Tool '#{action}' not found" } unless tool
+        
+        begin
+          result = tool.call(action_input)
+          {
+            success: true,
+            tool: action,
+            input: action_input,
+            result: result,
+            formatted: tool.format_result(result)
+          }
+        rescue => e
+          {
+            success: false,
+            tool: action,
+            input: action_input,
+            error: e.message
+          }
+        end
+      end
+
+      # Build prompt for reasoning step
+      # @param state [Hash] current state
+      # @param trace [Array] reasoning trace
+      # @param failed_actions [Hash] tracking of failed actions
+      # @return [String] formatted prompt
+      def build_reasoning_prompt(state, trace, failed_actions)
+        tools_description = @tools.tools_description
+        observations = state[:observations].map { |obs| obs[:formatted] }.join("\n")
+        
+        failed_actions_info = if failed_actions.any?
+          "Failed actions (avoid repeating):\n" + 
+          failed_actions.map { |action, count| "  #{action} (failed #{count} times)" }.join("\n")
+        else
+          "No failed actions yet"
+        end
+        
+        <<~PROMPT
+          You are a ReAct agent. Your task is: #{state[:task]}
+
+          Available tools:
+          #{tools_description}
+
+          Previous observations:
+          #{observations.empty? ? "None" : observations}
+
+          #{failed_actions_info}
+
+          Instructions:
+          - For calculations: Use calculator tool, then provide FINAL ANSWER
+          - For web searches: Use web_search tool, maximize requests as much as possible to get the most relevant information
+          - For dates and time: Use date_time tool with empty input or timezone name (e.g., "Moscow", "New York")
+          - For multiple timezones: Use date_time tool multiple times, once for each timezone
+          - For current information searches: ALWAYS first use date_time tool to get current date, then use web_search with current year
+          - For questions about current subjects, or recent events: First get current date with date_time, then search
+          - If you need to pass a date to web_search, use date_time tool to get the date in the correct format
+          - For code: Use code_interpreter tool
+          - For multi-step tasks (with "and"): Complete ALL steps before FINAL ANSWER
+          - After getting a good result, provide FINAL ANSWER
+          - Don't repeat failed actions
+          - Summarize the result in a few words
+          
+          IMPORTANT: When searching for current information (recent events), 
+          you MUST first use date_time tool to get the current year, then include that year in your web_search query.
+
+          Format:
+          Thought: [brief reasoning]
+          Action: [tool_name]
+          Action Input: [input]
+
+          Or when done:
+          Thought: [reasoning]
+          FINAL ANSWER: [answer]
+        PROMPT
+      end
+
+      # Format reasoning trace for prompt
+      # @param trace [Array] reasoning trace
+      # @return [String] formatted trace
+      def format_reasoning_trace(trace)
+        return "None" if trace.empty?
+        
+        trace.map do |step|
+          "Step #{step[:iteration]}: #{step[:thought]}"
+        end.join("\n")
+      end
+
+      # Parse LLM response to extract reasoning components
+      # @param response [String] LLM response
+      # @return [Hash] parsed thought, action, and action_input
+      def parse_reasoning_response(response)
+        # Try to extract structured response
+        if response.include?("Thought:") && response.include?("Action:")
+          thought_match = response.match(/Thought:\s*(.*?)(?=Action:|$)/m)
+          action_match = response.match(/Action:\s*(\w+)/)
+          input_match = response.match(/Action Input:\s*(.*?)(?=\n|$)/m)
+          
+          action_input = input_match&.[](1)&.strip
+          
+          # Clean up action input - remove markdown code blocks if present
+          if action_input&.start_with?("```")
+            action_input = action_input.gsub(/^```\w*\n/, "").gsub(/\n```$/, "")
+          end
+          
+          {
+            thought: thought_match&.[](1)&.strip || response,
+            action: action_match&.[](1),
+            action_input: action_input
+          }
+        else
+          # Fallback: treat entire response as thought
+          {
+            thought: response,
+            action: nil,
+            action_input: nil
+          }
+        end
+      end
+
+      # Extract final answer from reasoning trace
+      # @param trace [Array] reasoning trace
+      # @return [String] final answer
+      def extract_final_answer(trace)
+        # Look for FINAL ANSWER in the last reasoning step
+        last_step = trace.last
+        return nil unless last_step
+        
+        thought = last_step[:thought]
+        if thought.include?("FINAL ANSWER:")
+          thought.match(/FINAL ANSWER:\s*(.*)/m)&.[](1)&.strip
+        elsif last_step[:action_result]&.[](:success)
+          result = last_step[:action_result][:formatted]
+          # If result is JSON with error, try to get a better answer
+          if result.include?("error")
+            # Look for successful results in previous steps
+            trace.reverse.each do |step|
+              if step[:action_result]&.[](:success) && !step[:action_result][:formatted].include?("error")
+                return step[:action_result][:formatted]
+              end
+            end
+            return "Unable to complete task after #{trace.length} attempts"
+          else
+            result
+          end
+        else
+          thought
+        end
+      end
+    end
+  end
+end 

data/lib/llm_chain/agents.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'interfaces/agent'
+require_relative 'agents/agent_factory'
+require_relative 'agents/react_agent'
+require_relative 'agents/planner_agent'
+require_relative 'agents/composite_agent'
+
+module LLMChain
+  module Agents
+    # Register built-in agents
+    AgentFactory.register(:react, ReActAgent, description: "ReAct agent with reasoning and acting capabilities")
+    AgentFactory.register(:planner, PlannerAgent, description: "Planner agent that decomposes complex tasks into atomic steps.")
+    AgentFactory.register(:composite, CompositeAgent, description: "Composite agent with planning and execution capabilities for complex multi-step tasks")
+    
+    # Add more built-in agents here as they are implemented
+    # AgentFactory.register(:tool_using, ToolUsingAgent, "Simple tool-using agent")
+  end
+end 

data/lib/llm_chain/clients/gemma3.rb

@@ -4,6 +4,7 @@ require 'json'
 module LLMChain
   module Clients
     class Gemma3 < OllamaBase
+      class InvalidModelVersion < StandardError; end unless const_defined?(:InvalidModelVersion)
       # Доступные версии моделей Gemma3
       MODEL_VERSIONS = {
         gemma3: {
@@ -135,9 +136,10 @@ module LLMChain
 
       def clean_response(text)
         tags = INTERNAL_TAGS[:common].merge(INTERNAL_TAGS[model_version] || {})
-        tags.values.reduce(text) do |processed, regex|
-          processed.gsub(regex, '')
-        end.gsub(/\n{3,}/, "\n\n").strip
+        processed = tags.values.reduce(text) do |acc, regex|
+          acc.gsub(regex, "\n")
+        end
+        processed.gsub(/\n{2,}/, "\n\n").strip
       end
     end
   end

data/lib/llm_chain/clients/openai.rb

@@ -21,7 +21,7 @@ module LLMChain
         @default_options = DEFAULT_OPTIONS.merge(options)
       end
 
-      def chat(messages, stream: false, **options)
+      def chat(messages, stream: false, **options, &block)
         params = build_request_params(messages, stream: stream, **options)
 
         if stream

data/lib/llm_chain/clients/qwen.rb

@@ -4,6 +4,7 @@ require 'json'
 module LLMChain
   module Clients
     class Qwen < OllamaBase
+      class InvalidModelVersion < StandardError; end unless defined?(InvalidModelVersion)
       # Доступные версии моделей
       MODEL_VERSIONS = {
         qwen: {
@@ -47,7 +48,11 @@ module LLMChain
           reasoning: /<reasoning>.*?<\/reasoning>\s*/mi
         },
         qwen: {
-          system: /<\|system\|>.*?<\|im_end\|>\s*/mi
+          system: /<\|system\|>.*?<\|im_end\|>\s*/mi,
+          qwen_meta: /<qwen_meta>.*?<\/qwen_meta>\s*/mi
+        },
+        qwen2: {
+          qwen_meta: /<qwen_meta>.*?<\/qwen_meta>\s*/mi
         },
         qwen3: {
           qwen_meta: /<qwen_meta>.*?<\/qwen_meta>\s*/mi
@@ -55,11 +60,9 @@ module LLMChain
       }.freeze
 
       def initialize(model: nil, base_url: nil, **options)
-        model ||= detect_default_model
-
+        model ||= detect_default_model_from(model)
         @model = model
         validate_model_version(@model)
-
         super(
           model: @model,
           base_url: base_url,
@@ -105,18 +108,22 @@ module LLMChain
 
       private
 
+      def model_version_for(model)
+        return :qwen3 if model&.start_with?('qwen3:')
+        return :qwen2 if model&.start_with?('qwen2:')
+        :qwen
+      end
+
       def model_version
-        if @model.start_with?('qwen3:')
-          :qwen3
-        elsif @model.start_with?('qwen2:')
-          :qwen2
-        else
-          :qwen
-        end
+        model_version_for(@model)
+      end
+
+      def detect_default_model_from(model)
+        MODEL_VERSIONS[model_version_for(model)][:default]
       end
 
       def detect_default_model
-        MODEL_VERSIONS[model_version][:default]
+        detect_default_model_from(nil)
       end
 
       def validate_model_version(model)
@@ -151,9 +158,14 @@ module LLMChain
 
       def clean_response(text)
         tags = INTERNAL_TAGS[:common].merge(INTERNAL_TAGS[model_version] || {})
-        tags.values.reduce(text) do |processed, regex|
-          processed.gsub(regex, '')
-        end.gsub(/\n{3,}/, "\n\n").strip
+        # Добавляем <|system|>...<|im_end|> для qwen3, если не было
+        if model_version == :qwen3 && !tags.key?(:system)
+          tags[:system] = /<\|system\|>.*?<\|im_end\|>\s*/mi
+        end
+        processed = tags.values.reduce(text) do |acc, regex|
+          acc.gsub(regex, "\n")
+        end
+        processed.gsub(/\n{2,}/, "\n\n").strip
       end
     end
   end

data/lib/llm_chain/configuration_validator.rb

@@ -62,6 +62,8 @@ module LLMChain
       else
         add_warning("Unknown model type: #{model}. Proceeding with default settings.")
       end
+
+      validate_client_availability!(model)
     end
 
     def validate_openai_requirements!(model)
@@ -97,6 +99,8 @@ module LLMChain
         else
           add_warning("OpenAI API returned status #{response.code}. Service may be temporarily unavailable.")
         end
+      rescue ValidationError
+        raise
       rescue => e
         add_warning("Cannot verify OpenAI API availability: #{e.message}")
       end
@@ -300,8 +304,8 @@ module LLMChain
 
     def check_python_availability
       begin
-        output = `python3 --version 2>&1`
-        $?.success? && output.include?('Python')
+        out, status = Open3.capture2('python3 --version')
+        status.success? && out.include?('Python')
       rescue
         false
       end
@@ -309,8 +313,8 @@ module LLMChain
 
     def check_node_availability
       begin
-        output = `node --version 2>&1`
-        $?.success? && output.include?('v')
+        out, status = Open3.capture2('node --version')
+        status.success? && out.include?('v')
       rescue
         false
       end
@@ -318,9 +322,8 @@ module LLMChain
 
     def check_internet_connectivity
       begin
-        require 'socket'
-        Socket.tcp("8.8.8.8", 53, connect_timeout: 3) {}
-        true
+        resp = Net::HTTP.get_response(URI('https://www.google.com'))
+        resp.code == '200'
       rescue
         false
       end
@@ -335,6 +338,7 @@ module LLMChain
     end
 
     def add_warning(message)
+      @warnings ||= []
       @warnings << message
     end
 

data/lib/llm_chain/embeddings/clients/local/ollama_client.rb

@@ -55,6 +55,8 @@ module LLMChain
           def parse_response(response)
             data = JSON.parse(response.body)
             data['embedding'] or raise EmbeddingError, "No embedding in response"
+          rescue JSON::ParserError => e
+            raise EmbeddingError, "Invalid JSON: #{e.message}"
           end
 
           class EmbeddingError < StandardError; end

data/lib/llm_chain/embeddings/clients/local/weaviate_vector_store.rb

@@ -35,12 +35,12 @@ module LLMChain
 
           # Поиск по семантическому сходству
           def semantic_search(query, limit: 3, certainty: 0.7)
-            near_vector = "{ vector: #{@embedder.embed(query)}, certainty: 0.7 }"
+            near_vector = "{ vector: #{@embedder.embed(query)}, certainty: #{certainty} }"
 
             @client.query.get(
                 class_name: @class_name,
                 fields: "content metadata text",
-                limit: "1",
+                limit: limit.to_s,
                 offset: "1",
                 near_vector: near_vector,
             )

data/lib/llm_chain/interfaces/agent.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    # Abstract interface for all LLMChain agents
+    # 
+    # All agents must implement the run method and provide access to their
+    # model, tools, and memory. The constructor is left to individual implementations
+    # to allow for flexibility in parameter requirements.
+    #
+    # @abstract
+    class Agent
+      # Execute a task using the agent's capabilities
+      # @param task [String] the task to accomplish
+      # @param stream [Boolean] whether to stream reasoning steps
+      # @yield [Hash] reasoning step information (when streaming)
+      # @return [Hash] execution result with reasoning trace
+      def run(task, stream: false, &block)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Get the model identifier used by this agent
+      # @return [String] model name
+      def model
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Get the tool manager available to this agent
+      # @return [LLMChain::Interfaces::ToolManager] tool manager
+      def tools
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Get the memory system used by this agent
+      # @return [LLMChain::Interfaces::Memory] memory backend
+      def memory
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Check if the agent can handle the given task
+      # @param task [String] task description
+      # @return [Boolean] whether the agent can handle this task
+      def can_handle?(task)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Get a description of the agent's capabilities
+      # @return [String] agent description
+      def description
+        raise NotImplementedError, "Implement in subclass"
+      end
+    end
+  end
+end