llm_chain 0.5.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1963821b40f17c255520b55422bbc7cf6603be88555a99403a8ce24b1c4914f4
-  data.tar.gz: f27902811ba56ee4b1d9da09b22bd99204f01573b848c16e6a9e368f68eb40a4
+  metadata.gz: 59badf4884002e839c8cd2c429db8f49dd21ba160d48303d6cb6b82bb06ca530
+  data.tar.gz: e1e89a377cf916c7174347d1ec1db2008b751d42f6a92cbc1738144997d4e683
 SHA512:
-  metadata.gz: 4a3611448d4e85e2f3bcec56f0c8d1c599bcf9da467a963b23fcffe6466e28e1d99dcae34449bffde4bb4672b1be5a6fe4dc35146c97dba8d968ab1fd6b77af1
-  data.tar.gz: e918646ffa824e762d7cefa92da2effcb5a23b412202c6d967e99e6d719035fc89834c0c6f65aea68fe131a92e41474bcf20d93d6ec1cdc2900943f0d51faf39
+  metadata.gz: 67cc37814800ded158a5039532ab207c222fed04926ad2fbedb58f43a2c6558adb94c19dfbc338a0c4af59ff9cd019e6f2ef9996ff01b4fd88c140334be03c1e
+  data.tar.gz: 9d634723d69b612d59d3984fe3325cc5429aad6062e4f7a477ce15cfe70e61b2bdc6b016913c9fcb4d8a499963141d3fb39218853375a63227766b28613932c6

data/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2025-07-24
+
+### Added
+* **Smart CompositeAgent** - Intelligent planning and execution capabilities:
+  * Automatic detection of simple vs complex tasks (math, time queries vs multi-step tasks)
+  * Direct execution for simple tasks (no unnecessary planning overhead)
+  * Smart result validation and quality scoring (0-10 scale)
+  * Intelligent result aggregation with structured summaries
+  * Better error handling and graceful degradation
+  * Meaningful information extraction from tool responses
+* **Enhanced DateTime Tool** - Improved timezone handling and parsing:
+  * Support for multi-word timezone names (e.g., "New York", "Europe/Moscow")
+  * IANA timezone mapping and validation
+  * Better JSON input parsing
+  * Improved timezone abbreviation display
+  * Fallback handling for invalid timezones
+* **Improved ReActAgent** - Better tool usage and reasoning:
+  * Enhanced prompt instructions for DateTime tool integration
+  * Improved termination logic to prevent premature stopping
+  * Better guidance for current information queries (uses DateTime before WebSearch)
+  * Support for multiple timezone queries
+
+### Changed
+* **CompositeAgent Architecture** - Major refactoring for better performance:
+  * Split execution into `run_with_planning` and `execute_directly` methods
+  * Introduced `should_use_planner?` for intelligent task classification
+  * Enhanced result processing with `validate_and_process_result`
+  * Improved success validation with `validate_overall_success`
+  * Better streaming support with proper step tracking
+* **Example Files Cleanup** - Streamlined and improved examples:
+  * Removed redundant and temporary example files
+  * Cleaned up all comments for better readability
+  * Consolidated planner agent examples
+  * Improved composite agent demonstration
+* **Test Suite Improvements** - Better test coverage and reliability:
+  * Updated CompositeAgent specs to match new behavior
+  * Fixed DateTime tool specs with proper mocking
+  * Improved test isolation and dependency handling
+
+### Fixed
+* **DateTime Tool Parsing** - Fixed "Invalid identifier" errors for multi-word timezones
+* **ReActAgent Termination** - Prevented premature stopping after DateTime tool usage
+* **CompositeAgent Streaming** - Fixed keyword argument passing for stream parameter
+* **Test Reliability** - Resolved TZInfo dependency issues in test environment
+
 ## [0.5.5] - 2025-07-17
 
 ### Changed
@@ -110,8 +155,9 @@ 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.4...HEAD
-[0.5.4]: https://github.com/FuryCow/llm_chain/compare/v0.5.3...v0.5.4
+[Unreleased]: https://github.com/FuryCow/llm_chain/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/FuryCow/llm_chain/compare/v0.5.5...v0.6.0
+[0.5.5]: https://github.com/FuryCow/llm_chain/compare/v0.5.4...v0.5.5
 [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

data/README.md

@@ -1,20 +1,15 @@
 # 🦾 LLMChain
 
 [![Gem Version](https://badge.fury.io/rb/llm_chain.svg)](https://badge.fury.io/rb/llm_chain)
-[![Tests](https://github.com/FuryCow/llm_chain/actions/workflows/tests.yml/badge.svg)](https://github.com/FuryCow/llm_chain/actions)
+[![RSpec](https://github.com/FuryCow/llm_chain/actions/workflows/rspec.yml/badge.svg?branch=master)](https://github.com/FuryCow/llm_chain/actions/workflows/rspec.yml)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
 **A powerful Ruby library for working with Large Language Models (LLMs) with intelligent tool system**
 
-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.
+**LLMChain** is a powerful Ruby library that brings the magic of Large Language Models to your applications. Think of it as your AI Swiss Army knife - whether you need to chat with models, execute code, search the web, or build intelligent agents, LLMChain has you covered.
 
-## 🎉 What's New in v0.5.3
+Built with Ruby's elegance and designed for developers who want to harness AI capabilities without the complexity, LLMChain provides a unified interface for OpenAI, Ollama, Qwen, and other leading LLMs. It comes packed with intelligent tools, smart agents, and RAG capabilities out of the box.
 
-* 🖥️ **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.
@@ -22,8 +17,9 @@ That’s all you need to start talking to LLMs straight from the terminal. See t
 ## ✨ Key Features
 
 - 🤖 **Unified API** for multiple LLMs (OpenAI, Ollama, Qwen, LLaMA2, Gemma)
+- 🧠 **Smart Agents** - CompositeAgent, ReActAgent, PlannerAgent for complex reasoning
 - 🛠️ **Intelligent tool system** with automatic selection
-- 🧮 **Built-in tools**: Calculator, web search, code interpreter
+- 🧮 **Built-in tools**: Calculator, web search, code interpreter, DateTime
 - 🔍 **RAG-ready** with vector database integration
 - 💾 **Flexible memory system** (Array, Redis)
 - 🌊 **Streaming output** for real-time responses
@@ -199,6 +195,31 @@ puts result[:formatted]
 # Output: sqrt(144) = 12.0
 ```
 
+#### 🕐 DateTime (Enhanced in v0.6.0)
+```ruby
+datetime = LLMChain::Tools::DateTime.new
+
+# Current time
+result = datetime.call("What time is it?")
+puts result[:formatted]
+# Output: 2025-07-24 15:30:45 UTC
+
+# Time in specific timezone
+result = datetime.call("What time is it in New York?")
+puts result[:formatted]
+# Output: 2025-07-24 11:30:45 EDT
+
+# Time in Europe
+result = datetime.call("What time is it in Europe/Moscow?")
+puts result[:formatted]
+# Output: 2025-07-24 18:30:45 MSK
+
+# JSON input support
+result = datetime.call('{"timezone": "Asia/Tokyo"}')
+puts result[:formatted]
+# Output: 2025-07-25 00:30:45 JST
+```
+
 #### 🌐 Web Search
 ```ruby
 # Google search for accurate results (v0.5.1+)
@@ -627,6 +648,68 @@ code_result = code_runner.call("puts 'Hello World!'")
 
 ## 📚 Usage Examples
 
+### Smart Agents (v0.6.0+)
+
+#### CompositeAgent - Intelligent Planning and Execution
+
+```ruby
+require 'llm_chain'
+
+# Create a smart composite agent
+agent = LLMChain::Agents::AgentFactory.create(
+  type: :composite,
+  model: "qwen3:1.7b",
+  max_iterations: 3
+)
+
+# Simple task - direct execution (no planning overhead)
+result = agent.run("Calculate 15 * 7 + 32")
+puts result[:final_answer]  # "137"
+puts result[:approach]      # "direct"
+
+# Complex task - intelligent planning
+result = agent.run("Find the current president of the United States and the capital of France", stream: true) do |step|
+  if step[:type] == "step_completion"
+    puts "Step #{step[:step]}/#{step[:total_steps]}: #{step[:current_step]}"
+    puts "Quality: #{step[:validated_answer][:quality_score]}/10"
+  end
+end
+
+puts result[:final_answer]
+# "Joe Biden\n\nParis\n\nSummary: The current president of the United States is Joe Biden, and the capital of France is Paris."
+```
+
+#### ReActAgent - Reasoning and Acting
+
+```ruby
+# Create a ReAct agent for complex reasoning tasks
+react_agent = LLMChain::Agents::AgentFactory.create(
+  type: :react,
+  model: "qwen3:1.7b",
+  max_iterations: 5
+)
+
+# Agent will use tools intelligently
+result = react_agent.run("What time is it in New York and what's the weather like?")
+puts result[:final_answer]
+# Uses DateTime tool first, then WebSearch for weather
+```
+
+#### PlannerAgent - Task Decomposition
+
+```ruby
+# Create a planner agent for complex task breakdown
+planner_agent = LLMChain::Agents::AgentFactory.create(
+  type: :planner,
+  model: "qwen3:1.7b"
+)
+
+# Decompose complex task into steps
+result = planner_agent.run("Plan a vacation to Japan")
+puts result[:planning_result][:steps]
+# ["Research popular destinations in Japan", "Check visa requirements", "Find flights", "Book accommodations", "Plan itinerary"]
+```
+
 ### Chatbot with Tools
 
 ```ruby
@@ -713,6 +796,10 @@ bundle exec bin/console
 ### Main Classes
 
 - `LLMChain::Chain` - Main class for creating chains
+- `LLMChain::Agents::AgentFactory` - Factory for creating smart agents
+- `LLMChain::Agents::CompositeAgent` - Intelligent planning and execution
+- `LLMChain::Agents::ReActAgent` - Reasoning and acting agent
+- `LLMChain::Agents::PlannerAgent` - Task decomposition agent
 - `LLMChain::Tools::ToolManager` - Tool management
 - `LLMChain::Memory::Array/Redis` - Memory systems
 - `LLMChain::Clients::*` - Clients for various LLMs
@@ -741,17 +828,20 @@ chain.ask(prompt, stream: false, rag_context: false, rag_options: {})
 - [x] Enhanced error handling with retry logic
 - [x] Improved code extraction and tool stability
 
-### v0.6.0 (Next)
-- [ ] ReAct agents and multi-step reasoning
+### v0.6.0 ✅ Completed
+- [x] Smart CompositeAgent with intelligent planning
+- [x] Enhanced ReActAgent with better tool integration
+- [x] Improved DateTime tool with timezone support
+- [x] Better error handling and result validation
+- [x] Streamlined examples and improved test coverage
+
+### v0.7.0 (Next)
 - [ ] More tools (file system, database queries)
 - [ ] Claude integration
 - [ ] Advanced logging and metrics
-
-### v0.7.0
 - [ ] Multi-agent systems
 - [ ] Task planning and workflows
 - [ ] Web interface for testing
-- [ ] Metrics and monitoring
 
 ### v1.0.0
 - [ ] Stable API with semantic versioning

data/examples/composite_agent_example.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/llm_chain'
+
+puts "🚀 Improved CompositeAgent Final Demo"
+puts "=" * 50
+
+agent = LLMChain::Agents::AgentFactory.create(
+  type: :composite,
+  model: "qwen3:1.7b",
+  max_iterations: 3
+)
+
+puts "✅ Improved agent created successfully"
+puts "Model: #{agent.model}"
+puts "Description: #{agent.description}"
+puts
+
+puts "🎯 Test 1: Simple Math Task (Direct Execution)"
+task1 = "Calculate 2 + 2"
+puts "Task: #{task1}"
+
+begin
+  result1 = agent.run(task1)
+  puts "✅ Result: #{result1[:final_answer]}"
+  puts "✅ Success: #{result1[:success]}"
+  puts "✅ Iterations: #{result1[:iterations]}"
+  puts "✅ Approach: #{result1[:approach]}"
+rescue => e
+  puts "❌ Error: #{e.message}"
+end
+
+puts "\n" + "=" * 60
+
+puts "🎯 Test 2: Simple Time Task (Direct Execution)"
+task2 = "What time is it?"
+puts "Task: #{task2}"
+
+begin
+  result2 = agent.run(task2)
+  puts "✅ Result: #{result2[:final_answer]}"
+  puts "✅ Success: #{result2[:success]}"
+  puts "✅ Iterations: #{result2[:iterations]}"
+  puts "✅ Approach: #{result2[:approach]}"
+rescue => e
+  puts "❌ Error: #{e.message}"
+end
+
+puts "\n" + "=" * 60
+
+puts "🎯 Test 3: Complex Task (Planning)"
+task3 = "Find the current president of the United States and the capital of France"
+puts "Task: #{task3}"
+
+begin
+  result3 = agent.run(task3, stream: true) do |step|
+    if step[:type] == "step_completion"
+      puts "  📋 Step #{step[:step]}/#{step[:total_steps]}: #{step[:current_step]}"
+      if step[:validated_answer]
+        puts "    ✅ Validated: #{step[:validated_answer][:processed_answer][0..80]}..."
+        puts "    📊 Quality Score: #{step[:validated_answer][:quality_score]}/10"
+      end
+    end
+  end
+
+  puts "\n📊 Final Result:"
+  puts "✅ Answer: #{result3[:final_answer][0..200]}..."
+  puts "✅ Success: #{result3[:success]}"
+  puts "✅ Total iterations: #{result3[:iterations]}"
+  puts "✅ Planning steps: #{result3[:planning_result][:steps].length}"
+  puts "✅ Validated answers: #{result3[:validated_answers]&.length || 0}"
+  
+rescue => e
+  puts "❌ Error: #{e.message}"
+end
+
+puts "\n" + "=" * 60
+
+puts "🎯 Test 4: Performance Comparison"
+task4 = "Calculate 15 * 7 + 32"
+
+react_agent = LLMChain::Agents::AgentFactory.create(
+  type: :react,
+  model: "qwen3:1.7b",
+  max_iterations: 3
+)
+
+puts "Task: #{task4}"
+
+puts "\n📋 ReAct Agent:"
+begin
+  react_result = react_agent.run(task4)
+  puts "✅ Result: #{react_result[:final_answer]}"
+  puts "✅ Success: #{react_result[:success]}"
+  puts "✅ Iterations: #{react_result[:iterations]}"
+rescue => e
+  puts "❌ Error: #{e.message}"
+end
+
+puts "\n📋 Improved Composite Agent:"
+begin
+  composite_result = agent.run(task4)
+  puts "✅ Result: #{composite_result[:final_answer]}"
+  puts "✅ Success: #{composite_result[:success]}"
+  puts "✅ Iterations: #{composite_result[:iterations]}"
+  puts "✅ Approach: #{composite_result[:approach]}"
+rescue => e
+  puts "❌ Error: #{e.message}"
+end
+
+puts "\n🎉 Demo completed!"
+puts
+puts "📋 Key Improvements Achieved:"
+puts "1. ✅ Smart planning detection - simple tasks use direct execution"
+puts "2. ✅ Result validation - filters out error responses"
+puts "3. ✅ Quality scoring - rates answer quality (0-10)"
+puts "4. ✅ Smart aggregation - structures multi-part responses"
+puts "5. ✅ Better success validation - checks completeness of complex tasks"
+puts "6. ✅ Meaningful info extraction - extracts relevant data from responses"
+puts "7. ✅ Efficient execution - no unnecessary planning for simple tasks"
+puts "8. ✅ Better error handling - graceful handling of failed steps" 

data/examples/planner_agent_example.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/llm_chain'
+
+puts "🧠 Simple PlannerAgent Example"
+puts "=" * 40
+
+planner = LLMChain::Agents::AgentFactory.create(
+  type: :planner,
+  model: "qwen3:1.7b"
+)
+
+puts "✅ Planner agent created successfully"
+puts "Model: #{planner.model}"
+puts "Description: #{planner.description}"
+puts
+
+puts "🎯 Example 1: Simple Task"
+task1 = "What is 2 + 2?"
+puts "Task: #{task1}"
+
+steps1 = planner.plan(task1)
+puts "Steps:"
+steps1.each_with_index do |step, index|
+  puts "  #{index + 1}. #{step}"
+end
+
+puts
+
+puts "🎯 Example 2: Multi-Part Task"
+task2 = "Find the current president of the United States and the capital of France"
+puts "Task: #{task2}"
+
+steps2 = planner.plan(task2)
+puts "Steps:"
+steps2.each_with_index do |step, index|
+  puts "  #{index + 1}. #{step}"
+end
+
+puts
+
+puts "🎯 Example 3: Complex Task"
+task3 = "Calculate 15 * 7 + 32, find the current time in Moscow, and get the population of Tokyo"
+puts "Task: #{task3}"
+
+steps3 = planner.plan(task3)
+puts "Steps:"
+steps3.each_with_index do |step, index|
+  puts "  #{index + 1}. #{step}"
+end
+
+puts
+
+puts "🎯 Example 4: Using run() method"
+task4 = "What is the current time and what year is it?"
+puts "Task: #{task4}"
+
+result4 = planner.run(task4)
+puts "Result:"
+puts "  Task: #{result4[:task]}"
+puts "  Steps: #{result4[:steps].length}"
+result4[:steps].each_with_index do |step, index|
+  puts "  #{index + 1}. #{step}"
+end
+puts "  Full result: #{result4[:result]}"
+
+puts
+
+puts "🎯 Example 5: Comparison with ReAct Agent"
+puts "Note: PlannerAgent only plans, ReActAgent executes"
+
+react_agent = LLMChain::Agents::AgentFactory.create(
+  type: :react,
+  model: "qwen3:1.7b",
+  max_iterations: 3
+)
+
+comparison_task = "What is the current time?"
+puts "Task: #{comparison_task}"
+
+puts "\nPlannerAgent result:"
+planner_steps = planner.plan(comparison_task)
+planner_steps.each_with_index do |step, index|
+  puts "  #{index + 1}. #{step}"
+end
+
+puts "\nReActAgent result:"
+begin
+  react_result = react_agent.run(comparison_task)
+  puts "  Final answer: #{react_result[:final_answer]}"
+  puts "  Iterations: #{react_result[:iterations]}"
+  puts "  Success: #{react_result[:success]}"
+rescue => e
+  puts "  Error: #{e.message}"
+end
+
+puts "\n🎉 Example completed!"
+puts
+puts "📋 Key Points:"
+puts "1. PlannerAgent breaks down complex tasks into steps"
+puts "2. It doesn't execute tasks, only plans them"
+puts "3. Use plan() for just steps, run() for full result"
+puts "4. Combine with ReActAgent for execution" 

data/examples/quick_demo.rb

@@ -5,7 +5,6 @@ require_relative '../lib/llm_chain'
 puts "🦾 LLMChain v#{LlmChain::VERSION} - Quick Demo"
 puts "=" * 50
 
-# 1. Simple chain without tools
 puts "\n1. 💬 Simple conversation"
 begin
   simple_chain = LLMChain::Chain.new(
@@ -20,19 +19,16 @@ rescue => e
   puts "💡 Make sure Ollama is running and qwen3:1.7b model is downloaded"
 end
 
-# 2. Calculator
 puts "\n2. 🧮 Built-in calculator"
 calculator = LLMChain::Tools::Calculator.new
 result = calculator.call("Calculate 25 * 8 + 15")
 puts "📊 #{result[:formatted]}"
 
-# 3. Code interpreter
 puts "\n3. 💻 Code interpreter"
 begin
   interpreter = LLMChain::Tools::CodeInterpreter.new
   ruby_code = <<~RUBY_CODE
     ```ruby
-    # Simple program
     data = [1, 2, 3, 4, 5]
     total = data.sum
     puts "Sum of numbers: \#{total}"
@@ -54,7 +50,6 @@ rescue => e
   puts "❌ Interpreter error: #{e.message}"
 end
 
-# 4. Web search (may not work without internet)
 puts "\n4. 🔍 Web search"
 search = LLMChain::Tools::WebSearch.new
 search_result = search.call("Ruby programming language")
@@ -68,7 +63,6 @@ else
   puts "❌ Search failed or no results found"
 end
 
-# 5. Chain with tools
 puts "\n5. 🛠️ Chain with automatic tools"
 begin
   tool_manager = LLMChain::Tools::ToolManagerFactory.create_default_toolset

data/examples/react_agent_example.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/llm_chain'
+
+puts "🤖 LLMChain ReAct Agent Example"
+puts "=" * 50
+
+agent = LLMChain::Agents::AgentFactory.create(
+  type: :react,
+  model: "deepseek-coder-v2:16b",
+  max_iterations: 10
+)
+
+puts "Agent created: #{agent.description}"
+puts "Available tools: #{agent.tools.list_tools.map(&:name).join(', ')}"
+puts
+
+task = "Calculate 15 * 7 + 32"
+puts "🎯 Task: #{task}"
+puts "Processing..."
+
+result = agent.run(task, stream: true) do |step|
+  puts "  Step #{step[:iteration]}: #{step[:thought]}"
+  if step[:action]
+    puts "    Action: #{step[:action]} (#{step[:action_input]})"
+  end
+end
+
+puts
+puts "✅ Final Answer: #{result[:final_answer]}"
+puts "📊 Iterations: #{result[:iterations]}"
+puts "🎯 Success: #{result[:success]}"
+puts
+
+task2 = "Who is the president of the United States? and who was the president before him?"
+puts "🎯 Complex Task: #{task2}"
+puts "Processing..."
+
+result2 = agent.run(task2, stream: true) do |step|
+  puts "  Step #{step[:iteration]}: #{step[:thought][0..100]}..."
+  if step[:action]
+    puts "    Action: #{step[:action]} (#{step[:action_input]})"
+  end
+end
+
+puts
+puts "✅ Final Answer: #{result2[:final_answer]}"
+puts "📊 Iterations: #{result2[:iterations]}"
+puts "🎯 Success: #{result2[:success]}" 
+
+task3 = "Which tools are available to me?"
+puts "🎯 Task: #{task3}"
+puts "Processing..."
+
+result3 = agent.run(task3, stream: true) do |step|
+  puts "  Step #{step[:iteration]}: #{step[:thought]}"
+  if step[:action]
+    puts "    Action: #{step[:action]} (#{step[:action_input]})"
+  end
+end
+
+puts "✅ Final Answer: #{result3[:final_answer]}"
+puts "📊 Iterations: #{result3[:iterations]}"
+puts "🎯 Success: #{result3[:success]}"