soka 0.0.2 → 0.0.3

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

data/lib/soka/thoughts_memory.rb

@@ -15,7 +15,6 @@ module Soka
         thoughts: result.thoughts || [],
         final_answer: result.final_answer,
         status: result.status,
-        confidence_score: result.confidence_score,
         timestamp: Time.now
       }
 
@@ -52,14 +51,6 @@ module Soka
       @sessions.select { |s| s[:status] == :failed }
     end
 
-    def average_confidence_score
-      successful = successful_sessions
-      return 0.0 if successful.empty?
-
-      total = successful.sum { |s| s[:confidence_score] || 0.0 }
-      total / successful.size
-    end
-
     def average_iterations
       return 0 if @sessions.empty?
 
@@ -80,7 +71,6 @@ module Soka
         total: size,
         successful: successful_sessions.size,
         failed: failed_sessions.size,
-        avg_confidence: format('%.2f', average_confidence_score),
         avg_iterations: format('%.1f', average_iterations)
       }
     end
@@ -88,7 +78,6 @@ module Soka
     def format_stats_string(stats)
       "<Soka::ThoughtsMemory> (#{stats[:total]} sessions, " \
         "#{stats[:successful]} successful, #{stats[:failed]} failed, " \
-        "avg confidence: #{stats[:avg_confidence]}, " \
         "avg iterations: #{stats[:avg_iterations]})"
     end
 
@@ -103,7 +92,6 @@ module Soka
           total_sessions: size,
           successful_sessions: successful_sessions.size,
           failed_sessions: failed_sessions.size,
-          average_confidence_score: average_confidence_score,
           average_iterations: average_iterations
         }
       }

data/lib/soka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Soka
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: soka
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - jiunjiun
@@ -53,6 +53,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- examples/10_think_in_languages.rb
 - examples/1_basic.rb
 - examples/2_event_handling.rb
 - examples/3_memory.rb
@@ -61,6 +62,7 @@ files:
 - examples/6_retry.rb
 - examples/7_tool_conditional.rb
 - examples/8_multi_provider.rb
+- examples/9_custom_instructions.rb
 - lib/soka.rb
 - lib/soka/agent.rb
 - lib/soka/agent_tool.rb
@@ -73,7 +75,9 @@ files:
 - lib/soka/configuration.rb
 - lib/soka/engines/base.rb
 - lib/soka/engines/concerns/prompt_template.rb
+- lib/soka/engines/concerns/response_parser.rb
 - lib/soka/engines/concerns/response_processor.rb
+- lib/soka/engines/concerns/result_builder.rb
 - lib/soka/engines/react.rb
 - lib/soka/engines/reasoning_context.rb
 - lib/soka/llm.rb
@@ -83,7 +87,6 @@ files:
 - lib/soka/llms/openai.rb
 - lib/soka/memory.rb
 - lib/soka/result.rb
-- lib/soka/test_helpers.rb
 - lib/soka/thoughts_memory.rb
 - lib/soka/version.rb
 - sig/soka.rbs

data/lib/soka/test_helpers.rb

@@ -1,162 +0,0 @@
-# frozen_string_literal: true
-
-module Soka
-  # RSpec test helpers for Soka framework
-  module TestHelpers
-    def self.included(base)
-      base.class_eval do
-        let(:mock_llm_response) { nil }
-        let(:mock_tool_responses) { {} }
-      end
-    end
-
-    def mock_ai_response(response_data)
-      @mock_llm_response = response_data
-
-      # Create a mock LLM that returns the specified response
-      mock_llm = instance_double(Soka::LLM::Base)
-
-      # Format the response content based on the response data
-      content = build_react_content(response_data)
-
-      result = create_mock_llm_result(content)
-
-      allow(mock_llm).to receive(:chat).and_return(result)
-      allow(Soka::LLM).to receive(:new).and_return(mock_llm)
-
-      mock_llm
-    end
-
-    def create_mock_llm_result(content)
-      Soka::LLM::Result.new(
-        model: 'mock-model',
-        content: content,
-        input_tokens: 100,
-        output_tokens: 200,
-        finish_reason: 'stop',
-        raw_response: { mock: true }
-      )
-    end
-
-    def mock_tool_response(tool_class, response)
-      @mock_tool_responses[tool_class] = response
-
-      # Create a mock instance of the tool
-      mock_tool = instance_double(tool_class)
-      allow(mock_tool).to receive(:class).and_return(tool_class)
-      allow(mock_tool).to receive(:execute).and_return(response)
-
-      # Allow the tool class to be instantiated with the mock
-      allow(tool_class).to receive(:new).and_return(mock_tool)
-
-      mock_tool
-    end
-
-    def allow_tool_to_fail(tool_class, error)
-      mock_tool = instance_double(tool_class)
-      allow(mock_tool).to receive(:class).and_return(tool_class)
-      allow(mock_tool).to receive(:execute).and_raise(error)
-
-      allow(tool_class).to receive(:new).and_return(mock_tool)
-
-      mock_tool
-    end
-
-    def create_test_agent(options = {})
-      Class.new(Soka::Agent) do
-        provider :gemini
-        model 'gemini-2.5-flash'
-        max_iterations 5
-        timeout 10
-      end.new(**options)
-    end
-
-    def create_test_tool(name: 'test_tool', description: 'Test tool', &block)
-      Class.new(Soka::AgentTool) do
-        desc description
-
-        define_singleton_method :tool_name do
-          name
-        end
-
-        define_method :call, &block || -> { 'Test response' }
-      end
-    end
-
-    def stub_env(env_vars)
-      env_vars.each do |key, value|
-        allow(ENV).to receive(:fetch).with(key).and_return(value)
-        allow(ENV).to receive(:[]).with(key).and_return(value)
-      end
-    end
-
-    def with_configuration
-      original_config = Soka.configuration
-      Soka.reset!
-      yield
-    ensure
-      Soka.configuration = original_config
-    end
-
-    private
-
-    def build_react_content(response_data)
-      content = []
-
-      # Build thoughts and actions
-      response_data[:thoughts].each_with_index do |thought_data, _index|
-        content << "<Thought>#{thought_data[:thought]}</Thought>"
-
-        next unless thought_data[:action]
-
-        action = thought_data[:action]
-        params_json = action[:params].to_json
-
-        content << build_action_content(action[:tool], params_json)
-
-        # The observation will be added by the engine
-      end
-
-      # Add final answer if present
-      content << "<Final_Answer>#{response_data[:final_answer]}</Final_Answer>" if response_data[:final_answer]
-
-      content.join("\n")
-    end
-
-    def build_action_content(tool, params_json)
-      <<~ACTION
-        <Action>
-        Tool: #{tool}
-        Parameters: #{params_json}
-        </Action>
-      ACTION
-    end
-
-    # Matcher helpers for RSpec
-    module Matchers
-      def be_successful
-        satisfy(&:successful?)
-      end
-
-      def be_failed
-        satisfy(&:failed?)
-      end
-
-      def final_answer?(expected = nil)
-        if expected
-          satisfy { |result| result.final_answer == expected }
-        else
-          satisfy { |result| !result.final_answer.nil? }
-        end
-      end
-
-      def thoughts_count?(count)
-        satisfy { |result| result.thoughts.length == count }
-      end
-
-      def confidence_score_above?(threshold)
-        satisfy { |result| result.confidence_score > threshold }
-      end
-    end
-  end
-end