llm_chain 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d2f08734c93afa3880316d14f129a90502e0f6d9094d939257a5bf0740b6754
-  data.tar.gz: a1f6665f3dd39c1401e54770e8fd23f10fba1b47195f88b461b2e76fe4a0212a
+  metadata.gz: 8c94520a98ace3d2bb61ca2b470af041e0f95d6818120ce01dfc5a9cfe76316b
+  data.tar.gz: 5155099cdf777ecaed3a30c9da1e7e200476258369ef3b976967888daf001876
 SHA512:
-  metadata.gz: aebdbe64169f31b55ea55278103769acd71c4a8d786c1e84235abd9d2e6f271dcfe9eeba46796675c096a4bef3a34843a5f093dddf5964ad0fdfe974d18b2d79
-  data.tar.gz: 57f61024965d99528e8e0f56c60106af3168a408bc0f612b4c1fbca7ac79eeb46b564bee50f648128e34850268717f57362f96911b4be290a8a4288bcc548d83
+  metadata.gz: b37c6ed16c6b6a66d1f9c6e2a62717e576c5211aba605b98b97e5ba54b436d9a38602aabcedf34a23963ee034d6332dadefe03fa6c6a5d4d3f4941b2df9efd88
+  data.tar.gz: 4e5c3b6921e4f0656ea8266ca67a00dbcbc8c11736573df9172b8cb2d8821d3799f87085f31e7975d916d56c29f10a4637c6df5f102520fc2da3f5284143ef79

data/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.3] - 2025-07-05
+
+### Added
+* **CLI Executable** (`llm-chain`) with commands:
+  * `chat` – one-off prompt
+  * `diagnose` – system diagnostics
+  * `tools list` – list default tools
+  * `repl` – interactive Read-Eval-Print Loop with in-memory history and helper slash-commands
+
+### Changed
+* CLI autodetects Bundler only in development repo to avoid gem conflicts.
+
+### Fixed
+* Version conflicts when running CLI inside unrelated Bundler projects.
+
+## [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 +83,8 @@ 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.3...HEAD
+[0.5.3]: https://github.com/FuryCow/llm_chain/compare/v0.5.2...v0.5.3
+[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,16 @@
 
 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.3
 
-- ✅ **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
+* 🖥️ **New CLI executable** `llm-chain`
+  * `chat` – ask a one-off question from your shell
+  * `repl` – interactive session with conversation memory and helper commands (`/help`, `/mem clear`, `/tools list`)
+  * `diagnose` – run the built-in environment health-check
+  * `tools list` – inspect available tools
+* 🔄 **Bundler-aware loading** – CLI detects if it’s executed inside the gem repo and avoids version clashes with external Gemfiles.
+
+That’s all you need to start talking to LLMs straight from the terminal. See the **Command-line Interface** section below for usage examples.
 
 ## ✨ Key Features
 
@@ -80,6 +82,87 @@ response = chain.ask("Hello! How are you?")
 puts response
 ```
 
+## 🖥️ Command-line Interface (v0.5.3+)
+
+Alongside the Ruby API, LLMChain ships with a convenient CLI executable `llm-chain`.
+
+### Basic commands
+
+```bash
+# One-off question
+llm-chain chat "Hello! How are you?"
+
+# Interactive REPL with conversation memory (/help in session)
+llm-chain repl
+
+# System diagnostics (same as LLMChain.diagnose_system)
+llm-chain diagnose
+
+# List default tools
+llm-chain tools list
+
+# Show gem version
+llm-chain -v
+```
+
+The CLI is installed automatically with the gem. If your shell doesn’t find the command, make sure RubyGems’ bindir is in your `$PATH` or use Bundler-aware launch:
+
+```bash
+bundle exec llm-chain chat "…"
+```
+
+Set `LLM_CHAIN_DEBUG=true` to print extra logs.
+
+## 🔍 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 +213,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 +226,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 +258,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 +558,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 +726,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/exe/llm-chain

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Load Bundler only if running from the development repo (Gemfile present)
+if File.exist?(File.expand_path("../../Gemfile", __dir__))
+  begin
+    require "bundler/setup"
+  rescue LoadError
+    warn "[llm-chain] Bundler not available; continuing without it"
+  end
+end
+
+require "llm_chain"
+require "optparse"
+require "readline"
+
+USAGE = <<~TEXT.freeze
+  Usage: llm-chain <command> [options]
+
+  Commands:
+    chat <prompt>        Send prompt to quick_chain and print response
+    repl                Start interactive REPL session
+    diagnose             Run system diagnostics
+    tools list           List registered tools in the default toolset
+    version              Print LLMChain gem version
+
+  Environment variables:
+    LLM_CHAIN_DEBUG      Enable verbose diagnostic logs
+TEXT
+
+# Exit with usage if no command
+if ARGV.empty?
+  warn USAGE
+  exit 1
+end
+
+command = ARGV.shift
+
+case command
+when "repl"
+  puts "LLMChain REPL — type /help for commands, /exit to quit"
+  chain = LLMChain.quick_chain
+
+  loop do
+    line = Readline.readline("> ", true)
+    break if line.nil? || line.strip == "/exit" || line.strip == "/quit"
+
+    case line.strip
+    when "/help"
+      puts "/exit            Exit REPL\n" \
+           "/mem clear       Clear conversation memory\n" \
+           "/tools list      List available tools"
+      next
+    when "/mem clear"
+      chain.memory.clear if chain.memory.respond_to?(:clear)
+      puts "[memory cleared]"
+      next
+    when "/tools list"
+      if chain.tools.respond_to?(:tools_description)
+        puts chain.tools.tools_description
+      else
+        puts "No ToolManager attached"
+      end
+      next
+    end
+
+    # Empty input => skip
+    next if line.strip.empty?
+
+    begin
+      response = chain.ask(line)
+      puts response
+    rescue => e
+      warn "Error: #{e.message}"
+    end
+  end
+
+  puts "Bye!"
+
+when "chat"
+  # Collect prompt from remaining args or STDIN
+  prompt = if ARGV.empty?
+             puts "Enter prompt (end with CTRL+D):"
+             STDIN.read
+           else
+             ARGV.join(" ")
+           end
+  if prompt.nil? || prompt.strip.empty?
+    warn "No prompt provided"
+    exit 1
+  end
+
+  begin
+    chain = LLMChain.quick_chain
+    response = chain.ask(prompt)
+    puts "\n=== Response ===\n"
+    puts response
+  rescue Interrupt
+    warn "Interrupted"
+  rescue => e
+    warn "Error: #{e.message}"
+    exit 1
+  end
+
+when "diagnose"
+  LLMChain.diagnose_system
+
+when "tools"
+  sub = ARGV.shift
+  case sub
+  when "list"
+    tm = LLMChain::Tools::ToolManager.create_default_toolset
+    puts tm.tools_description
+  else
+    warn "Unknown tools subcommand"; warn USAGE
+    exit 1
+  end
+
+when "version", "--version", "-v"
+  puts LlmChain::VERSION
+
+else
+  warn "Unknown command: #{command}"
+  warn USAGE
+  exit 1
+end 

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