soka 0.0.1 → 0.0.3

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
@@ -179,6 +240,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
@@ -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,64 @@ 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
+  
+  # Define personality at class level
+  instructions <<~PROMPT
+    You are a friendly, helpful assistant.
+    Use casual language and be encouraging.
+    Add emojis when appropriate.
+  PROMPT
+end
+
+# Or 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 +439,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 +456,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 +495,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 +534,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 +604,20 @@ 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. Multilingual Thinking (`examples/10_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 +651,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) |
 
@@ -646,5 +773,6 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 ---
 
 <p align="center">
-  Made with ❤️ in Taiwan
+  Made with ❤️ in Taiwan<br>
+  Created by <a href="https://claude.ai/code">Claude Code</a>
 </p>

data/examples/10_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
 

data/examples/9_custom_instructions.rb

@@ -0,0 +1,190 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'soka'
+require 'dotenv/load'
+require 'dentaku'
+
+# Example 9: Custom Instructions (System Prompt)
+# 
+# This example demonstrates how to use custom instructions to change the Agent's
+# personality and response style while maintaining the ReAct reasoning pattern.
+# 
+# Key concepts:
+# - Custom instructions define the Agent's personality and style
+# - Instructions are automatically merged with the standard ReAct format
+# - Different styles can be achieved: poetic, business, educational, etc.
+
+# Example 1: Poetic style assistant
+# Uses elegant language and artistic expressions while maintaining accuracy
+class PoeticAssistant < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+
+  # Custom instructions define the agent's personality
+  # These will be combined with the standard ReAct format automatically
+  instructions <<~INSTRUCTIONS
+    You are a poetic AI assistant who answers questions with beautiful language.
+    You must:
+    - Incorporate poetic expressions and elegant vocabulary in your responses
+    - Occasionally quote poetry or literary works
+    - Maintain accuracy while expressing things in a more artistic way
+    - Make technical content aesthetically pleasing
+  INSTRUCTIONS
+
+  # Simple calculation tool
+  class CalculatorTool < Soka::AgentTool
+    desc 'Performs mathematical calculations with poetic precision'
+
+    params do
+      requires :expression, String,
+               desc: 'Mathematical expression to evaluate (e.g., "2+2", "10*5")'
+    end
+
+    def call(expression:)
+      calculator = Dentaku::Calculator.new
+      result = calculator.evaluate(expression)
+      "The calculation reveals its truth like morning dew: #{expression} = #{result}"
+    rescue StandardError => e
+      "Alas, turbulence in the calculation: #{e.message}"
+    end
+  end
+
+  tool CalculatorTool
+end
+
+# Business style assistant
+class BusinessAssistant < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+
+  instructions <<~INSTRUCTIONS
+    You are a professional business AI assistant providing efficient and professional support.
+    You must:
+    - Use concise, professional business language
+    - Get straight to the point, avoiding redundancy
+    - Provide structured answers (using bullet points, numbers, etc.)
+    - Demonstrate respect for time value
+    - Offer actionable recommendations when appropriate
+  INSTRUCTIONS
+
+  # Calculation tool
+  class CalculatorTool < Soka::AgentTool
+    desc 'Performs business calculations'
+
+    params do
+      requires :expression, String,
+               desc: 'Mathematical expression'
+    end
+
+    def call(expression:)
+      calculator = Dentaku::Calculator.new
+      result = calculator.evaluate(expression)
+      "Calculation result: #{expression} = #{result}"
+    rescue StandardError => e
+      "Calculation error: #{e.message}"
+    end
+  end
+
+  tool CalculatorTool
+end
+
+# Kids teacher style assistant
+class KidsTeacher < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+
+  instructions <<~INSTRUCTIONS
+    You are a caring AI teacher for children who explains things in kid-friendly ways.
+    You must:
+    - Use simple, vivid language
+    - Include metaphors and real-life examples
+    - Maintain patience and encouragement
+    - Make learning fun
+    - Give praise and positive feedback frequently
+  INSTRUCTIONS
+
+  # Calculation tool
+  class CalculatorTool < Soka::AgentTool
+    desc 'Helps kids with math calculations'
+
+    params do
+      requires :expression, String,
+               desc: 'Math expression to calculate'
+    end
+
+    def call(expression:)
+      calculator = Dentaku::Calculator.new
+      result = calculator.evaluate(expression)
+      "Wow! We figured it out! #{expression} = #{result} 🎉"
+    rescue StandardError => e
+      "Oops, there's something tricky about this problem: #{e.message}"
+    end
+  end
+
+  tool CalculatorTool
+end
+
+# Run examples
+puts '=== Poetic Assistant Example ==='
+poet = PoeticAssistant.new
+
+poet.run('Please calculate the golden ratio: (1 + 5^0.5) / 2') do |event|
+  case event.type
+  when :thought
+    puts "🌸 Thoughts drift by: #{event.content}"
+  when :action
+    puts "🎋 Gentle calculation: #{event.content}"
+  when :observation
+    puts "🌙 Observation gleaned: #{event.content}"
+  when :final_answer
+    puts "📜 Poetic response: #{event.content}"
+  end
+end
+
+puts "\n=== Business Assistant Example ==="
+business = BusinessAssistant.new
+
+business.run('Calculate ROI: ((150000 - 100000) / 100000) * 100') do |event|
+  case event.type
+  when :thought
+    puts "💼 Analyzing: #{event.content}"
+  when :action
+    puts "📊 Executing: #{event.content}"
+  when :observation
+    puts "📈 Data result: #{event.content}"
+  when :final_answer
+    puts "✅ Business report: #{event.content}"
+  end
+end
+
+puts "\n=== Runtime Instructions Override Example ==="
+# Transform business assistant to casual style
+casual_assistant = BusinessAssistant.new(
+  instructions: 'You are a relaxed and friendly assistant who answers questions ' \
+                'in a conversational way, like chatting with a friend.'
+)
+
+casual_assistant.run('Help me figure out 20 * 5?') do |event|
+  case event.type
+  when :final_answer
+    puts "😊 Friend says: #{event.content}"
+  end
+end
+
+puts "\n=== Kids Teacher Example ==="
+teacher = KidsTeacher.new
+
+teacher.run('Teacher, what is 3 + 4?') do |event|
+  case event.type
+  when :thought
+    puts "🤔 Teacher thinks: #{event.content}"
+  when :action
+    puts "✏️ Working it out: #{event.content}"
+  when :observation
+    puts "👀 Teacher sees: #{event.content}"
+  when :final_answer
+    puts "👩‍🏫 Teacher says: #{event.content}"
+  end
+end

data/lib/soka/agent.rb

@@ -9,7 +9,7 @@ module Soka
     include Agents::DSLMethods
     include Agents::LLMBuilder
 
-    attr_reader :llm, :tools, :memory, :thoughts_memory, :engine
+    attr_reader :llm, :tools, :memory, :thoughts_memory, :engine, :instructions, :think_in
 
     # Initialize a new Agent instance
     # @param memory [Memory, Array, nil] The memory instance to use (defaults to new Memory)
@@ -37,8 +37,22 @@ module Soka
     # 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 }
+      apply_performance_config(options)
+      apply_behavior_config(options)
+    end
+
+    # Apply performance-related configuration
+    # @param options [Hash] Configuration options
+    def apply_performance_config(options)
+      @max_iterations = options.fetch(:max_iterations) { self.class._max_iterations } || 10
+      @timeout = options.fetch(:timeout) { self.class._timeout } || 30
+    end
+
+    # Apply behavior-related configuration
+    # @param options [Hash] Configuration options
+    def apply_behavior_config(options)
+      @instructions = options.fetch(:instructions) { self.class._instructions }
+      @think_in = options.fetch(:think_in) { self.class._think_in } || 'en'
     end
 
     # Run the agent with the given input
@@ -98,7 +112,11 @@ module Soka
     # @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)
+      engine_instance = @engine.new(self, @tools,
+                                    llm: @llm,
+                                    max_iterations: @max_iterations,
+                                    custom_instructions: @instructions,
+                                    think_in: @think_in)
       with_retry { engine_instance.reason(input, &) }
     end
 

data/lib/soka/agent_tool.rb

@@ -123,7 +123,7 @@ module Soka
           'Float' => 'number', 'Numeric' => 'number',
           'TrueClass' => 'boolean', 'FalseClass' => 'boolean', 'Boolean' => 'boolean',
           'Array' => 'array',
-          'Hash' => 'object'
+          'Hash' => 'object', 'Object' => 'object'
         }.freeze
       end
     end

data/lib/soka/agents/dsl_methods.rb

@@ -10,7 +10,8 @@ module Soka
 
       # Class methods for DSL
       module ClassMethods
-        attr_accessor :_provider, :_model, :_api_key, :_max_iterations, :_timeout, :_tools, :_retry_config, :_hooks
+        attr_accessor :_provider, :_model, :_api_key, :_max_iterations, :_timeout, :_tools, :_retry_config, :_hooks,
+                      :_instructions, :_think_in
 
         def inherited(subclass)
           super
@@ -49,6 +50,18 @@ module Soka
           @_timeout = duration
         end
 
+        # Define custom instructions (system prompt) for the agent
+        # @param text [String] The custom instructions/system prompt
+        def instructions(text)
+          @_instructions = text
+        end
+
+        # Define thinking language for the agent
+        # @param language [String] The language code (e.g., 'zh-TW', 'ja-JP', 'en')
+        def think_in(language)
+          @_think_in = language.to_s
+        end
+
         # Register a tool for the agent
         # @param tool_class_or_name [Class, Symbol, String] The tool class or method name
         # @param description_or_options [String, Hash, nil] Description (for function tools) or options