soka 0.0.1.beta2

data/lib/soka/configuration.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Soka
+  # Global configuration for Soka framework
+  class Configuration
+    # AI provider configuration
+    class AIConfig
+      attr_accessor :provider, :model, :api_key, :fallback_provider, :fallback_model, :fallback_api_key
+
+      def initialize
+        @provider = :gemini
+        @model = 'gemini-2.5-flash-lite'
+      end
+    end
+
+    # Performance-related configuration
+    class PerformanceConfig
+      attr_accessor :max_iterations, :timeout
+
+      def initialize
+        @max_iterations = 10
+        @timeout = 30
+      end
+    end
+
+    attr_accessor :tools
+
+    def initialize
+      @ai = AIConfig.new
+      @performance = PerformanceConfig.new
+      @tools = []
+    end
+
+    # Configure a specific section
+    # @param section [Symbol] The section to configure (:ai, :performance, :logging)
+    # @yield Configuration block for the section
+    # @return [Object] The configuration section
+    def configure(section)
+      config_object = instance_variable_get("@#{section}")
+      yield(config_object) if block_given? && config_object
+      config_object
+    end
+
+    # Configuration accessor methods with block support
+
+    # Access or configure AI settings
+    # @yield [AIConfig] Configuration block for AI settings
+    # @return [AIConfig] The AI configuration
+    def ai(&)
+      block_given? ? configure(:ai, &) : @ai
+    end
+
+    # Access or configure performance settings
+    # @yield [PerformanceConfig] Configuration block for performance settings
+    # @return [PerformanceConfig] The performance configuration
+    def performance(&)
+      block_given? ? configure(:performance, &) : @performance
+    end
+  end
+end

data/lib/soka/engines/base.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    # Base class for reasoning engines
+    class Base
+      attr_reader :agent, :llm, :tools, :max_iterations
+
+      def initialize(agent, llm, tools, max_iterations)
+        @agent = agent
+        @llm = llm
+        @tools = tools
+        @max_iterations = max_iterations
+      end
+
+      def reason(task)
+        raise NotImplementedError, "#{self.class} must implement #reason method"
+      end
+
+      protected
+
+      def find_tool(name)
+        tools.find { |tool| tool.class.tool_name == name.to_s.downcase }
+      end
+
+      def execute_tool(tool_name, params = {})
+        tool = find_tool(tool_name)
+        raise ToolError, "Tool not found: #{tool_name}" unless tool
+
+        tool.execute(**params)
+      end
+
+      def emit_event(type, content)
+        return unless block_given?
+
+        event = Struct.new(:type, :content).new(type, content)
+        yield(event)
+      end
+
+      def build_messages(task)
+        messages = [system_message]
+        add_memory_messages(messages)
+        messages << user_message(task)
+        messages
+      end
+
+      def system_message
+        { role: 'system', content: system_prompt }
+      end
+
+      def add_memory_messages(messages)
+        return unless agent.respond_to?(:memory) && agent.memory
+
+        messages.concat(agent.memory.to_messages)
+      end
+
+      def user_message(task)
+        { role: 'user', content: task }
+      end
+
+      def system_prompt
+        # This should be overridden by specific engines
+        'You are a helpful AI assistant.'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Concerns
+      # Module for handling prompt templates in ReAct engine
+      module PromptTemplate
+        private
+
+        def system_prompt
+          tools_description = format_tools_description(tools)
+
+          <<~PROMPT
+            You are an AI assistant that uses the ReAct (Reasoning and Acting) framework to solve problems step by step.
+
+            You have access to the following tools:
+            #{tools_description}
+
+            #{format_instructions}
+          PROMPT
+        end
+
+        def format_instructions
+          <<~INSTRUCTIONS
+            You must follow this exact format for each step:
+
+            <Thought>Your reasoning about what to do next</Thought>
+            <Action>
+            Tool: tool_name
+            Parameters: {"param1": "value1", "param2": "value2"}
+            </Action>
+
+            STOP HERE after each Action. Do NOT include <Observation> in your response.
+            The system will execute the tool and provide the observation.
+
+            After receiving the observation, you can continue with more Thought/Action cycles or provide a final answer:
+
+            <Final_Answer>Your complete answer to the user's question</Final_Answer>
+
+            Important rules:
+            1. Always start with a <Thought> to analyze the problem
+            2. Use tools when you need information or to perform actions
+            3. Parameters MUST be valid JSON format (e.g., {"query": "weather"} not {query: "weather"})
+            4. For tools without parameters, use empty JSON object: {}
+            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
+        end
+
+        def format_tools_description(tools)
+          return 'No tools available.' if tools.empty?
+
+          tools.map do |tool|
+            schema = tool.class.to_h
+            params_desc = format_parameters(schema[:parameters])
+
+            "- #{schema[:name]}: #{schema[:description]}\n  Parameters: #{params_desc}"
+          end.join("\n")
+        end
+
+        def format_parameters(params_schema)
+          return 'none' if params_schema[:properties].empty?
+
+          properties = params_schema[:properties].map do |name, config|
+            required = params_schema[:required].include?(name.to_s) ? '(required)' : '(optional)'
+            type = config[:type]
+            desc = config[:description]
+
+            "#{name} #{required} [#{type}] - #{desc}"
+          end
+
+          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
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Concerns
+      # Module for processing responses in ReAct engine
+      module ResponseProcessor
+        include Concerns::PromptTemplate
+
+        private
+
+        # Process thoughts from parsed response
+        # @param parsed_thoughts [Array<String>] The thoughts to process
+        # @param context [ReasoningContext] The reasoning context
+        def process_thoughts(parsed_thoughts, context)
+          parsed_thoughts.each do |thought|
+            context.emit_event(:thought, thought)
+            context.add_thought(thought)
+          end
+        end
+
+        # Process an action from the response
+        # @param action [Hash] The action to process
+        # @param context [ReasoningContext] The reasoning context
+        # @param content [String] The raw response content
+        def process_action(action, context, content)
+          context.emit_event(:action, action)
+
+          begin
+            observation = execute_tool(action[:tool], action[:params])
+            context.emit_event(:observation, observation)
+            add_observation_to_messages(context, content, observation)
+            context.update_last_thought(action: action, observation: observation)
+          rescue ToolError => e
+            handle_tool_error(e, context, action, content)
+          end
+        end
+
+        # Add observation to messages in the context
+        # @param context [ReasoningContext] The reasoning context
+        # @param content [String] The assistant's response content
+        # @param observation [String] The observation to add
+        def add_observation_to_messages(context, content, observation)
+          observation_text = format_observation(observation)
+          context.add_message(role: 'assistant', content: content)
+          context.add_message(role: 'user', content: observation_text)
+        end
+
+        # Handle tool execution errors
+        # @param error [ToolError] The error that occurred
+        # @param context [ReasoningContext] The reasoning context
+        # @param action [Hash] The action that failed
+        # @param content [String] The raw response content
+        # @raise [ToolError] Re-raises the error to trigger on_error hooks and terminate reasoning
+        def handle_tool_error(error, context, action, content)
+          error_message = "Tool error: #{error.message}"
+          context.emit_event(:error, error_message)
+
+          # Add error as observation so AI can see what happened
+          add_observation_to_messages(context, content, error_message)
+          context.update_last_thought(action: action, observation: error_message)
+
+          # Re-raise the error to propagate to agent level
+          # This will trigger on_error hook and terminate the reasoning process
+          # If you want reasoning to continue after tool errors, comment out this line
+          # raise error
+        end
+
+        # Execute a tool with the given name and input
+        # @param tool_name [String] The name of the tool to execute
+        # @param tool_input [Hash] The input parameters for the tool
+        # @return [String] The result of the tool execution
+        # @raise [ToolError] If the tool is not found or execution fails
+        def execute_tool(tool_name, tool_input)
+          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}"
+        end
+
+        def symbolize_keys(hash)
+          return {} unless hash.is_a?(Hash)
+
+          hash.transform_keys(&:to_sym)
+        end
+
+        # Handle case when no action is found in response
+        # @param context [ReasoningContext] The reasoning context
+        # @param content [String] The raw response content
+        def handle_no_action(context, content)
+          context.add_message(role: 'assistant', content: content)
+          context.add_message(
+            role: 'user',
+            content: 'Please follow the exact format with <Thought>, <Action>, and <Final_Answer> tags.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/soka/engines/react.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Soka
+  module Engines
+    # ReAct (Reasoning and Acting) engine implementation
+    class React < Base
+      include Concerns::ResponseProcessor
+      include Concerns::PromptTemplate
+
+      ReasonResult = Struct.new(:input, :thoughts, :final_answer, :status, :error, :confidence_score,
+                                keyword_init: true) do
+        def successful?
+          status == :success
+        end
+      end
+
+      # Main reasoning entry point
+      # @param task [String] The task to process
+      # @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.messages = build_messages(task)
+
+        result = iterate_reasoning(context)
+        result || max_iterations_result(context)
+      end
+
+      # Iterate through reasoning cycles
+      # @param context [ReasoningContext] The reasoning context
+      # @return [ReasonResult, nil] The result if found, nil otherwise
+      def iterate_reasoning(context)
+        max_iterations.times do
+          result = process_iteration(context)
+          return result if result
+
+          context.increment_iteration!
+        end
+        nil
+      end
+
+      # Build result when max iterations reached
+      # @param context [ReasoningContext] The reasoning context
+      # @return [ReasonResult] The error result
+      def max_iterations_result(context)
+        context.emit_event(:error, "Maximum iterations (#{context.max_iterations}) reached")
+        build_result(
+          input: context.task,
+          thoughts: context.thoughts,
+          final_answer: "I couldn't complete the task within the maximum number of iterations.",
+          status: :max_iterations_reached
+        )
+      end
+
+      private
+
+      # Process a single iteration of reasoning
+      # @param context [ReasoningContext] The reasoning context
+      # @return [ReasonResult, nil] The result if final answer found, nil otherwise
+      def process_iteration(context)
+        response = llm.chat(context.messages)
+        content = response.content
+        context.parsed_response = parse_response(content)
+
+        process_parsed_response(context, content)
+      end
+
+      # Process the parsed response
+      # @param context [ReasoningContext] The reasoning context
+      # @param content [String] The raw response content
+      # @return [ReasonResult, nil] The result if final answer found, nil otherwise
+      def process_parsed_response(context, content)
+        parsed = context.parsed_response
+        process_thoughts(parsed[:thoughts], context)
+
+        return process_final_answer(parsed[:final_answer], context) if parsed[:final_answer]
+
+        handle_actions_or_no_action(parsed, context, content)
+        nil
+      end
+
+      # Handle either actions or no action in response
+      # @param parsed [Hash] The parsed response
+      # @param context [ReasoningContext] The reasoning context
+      # @param content [String] The raw response content
+      def handle_actions_or_no_action(parsed, context, content)
+        if parsed[:actions].any?
+          process_action(parsed[:actions].first, context, content)
+        else
+          handle_no_action(context, content)
+        end
+      end
+
+      # Process the final answer
+      # @param final_answer [String] The final answer from the LLM
+      # @param context [ReasoningContext] The reasoning context
+      # @return [ReasonResult] The success result
+      def process_final_answer(final_answer, context)
+        context.emit_event(:final_answer, final_answer)
+        build_result(
+          input: context.task,
+          thoughts: context.thoughts,
+          final_answer: final_answer,
+          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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    # Context object that encapsulates all data needed during reasoning process
+    # This eliminates the need to pass multiple parameters and blocks through method chains
+    class ReasoningContext
+      # Event structure for emitting events
+      Event = Struct.new(:type, :content)
+
+      attr_accessor :messages, :thoughts, :task, :iteration, :parsed_response
+      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)
+        @task = task
+        @event_handler = event_handler
+        @max_iterations = max_iterations
+        @messages = []
+        @thoughts = []
+        @iteration = 0
+        @parsed_response = nil
+      end
+
+      # Emit an event to the event handler if present
+      # @param type [Symbol] The type of event (e.g., :thought, :action, :observation)
+      # @param content [String, Hash] The content of the event
+      def emit_event(type, content)
+        return unless @event_handler
+
+        event = Event.new(type, content)
+        @event_handler.call(event)
+      end
+
+      # Check if we've reached the maximum number of iterations
+      # @return [Boolean] true if max iterations reached
+      def max_iterations_reached?
+        @iteration >= @max_iterations
+      end
+
+      # Increment the iteration counter
+      # @return [Integer] The new iteration count
+      def increment_iteration!
+        @iteration += 1
+      end
+
+      # Get the current iteration number (1-based for display)
+      # @return [Integer] The current iteration number for display
+      def current_step
+        @iteration + 1
+      end
+
+      # Add a thought to the thoughts collection
+      # @param thought [String] The thought content
+      # @param action [Hash, nil] Optional action associated with the thought
+      # @param observation [String, nil] Optional observation from action
+      def add_thought(thought, action: nil, observation: nil)
+        thought_data = { step: current_step, thought: thought }
+        thought_data[:action] = action if action
+        thought_data[:observation] = observation if observation
+        @thoughts << thought_data
+      end
+
+      # Update the last thought with action and observation
+      # @param action [Hash] The action that was taken
+      # @param observation [String] The observation from the action
+      def update_last_thought(action:, observation:)
+        return if @thoughts.empty?
+
+        @thoughts.last[:action] = action
+        @thoughts.last[:observation] = observation
+      end
+
+      # Add a message to the conversation
+      # @param role [String] The role of the message sender
+      # @param content [String] The message content
+      def add_message(role:, content:)
+        @messages << { role: role, content: content }
+      end
+
+      # Get the last assistant message content
+      # @return [String, nil] The content of the last assistant message
+      def last_assistant_content
+        last_assistant = @messages.reverse.find { |msg| msg[:role] == 'assistant' }
+        last_assistant&.fetch(:content, nil)
+      end
+    end
+  end
+end

data/lib/soka/llm.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Soka
+  # LLM wrapper class that delegates to specific provider implementations
+  class LLM
+    attr_reader :provider
+
+    # Initialize LLM with specified provider
+    # @param provider_name [Symbol, nil] The provider to use (:gemini, :openai, :anthropic)
+    # @param options [Hash] Provider-specific options (model, api_key, etc.)
+    def initialize(provider_name = nil, **options)
+      provider_name ||= Soka.configuration.ai.provider
+
+      # Merge configuration options if no explicit options provided
+      if options.empty? && provider_name == Soka.configuration.ai.provider
+        config = Soka.configuration.ai
+        options = {
+          api_key: config.api_key,
+          model: config.model
+        }.compact
+      end
+
+      @provider = create_provider(provider_name, **options)
+    end
+
+    # Chat with the LLM
+    # @param messages [Array<Hash>] Array of message hashes with role and content
+    # @param params [Hash] Additional parameters for the chat
+    # @return [LLMs::Result] The chat result
+    def chat(messages, **params)
+      @provider.chat(messages, **params)
+    end
+
+    # Stream chat responses
+    # @param messages [Array<Hash>] Array of message hashes
+    # @param params [Hash] Additional parameters
+    # @yield [chunk] Yields each response chunk
+    def streaming_chat(messages, **params, &)
+      @provider.streaming_chat(messages, **params, &)
+    end
+
+    # Check if provider supports streaming
+    # @return [Boolean] True if streaming is supported
+    def supports_streaming?
+      @provider.supports_streaming?
+    end
+
+    # Get the model being used
+    # @return [String] The model name
+    def model
+      @provider.model
+    end
+
+    # Build LLM instance from configuration object
+    # @param config [Object] Configuration with provider, model, and api_key
+    # @return [LLM] New LLM instance
+    def self.build(config)
+      options = {
+        model: config.model,
+        api_key: config.api_key
+      }.compact
+
+      new(config.provider, **options)
+    end
+
+    private
+
+    # Create the appropriate provider instance
+    # @param provider_name [Symbol] Provider type
+    # @param options [Hash] Provider options
+    # @return [LLMs::Base] Provider instance
+    def create_provider(provider_name, **)
+      case provider_name.to_sym
+      when :gemini
+        LLMs::Gemini.new(**)
+      when :openai
+        LLMs::OpenAI.new(**)
+      when :anthropic
+        LLMs::Anthropic.new(**)
+      else
+        raise LLMError, "Unknown LLM provider: #{provider_name}"
+      end
+    end
+  end
+end