soka 0.0.1 → 0.0.3

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
@@ -75,10 +73,7 @@ module Soka
           tool = tools.find { |t| t.class.tool_name == tool_name }
           raise ToolError, "Tool '#{tool_name}' not found" unless tool
 
-          tool.call(**symbolize_keys(tool_input))
-        rescue StandardError => e
-          # Re-raise as ToolError to be caught by process_action
-          raise ToolError, "Error executing tool: #{e.message}"
+          tool.execute(**symbolize_keys(tool_input))
         end
 
         def symbolize_keys(hash)
@@ -97,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.1'
+  VERSION = '0.0.3'
 end

data/lib/soka.rb

@@ -2,9 +2,6 @@
 
 require 'zeitwerk'
 require 'faraday'
-require 'dry-validation'
-require 'dry-struct'
-require 'dry-types'
 
 # Main module for the Soka ReAct Agent Framework
 # Provides AI agent capabilities with multiple LLM providers support

metadata

@@ -1,56 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: soka
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - jiunjiun
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: dry-struct
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-- !ruby/object:Gem::Dependency
-  name: dry-types
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.7'
-- !ruby/object:Gem::Dependency
-  name: dry-validation
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -80,7 +38,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.6'
 description: Soka is a Ruby framework for building AI agents using the ReAct (Reasoning
-  and Acting) pattern. It supports multiple AI providers including Gemini Studio,
+  and Acting) pattern. It supports multiple AI providers including Gemini AI Studio,
   OpenAI, and Anthropic.
 email:
 - imjiunjiun@gmail.com
@@ -95,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
@@ -103,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
@@ -115,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
@@ -125,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