soka 0.0.2 → 0.0.4

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) { resolve_instructions }
+      @think_in = options.fetch(:think_in) { self.class._think_in } || 'en'
     end
 
     # Run the agent with the given input
@@ -72,6 +86,35 @@ module Soka
       end
     end
 
+    # Resolve instructions from class configuration
+    # @return [String, nil] The resolved instructions
+    def resolve_instructions
+      return nil unless self.class._instructions
+
+      case self.class._instructions
+      when Symbol
+        # Call the method if it's a symbol
+        send(self.class._instructions) if respond_to?(self.class._instructions, true)
+      else
+        # Return string or any other value directly
+        self.class._instructions
+      end
+    end
+
+    # Resolve current instructions (may be dynamic)
+    # @return [String, nil] The current instructions
+    def resolve_current_instructions
+      case @instructions
+      when Symbol
+        send(@instructions) if respond_to?(@instructions, true)
+      when Proc
+        @instructions.call
+      else
+        # Return string or any other value directly
+        @instructions
+      end
+    end
+
     # Validate the input is not empty
     # @param input [String] The input to validate
     # @raise [ArgumentError] If input is empty
@@ -98,7 +141,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: resolve_current_instructions,
+                                    think_in: @think_in)
       with_retry { engine_instance.reason(input, &) }
     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,22 @@ module Soka
           @_timeout = duration
         end
 
+        # Define custom instructions (system prompt) for the agent
+        # @param text_or_method [String, Symbol] The custom instructions/system prompt or method name
+        # @example Using a string
+        #   instructions "You are a helpful assistant"
+        # @example Using a method
+        #   instructions :generate_instructions
+        def instructions(text_or_method)
+          @_instructions = text_or_method
+        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

data/lib/soka/engines/base.rb

@@ -4,13 +4,15 @@ module Soka
   module Engines
     # Base class for reasoning engines
     class Base
-      attr_reader :agent, :llm, :tools, :max_iterations
+      attr_reader :agent, :llm, :tools, :max_iterations, :custom_instructions, :think_in
 
-      def initialize(agent, llm, tools, max_iterations)
+      def initialize(agent, tools, **options)
         @agent = agent
-        @llm = llm
         @tools = tools
-        @max_iterations = max_iterations
+        @llm = options[:llm]
+        @max_iterations = options[:max_iterations] || 10
+        @custom_instructions = options[:custom_instructions]
+        @think_in = options[:think_in]
       end
 
       def reason(task)

data/lib/soka/engines/concerns/prompt_template.rb

@@ -8,6 +8,15 @@ module Soka
         private
 
         def system_prompt
+          # Use custom instructions if provided, otherwise use default ReAct prompt
+          if custom_instructions
+            combine_with_react_format(custom_instructions)
+          else
+            default_react_prompt
+          end
+        end
+
+        def default_react_prompt
           tools_description = format_tools_description(tools)
 
           <<~PROMPT
@@ -20,16 +29,50 @@ module Soka
           PROMPT
         end
 
+        def combine_with_react_format(instructions)
+          tools_description = format_tools_description(tools)
+
+          <<~PROMPT
+            #{instructions}
+
+            You have access to the following tools:
+            #{tools_description}
+
+            #{format_instructions}
+          PROMPT
+        end
+
         def format_instructions
+          thinking_instruction = build_thinking_instruction(think_in)
+
           <<~INSTRUCTIONS
             You must follow this exact format for each step:
 
+            #{thinking_instruction}
+
             <Thought>Your reasoning about what to do next</Thought>
             <Action>
             Tool: tool_name
             Parameters: {"param1": "value1", "param2": "value2"}
             </Action>
 
+            #{action_format_rules}
+          INSTRUCTIONS
+        end
+
+        # Build thinking instruction based on language
+        # @param language [String, nil] The language to use for thinking
+        # @return [String] The thinking instruction
+        def build_thinking_instruction(language)
+          return '' unless language
+
+          "Use #{language} for your reasoning in <Thought> tags."
+        end
+
+        # Action format rules
+        # @return [String] The action format rules
+        def action_format_rules
+          <<~RULES
             STOP HERE after each Action. Do NOT include <Observation> in your response.
             The system will execute the tool and provide the observation.
 
@@ -45,7 +88,7 @@ module Soka
             5. NEVER include <Observation> tags - wait for the system to provide them
             6. Provide a clear and complete <Final_Answer> when done
             7. If you cannot complete the task, explain why in the <Final_Answer>
-          INSTRUCTIONS
+          RULES
         end
 
         def format_tools_description(tools)
@@ -72,58 +115,6 @@ module Soka
 
           properties.join(', ')
         end
-
-        def parse_response(text)
-          thoughts = extract_tagged_content(text, 'Thought')
-          actions = extract_actions(text)
-          final_answer = extract_tagged_content(text, 'Final_Answer').first
-
-          {
-            thoughts: thoughts,
-            actions: actions,
-            final_answer: final_answer
-          }
-        end
-
-        def extract_tagged_content(text, tag)
-          pattern = %r{<#{tag}>(.*?)</#{tag}>}m
-          text.scan(pattern).map { |match| match[0].strip }
-        end
-
-        def extract_actions(text)
-          action_blocks = text.scan(%r{<Action>(.*?)</Action>}m)
-          action_blocks.filter_map { |block| parse_action_block(block[0]) }
-        end
-
-        def parse_action_block(content)
-          content = content.strip
-          tool_match = content.match(/Tool:\s*(.+)/)
-          params_match = content.match(/Parameters:\s*(.+)/m)
-
-          return unless tool_match && params_match
-
-          tool_name = tool_match[1].strip
-          params_json = params_match[1].strip
-          params = parse_json_params(params_json)
-
-          { tool: tool_name, params: params }
-        end
-
-        # Parse JSON parameters from action block
-        # @param params_json [String] The JSON string to parse
-        # @return [Hash] The parsed parameters as a hash with symbol keys
-        def parse_json_params(params_json)
-          # Clean up the JSON string - remove any trailing commas or whitespace
-          cleaned_json = params_json.strip.gsub(/,\s*}/, '}').gsub(/,\s*\]/, ']')
-          JSON.parse(cleaned_json, symbolize_names: true)
-        rescue JSON::ParserError
-          # Return empty hash to continue when JSON parsing fails
-          {}
-        end
-
-        def format_observation(observation)
-          "<Observation>#{observation}</Observation>"
-        end
       end
     end
   end

data/lib/soka/engines/concerns/response_parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Concerns
+      # Module for parsing LLM responses in ReAct format
+      module ResponseParser
+        private
+
+        def parse_response(text)
+          extract_response_parts(text)
+        end
+
+        def extract_response_parts(text)
+          {
+            thoughts: extract_tagged_content(text, 'Thought'),
+            actions: extract_actions(text),
+            final_answer: extract_tagged_content(text, 'Final_Answer').first
+          }
+        end
+
+        def extract_tagged_content(text, tag)
+          pattern = %r{<#{tag}>(.*?)</#{tag}>}m
+          text.scan(pattern).map { |match| match[0].strip }
+        end
+
+        def extract_actions(text)
+          action_blocks = text.scan(%r{<Action>(.*?)</Action>}m)
+          action_blocks.filter_map { |block| parse_action_block(block[0]) }
+        end
+
+        def parse_action_block(content)
+          content = content.strip
+          tool_match = content.match(/Tool:\s*(.+)/)
+          params_match = content.match(/Parameters:\s*(.+)/m)
+
+          return unless tool_match && params_match
+
+          tool_name = tool_match[1].strip
+          params_json = params_match[1].strip
+          params = parse_json_params(params_json)
+
+          { tool: tool_name, params: params }
+        end
+
+        # Parse JSON parameters from action block
+        # @param params_json [String] The JSON string to parse
+        # @return [Hash] The parsed parameters as a hash with symbol keys
+        def parse_json_params(params_json)
+          # Clean up the JSON string - remove any trailing commas or whitespace
+          cleaned_json = params_json.strip.gsub(/,\s*}/, '}').gsub(/,\s*\]/, ']')
+          JSON.parse(cleaned_json, symbolize_names: true)
+        rescue JSON::ParserError
+          # Return empty hash to continue when JSON parsing fails
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/soka/engines/concerns/response_processor.rb

@@ -5,8 +5,6 @@ module Soka
     module Concerns
       # Module for processing responses in ReAct engine
       module ResponseProcessor
-        include Concerns::PromptTemplate
-
         private
 
         # Process thoughts from parsed response
@@ -94,6 +92,10 @@ module Soka
             content: 'Please follow the exact format with <Thought>, <Action>, and <Final_Answer> tags.'
           )
         end
+
+        def format_observation(observation)
+          "<Observation>#{observation}</Observation>"
+        end
       end
     end
   end

data/lib/soka/engines/concerns/result_builder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Concerns
+      # Module for building ReAct reasoning results
+      module ResultBuilder
+        private
+
+        def build_result(input:, thoughts:, final_answer:, status:, error: nil)
+          result = {
+            input: input,
+            thoughts: thoughts,
+            final_answer: final_answer,
+            status: status
+          }
+
+          result[:error] = error if error
+
+          Soka::Engines::React::ReasonResult.new(**result)
+        end
+      end
+    end
+  end
+end

data/lib/soka/engines/react.rb

@@ -8,6 +8,8 @@ module Soka
     class React < Base
       include Concerns::ResponseProcessor
       include Concerns::PromptTemplate
+      include Concerns::ResponseParser
+      include Concerns::ResultBuilder
 
       ReasonResult = Struct.new(:input, :thoughts, :final_answer, :status, :error, :confidence_score,
                                 keyword_init: true) do
@@ -21,7 +23,8 @@ module Soka
       # @yield [event] Optional block to handle events during execution
       # @return [ReasonResult] The result of the reasoning process
       def reason(task, &block)
-        context = ReasoningContext.new(task: task, event_handler: block, max_iterations: max_iterations)
+        context = ReasoningContext.new(task: task, event_handler: block, max_iterations: max_iterations,
+                                       think_in: think_in)
         context.messages = build_messages(task)
 
         result = iterate_reasoning(context)
@@ -106,31 +109,6 @@ module Soka
           status: :success
         )
       end
-
-      def build_result(input:, thoughts:, final_answer:, status:, error: nil)
-        result = {
-          input: input,
-          thoughts: thoughts,
-          final_answer: final_answer,
-          status: status
-        }
-
-        result[:error] = error if error
-
-        # Calculate confidence score based on iterations and status
-        result[:confidence_score] = calculate_confidence_score(thoughts, status)
-
-        ReasonResult.new(**result)
-      end
-
-      def calculate_confidence_score(thoughts, status)
-        return 0.0 if status != :success
-
-        base_score = 0.85
-        iteration_penalty = thoughts.length * 0.05
-
-        [base_score - iteration_penalty, 0.5].max
-      end
     end
   end
 end

data/lib/soka/engines/reasoning_context.rb

@@ -8,17 +8,19 @@ module Soka
       # Event structure for emitting events
       Event = Struct.new(:type, :content)
 
-      attr_accessor :messages, :thoughts, :task, :iteration, :parsed_response
+      attr_accessor :messages, :thoughts, :task, :iteration, :parsed_response, :think_in
       attr_reader :event_handler, :max_iterations
 
       # Initialize a new reasoning context
       # @param task [String] The task to be processed
       # @param event_handler [Proc, nil] Optional block to handle events
       # @param max_iterations [Integer] Maximum number of reasoning iterations
-      def initialize(task:, event_handler: nil, max_iterations: 10)
+      # @param think_in [String, nil] The language to use for thinking
+      def initialize(task:, event_handler: nil, max_iterations: 10, think_in: nil)
         @task = task
         @event_handler = event_handler
         @max_iterations = max_iterations
+        @think_in = think_in
         @messages = []
         @thoughts = []
         @iteration = 0

data/lib/soka/result.rb

@@ -3,14 +3,13 @@
 module Soka
   # Represents the result of an agent's reasoning process
   class Result
-    attr_reader :input, :thoughts, :final_answer, :confidence_score, :status, :error, :execution_time
+    attr_reader :input, :thoughts, :final_answer, :status, :error, :execution_time
 
     # Initialize a new Result instance
     # @param attributes [Hash] Result attributes
     # @option attributes [String] :input The original input
     # @option attributes [Array] :thoughts Array of thought objects
     # @option attributes [String] :final_answer The final answer
-    # @option attributes [Float] :confidence_score Confidence score (0.0-1.0)
     # @option attributes [Symbol] :status The result status
     # @option attributes [String] :error Error message if failed
     # @option attributes [Float] :execution_time Time taken in seconds
@@ -18,7 +17,6 @@ module Soka
       @input = attributes[:input]
       @thoughts = attributes[:thoughts] || []
       @final_answer = attributes[:final_answer]
-      @confidence_score = attributes[:confidence_score] || 0.0
       @status = attributes[:status] || :pending
       @error = attributes[:error]
       @execution_time = attributes[:execution_time]
@@ -82,7 +80,6 @@ module Soka
     def execution_details
       {
         iterations: iterations,
-        confidence: confidence_score ? format('%.1f%%', confidence_score * 100) : 'N/A',
         time: execution_time ? "#{execution_time.round(2)}s" : 'N/A',
         status: status
       }
@@ -99,7 +96,6 @@ module Soka
         input: input,
         thoughts: thoughts,
         final_answer: final_answer,
-        confidence_score: confidence_score,
         status: status
       }
     end