soka 0.0.2 → 0.0.4

data/README.md

@@ -98,6 +98,67 @@ puts result.final_answer
 ruby examples/1_basic.rb
 ```
 
+## Rails Integration
+
+### Soka Rails
+
+For Rails applications, we provide a dedicated gem `soka-rails` that offers seamless integration with Rails conventions:
+
+```ruby
+# Gemfile
+gem 'soka-rails'
+```
+
+#### Features
+
+- 🚂 **Native Rails Integration**: Following Rails conventions and best practices
+- 📁 **Auto-loading Support**: Automatically loads the `app/soka` directory
+- 🛠️ **Generator Support**: Quickly generate Agent and Tool templates
+- ⚙️ **Rails Configuration Integration**: Uses Rails' configuration system
+- 🧪 **Rails Testing Integration**: Seamless integration with RSpec
+- 🔄 **Rails Lifecycle Hooks**: Integrates with Rails logging and error tracking
+
+#### Quick Setup
+
+```bash
+# Install the gem
+bundle add soka-rails
+
+# Run the installation generator
+rails generate soka:install
+
+# Generate an agent
+rails generate soka:agent customer_support
+
+# Generate a tool
+rails generate soka:tool order_lookup order_id:string
+```
+
+#### Basic Usage in Rails
+
+```ruby
+# app/soka/agents/customer_support_agent.rb
+class CustomerSupportAgent < ApplicationAgent
+  tool OrderLookupTool
+  tool UserInfoTool
+end
+
+# app/controllers/conversations_controller.rb
+class ConversationsController < ApplicationController
+  def create
+    agent = CustomerSupportAgent.new
+    result = agent.run(params[:message])
+
+    render json: {
+      answer: result.final_answer,
+      status: result.status
+    }
+  end
+end
+```
+
+For more details, visit the [soka-rails repository](https://github.com/jiunjiun/soka-rails).
+
 ## Core Concepts
 
 ### Global Configuration
@@ -180,6 +241,12 @@ class WeatherAgent < Soka::Agent
   # Custom tool (functional) - requires description as second parameter
   tool :get_weather, "Get weather for a location"
 
+  # Custom instructions (optional)
+  instructions "You are a weather expert. Provide detailed weather information."
+
+  # Thinking language (optional)
+  think_in 'en'  # Default is 'en'
+
   # Lifecycle hooks
   before_action :track_action
   after_action :update_metrics
@@ -246,7 +313,6 @@ result = agent.run('What is the weather in Tokyo today?')
 
 # Result object provides rich information
 puts result.final_answer      # Final answer
-puts result.confidence_score  # Confidence score (0.0-1.0)
 puts result.iterations       # Number of iterations used
 puts result.status          # :success, :failed, :timeout, :max_iterations_reached
 puts result.execution_time  # Execution time (if recorded)
@@ -293,16 +359,85 @@ puts agent.memory
 ```ruby
 # View complete thought process
 puts agent.thoughts_memory
-# <Soka::ThoughtsMemory> (3 sessions, 2 successful, 1 failed, avg confidence: 0.82, avg iterations: 2.3)
+# <Soka::ThoughtsMemory> (3 sessions, 2 successful, 1 failed, avg iterations: 2.3)
 
 # Get detailed information for specific session
 last_session = agent.thoughts_memory.last_session
 puts last_session[:thoughts]  # All thinking steps
-puts last_session[:confidence_score]  # Confidence score for that execution
+puts last_session[:final_answer]  # Final answer for that execution
 ```
 
 ## Advanced Features
 
+### Custom Instructions
+
+Customize your agent's personality and response style:
+
+```ruby
+class FriendlyAgent < Soka::Agent
+  provider :gemini
+
+  # Method 1: Static string instructions
+  instructions <<~PROMPT
+    You are a friendly, helpful assistant.
+    Use casual language and be encouraging.
+    Add emojis when appropriate.
+  PROMPT
+end
+
+# Method 2: Dynamic instructions using method
+class DynamicAgent < Soka::Agent
+  provider :gemini
+
+  # Reference a method for dynamic instructions
+  instructions :generate_instructions
+
+  private
+
+  def generate_instructions
+    hour = Time.now.hour
+    mood = hour < 12 ? 'cheerful morning' : 'relaxed afternoon'
+
+    <<~PROMPT
+      You are a #{mood} assistant.
+      Current Time: #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}
+      Adjust your tone based on the time of day.
+    PROMPT
+  end
+end
+
+# Method 3: Override at runtime
+agent = FriendlyAgent.new(
+  instructions: 'Be more formal and professional.'
+)
+result = agent.run("Help me with this task")
+```
+
+### Multilingual Thinking (Think In)
+
+Optimize reasoning for specific languages:
+
+```ruby
+class GlobalAgent < Soka::Agent
+  provider :gemini
+
+  # Set default thinking language
+  think_in 'zh-TW'  # Think in Traditional Chinese
+end
+
+# Or set dynamically
+agent = GlobalAgent.new(think_in: 'ja-JP')
+result = agent.run("幫我解決這個問題")  # Input in Chinese
+# Agent thinks in Japanese internally, responds in Chinese
+```
+
+**Key Points:**
+- Thinking language affects internal reasoning only
+- Responses adapt to user's input language
+- Default is English (`'en'`)
+- No automatic language detection (explicit setting required)
+- Improves reasoning quality for language-specific contexts
+
 ### ReAct Flow Format
 
 Soka uses a tagged ReAct format:
@@ -325,7 +460,6 @@ Parameters: {"query": "Tokyo weather", "location": "Japan"}
 result.input            # User input
 result.thoughts         # Array of thinking steps
 result.final_answer     # Final answer
-result.confidence_score # Confidence score (0.0-1.0)
 result.status          # Status (:success, :failed, :timeout, :max_iterations_reached)
 result.error           # Error message (if any)
 result.execution_time  # Execution time (seconds)
@@ -343,7 +477,6 @@ result.iterations      # Number of iterations
     }
   ],
   final_answer: "Final answer",
-  confidence_score: 0.85,  # Calculated based on iterations
   status: :success,        # :success, :failed, :timeout, :max_iterations_reached
   error: nil,             # Error message (if any)
   execution_time: 1.23,   # Execution time (seconds)
@@ -383,7 +516,7 @@ RSpec.describe WeatherAgent do
     expect(result).to be_successful
     expect(result.final_answer).to include("sunny")
     expect(result).to have_thoughts_count(1)
-    expect(result).to have_confidence_score_above(0.8)
+    expect(result.status).to eq(:success)
   end
 
   it "handles tool errors gracefully" do
@@ -422,8 +555,7 @@ class CustomEngine < Soka::Engines::Base
       input: task,
       thoughts: thoughts,
       final_answer: answer,
-      status: :success,
-      confidence_score: calculate_confidence_score(thoughts, :success)
+      status: :success
     )
   end
 end
@@ -493,6 +625,27 @@ Demonstrates using different AI providers:
 - Comparing outputs across models
 - Cost optimization strategies
 
+### 9. Custom Instructions (`examples/9_custom_instructions.rb`)
+Shows how to customize agent personality:
+- Setting instructions at class level
+- Runtime instruction override
+- Creating different agent personalities
+- Use cases for different domains
+
+### 10. Dynamic Instructions (`examples/10_dynamic_instructions.rb`)
+Demonstrates dynamic instruction generation:
+- Using methods to generate instructions dynamically
+- Time-based instruction changes
+- Environment-based configuration
+- Session-based personality switching
+
+### 11. Multilingual Thinking (`examples/11_think_in_languages.rb`)
+Demonstrates language-specific reasoning:
+- Setting thinking language with `think_in`
+- Class-level vs instance-level configuration
+- Performance comparison across languages
+- Cultural context optimization
+
 To run any example:
 ```bash
 # Make sure you have the required API keys in your .env file
@@ -526,6 +679,8 @@ ruby examples/1_basic.rb
 | `ai.provider` | Symbol | `:gemini` | AI provider |
 | `ai.model` | String | `"gemini-2.5-flash-lite"` | Model to use |
 | `ai.api_key` | String | nil | API key |
+| `ai.instructions` | String | nil | Custom agent instructions |
+| `ai.think_in` | String | `"en"` | Thinking language |
 | `performance.max_iterations` | Integer | 10 | Max iterations |
 | `performance.timeout` | Integer | 30 | Timeout (seconds) |
 

data/examples/10_dynamic_instructions.rb

@@ -0,0 +1,248 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'soka'
+require 'dotenv/load'
+require 'dentaku'
+
+# Example 10: Dynamic Instructions via Method
+# 
+# This example demonstrates how to use a method to generate instructions dynamically.
+# Instead of static string instructions, you can define a method that returns
+# instructions based on runtime conditions.
+# 
+# Key concepts:
+# - Using a Symbol to reference an instructions method
+# - Dynamic instruction generation based on context
+# - Maintaining compatibility with string-based instructions
+
+# Example 1: Time-aware Assistant
+# Instructions change based on time of day
+class TimeAwareAssistant < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+
+  # Use a method to generate instructions
+  instructions :generate_time_based_instructions
+
+  class GreetingTool < Soka::AgentTool
+    desc 'Generate appropriate greetings'
+
+    params do
+      requires :name, String, desc: 'Name of the person to greet'
+    end
+
+    def call(name:)
+      "Greeting generated for #{name}"
+    end
+  end
+
+  tool GreetingTool
+
+  private
+
+  def generate_time_based_instructions
+    hour = Time.now.hour
+
+    base_instructions = if hour < 12
+                          'You are a cheerful morning assistant who is energetic and motivating.'
+                        elsif hour < 17
+                          'You are a focused afternoon assistant who is professional and efficient.'
+                        else
+                          'You are a relaxed evening assistant who is calm and supportive.'
+                        end
+
+    <<~INSTRUCTIONS
+      #{base_instructions}
+      Current time: #{Time.now.strftime('%H:%M')}
+      
+      You must:
+      - Acknowledge the time of day in your responses
+      - Adjust your tone based on the time period
+      - Be helpful while matching the appropriate energy level
+    INSTRUCTIONS
+  end
+end
+
+# Example 2: Environment-based Assistant
+# Instructions change based on environment variables
+class EnvironmentAwareAssistant < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+
+  # Use a method for environment-based instructions
+  instructions :build_environment_instructions
+
+  class CalculatorTool < Soka::AgentTool
+    desc 'Performs calculations'
+
+    params do
+      requires :expression, String, desc: 'Math expression'
+    end
+
+    def call(expression:)
+      calculator = Dentaku::Calculator.new
+      result = calculator.evaluate(expression)
+      "Result: #{expression} = #{result}"
+    rescue StandardError => e
+      "Error: #{e.message}"
+    end
+  end
+
+  tool CalculatorTool
+
+  private
+
+  def build_environment_instructions
+    user_level = ENV['USER_LEVEL'] || 'beginner'
+    debug_mode = ENV['DEBUG'] == 'true'
+
+    style = case user_level
+            when 'expert'
+              'Use technical terminology and assume deep knowledge. Be concise.'
+            when 'intermediate'
+              'Balance technical accuracy with clear explanations. Provide context when needed.'
+            else
+              'Use simple language and explain concepts thoroughly. Avoid jargon.'
+            end
+
+    debug_info = if debug_mode
+                   "\n- Include detailed technical information in responses"
+                 else
+                   "\n- Keep responses focused on the essential information"
+                 end
+
+    <<~INSTRUCTIONS
+      You are an AI assistant adapting to the user's expertise level.
+      
+      Communication style: #{style}
+      User level: #{user_level}
+      Debug mode: #{debug_mode}
+      
+      Guidelines:#{debug_info}
+      - Adapt your responses to the #{user_level} level
+      - Maintain accuracy while adjusting complexity
+    INSTRUCTIONS
+  end
+end
+
+# Example 3: Session-based Assistant
+# Instructions change based on a session ID
+class SessionAssistant < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+
+  # Use method for session-based instructions
+  instructions :generate_session_instructions
+
+  class InfoTool < Soka::AgentTool
+    desc 'Provides information'
+
+    params do
+      requires :query, String, desc: 'Information query'
+    end
+
+    def call(query:)
+      "Information about: #{query}"
+    end
+  end
+
+  tool InfoTool
+
+  private
+
+  def generate_session_instructions
+    # Simulate different session types based on time
+    session_type = Time.now.min % 3
+    
+    personality = case session_type
+                  when 0
+                    'You are a formal, professional assistant.'
+                  when 1
+                    'You are a friendly, casual assistant.'
+                  else
+                    'You are an educational, patient assistant.'
+                  end
+
+    <<~INSTRUCTIONS
+      #{personality}
+      Session ID: #{Time.now.to_i}
+      
+      Guidelines:
+      - Maintain consistent personality throughout the session
+      - Provide helpful and accurate information
+      - Adapt your tone to match the session style
+    INSTRUCTIONS
+  end
+end
+
+# Run examples
+puts '=== Time-Aware Assistant Example ==='
+time_assistant = TimeAwareAssistant.new
+
+time_assistant.run('Please greet John appropriately for the current time') do |event|
+  case event.type
+  when :thought
+    puts "⏰ Thinking: #{event.content}"
+  when :final_answer
+    puts "📝 Response: #{event.content}"
+  end
+end
+
+puts "\n=== Environment-based Assistant (Beginner) Example ==="
+ENV['USER_LEVEL'] = 'beginner'
+ENV['DEBUG'] = 'false'
+
+beginner_assistant = EnvironmentAwareAssistant.new
+
+beginner_assistant.run('Calculate 15% of 200') do |event|
+  case event.type
+  when :thought
+    puts "🎓 Thinking: #{event.content}"
+  when :final_answer
+    puts "📚 Response: #{event.content}"
+  end
+end
+
+puts "\n=== Environment-based Assistant (Expert) Example ==="
+ENV['USER_LEVEL'] = 'expert'
+ENV['DEBUG'] = 'true'
+
+expert_assistant = EnvironmentAwareAssistant.new
+
+expert_assistant.run('Calculate 15% of 200') do |event|
+  case event.type
+  when :final_answer
+    puts "💼 Response: #{event.content}"
+  end
+end
+
+puts "\n=== Session Assistant Example ==="
+session_assistant = SessionAssistant.new
+
+session_assistant.run('Tell me about Ruby') do |event|
+  case event.type
+  when :thought
+    puts "🔧 Thinking: #{event.content}"
+  when :final_answer
+    puts "🖥️ Response: #{event.content}"
+  end
+end
+
+puts "\n=== Mixed: String and Method Instructions ==="
+# You can still use string instructions
+class StringInstructionsAgent < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+  
+  instructions 'You are a helpful assistant that always responds concisely.'
+end
+
+puts "String instructions work as before."
+
+# And override at runtime
+TimeAwareAssistant.new(
+  instructions: 'Override with a custom string instruction at runtime.'
+)
+puts "Runtime overrides still work with both string and method-based instructions."

data/examples/11_think_in_languages.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative '../lib/soka'
+require 'dotenv/load'
+require 'dentaku'
+
+# Example 10: Think In Languages Feature
+#
+# This example demonstrates the think_in feature that allows Agents to use
+# a specific language for their internal reasoning process.
+#
+# Key concepts:
+# - think_in specifies the language for internal thoughts
+# - Final answers typically match the user's input language
+# - Default thinking language is 'en' (English)
+# - No automatic language detection - you must specify explicitly
+#
+# Benefits:
+# - Improved reasoning quality for specific languages
+# - Better cultural context understanding
+# - Consistent reasoning patterns across teams
+# - Reduced API calls (no language detection)
+
+# Example: Multilingual Agent with configurable thinking language
+class MultilingualAgent < Soka::Agent
+  provider ENV.fetch('AGENT_PROVIDER', :gemini).to_sym
+  model ENV.fetch('AGENT_MODEL', nil)
+  
+  # Define a simple calculator tool
+  class CalculateTool < Soka::AgentTool
+    desc 'Perform mathematical calculations'
+    
+    params do
+      requires :expression, String, desc: 'Mathematical expression to evaluate'
+    end
+    
+    def call(expression:)
+      calculator = Dentaku::Calculator.new
+      result = calculator.evaluate(expression)
+      "The result of #{expression} is #{result}"
+    rescue StandardError => e
+      "Error calculating: #{e.message}"
+    end
+  end
+  
+  tool CalculateTool
+end
+
+puts "=== Think In Languages Example ==="
+puts
+
+# Example 1: Default behavior - thinks in English
+# Without specifying think_in, the agent defaults to English thinking
+# but still understands and responds appropriately to Chinese input
+puts "1. Chinese Input (Default English thinking):"
+agent = MultilingualAgent.new  # No think_in specified, defaults to 'en'
+result = agent.run("幫我計算 123 + 456 的結果")
+puts "Answer: #{result.final_answer}"
+puts
+
+# Example 2: Explicit Japanese thinking
+# Specifying think_in='ja-JP' makes the agent think in Japanese
+# This can improve reasoning quality for Japanese cultural contexts
+puts "2. English Input with Japanese Thinking:"
+agent = MultilingualAgent.new(think_in: 'ja-JP')
+result = agent.run("Calculate the sum of 789 and 321")
+puts "Answer: #{result.final_answer}"
+puts
+
+# Example 3: DSL configuration for Korean thinking
+# Using the DSL to set think_in at the class level
+# All instances of KoreanAgent will think in Korean by default
+puts "3. DSL Configuration (Korean thinking):"
+class KoreanAgent < MultilingualAgent
+  think_in 'ko-KR'  # Class-level configuration
+end
+
+agent = KoreanAgent.new
+result = agent.run("What is 1000 minus 250?")
+puts "Answer: #{result.final_answer}"
+puts
+
+# Example 4: Show the thinking process
+puts "4. Showing Thinking Process:"
+agent = MultilingualAgent.new(think_in: 'zh-TW')
+result = agent.run("請計算 50 乘以 8") do |event|
+  case event.type
+  when :thought
+    puts "思考: #{event.content}"
+  when :action
+    puts "行動: 使用工具 #{event.content[:tool]}"
+  when :observation
+    puts "觀察: #{event.content}"
+  when :final_answer
+    puts "最終答案: #{event.content}"
+  end
+end
+puts
+
+# Example 5: Multiple languages in sequence
+puts "5. Multiple Languages:"
+languages = {
+  'en' => "Calculate 100 divided by 4",
+  'zh-TW' => "請計算 100 除以 4",
+  'ja-JP' => "100を4で割った結果を計算してください",
+  'es' => "Calcula 100 dividido por 4"
+}
+
+languages.each do |lang, question|
+  agent = MultilingualAgent.new(think_in: lang)
+  result = agent.run(question)
+  puts "#{lang}: #{result.final_answer}"
+end

data/examples/2_event_handling.rb

@@ -4,6 +4,7 @@
 require 'bundler/setup'
 require 'soka'
 require 'dotenv/load'
+require 'dentaku'
 
 # Configure Soka
 Soka.setup do |config|
@@ -21,14 +22,15 @@ end
 
 # Simple calculation tool
 class CalculatorTool < Soka::AgentTool
-  desc 'Perform calculations'
+  desc 'Perform calculations using Dentaku (safe math evaluator)'
 
   params do
-    requires :expression, String, desc: 'Mathematical expression to calculate'
+    requires :expression, String, desc: 'Mathematical expression (use ^ for power, e.g., "2^3" = 8)'
   end
 
   def call(expression:)
-    result = eval(expression) # rubocop:disable Security/Eval
+    calculator = Dentaku::Calculator.new
+    result = calculator.evaluate(expression)
     "Result: #{expression} = #{result}"
   rescue StandardError => e
     "Error: #{e.message}"
@@ -109,7 +111,6 @@ 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 ==="

data/examples/3_memory.rb

@@ -5,6 +5,7 @@ require 'bundler/setup'
 require 'soka'
 require 'dotenv/load'
 require 'singleton'
+require 'dentaku'
 
 # Configure Soka
 Soka.setup do |config|
@@ -29,8 +30,9 @@ class CalculatorTool < Soka::AgentTool
   end
 
   def call(expression:)
-    # Simple math expression evaluation (production should use safer methods)
-    result = eval(expression) # rubocop:disable Security/Eval
+    # Safe math expression evaluation using Dentaku
+    calculator = Dentaku::Calculator.new
+    result = calculator.evaluate(expression)
     "Calculation result: #{expression} = #{result}"
   rescue StandardError => e
     "Calculation error: #{e.message}"

data/examples/4_hooks.rb

@@ -59,7 +59,6 @@ class HookedAgent < Soka::Agent
     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