soka 0.0.1.beta2

data/examples/1_basic.rb

@@ -0,0 +1,94 @@
+#!/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
+
+  config.performance do |perf|
+    perf.max_iterations = 5
+    perf.timeout = 30
+  end
+end
+
+# Define a simple search tool
+class SearchTool < Soka::AgentTool
+  desc 'Search the web for information'
+
+  params do
+    requires :query, String, desc: 'The query to search for'
+  end
+
+  def call(query:)
+    puts "SearchTool call: #{query}"
+    # This is a simulated search result
+    case query.downcase
+    when /weather/
+      'Today in Taipei: Sunny, Temperature 28°C, Humidity 65%'
+    when /news/
+      'Today\'s headline: AI technology reaches new milestone'
+    else
+      "Searching for information about '#{query}'..."
+    end
+  end
+end
+
+# Define time tool
+class TimeTool < Soka::AgentTool
+  desc 'Get current time and date'
+
+  def call
+    puts 'TimeTool call'
+    Time.now.strftime('%Y-%m-%d %H:%M:%S')
+  end
+end
+
+# Define Agent
+class DemoAgent < Soka::Agent
+  tool SearchTool
+  tool TimeTool
+end
+
+# Use Agent
+agent = DemoAgent.new
+
+puts '=== Soka Demo Agent ==='
+puts
+
+# Example 1: Ask about weather
+puts 'Question: What\'s the weather like in Taipei today?'
+puts '-' * 50
+
+agent.run('What\'s the weather like in Taipei today?') do |event|
+  case event.type
+  when :thought
+    puts "💭 Thinking: #{event.content}"
+  when :action
+    puts "🔧 Action: Using tool #{event.content[:tool]}"
+  when :observation
+    puts "👀 Observation: #{event.content}"
+  when :final_answer
+    puts "✅ Answer: #{event.content}"
+  end
+end
+
+puts
+puts '=' * 50
+puts
+
+# Example 2: Ask about time
+puts 'Question: What time is it now?'
+puts '-' * 50
+
+result = agent.run('What time is it now?')
+puts "✅ Answer: #{result.final_answer}"
+puts "📊 Confidence: #{(result.confidence_score * 100).round(1)}%"
+puts "⏱️  Iterations: #{result.iterations}"

data/examples/2_event_handling.rb

@@ -0,0 +1,120 @@
+#!/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
+
+  config.performance do |perf|
+    perf.max_iterations = 5
+    perf.timeout = 30
+  end
+end
+
+# Simple calculation tool
+class CalculatorTool < Soka::AgentTool
+  desc 'Perform calculations'
+
+  params do
+    requires :expression, String, desc: 'Mathematical expression to calculate'
+  end
+
+  def call(expression:)
+    result = eval(expression) # rubocop:disable Security/Eval
+    "Result: #{expression} = #{result}"
+  rescue StandardError => e
+    "Error: #{e.message}"
+  end
+end
+
+# Weather tool
+class WeatherTool < Soka::AgentTool
+  desc 'Get weather information'
+
+  params do
+    requires :location, String, desc: 'Location to get weather for'
+  end
+
+  def call(location:)
+    # Simulated weather data
+    "Weather in #{location}: Sunny, 22°C"
+  end
+end
+
+# Define streaming agent
+class StreamingAgent < Soka::Agent
+  tool CalculatorTool
+  tool WeatherTool
+end
+
+# Main program
+puts '=== Soka Event Handling Example ==='
+puts "Demonstrating event-based responses\n\n"
+puts "NOTE: Streaming is not yet fully integrated with the event system\n"
+
+agent = StreamingAgent.new
+
+# Example 1: Event-based response handling
+puts 'Example 1: Simple calculation with event handling'
+puts '-' * 50
+
+agent.run('Calculate 123 * 456') do |event|
+  case event.type
+  when :thought
+    puts "💭 Thinking: #{event.content}"
+  when :action
+    puts "🔧 Action: Using #{event.content[:tool]}"
+  when :observation
+    puts "👀 Result: #{event.content}"
+  when :final_answer
+    puts "✅ Final: #{event.content}"
+  when :error
+    puts "❌ Error: #{event.content}"
+  end
+end
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 2: Multi-step task with event handling
+puts 'Example 2: Multi-step task with event handling'
+puts '-' * 50
+
+agent.run('What is the weather in Tokyo? Also calculate 15% tip on $85.50') do |event|
+  case event.type
+  when :thought
+    puts "💭 Thinking: #{event.content}"
+  when :action
+    puts "🔧 Action: #{event.content[:tool]}"
+    puts "   Input: #{event.content[:params]}" if event.content[:params]
+  when :observation
+    puts "👀 Result: #{event.content}"
+  when :final_answer
+    puts "✅ Complete: #{event.content}"
+  end
+end
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 3: Without event handling (direct result)
+puts 'Example 3: Without event handling (direct result)'
+puts '-' * 50
+
+result = agent.run('Calculate the area of a circle with radius 5')
+puts "Direct result: #{result.final_answer}"
+puts "Confidence: #{(result.confidence_score * 100).round(1)}%"
+puts "Iterations: #{result.iterations}"
+
+puts "\n=== Event Handling Benefits ==="
+puts "1. Real-time feedback on agent's thinking process"
+puts "2. Visibility into tool usage and results"
+puts "3. Can track progress during complex tasks"
+puts "4. Debugging support with detailed event logs"
+puts "\nNote: True streaming of LLM responses is not yet integrated with events"

data/examples/3_memory.rb

@@ -0,0 +1,182 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'soka'
+require 'dotenv/load'
+require 'singleton'
+
+# 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
+
+  config.performance do |perf|
+    perf.max_iterations = 10
+    perf.timeout = 30
+  end
+end
+
+# Calculator tool - Simple math calculations
+class CalculatorTool < Soka::AgentTool
+  desc 'Perform basic math operations'
+
+  params do
+    requires :expression, String, desc: "Mathematical expression, e.g., '2 + 2' or '10 * 5'"
+  end
+
+  def call(expression:)
+    # Simple math expression evaluation (production should use safer methods)
+    result = eval(expression) # rubocop:disable Security/Eval
+    "Calculation result: #{expression} = #{result}"
+  rescue StandardError => e
+    "Calculation error: #{e.message}"
+  end
+end
+
+# Shared memory manager
+class SharedMemory
+  include Singleton
+
+  def initialize
+    @storage = {}
+  end
+
+  def store(key, value)
+    @storage[key] = value
+  end
+
+  def retrieve(key)
+    @storage[key]
+  end
+
+  def exists?(key)
+    @storage.key?(key)
+  end
+end
+
+# Memory tool - Store and retrieve information
+class MemoryTool < Soka::AgentTool
+  desc 'Remember important information'
+
+  params do
+    requires :key, String, desc: 'Information key'
+    requires :value, String, desc: 'Content to remember'
+  end
+
+  def call(key:, value:)
+    SharedMemory.instance.store(key, value)
+    "Remembered: #{key} = #{value}"
+  end
+end
+
+# Recall tool - Retrieve previously remembered information
+class RecallTool < Soka::AgentTool
+  desc 'Recall previously remembered information'
+
+  params do
+    requires :key, String, desc: 'Information key to recall'
+  end
+
+  def call(key:)
+    if SharedMemory.instance.exists?(key)
+      value = SharedMemory.instance.retrieve(key)
+      "Recalled: #{key} = #{value}"
+    else
+      "No memory found for '#{key}'"
+    end
+  end
+end
+
+# Define Agent
+class MemoryAgent < Soka::Agent
+  tool CalculatorTool
+  tool MemoryTool
+  tool RecallTool
+end
+
+# Main program
+puts '=== Soka Memory Example ==='
+puts "Testing Agent memory functionality\n\n"
+
+# Program starts
+
+# Method 1: Using Soka::Memory class
+puts '>>> Method 1: Using Soka::Memory class'
+soka_memory = Soka::Memory.new
+soka_memory.add(role: 'user', content: 'My name is Xiao Ming, I am 25 years old')
+soka_memory.add(role: 'assistant', content: 'Nice to meet you, Xiao Ming! I will remember that you are 25 years old.')
+
+# Method 2: Using Array (direct format)
+puts '>>> Method 2: Using Array (direct format)'
+memory_array = [{
+  role: 'user',
+  content: 'My name is Xiao Ming, I am 25 years old'
+}, {
+  role: 'assistant',
+  content: 'Nice to meet you, Xiao Ming! I will remember that you are 25 years old.'
+}]
+
+# Both methods work - Soka will convert Array to Memory object automatically
+memory = soka_memory  # You can use either initial_memory_obj or initial_memory_array
+
+# Example of using array format (uncomment to use this instead)
+# memory = memory_array
+
+# Test case 1: Basic calculation and memory
+puts '\nTest 1: Basic calculation and memory'
+# Agent with initial memory
+agent_with_memory = MemoryAgent.new(memory: memory)
+result = agent_with_memory.run(
+  "Please calculate 15 * 8, and remember this calculation result with key 'first_calc'"
+)
+puts "Agent: #{result.final_answer}"
+puts "Confidence: #{(result.confidence_score * 100).round(1)}%"
+puts "Iterations: #{result.iterations}"
+puts '-' * 50
+
+# Test case 2: Recall previous information
+puts "\nTest 2: Recall previous calculation"
+# Continue using the same agent, as it already has memory
+result = agent_with_memory.run(
+  "Please recall what the value of 'first_calc' is?"
+)
+puts "Agent: #{result.final_answer}"
+puts '-' * 50
+
+# Test case 3: Use remembered information for new calculations
+puts "\nTest 3: Complex memory operations"
+result = agent_with_memory.run(
+  "Please remember that pi is 3.14159, then calculate the area of a circle with radius 5 (using pi * r * r), and remember the result as 'circle_area'"
+)
+puts "Agent: #{result.final_answer}"
+puts '-' * 50
+
+# Test case 4: Recall information from initial memory
+puts "\nTest 4: Recall initial information"
+result = agent_with_memory.run(
+  'Do you remember my name and age?'
+)
+puts "Agent: #{result.final_answer}"
+puts '-' * 50
+
+# Display complete conversation history
+puts "\n=== Complete Conversation History ==="
+agent_with_memory.memory.messages.each_with_index do |msg, idx|
+  puts "#{idx + 1}. [#{msg[:role]}]: #{msg[:content][0..100]}#{'…' if msg[:content].length > 100}"
+end
+
+# Display the last thinking process
+puts "\n=== Last Thinking Process ==="
+if result.thoughts&.any?
+  result.thoughts.each_with_index do |thought_item, idx|
+    step = thought_item[:step] || (idx + 1)
+    content = thought_item[:thought] || thought_item[:content] || ''
+    puts "#{step}. #{content[0..200]}#{'…' if content.length > 200}"
+  end
+else
+  puts 'No thinking process recorded'
+end

data/examples/4_hooks.rb

@@ -0,0 +1,140 @@
+#!/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
+
+# Simple database tool
+class DatabaseTool < Soka::AgentTool
+  desc 'Query database'
+
+  params do
+    requires :query, String, desc: 'SQL query to execute'
+  end
+
+  def call(query:)
+    # Simulated database query
+    if query.downcase.include?('select')
+      "Found 5 records matching your query"
+    else
+      "Query executed successfully"
+    end
+  end
+end
+
+# Agent with hooks
+class HookedAgent < Soka::Agent
+  tool DatabaseTool
+
+  # Hook called before action
+  before_action :log_request
+  
+  # Hook called after action
+  after_action :log_response
+  
+  # Hook called on error
+  on_error :handle_error
+
+  private
+
+  def log_request(input)
+    puts "🔵 [BEFORE] Starting request: #{input}"
+    puts "🔵 [BEFORE] Memory size: #{@memory.messages.size} messages"
+    puts "🔵 [BEFORE] Available tools: #{@tools.map { |t| t.class.name }.join(', ')}"
+    puts '-' * 50
+  end
+
+  def log_response(result)
+    puts '-' * 50
+    puts "🟢 [AFTER] Request completed"
+    puts "🟢 [AFTER] Final answer: #{result.final_answer[0..100]}..."
+    puts "🟢 [AFTER] Iterations: #{result.iterations}"
+    puts "🟢 [AFTER] Confidence: #{(result.confidence_score * 100).round(1)}%"
+    puts "🟢 [AFTER] Memory size: #{@memory.messages.size} messages"
+  end
+
+  def handle_error(error, input)
+    puts "🔴 [ERROR] An error occurred!"
+    puts "🔴 [ERROR] Input: #{input}"
+    puts "🔴 [ERROR] Error: #{error.message}"
+    puts "🔴 [ERROR] Backtrace: #{error.backtrace.first(3).join("\n")}"
+    
+    # Return :continue to continue execution with error result
+    # Return :stop to re-raise the error
+    :continue
+  end
+end
+
+# Main program
+puts '=== Soka Hooks Example ==='
+puts "Demonstrating lifecycle hooks\n\n"
+
+agent = HookedAgent.new
+
+# Example 1: Normal execution with hooks
+puts 'Example 1: Normal execution showing all hooks'
+puts '=' * 50
+
+result = agent.run('Query the database for user statistics')
+puts "\nResult: #{result.final_answer}" if result.respond_to?(:final_answer)
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 2: Multiple calls showing memory growth
+puts 'Example 2: Multiple calls showing memory tracking'
+puts '=' * 50
+
+queries = [
+  'Select all active users',
+  'Count total orders this month',
+  'Find top selling products'
+]
+
+queries.each_with_index do |query, index|
+  puts "\n--- Query #{index + 1} ---"
+  agent.run(query)
+  sleep(0.5) # Small delay for visibility
+end
+
+puts "\n" + '=' * 50 + "\n"
+
+# Example 3: Error handling
+puts 'Example 3: Error handling with hooks'
+puts '=' * 50
+
+# Create a tool that will trigger an error
+class ErrorTool < Soka::AgentTool
+  desc 'This tool simulates errors'
+  
+  def call
+    raise StandardError, 'This is a simulated tool error!'
+  end
+end
+
+class ErrorHandlingAgent < HookedAgent
+  tool ErrorTool
+end
+
+error_agent = ErrorHandlingAgent.new
+result = error_agent.run('Use the error tool to test error handling')
+puts "\nError handled gracefully: #{result.failed? ? 'Yes' : 'No'}"
+puts "Final answer: #{result.final_answer}" if result.final_answer
+puts "Error message: #{result.error}" if result.error
+
+puts "\n=== Hook Benefits ==="
+puts "1. Logging and monitoring of agent activity"
+puts "2. Pre-processing of inputs before execution"
+puts "3. Post-processing of results"
+puts "4. Custom error handling and recovery"
+puts "5. Performance tracking and metrics"
+puts "6. Integration with external systems"

data/examples/5_error_handling.rb

@@ -0,0 +1,85 @@
+#!/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
+
+# Tool that can demonstrate different scenarios
+class DemoTool < Soka::AgentTool
+  desc 'A tool that can succeed or fail based on input'
+
+  params do
+    requires :action, String, inclusion: %w[success fail],
+                              desc: 'Whether to succeed or fail'
+  end
+
+  def call(action:)
+    case action
+    when 'success'
+      'Operation completed successfully!'
+    when 'fail'
+      raise StandardError, 'Tool execution failed as requested!'
+    end
+  end
+end
+
+# Agent with error handling
+class ErrorDemoAgent < Soka::Agent
+  tool DemoTool
+
+  # This hook now handles ALL errors (both Tool and Agent-level)
+  on_error :handle_errors
+
+  private
+
+  def handle_errors(error, input)
+    puts "\n🔴 Error Handler Triggered!"
+    puts "   Error Type: #{error.class}"
+    puts "   Error Message: #{error.message}"
+    puts "   Original Input: #{input}"
+
+    # Return :continue to get an error result but continue execution
+    # Return :stop to re-raise the error and halt
+    :continue
+  end
+end
+
+# Run demonstrations
+puts "=== Soka Error Handling Example ==="
+puts "Demonstrating that ALL errors now trigger the on_error hook\n\n"
+
+agent = ErrorDemoAgent.new
+
+# Example 1: Successful operation
+puts "1. Successful Operation:"
+puts "-" * 40
+result = agent.run('Use the demo tool with action=success')
+puts "Status: #{result.status}"
+puts "Success?: #{result.successful?}"
+puts "Answer: #{result.final_answer}"
+
+# Example 2: Tool error (NOW triggers on_error)
+puts "\n2. Tool Error (triggers on_error hook):"
+puts "-" * 40
+result = agent.run('Use the demo tool with action=fail')
+puts "\nResult after error handling:"
+puts "Status: #{result.status}"
+puts "Failed?: #{result.failed?}"
+puts "Error: #{result.error}"
+puts "Answer: #{result.final_answer || 'No answer due to error'}"
+
+puts "\n=== Key Points ==="
+puts "✅ ALL errors now trigger the on_error hook (Tool and Agent errors)"
+puts "✅ Tool errors are wrapped as Soka::ToolError"
+puts "✅ Return :continue from on_error to continue with error result"
+puts "✅ Return :stop from on_error to re-raise and halt execution"