llm_chain 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d2f08734c93afa3880316d14f129a90502e0f6d9094d939257a5bf0740b6754
-  data.tar.gz: a1f6665f3dd39c1401e54770e8fd23f10fba1b47195f88b461b2e76fe4a0212a
+  metadata.gz: a926b1222ae2f5fda1d4562ade3663cf1b9d9aff0e1162f8c8c6b17ab817a27c
+  data.tar.gz: 9a9c7ad9c081899e5ae014d0236eaf01cf93fa66fcdae2c439d18cf54e7de532
 SHA512:
-  metadata.gz: aebdbe64169f31b55ea55278103769acd71c4a8d786c1e84235abd9d2e6f271dcfe9eeba46796675c096a4bef3a34843a5f093dddf5964ad0fdfe974d18b2d79
-  data.tar.gz: 57f61024965d99528e8e0f56c60106af3168a408bc0f612b4c1fbca7ac79eeb46b564bee50f648128e34850268717f57362f96911b4be290a8a4288bcc548d83
+  metadata.gz: 0f6736ee81ee8cc057e7f283de27f7d7cda086a3161b2c0bd7b8b434542b9df3c52df905cbc4c561c069f47afbaa333f36f52fbbe9fac56a83fe766a165c71f2
+  data.tar.gz: 17750148dce41dd667b24621d1e19051f9ff253213a72ef4e79ffda7d6291494c2db79a88215257f0afb69b4a857583e734e9872fa515e10d7879d5b62f139cb

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.2] - 2025-01-XX
+
+### Added
+- **Configuration Validator** - Comprehensive system validation before chain initialization
+- **System Diagnostics** - `LLMChain.diagnose_system` method for health checks
+- **Retry Logic** - Exponential backoff for HTTP requests with configurable max retries
+- **Enhanced Logging** - Structured logging with debug mode support
+- **Internet Connectivity Detection** - Automatic offline mode detection
+- **Code Extraction Improvements** - Better parsing of code blocks and inline commands
+
+### Changed
+- **Improved Error Handling** - Better error messages with suggested solutions
+- **Enhanced WebSearch** - More robust fallback mechanisms and timeout handling
+- **CodeInterpreter Enhancements** - Improved code extraction from various formats
+- **Better Validation** - Early detection of configuration issues with helpful warnings
+
+### Fixed
+- **WebSearch Stability** - Fixed timeout and connection issues with retry logic
+- **Code Block Parsing** - Resolved issues with multiline regex and Windows line endings
+- **Graceful Degradation** - Better handling of offline scenarios and API failures
+- **Memory Leaks** - Improved cleanup of temporary files and resources
+
 ## [0.5.1] - 2025-06-26
 
 ### Added
@@ -46,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Initial stable release with core functionality
 
-[Unreleased]: https://github.com/FuryCow/llm_chain/compare/v0.5.1...HEAD
+[Unreleased]: https://github.com/FuryCow/llm_chain/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/FuryCow/llm_chain/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/FuryCow/llm_chain/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/FuryCow/llm_chain/releases/tag/v0.5.0 

data/README.md

@@ -8,14 +8,14 @@
 
 LLMChain is a Ruby analog of LangChain, providing a unified interface for interacting with various LLMs, built-in tool system, and RAG (Retrieval-Augmented Generation) support.
 
-## 🎉 What's New in v0.5.1
+## 🎉 What's New in v0.5.2
 
-- ✅ **Google Search Integration** - Accurate, up-to-date search results
-- ✅ **Fixed Calculator** - Improved expression parsing and evaluation
-- ✅ **Enhanced Code Interpreter** - Better code extraction from prompts
-- ✅ **Production-Ready Output** - Clean interface without debug noise
-- ✅ **Quick Chain Creation** - Simple `LLMChain.quick_chain` method
-- ✅ **Simplified Configuration** - Easy setup with sensible defaults
+- ✅ **System Diagnostics** - Built-in health checks with `LLMChain.diagnose_system`
+- ✅ **Configuration Validation** - Early detection of setup issues and helpful warnings  
+- ✅ **Enhanced Error Handling** - Retry logic with exponential backoff for network requests
+- ✅ **Robust WebSearch** - Better timeout handling and graceful degradation
+- ✅ **Improved Code Extraction** - Enhanced support for various code block formats
+- ✅ **Debug Logging** - Structured logging with `LLM_CHAIN_DEBUG=true`
 
 ## ✨ Key Features
 
@@ -80,6 +80,56 @@ response = chain.ask("Hello! How are you?")
 puts response
 ```
 
+## 🔍 System Diagnostics (v0.5.2+)
+
+Before diving into development, it's recommended to check your system configuration:
+
+```ruby
+require 'llm_chain'
+
+# Run comprehensive system diagnostics
+LLMChain.diagnose_system
+# 🔍 LLMChain System Diagnostics
+# ==================================================
+# 📋 System Components:
+#   Ruby: ✅ (3.2.2)
+#   Python: ✅
+#   Node.js: ✅
+#   Internet: ✅
+#   Ollama: ✅
+# 🔑 API Keys:
+#   Openai: ❌
+#   Google_search: ❌
+# 💡 Recommendations:
+#   • Configure API keys for enhanced features
+#   • Start Ollama server: ollama serve
+```
+
+### Configuration Validation
+
+Chains now validate their configuration on startup:
+
+```ruby
+# Automatic validation (v0.5.2+)
+begin
+  chain = LLMChain.quick_chain(model: "qwen3:1.7b")
+rescue LLMChain::Error => e
+  puts "Configuration issue: #{e.message}"
+end
+
+# Disable validation if needed
+chain = LLMChain.quick_chain(
+  model: "qwen3:1.7b",
+  validate_config: false
+)
+
+# Manual validation
+LLMChain::ConfigurationValidator.validate_chain_config!(
+  model: "qwen3:1.7b",
+  tools: LLMChain::Tools::ToolManager.create_default_toolset
+)
+```
+
 ## 🛠️ Tool System
 
 ### Automatic Tool Usage
@@ -130,9 +180,11 @@ results = search.call("Which is the latest version of Ruby?")
 # Works even without Google API configured
 ```
 
-#### 💻 Code Interpreter
+#### 💻 Code Interpreter (Enhanced in v0.5.2)
 ```ruby
 interpreter = LLMChain::Tools::CodeInterpreter.new
+
+# Standard markdown blocks
 result = interpreter.call(<<~CODE)
   ```ruby
   def factorial(n)
@@ -141,10 +193,25 @@ result = interpreter.call(<<~CODE)
   puts factorial(5)
   ```
 CODE
+
+# Inline code commands (v0.5.2+)
+result = interpreter.call("Execute code: puts 'Hello World!'")
+
+# Code without language specification
+result = interpreter.call(<<~CODE)
+  ```
+  numbers = [1, 2, 3, 4, 5]
+  puts numbers.sum
+  ```
+CODE
+
+# Windows line endings support (v0.5.2+)
+result = interpreter.call("```ruby\r\nputs 'Windows compatible'\r\n```")
+
 puts result[:formatted]
 ```
 
-## ⚙️ Configuration (v0.5.1+)
+## ⚙️ Configuration (v0.5.2+)
 
 ```ruby
 # Global configuration
@@ -158,14 +225,48 @@ end
 # Quick chain with default settings
 chain = LLMChain.quick_chain
 
-# Override settings per chain
+# Override settings per chain (v0.5.2+)
 chain = LLMChain.quick_chain(
   model: "gpt-4",
   tools: false,                               # Disable tools
-  memory: false                               # Disable memory
+  memory: false,                              # Disable memory
+  validate_config: false                      # Skip validation
 )
 ```
 
+### Debug Mode (v0.5.2+)
+
+Enable detailed logging for troubleshooting:
+
+```bash
+# Enable debug logging
+export LLM_CHAIN_DEBUG=true
+
+# Or in Ruby
+ENV['LLM_CHAIN_DEBUG'] = 'true'
+```
+
+### Validation and Error Handling (v0.5.2+)
+
+```ruby
+# Comprehensive environment check
+results = LLMChain::ConfigurationValidator.validate_environment
+puts "Ollama available: #{results[:ollama]}"
+puts "Internet: #{results[:internet]}"
+puts "Warnings: #{results[:warnings]}"
+
+# Chain validation with custom settings
+begin
+  LLMChain::ConfigurationValidator.validate_chain_config!(
+    model: "gpt-4",
+    tools: [LLMChain::Tools::Calculator.new, LLMChain::Tools::WebSearch.new]
+  )
+rescue LLMChain::ConfigurationValidator::ValidationError => e
+  puts "Setup issue: #{e.message}"
+  # Handle configuration problems
+end
+```
+
 ### Creating Custom Tools
 
 ```ruby
@@ -424,23 +525,64 @@ openai = LLMChain::Clients::OpenAI.new(
 )
 ```
 
-## 🔧 Error Handling
+## 🔧 Error Handling (Enhanced in v0.5.2)
 
 ```ruby
 begin
   chain = LLMChain::Chain.new(model: "qwen3:1.7b")
   response = chain.ask("Complex query")
+rescue LLMChain::ConfigurationValidator::ValidationError => e
+  puts "Configuration issue: #{e.message}"
+  # Use LLMChain.diagnose_system to check setup
 rescue LLMChain::UnknownModelError => e
   puts "Unknown model: #{e.message}"
+  # Check available models with ollama list
 rescue LLMChain::ClientError => e
   puts "Client error: #{e.message}"
+  # Network or API issues
 rescue LLMChain::TimeoutError => e
   puts "Timeout exceeded: #{e.message}"
+  # Increase timeout or use faster model
 rescue LLMChain::Error => e
   puts "General LLMChain error: #{e.message}"
 end
 ```
 
+### Automatic Retry Logic (v0.5.2+)
+
+WebSearch and other tools now include automatic retry with exponential backoff:
+
+```ruby
+# Retry configuration is automatic, but you can observe it:
+ENV['LLM_CHAIN_DEBUG'] = 'true'
+
+search = LLMChain::Tools::WebSearch.new
+result = search.call("search query")
+# [WebSearch] Retrying search (1/3) after 0.5s: Net::TimeoutError
+# [WebSearch] Retrying search (2/3) after 1.0s: Net::TimeoutError
+# [WebSearch] Search failed after 3 attempts: Net::TimeoutError
+
+# Tools gracefully degrade to fallback methods when possible
+puts result[:formatted] # Still provides useful response
+```
+
+### Graceful Degradation
+
+```ruby
+# Tools handle failures gracefully
+calculator = LLMChain::Tools::Calculator.new
+web_search = LLMChain::Tools::WebSearch.new
+code_runner = LLMChain::Tools::CodeInterpreter.new
+
+# Even with network issues, you get useful responses:
+search_result = web_search.call("latest Ruby version")
+# Falls back to hardcoded data for common queries
+
+# Safe code execution with timeout protection:
+code_result = code_runner.call("puts 'Hello World!'")
+# Executes safely with proper sandboxing
+```
+
 ## 📚 Usage Examples
 
 ### Chatbot with Tools
@@ -551,11 +693,17 @@ chain.ask(prompt, stream: false, rag_context: false, rag_options: {})
 
 ## 🛣️ Roadmap
 
-### v0.6.0
+### v0.5.2 ✅ Completed
+- [x] System diagnostics and health checks
+- [x] Configuration validation
+- [x] Enhanced error handling with retry logic
+- [x] Improved code extraction and tool stability
+
+### v0.6.0 (Next)
 - [ ] ReAct agents and multi-step reasoning
 - [ ] More tools (file system, database queries)
 - [ ] Claude integration
-- [ ] Enhanced error handling
+- [ ] Advanced logging and metrics
 
 ### v0.7.0
 - [ ] Multi-agent systems

data/lib/llm_chain/chain.rb

@@ -9,7 +9,22 @@ module LLMChain
     # @param tools [Array<Tool>] Массив инструментов
     # @param retriever [#search] RAG-ретривер (Weaviate, Pinecone и т.д.)
     # @param client_options [Hash] Опции для клиента LLM
-    def initialize(model: nil, memory: nil, tools: [], retriever: nil, **client_options)
+    def initialize(model: nil, memory: nil, tools: [], retriever: nil, validate_config: true, **client_options)
+      # Валидация конфигурации (можно отключить через validate_config: false)
+      if validate_config
+        begin
+          ConfigurationValidator.validate_chain_config!(
+            model: model, 
+            tools: tools, 
+            memory: memory,
+            retriever: retriever,
+            **client_options
+          )
+        rescue ConfigurationValidator::ValidationError => e
+          raise Error, "Configuration validation failed: #{e.message}"
+        end
+      end
+
       @model = model
       @memory = memory || Memory::Array.new
       @tools = tools

data/lib/llm_chain/configuration_validator.rb

@@ -0,0 +1,349 @@
+require 'net/http'
+require 'uri'
+require 'json'
+
+module LLMChain
+  class ConfigurationValidator
+    class ValidationError < Error; end
+    class ValidationWarning < StandardError; end
+
+    def self.validate_chain_config!(model: nil, **options)
+      new.validate_chain_config!(model: model, **options)
+    end
+
+    def validate_chain_config!(model: nil, **options)
+      @warnings = []
+      
+      begin
+        validate_model!(model) if model
+        validate_client_availability!(model) if model
+        validate_tools!(options[:tools]) if options[:tools]
+        validate_memory!(options[:memory]) if options[:memory]
+        validate_retriever!(options[:retriever]) if options[:retriever]
+        
+        # Выводим предупреждения, если есть
+        @warnings.each { |warning| warn_user(warning) } if @warnings.any?
+        
+        true
+      rescue => e
+        raise ValidationError, "Configuration validation failed: #{e.message}"
+      end
+    end
+
+    def self.validate_environment
+      new.validate_environment
+    end
+
+    def validate_environment
+      @warnings = []
+      results = {}
+      
+      results[:ollama] = check_ollama_availability
+      results[:ruby] = check_ruby_version
+      results[:python] = check_python_availability
+      results[:node] = check_node_availability
+      results[:internet] = check_internet_connectivity
+      results[:apis] = check_api_keys
+      
+      results[:warnings] = @warnings
+      results
+    end
+
+    private
+
+    def validate_model!(model)
+      return if model.nil?
+      
+      case model.to_s
+      when /^gpt/
+        validate_openai_requirements!(model)
+      when /qwen|llama|gemma/
+        validate_ollama_requirements!(model)
+      else
+        add_warning("Unknown model type: #{model}. Proceeding with default settings.")
+      end
+    end
+
+    def validate_openai_requirements!(model)
+      api_key = ENV['OPENAI_API_KEY']
+      unless api_key
+        raise ValidationError, "OpenAI API key required for model '#{model}'. Set OPENAI_API_KEY environment variable."
+      end
+      
+      if api_key.length < 20
+        raise ValidationError, "OpenAI API key appears to be invalid (too short)."
+      end
+      
+      # Проверяем доступность OpenAI API
+      begin
+        uri = URI('https://api.openai.com/v1/models')
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 5
+        http.read_timeout = 5
+        
+        request = Net::HTTP::Get.new(uri)
+        request['Authorization'] = "Bearer #{api_key}"
+        
+        response = http.request(request)
+        
+        case response.code
+        when '200'
+          # OK
+        when '401'
+          raise ValidationError, "OpenAI API key is invalid or expired."
+        when '429'
+          add_warning("OpenAI API rate limit reached. Service may be temporarily unavailable.")
+        else
+          add_warning("OpenAI API returned status #{response.code}. Service may be temporarily unavailable.")
+        end
+      rescue => e
+        add_warning("Cannot verify OpenAI API availability: #{e.message}")
+      end
+    end
+
+    def validate_ollama_requirements!(model)
+      unless check_ollama_availability
+        raise ValidationError, "Ollama is not running. Please start Ollama server with: ollama serve"
+      end
+      
+      unless model_available_in_ollama?(model)
+        raise ValidationError, "Model '#{model}' not found in Ollama. Available models: #{list_ollama_models.join(', ')}"
+      end
+    end
+
+    def validate_client_availability!(model)
+      case model.to_s
+      when /qwen|llama|gemma/
+        unless check_ollama_availability
+          raise ValidationError, "Ollama server is not running for model '#{model}'"
+        end
+      end
+    end
+
+    def validate_tools!(tools)
+      return unless tools
+      
+      if tools.respond_to?(:tools) # ToolManager
+        tools.tools.each { |tool| validate_single_tool!(tool) }
+      elsif tools.is_a?(Array)
+        tools.each { |tool| validate_single_tool!(tool) }
+      else
+        validate_single_tool!(tools)
+      end
+    end
+
+    def validate_single_tool!(tool)
+      case tool.class.name
+      when /WebSearch/
+        validate_web_search_tool!(tool)
+      when /CodeInterpreter/
+        validate_code_interpreter_tool!(tool)
+      when /Calculator/
+        # Calculator не требует дополнительной валидации
+      end
+    end
+
+    def validate_web_search_tool!(tool)
+      # Проверяем доступность Google Search API
+      if ENV['GOOGLE_API_KEY'] && ENV['GOOGLE_SEARCH_ENGINE_ID']
+        # Есть API ключи, но проверим их валидность
+        begin
+          # Простая проверка доступности
+          uri = URI('https://www.googleapis.com/customsearch/v1')
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 3
+          http.read_timeout = 3
+          
+          response = http.get('/')
+          # Если получили любой ответ, значит API доступен
+        rescue => e
+          add_warning("Google Search API may be unavailable: #{e.message}")
+        end
+      else
+        add_warning("Google Search API not configured. Search will use fallback methods.")
+      end
+      
+      # Проверяем доступность интернета для fallback поиска
+      unless check_internet_connectivity
+        add_warning("No internet connection detected. Search functionality will be limited.")
+      end
+    end
+
+    def validate_code_interpreter_tool!(tool)
+      # Проверяем доступность языков программирования
+      languages = tool.instance_variable_get(:@allowed_languages) || ['ruby']
+      
+      languages.each do |lang|
+        case lang
+        when 'ruby'
+          unless check_ruby_version
+            add_warning("Ruby interpreter not found or outdated.")
+          end
+        when 'python'
+          unless check_python_availability
+            add_warning("Python interpreter not found.")
+          end
+        when 'javascript'
+          unless check_node_availability
+            add_warning("Node.js interpreter not found.")
+          end
+        end
+      end
+    end
+
+    def validate_memory!(memory)
+      return unless memory
+      
+      case memory.class.name
+      when /Redis/
+        validate_redis_memory!(memory)
+      when /Array/
+        # Array memory не требует дополнительной валидации
+      end
+    end
+
+    def validate_redis_memory!(memory)
+      begin
+        # Проверяем подключение к Redis
+        redis_client = memory.instance_variable_get(:@redis) || memory.redis
+        if redis_client.respond_to?(:ping)
+          redis_client.ping
+        end
+      rescue => e
+        raise ValidationError, "Redis connection failed: #{e.message}"
+      end
+    end
+
+    def validate_retriever!(retriever)
+      return unless retriever
+      return if retriever == false
+      
+      case retriever.class.name
+      when /Weaviate/
+        validate_weaviate_retriever!(retriever)
+      end
+    end
+
+    def validate_weaviate_retriever!(retriever)
+      # Проверяем доступность Weaviate
+      begin
+        # Попытка подключения к Weaviate
+        uri = URI('http://localhost:8080/v1/.well-known/ready')
+        response = Net::HTTP.get_response(uri)
+        
+        unless response.code == '200'
+          raise ValidationError, "Weaviate server is not ready. Please start Weaviate."
+        end
+      rescue => e
+        raise ValidationError, "Cannot connect to Weaviate: #{e.message}"
+      end
+    end
+
+    # Вспомогательные методы для проверки системы
+
+    def check_ollama_availability
+      begin
+        uri = URI('http://localhost:11434/api/tags')
+        response = Net::HTTP.get_response(uri)
+        response.code == '200'
+      rescue
+        false
+      end
+    end
+
+    def model_available_in_ollama?(model)
+      begin
+        uri = URI('http://localhost:11434/api/tags')
+        response = Net::HTTP.get_response(uri)
+        return false unless response.code == '200'
+        
+        data = JSON.parse(response.body)
+        models = data['models'] || []
+        models.any? { |m| m['name'].include?(model.to_s.split(':').first) }
+      rescue
+        false
+      end
+    end
+
+    def list_ollama_models
+      begin
+        uri = URI('http://localhost:11434/api/tags')
+        response = Net::HTTP.get_response(uri)
+        return [] unless response.code == '200'
+        
+        data = JSON.parse(response.body)
+        models = data['models'] || []
+        models.map { |m| m['name'] }
+      rescue
+        []
+      end
+    end
+
+    def check_ruby_version
+      begin
+        version = RUBY_VERSION
+        major, minor, patch = version.split('.').map(&:to_i)
+        
+        # Требуем Ruby >= 3.1.0
+        if major > 3 || (major == 3 && minor >= 1)
+          true
+        else
+          add_warning("Ruby version #{version} detected. Minimum required: 3.1.0")
+          false
+        end
+      rescue
+        false
+      end
+    end
+
+    def check_python_availability
+      begin
+        output = `python3 --version 2>&1`
+        $?.success? && output.include?('Python')
+      rescue
+        false
+      end
+    end
+
+    def check_node_availability
+      begin
+        output = `node --version 2>&1`
+        $?.success? && output.include?('v')
+      rescue
+        false
+      end
+    end
+
+    def check_internet_connectivity
+      begin
+        require 'socket'
+        Socket.tcp("8.8.8.8", 53, connect_timeout: 3) {}
+        true
+      rescue
+        false
+      end
+    end
+
+    def check_api_keys
+      keys = {}
+      keys[:openai] = !ENV['OPENAI_API_KEY'].nil?
+      keys[:google_search] = !ENV['GOOGLE_API_KEY'].nil? && !ENV['GOOGLE_SEARCH_ENGINE_ID'].nil?
+      keys[:bing_search] = !ENV['BING_API_KEY'].nil?
+      keys
+    end
+
+    def add_warning(message)
+      @warnings << message
+    end
+
+    def warn_user(message)
+      if defined?(Rails) && Rails.logger
+        Rails.logger.warn "[LLMChain] #{message}"
+      else
+        warn "[LLMChain] Warning: #{message}"
+      end
+    end
+  end
+end