soka 0.0.1.beta2

data/examples/6_retry.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'soka'
+require 'dotenv/load'
+
+# Configure Soka
+Soka.setup do |config|
+  config.ai do |ai|
+    ai.provider = :gemini
+    ai.model = 'gemini-2.5-flash-lite'
+    ai.api_key = ENV.fetch('GEMINI_API_KEY', nil)
+  end
+end
+
+# Flaky API tool that fails randomly
+class FlakyApiTool < Soka::AgentTool
+  desc 'Call unreliable API'
+
+  params do
+    requires :action, String, desc: 'Action to perform'
+  end
+
+  def initialize
+    super
+    @call_count = 0
+  end
+
+  def call(action:)
+    @call_count += 1
+    puts "  🔄 API call attempt ##{@call_count} for: #{action}"
+    
+    # Fail 60% of the time on first 2 attempts
+    if @call_count <= 2 && rand < 0.6
+      raise StandardError, "Network timeout on attempt #{@call_count}"
+    end
+    
+    "Success: #{action} completed after #{@call_count} attempts"
+  end
+end
+
+# Rate limited tool
+class RateLimitedTool < Soka::AgentTool
+  desc 'API with rate limiting'
+
+  params do
+    requires :query, String, desc: 'Query to execute'
+  end
+
+  def initialize
+    super
+    @last_call = Time.now - 10
+  end
+
+  def call(query:)
+    time_since_last = Time.now - @last_call
+    
+    if time_since_last < 1
+      raise StandardError, 'Rate limit exceeded. Please wait 1 second between calls.'
+    end
+    
+    @last_call = Time.now
+    "Query result for: #{query}"
+  end
+end
+
+# Agent with retry configuration
+class RetryAgent < Soka::Agent
+  tool FlakyApiTool
+  tool RateLimitedTool
+  
+  # The framework has built-in retry with exponential backoff
+end
+
+# Agent with custom configuration
+class CustomRetryAgent < Soka::Agent
+  tool FlakyApiTool
+  
+  # Configure max iterations (which affects retry behavior)
+  max_iterations 2
+end
+
+# Main program
+puts '=== Soka Retry Example ==='
+puts "Demonstrating retry mechanisms\n\n"
+
+# Example 1: Basic retry with exponential backoff
+puts 'Example 1: Retry with exponential backoff'
+puts '-' * 50
+
+agent = RetryAgent.new
+puts "Calling flaky API (may fail and retry)..."
+
+result = agent.run('Call the flaky API to fetch user data')
+puts "\nFinal result: #{result.final_answer}"
+puts "Success after retries: #{!result.failed?}"
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 2: Simple retry configuration
+puts 'Example 2: Simple retry configuration'
+puts '-' * 50
+
+simple_agent = CustomRetryAgent.new
+puts "Using simple retry (max 2 attempts)..."
+
+# Reset the tool's call count
+simple_agent.tools.first.instance_variable_set(:@call_count, 0)
+
+result = simple_agent.run('Perform critical operation')
+puts "\nResult: #{result.final_answer}"
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 3: Rate limiting with retry
+puts 'Example 3: Handling rate limits'
+puts '-' * 50
+
+agent = RetryAgent.new
+puts "Making rapid API calls (will hit rate limit)..."
+
+queries = ['Query 1', 'Query 2', 'Query 3']
+queries.each do |query|
+  puts "\nExecuting: #{query}"
+  result = agent.run("Use the rate limited API for: #{query}")
+  puts "Result: #{result.final_answer[0..50]}..."
+  sleep(0.5) # Small delay between queries
+end
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 4: No retry configuration
+puts 'Example 4: Agent without retry (for comparison)'
+puts '-' * 50
+
+class NoRetryAgent < Soka::Agent
+  tool FlakyApiTool
+end
+
+no_retry_agent = NoRetryAgent.new
+puts "Calling flaky API without retry..."
+
+begin
+  # Reset call count
+  no_retry_agent.tools.first.instance_variable_set(:@call_count, 0)
+  result = no_retry_agent.run('Try once without retry')
+  puts "Success on first try!"
+rescue => e
+  puts "Failed immediately: #{e.message}"
+end
+
+puts "\n=== Retry Benefits ==="
+puts "1. Handles transient network failures"
+puts "2. Deals with rate limiting gracefully"
+puts "3. Improves reliability of AI agents"
+puts "4. Configurable backoff strategies"
+puts "5. Selective retry based on error types"
+
+puts "\n=== Retry Strategies ==="
+puts "1. Fixed delay: Wait same time between retries"
+puts "2. Exponential backoff: Increasing delays (1s, 2s, 4s...)"
+puts "3. Linear backoff: Linear increase (1s, 2s, 3s...)"
+puts "4. Custom logic: Define your own retry behavior"

data/examples/7_tool_conditional.rb

@@ -0,0 +1,180 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'soka'
+require 'dotenv/load'
+
+# Configure Soka
+Soka.setup do |config|
+  config.ai do |ai|
+    ai.provider = :gemini
+    ai.model = 'gemini-2.5-flash-lite'
+    ai.api_key = ENV.fetch('GEMINI_API_KEY', nil)
+  end
+end
+
+# Development-only debugging tool
+class DebugTool < Soka::AgentTool
+  desc 'Debug internal state (dev only)'
+
+  def call
+    "Debug info: Memory size=#{@agent&.memory&.messages&.size || 0}, Time=#{Time.now}"
+  end
+end
+
+# Production monitoring tool
+class MonitoringTool < Soka::AgentTool
+  desc 'Monitor system metrics'
+
+  def call
+    "System metrics: CPU=#{rand(10..90)}%, Memory=#{rand(30..70)}%, Uptime=#{rand(1..100)}h"
+  end
+end
+
+# Admin-only tool
+class AdminTool < Soka::AgentTool
+  desc 'Perform admin operations'
+
+  params do
+    requires :operation, String, desc: 'Admin operation to perform'
+  end
+
+  def call(operation:)
+    "Admin operation '#{operation}' completed successfully"
+  end
+end
+
+# Feature flag tool
+class FeatureFlagTool < Soka::AgentTool
+  desc 'Check feature flags'
+
+  params do
+    requires :flag, String, desc: 'Feature flag name'
+  end
+
+  def call(flag:)
+    # Simulate feature flag service
+    enabled = %w[new_ui dark_mode beta_features].include?(flag)
+    "Feature '#{flag}' is #{enabled ? 'enabled' : 'disabled'}"
+  end
+end
+
+# Environment-aware agent
+class ConditionalAgent < Soka::Agent
+  # Always available tools
+  tool FeatureFlagTool
+
+  # Conditional tools based on environment
+  tool DebugTool, if: -> { ENV['ENVIRONMENT'] == 'development' }
+  tool MonitoringTool, if: -> { %w[staging production].include?(ENV['ENVIRONMENT']) }
+  tool AdminTool, if: -> { ENV['USER_ROLE'] == 'admin' }
+end
+
+# Dynamic condition agent
+class DynamicConditionAgent < Soka::Agent
+  # Load tool based on time of day
+  tool DebugTool, if: -> { Time.now.hour.between?(9, 17) } # Business hours only
+  
+  # Load based on environment variable
+  tool MonitoringTool, if: -> { ENV['ENABLE_MONITORING'] == 'true' }
+  
+  # Multiple conditions
+  tool AdminTool, if: -> { ENV['USER_ROLE'] == 'admin' && ENV['SECURE_MODE'] == 'true' }
+end
+
+# Main program
+puts '=== Soka Conditional Tool Example ==='
+puts "Demonstrating conditional tool loading\n\n"
+
+# Example 1: Environment-based tools
+puts 'Example 1: Environment-based tool loading'
+puts '-' * 50
+
+environments = %w[development staging production]
+
+environments.each do |env|
+  ENV['ENVIRONMENT'] = env
+  agent = ConditionalAgent.new
+  
+  puts "\nEnvironment: #{env}"
+  puts "Loaded tools: #{agent.tools.map { |t| t.class.name }.join(', ')}"
+  
+  # Try to use monitoring
+  result = agent.run('Check system monitoring metrics')
+  puts "Result: #{result.final_answer}"
+end
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 2: Role-based tools
+puts 'Example 2: Role-based tool access'
+puts '-' * 50
+
+roles = %w[user admin guest]
+
+roles.each do |role|
+  ENV['USER_ROLE'] = role
+  ENV['ENVIRONMENT'] = 'production'
+  agent = ConditionalAgent.new
+  
+  puts "\nUser role: #{role}"
+  puts "Available tools: #{agent.tools.map { |t| t.class.name }.join(', ')}"
+  
+  if role == 'admin'
+    result = agent.run('Perform admin operation: restart_service')
+    puts "Admin result: #{result.final_answer}"
+  else
+    puts "Admin tools not available for #{role} role"
+  end
+end
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 3: Dynamic conditions
+puts 'Example 3: Dynamic condition checking'
+puts '-' * 50
+
+# Set up dynamic conditions
+ENV['ENABLE_MONITORING'] = 'true'
+ENV['USER_ROLE'] = 'admin'
+ENV['SECURE_MODE'] = 'true'
+
+dynamic_agent = DynamicConditionAgent.new
+puts "Current time: #{Time.now}"
+puts "Business hours tool available: #{Time.now.hour.between?(9, 17)}"
+puts "Monitoring enabled: #{ENV['ENABLE_MONITORING']}"
+puts "Admin with secure mode: #{ENV['USER_ROLE'] == 'admin' && ENV['SECURE_MODE'] == 'true'}"
+puts "\nLoaded tools: #{dynamic_agent.tools.map { |t| t.class.name }.join(', ')}"
+
+result = dynamic_agent.run('List all available debugging options')
+puts "\nResult: #{result.final_answer}"
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 4: Feature flags
+puts 'Example 4: Feature flag integration'
+puts '-' * 50
+
+agent = ConditionalAgent.new
+features = %w[new_ui dark_mode legacy_support beta_features]
+
+puts "Checking feature flags:"
+features.each do |feature|
+  result = agent.run("Check if feature flag '#{feature}' is enabled")
+  puts "- #{feature}: #{result.final_answer.include?('enabled') ? '✓' : '✗'}"
+end
+
+puts "\n=== Conditional Tool Benefits ==="
+puts "1. Environment-specific functionality"
+puts "2. Role-based access control"
+puts "3. Feature flag integration"
+puts "4. Resource optimization"
+puts "5. Security through tool isolation"
+
+puts "\n=== Use Cases ==="
+puts "1. Debug tools only in development"
+puts "2. Admin tools for privileged users"
+puts "3. Monitoring in production only"
+puts "4. Beta features behind flags"
+puts "5. Time-based tool availability"

data/examples/8_multi_provider.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'soka'
+require 'dotenv/load'
+
+# Configure Soka with all providers
+Soka.setup do |config|
+  # Default configuration can be overridden per agent
+  config.ai do |ai|
+    ai.provider = :gemini
+    ai.model = 'gemini-2.5-flash-lite'
+  end
+end
+
+# Simple analysis tool
+class AnalysisTool < Soka::AgentTool
+  desc 'Analyze text or data'
+
+  params do
+    requires :content, String, desc: 'Content to analyze'
+  end
+
+  def call(content:)
+    word_count = content.split.size
+    char_count = content.length
+    "Analysis: #{word_count} words, #{char_count} characters"
+  end
+end
+
+# Gemini Agent
+class GeminiAgent < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+  api_key ENV.fetch('GEMINI_API_KEY', nil)
+
+  tool AnalysisTool
+end
+
+# OpenAI Agent
+class OpenAIAgent < Soka::Agent
+  provider :openai
+  model 'gpt-4o-mini'
+  api_key ENV.fetch('OPENAI_API_KEY', nil)
+
+  tool AnalysisTool
+end
+
+# Anthropic Agent
+class AnthropicAgent < Soka::Agent
+  provider :anthropic
+  model 'claude-3-5-haiku-latest'
+  api_key ENV.fetch('ANTHROPIC_API_KEY', nil)
+
+  tool AnalysisTool
+end
+
+# Main program
+puts '=== Soka Multi-Provider Example ==='
+puts "Demonstrating multiple LLM providers\n\n"
+
+# Example 1: Different providers for same task
+puts 'Example 1: Same task with different providers'
+puts '-' * 50
+
+task = 'Analyze this text: "Soka is a Ruby framework for building AI agents"'
+
+# Try with Gemini
+if ENV['GEMINI_API_KEY']
+  puts "\n🔷 Using Gemini:"
+  gemini_agent = GeminiAgent.new
+  result = gemini_agent.run(task)
+  puts "Response: #{result.final_answer}"
+  puts "Provider: Gemini (#{gemini_agent.llm.model})"
+else
+  puts "\n🔷 Gemini: Skipped (no API key)"
+end
+
+# Try with OpenAI
+if ENV['OPENAI_API_KEY']
+  puts "\n🟧 Using OpenAI:"
+  openai_agent = OpenAIAgent.new
+  result = openai_agent.run(task)
+  puts "Response: #{result.final_answer}"
+  puts "Provider: OpenAI (#{openai_agent.llm.model})"
+else
+  puts "\n🟧 OpenAI: Skipped (no API key)"
+end
+
+# Try with Anthropic
+if ENV['ANTHROPIC_API_KEY']
+  puts "\n🔶 Using Anthropic:"
+  anthropic_agent = AnthropicAgent.new
+  result = anthropic_agent.run(task)
+  puts "Response: #{result.final_answer}"
+  puts "Provider: Anthropic (#{anthropic_agent.llm.model})"
+else
+  puts "\n🔶 Anthropic: Skipped (no API key)"
+end
+
+puts "\n=== Multi-Provider Benefits ==="
+puts '1. Flexibility to choose best model for each task'
+puts '2. Cost optimization (use cheaper models when appropriate)'
+puts '3. Fallback options for reliability'
+puts '4. Access to provider-specific features'
+puts '5. Compare outputs across different models'
+
+puts "\n=== Provider Comparison ==="
+puts 'Gemini: Fast, cost-effective, good for general tasks'
+puts 'OpenAI: Powerful GPT models, great for complex reasoning'
+puts 'Anthropic: Claude models, excellent for analysis and writing'

data/lib/soka/agent.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Soka
+  # Base class for AI agents that use ReAct pattern
+  class Agent
+    include Agents::RetryHandler
+    include Agents::ToolBuilder
+    include Agents::HookManager
+    include Agents::DSLMethods
+    include Agents::LLMBuilder
+
+    attr_reader :llm, :tools, :memory, :thoughts_memory, :engine
+
+    # Initialize a new Agent instance
+    # @param memory [Memory, Array, nil] The memory instance to use (defaults to new Memory)
+    #   Can be a Memory instance or an Array of message hashes
+    # @param engine [Class] The engine class to use (defaults to Engine::React)
+    # @param options [Hash] Configuration options
+    # @option options [Integer] :max_iterations Maximum iterations for reasoning
+    # @option options [Integer] :timeout Timeout in seconds for operations
+    # @option options [Symbol] :provider LLM provider override
+    # @option options [String] :model LLM model override
+    # @option options [String] :api_key LLM API key override
+    def initialize(memory: nil, engine: Engines::React, **options)
+      @memory = initialize_memory(memory)
+      @thoughts_memory = ThoughtsMemory.new
+      @engine = engine
+
+      # Initialize components
+      @llm = build_llm(options)
+      @tools = build_tools
+
+      # Apply configuration with clear defaults
+      apply_configuration(options)
+    end
+
+    # Apply configuration options with defaults
+    # @param options [Hash] Configuration options
+    def apply_configuration(options)
+      @max_iterations = options.fetch(:max_iterations) { self.class._max_iterations || 10 }
+      @timeout = options.fetch(:timeout) { self.class._timeout || 30 }
+    end
+
+    # Run the agent with the given input
+    # @param input [String] The input query or task
+    # @yield [event] Optional block to handle events during execution
+    # @return [Result] The result of the agent's reasoning
+    def run(input, &)
+      validate_input(input)
+      execute_reasoning(input, &)
+    rescue ArgumentError
+      raise # Re-raise ArgumentError without handling
+    rescue StandardError => e
+      handle_error(e, input)
+    end
+
+    private
+
+    # Initialize memory from various input formats
+    # @param memory [Memory, Array, nil] The memory input
+    # @return [Memory] The initialized memory instance
+    def initialize_memory(memory)
+      case memory
+      when Memory
+        memory
+      when Array
+        Memory.new(memory)
+      when nil
+        Memory.new
+      else
+        raise ArgumentError, "Invalid memory type: #{memory.class}. Expected Memory, Array, or nil"
+      end
+    end
+
+    # Validate the input is not empty
+    # @param input [String] The input to validate
+    # @raise [ArgumentError] If input is empty
+    def validate_input(input)
+      raise ArgumentError, 'Input cannot be empty' if input.to_s.strip.empty?
+    end
+
+    # Execute the reasoning process with hooks
+    # @param input [String] The input query
+    # @yield [event] Optional block to handle events
+    # @return [Result] The reasoning result
+    def execute_reasoning(input, &)
+      run_hooks(:before_action, input)
+
+      engine_result = perform_reasoning(input, &)
+      result = convert_engine_result(engine_result)
+
+      finalize_result(input, result)
+      result
+    end
+
+    # Perform the actual reasoning using the engine
+    # @param input [String] The input query
+    # @yield [event] Optional block to handle events
+    # @return [EngineResult] The raw engine result
+    def perform_reasoning(input, &)
+      engine_instance = @engine.new(self, @llm, @tools, @max_iterations)
+      with_retry { engine_instance.reason(input, &) }
+    end
+
+    # Finalize the result by updating memories and running hooks
+    # @param input [String] The original input
+    # @param result [Result] The result to finalize
+    def finalize_result(input, result)
+      update_memories(input, result)
+      run_hooks(:after_action, result)
+    end
+
+    # Handle errors during execution
+    # @param error [StandardError] The error that occurred
+    # @param input [String] The original input
+    # @return [Result] An error result
+    # @raise [StandardError] Re-raises if on_error hook returns :stop
+    def handle_error(error, input)
+      error_action = run_hooks(:on_error, error, input)
+      raise error if error_action == :stop
+
+      build_error_result(input, error)
+    end
+
+    # Tool building methods are in ToolBuilder module
+    # Retry handling methods are in RetryHandler module
+    # LLM building methods are in LLMBuilder module
+    # Hook management methods are in HookManager module
+  end
+end