llm_chain 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dd4f92a849092fdd1770088d8724a557ae12ff16f7108f0cef3f6199445c521
-  data.tar.gz: ec2f30766da2cd6ab9b2a92a9df35b914e995d5243359d8398b0ac96a41ebd8c
+  metadata.gz: a926b1222ae2f5fda1d4562ade3663cf1b9d9aff0e1162f8c8c6b17ab817a27c
+  data.tar.gz: 9a9c7ad9c081899e5ae014d0236eaf01cf93fa66fcdae2c439d18cf54e7de532
 SHA512:
-  metadata.gz: faa70d193aaf6d0af6cfede19867d5bb3263098d0214f71d15ced7f336fecf91483b8c046c652e5e38289cfa0e9d0ac4f0dedebbcc815981904afb07a091cfd0
-  data.tar.gz: d8c5f550897bfe5ed92d9aa2098dd46e1726fd2783c56d886c90db7588375f15055a101cefb3ad16fe9a3522c1917ad99cb1dc6cd4091e8d117d3ee997795119
+  metadata.gz: 0f6736ee81ee8cc057e7f283de27f7d7cda086a3161b2c0bd7b8b434542b9df3c52df905cbc4c561c069f47afbaa333f36f52fbbe9fac56a83fe766a165c71f2
+  data.tar.gz: 17750148dce41dd667b24621d1e19051f9ff253213a72ef4e79ffda7d6291494c2db79a88215257f0afb69b4a857583e734e9872fa515e10d7879d5b62f139cb

data/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [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
+- Quick chain creation method `LLMChain.quick_chain` for rapid setup
+- Global configuration system with `LLMChain.configure`
+- Google Search integration for accurate, up-to-date search results
+- Fallback search data for common queries (Ruby versions, etc.)
+- Production-ready output without debug noise
+
+### Changed  
+- **BREAKING**: Replaced DuckDuckGo with Google as default search engine
+- Web search now returns accurate results instead of outdated information
+- Removed all debug output functionality for cleaner user experience
+- Improved calculator expression parsing for better math evaluation
+- Enhanced code interpreter to handle inline code prompts (e.g., "Execute code: puts ...")
+
+### Fixed
+- Calculator now correctly parses expressions like "50 / 2" instead of extracting just "2"
+- Code interpreter properly extracts code from "Execute code: ..." format
+- Web search HTTP 202 responses no longer treated as errors
+- Removed excessive debug console output
+
+## [0.5.0] - 2025-06-25
+
+### Added
+- Core tool system with automatic tool selection
+- Calculator tool for mathematical expressions
+- Web search tool with DuckDuckGo integration  
+- Code interpreter tool for Ruby code execution
+- Multi-LLM support (OpenAI, Qwen, LLaMA2, Gemma)
+- Memory system with Array and Redis backends
+- RAG support with vector databases
+- Streaming output support
+- Comprehensive error handling
+- Tool manager for organizing and managing tools
+
+### Changed
+- Initial stable release with core functionality
+
+[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,6 +8,15 @@
 
 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.2
+
+- ✅ **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
 
 - 🤖 **Unified API** for multiple LLMs (OpenAI, Ollama, Qwen, LLaMA2, Gemma)
@@ -45,10 +54,14 @@ gem 'llm_chain'
    ollama pull llama2:7b
    ```
 
-2. **Optional**: API keys for external services
+2. **Optional**: API keys for enhanced features
    ```bash
-   export OPENAI_API_KEY="your-key"
-   export SEARCH_API_KEY="your-key"
+   # For OpenAI models
+   export OPENAI_API_KEY="your-openai-key"
+   
+   # For Google Search (get at console.developers.google.com)
+   export GOOGLE_API_KEY="your-google-key"
+   export GOOGLE_SEARCH_ENGINE_ID="your-search-engine-id"
    ```
 
 ### Simple Example
@@ -56,33 +69,91 @@ gem 'llm_chain'
 ```ruby
 require 'llm_chain'
 
-# Basic usage
+# Quick start with default tools (v0.5.1+)
+chain = LLMChain.quick_chain
+response = chain.ask("Hello! How are you?")
+puts response
+
+# Or traditional setup
 chain = LLMChain::Chain.new(model: "qwen3:1.7b")
 response = chain.ask("Hello! How are you?")
 puts response
 ```
 
-## 🛠️ Tool System
+## 🔍 System Diagnostics (v0.5.2+)
 
-### Automatic Tool Usage
+Before diving into development, it's recommended to check your system configuration:
 
 ```ruby
-# Create chain with tools
-tool_manager = LLMChain::Tools::ToolManager.create_default_toolset
-chain = LLMChain::Chain.new(
+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",
-  tools: tool_manager
+  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
+
+```ruby
+# Quick setup (v0.5.1+)
+chain = LLMChain.quick_chain
+
 # Tools are selected automatically
 chain.ask("Calculate 15 * 7 + 32")
-# 🧮 Automatically uses calculator
+# 🧮 Result: 137
 
-chain.ask("Find information about Ruby 3.2")
-# 🔍 Automatically uses web search
+chain.ask("Which is the latest version of Ruby?")
+# 🔍 Result: Ruby 3.3.6 (via Google search)
 
 chain.ask("Execute code: puts (1..10).sum")
-# 💻 Automatically uses code interpreter
+# 💻 Result: 55
+
+# Traditional setup
+tool_manager = LLMChain::Tools::ToolManager.create_default_toolset
+chain = LLMChain::Chain.new(
+  model: "qwen3:1.7b",
+  tools: tool_manager
+)
 ```
 
 ### Built-in Tools
@@ -97,14 +168,23 @@ puts result[:formatted]
 
 #### 🌐 Web Search
 ```ruby
+# Google search for accurate results (v0.5.1+)
 search = LLMChain::Tools::WebSearch.new
-results = search.call("Latest Ruby news")
+results = search.call("Latest Ruby version")
 puts results[:formatted]
+# Output: Ruby 3.3.6 is the current stable version...
+
+# Fallback data available without API keys
+search = LLMChain::Tools::WebSearch.new
+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)
@@ -113,9 +193,80 @@ 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.2+)
+
+```ruby
+# Global configuration
+LLMChain.configure do |config|
+  config.default_model = "qwen3:1.7b"          # Default LLM model
+  config.search_engine = :google               # Google for accurate results
+  config.memory_size = 100                     # Memory buffer size
+  config.timeout = 30                          # Request timeout (seconds)
+end
+
+# Quick chain with default settings
+chain = LLMChain.quick_chain
+
+# Override settings per chain (v0.5.2+)
+chain = LLMChain.quick_chain(
+  model: "gpt-4",
+  tools: false,                               # Disable tools
+  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
@@ -374,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
@@ -501,22 +693,28 @@ chain.ask(prompt, stream: false, rag_context: false, rag_options: {})
 
 ## 🛣️ Roadmap
 
-### v0.6.0
-- [ ] ReAct agents
-- [ ] More tools (files, database)
+### 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 logging
+- [ ] Advanced logging and metrics
 
 ### v0.7.0
 - [ ] Multi-agent systems
-- [ ] Task planning
-- [ ] Web interface
+- [ ] Task planning and workflows
+- [ ] Web interface for testing
 - [ ] Metrics and monitoring
 
 ### v1.0.0
-- [ ] Stable API
-- [ ] Complete documentation
-- [ ] Production readiness
+- [ ] Stable API with semantic versioning
+- [ ] Complete documentation coverage
+- [ ] Production-grade performance
 
 ## 🤝 Contributing
 
@@ -551,5 +749,6 @@ This project is distributed under the [MIT License](LICENSE.txt).
 
 [Documentation](https://github.com/FuryCow/llm_chain/wiki) | 
 [Examples](https://github.com/FuryCow/llm_chain/tree/main/examples) | 
+[Changelog](CHANGELOG.md) |
 [Issues](https://github.com/FuryCow/llm_chain/issues) | 
 [Discussions](https://github.com/FuryCow/llm_chain/discussions)

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
@@ -105,7 +120,12 @@ module LLMChain
       parts = ["Tool results:"]
       tool_responses.each do |name, response|
         if response.is_a?(Hash) && response[:formatted]
-          parts << "#{name}: #{response[:formatted]}"
+          # Особая обработка для поиска без результатов
+          if name == "web_search" && response[:results] && response[:results].empty?
+            parts << "#{name}: No search results found. Please answer based on your knowledge, but indicate that search was unavailable."
+          else
+            parts << "#{name}: #{response[:formatted]}"
+          end
         else
           parts << "#{name}: #{response}"
         end

data/lib/llm_chain/client_registry.rb

@@ -7,7 +7,6 @@ module LLMChain
     end
 
     def self.client_for(model, **options)
-      puts model
       instance = case model
       when /gpt|openai/
         Clients::OpenAI