llm_chain 0.5.3 → 0.5.5

data/lib/llm_chain/interfaces/builders/memory_context_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    module Builders
+      # Abstract interface for building memory context in LLMChain.
+      # Implementations must provide a method to format conversation history for the prompt.
+      #
+      # @abstract
+      class MemoryContext
+        # Build the memory context string for the prompt.
+        # @param memory_history [Array<Hash>] conversation history
+        # @return [String] formatted memory context
+        def build(memory_history)
+          raise NotImplementedError, "Implement in subclass"
+        end
+      end
+    end
+  end
+end 

data/lib/llm_chain/interfaces/builders/prompt_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    module Builders
+      # Abstract interface for prompt building in LLMChain.
+      # Implementations must provide a method to assemble the final prompt for the LLM.
+      #
+      # @abstract
+      class Prompt
+        # Build the final prompt for the LLM.
+        # @param memory_context [String]
+        # @param tool_responses [String]
+        # @param rag_documents [String]
+        # @param prompt [String]
+        # @return [String] final prompt for LLM
+        def build(memory_context:, tool_responses:, rag_documents:, prompt:)
+          raise NotImplementedError, "Implement in subclass"
+        end
+      end
+    end
+  end
+end 

data/lib/llm_chain/interfaces/builders/rag_documents_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    module Builders
+      # Abstract interface for building RAG documents context in LLMChain.
+      # Implementations must provide a method to format retrieved documents for the prompt.
+      #
+      # @abstract
+      class RagDocuments
+        # Build the RAG documents string for the prompt.
+        # @param rag_documents [Array<Hash>] list of retrieved documents
+        # @return [String] formatted RAG context
+        def build(rag_documents)
+          raise NotImplementedError, "Implement in subclass"
+        end
+      end
+    end
+  end
+end 

data/lib/llm_chain/interfaces/builders/retriever_context_builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    module Builders
+      # Abstract interface for retrieving and formatting RAG context in LLMChain.
+      # Implementations must provide a method to retrieve and format context documents.
+      #
+      # @abstract
+      class RetrieverContext
+        # Retrieve and format RAG context documents.
+        # @param retriever [Object] retriever instance
+        # @param query [String] user query
+        # @param options [Hash]
+        # @return [Array<Hash>] list of retrieved documents
+        def retrieve(retriever, query, options = {})
+          raise NotImplementedError, "Implement in subclass"
+        end
+      end
+    end
+  end
+end 

data/lib/llm_chain/interfaces/builders/tool_responses_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    module Builders
+      # Abstract interface for building tool responses context in LLMChain.
+      # Implementations must provide a method to format tool results for the prompt.
+      #
+      # @abstract
+      class ToolResponses
+        # Build the tool responses string for the prompt.
+        # @param tool_results [Hash] tool name => result
+        # @return [String] formatted tool responses
+        def build(tool_results)
+          raise NotImplementedError, "Implement in subclass"
+        end
+      end
+    end
+  end
+end 

data/lib/llm_chain/interfaces/memory.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    # Abstract interface for memory adapters in LLMChain.
+    # Implementations must provide methods for storing and recalling conversation history.
+    #
+    # @abstract
+    class Memory
+      # Store a prompt/response pair in memory.
+      # @param prompt [String]
+      # @param response [String]
+      # @return [void]
+      def store(prompt, response)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Recall conversation history (optionally filtered by prompt).
+      # @param prompt [String, nil]
+      # @return [Array<Hash>] [{ prompt: ..., response: ... }, ...]
+      def recall(prompt = nil)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Clear all memory.
+      # @return [void]
+      def clear
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Return number of stored items.
+      # @return [Integer]
+      def size
+        raise NotImplementedError, "Implement in subclass"
+      end
+    end
+  end
+end 

data/lib/llm_chain/interfaces/tool_manager.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module LLMChain
+  module Interfaces
+    # Abstract interface for tool management in LLMChain.
+    # Implementations must provide methods for registering, finding, and executing tools.
+    #
+    # @abstract
+    class ToolManager
+      # Register a new tool instance.
+      # @param tool [LLMChain::Tools::Base]
+      # @return [void]
+      def register_tool(tool)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Unregister a tool by name.
+      # @param name [String]
+      # @return [void]
+      def unregister_tool(name)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Fetch a tool by its name.
+      # @param name [String]
+      # @return [LLMChain::Tools::Base, nil]
+      def get_tool(name)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # List all registered tools.
+      # @return [Array<LLMChain::Tools::Base>]
+      def list_tools
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Find tools whose #match? returns true for the prompt.
+      # @param prompt [String]
+      # @return [Array<LLMChain::Tools::Base>]
+      def find_matching_tools(prompt)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Execute every matching tool and collect results.
+      # @param prompt [String]
+      # @param context [Hash]
+      # @return [Hash] mapping tool name → result hash
+      def execute_tools(prompt, context: {})
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Format tool execution results for inclusion into an LLM prompt.
+      # @param results [Hash]
+      # @return [String]
+      def format_tool_results(results)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Human-readable list of available tools.
+      # @return [String]
+      def tools_description
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Determine if prompt likely needs tool usage.
+      # @param prompt [String]
+      # @return [Boolean]
+      def needs_tools?(prompt)
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Auto-select and execute best tools for prompt.
+      # @param prompt [String]
+      # @param context [Hash]
+      # @return [Hash]
+      def auto_execute(prompt, context: {})
+        raise NotImplementedError, "Implement in subclass"
+      end
+
+      # Build JSON schemas for all registered tools.
+      # @return [Array<Hash>]
+      def get_tools_schema
+        raise NotImplementedError, "Implement in subclass"
+      end
+    end
+  end
+end 

data/lib/llm_chain/memory/array.rb

@@ -1,24 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../interfaces/memory'
+
 module LLMChain
   module Memory
-    class Array
+    # In-memory array-based memory adapter for LLMChain.
+    # Stores conversation history in a simple Ruby array.
+    class Array < Interfaces::Memory
       def initialize(max_size: 10)
         @storage = []
         @max_size = max_size
       end
 
+      # Store a prompt/response pair in memory.
+      # @param prompt [String]
+      # @param response [String]
+      # @return [void]
       def store(prompt, response)
         @storage << { prompt: prompt, response: response }
         @storage.shift if @storage.size > @max_size
       end
 
+      # Recall conversation history (optionally filtered by prompt).
+      # @param prompt [String, nil]
+      # @return [Array<Hash>]
       def recall(_ = nil)
         @storage.dup
       end
 
+      # Clear all memory.
+      # @return [void]
       def clear
         @storage.clear
       end
 
+      # Return number of stored items.
+      # @return [Integer]
       def size
         @storage.size
       end

data/lib/llm_chain/memory/redis.rb

@@ -1,9 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../interfaces/memory'
+
 require 'redis'
 require 'json'
 
 module LLMChain
   module Memory
-    class Redis
+    # Redis-based memory adapter for LLMChain.
+    # Stores conversation history in a Redis list.
+    class Redis < Interfaces::Memory
       class Error < StandardError; end
 
       def initialize(max_size: 10, redis_url: nil, namespace: 'llm_chain')
@@ -13,27 +19,38 @@ module LLMChain
         @session_key = "#{namespace}:session"
       end
 
+      # Store a prompt/response pair in memory.
+      # @param prompt [String]
+      # @param response [String]
+      # @return [void]
       def store(prompt, response)
         entry = { prompt: prompt, response: response, timestamp: Time.now.to_i }.to_json
         @redis.multi do
           @redis.rpush(@session_key, entry)
-          @redis.ltrim(@session_key, -@max_size, -1) # Сохраняем только последние max_size записей
+          @redis.ltrim(@session_key, -@max_size, -1)
         end
       end
 
+      # Recall conversation history (optionally filtered by prompt).
+      # @param prompt [String, nil]
+      # @return [Array<Hash>]
       def recall(_ = nil)
         entries = @redis.lrange(@session_key, 0, -1)
         entries.map { |e| symbolize_keys(JSON.parse(e)) }
       rescue JSON::ParserError
         []
       rescue ::Redis::CannotConnectError
-        raise MemoryError, "Cannot connect to Redis server"
+        raise Error, "Cannot connect to Redis server"
       end
 
+      # Clear all memory.
+      # @return [void]
       def clear
         @redis.del(@session_key)
       end
 
+      # Return number of stored items.
+      # @return [Integer]
       def size
         @redis.llen(@session_key)
       end

data/lib/llm_chain/system_diagnostics.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module LLMChain
+  # System diagnostics utility for checking LLMChain environment
+  class SystemDiagnostics
+    DIAGNOSTICS_HEADER = "🔍 LLMChain System Diagnostics"
+    SEPARATOR = "=" * 50
+
+    def self.run
+      new.run
+    end
+
+    def run
+      puts_header
+      results = ConfigurationValidator.validate_environment
+      display_results(results)
+      display_recommendations(results)
+      puts_footer
+      results
+    end
+
+    private
+
+    def puts_header
+      puts DIAGNOSTICS_HEADER
+      puts SEPARATOR
+    end
+
+    def puts_footer
+      puts SEPARATOR
+    end
+
+    def display_results(results)
+      display_system_components(results)
+      display_api_keys(results)
+      display_warnings(results)
+    end
+
+    def display_system_components(results)
+      puts "\n📋 System Components:"
+      puts "  Ruby: #{status_icon(results[:ruby])} (#{RUBY_VERSION})"
+      puts "  Python: #{status_icon(results[:python])}"
+      puts "  Node.js: #{status_icon(results[:node])}"
+      puts "  Internet: #{status_icon(results[:internet])}"
+      puts "  Ollama: #{status_icon(results[:ollama])}"
+    end
+
+    def display_api_keys(results)
+      puts "\n🔑 API Keys:"
+      results[:apis].each do |api, available|
+        puts "  #{api.to_s.capitalize}: #{status_icon(available)}"
+      end
+    end
+
+    def display_warnings(results)
+      return unless results[:warnings].any?
+
+      puts "\n⚠️  Warnings:"
+      results[:warnings].each { |warning| puts "  • #{warning}" }
+    end
+
+    def display_recommendations(results)
+      puts "\n💡 Recommendations:"
+      puts "  • Install missing components for full functionality"
+      puts "  • Configure API keys for enhanced features"
+      puts "  • Start Ollama server: ollama serve" unless results[:ollama]
+    end
+
+    def status_icon(status)
+      status ? '✅' : '❌'
+    end
+  end
+end 

data/lib/llm_chain/tools/base.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+module LLMChain
+  module Tools
+    # Base class for all LLMChain tools.
+    #
+    # Subclasses must implement:
+    #   * {#match?} – decide whether the tool should run for a given prompt.
+    #   * {#call}   – perform the work and return result (`String` or `Hash`).
+    #
+    # Optional overrides: {#extract_parameters}, {#format_result}.
+    #
+    # @abstract
+    class Base
+      attr_reader :name, :description, :parameters
+
+      # @param name [String]
+      # @param description [String]
+      # @param parameters [Hash]
+      def initialize(name:, description:, parameters: {})
+        @name = name
+        @description = description
+        @parameters = parameters
+      end
+
+      # Check whether this tool matches the given prompt.
+      # @param prompt [String]
+      # @return [Boolean]
+      def match?(prompt)
+        raise NotImplementedError, "Subclasses must implement #match?"
+      end
+
+      # Perform the tool action.
+      # @param prompt [String]
+      # @param context [Hash]
+      # @return [String, Hash]
+      def call(prompt, context: {})
+        raise NotImplementedError, "Subclasses must implement #call"
+      end
+
+      # Build a JSON schema describing the tool interface for LLMs.
+      # @return [Hash]
+      def to_schema
+        {
+          name: @name,
+          description: @description,
+          parameters: {
+            type: "object",
+            properties: @parameters,
+            required: required_parameters
+          }
+        }
+      end
+
+      # Extract parameters from prompt if needed.
+      # @param prompt [String]
+      # @return [Hash]
+      def extract_parameters(prompt)
+        {}
+      end
+
+      # Format result for inclusion into LLM prompt.
+      # @param result [Object]
+      # @return [String]
+      def format_result(result)
+        case result
+        when String then result
+        when Hash, Array then JSON.pretty_generate(result)
+        else result.to_s
+        end
+      end
+
+      protected
+
+      # List of required parameter names
+      # @return [Array<String>]
+      def required_parameters
+        []
+      end
+
+      # Helper: checks if prompt contains any keyword
+      # @param prompt [String]
+      # @param keywords [Array<String>]
+      # @return [Boolean]
+      def contains_keywords?(prompt, keywords)
+        keywords.any? { |keyword| prompt.downcase.include?(keyword.downcase) }
+      end
+
+      # Helper: extract numeric values from text
+      # @param text [String]
+      # @return [Array<Float>]
+      def extract_numbers(text)
+        text.scan(/-?\d+\.?\d*/).map(&:to_f)
+      end
+
+      # Helper: extract URLs from text
+      # @param text [String]
+      # @return [Array<String>]
+      def extract_urls(text)
+        text.scan(%r{https?://[^\s]+})
+      end
+    end
+  end
+end 

data/lib/llm_chain/tools/base_tool.rb

@@ -1,81 +1,11 @@
+# frozen_string_literal: true
+require_relative 'base'
+
 module LLMChain
   module Tools
-    class BaseTool
-      attr_reader :name, :description, :parameters
-
-      def initialize(name:, description:, parameters: {})
-        @name = name
-        @description = description
-        @parameters = parameters
-      end
-
-      # Проверяет, подходит ли инструмент для данного промпта
-      # @param prompt [String] Входной промпт от пользователя
-      # @return [Boolean] true если инструмент должен быть вызван
-      def match?(prompt)
-        raise NotImplementedError, "Subclasses must implement #match?"
-      end
-
-      # Выполняет инструмент
-      # @param prompt [String] Входной промпт от пользователя
-      # @param context [Hash] Дополнительный контекст
-      # @return [String, Hash] Результат выполнения инструмента
-      def call(prompt, context: {})
-        raise NotImplementedError, "Subclasses must implement #call"
-      end
-
-      # Возвращает JSON-схему для LLM
-      def to_schema
-        {
-          name: @name,
-          description: @description,
-          parameters: {
-            type: "object",
-            properties: @parameters,
-            required: required_parameters
-          }
-        }
-      end
-
-      # Извлекает параметры из промпта (для автоматического парсинга)
-      # @param prompt [String] Входной промпт
-      # @return [Hash] Извлеченные параметры
-      def extract_parameters(prompt)
-        {}
-      end
-
-      # Форматирует результат для включения в промпт
-      # @param result [Object] Результат выполнения инструмента
-      # @return [String] Форматированный результат
-      def format_result(result)
-        case result
-        when String then result
-        when Hash, Array then JSON.pretty_generate(result)
-        else result.to_s
-        end
-      end
-
-      protected
-
-      # Список обязательных параметров
-      def required_parameters
-        []
-      end
-
-      # Помощник для проверки ключевых слов в промпте
-      def contains_keywords?(prompt, keywords)
-        keywords.any? { |keyword| prompt.downcase.include?(keyword.downcase) }
-      end
-
-      # Помощник для извлечения числовых значений
-      def extract_numbers(text)
-        text.scan(/-?\d+\.?\d*/).map(&:to_f)
-      end
-
-      # Помощник для извлечения URL
-      def extract_urls(text)
-        text.scan(%r{https?://[^\s]+})
-      end
+    # @deprecated Use {LLMChain::Tools::Base}. Will be removed in 0.7.0.
+    class BaseTool < Base
+      # Empty shim for backward compatibility
     end
   end
 end