soka 0.0.1.beta2

data/lib/soka/agent_tool.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Soka
+  # Base class for agent tools with parameter validation
+  class AgentTool
+    include AgentTools::ParamsValidator
+
+    # Handles parameter definitions for tools
+    class ParamsDefinition
+      attr_reader :required_params, :optional_params, :validations
+
+      def initialize
+        @required_params = {}
+        @optional_params = {}
+        @validations = {}
+      end
+
+      def requires(name, type, desc: nil, **options)
+        param_config = {
+          type: type,
+          desc: desc
+        }
+        param_config[:default] = options[:default] if options.key?(:default)
+        @required_params[name] = param_config
+      end
+
+      def optional(name, type, desc: nil, **options)
+        param_config = {
+          type: type,
+          desc: desc
+        }
+        param_config[:default] = options[:default] if options.key?(:default)
+        @optional_params[name] = param_config
+      end
+
+      def validates(name, **rules)
+        @validations[name] = rules
+      end
+    end
+
+    class << self
+      attr_reader :description, :params_definition
+
+      def desc(description)
+        @description = description
+      end
+
+      def params(&)
+        @params_definition = ParamsDefinition.new
+        @params_definition.instance_eval(&) if block_given?
+      end
+
+      def tool_name
+        return 'anonymous' if name.nil?
+
+        name.split('::').last.gsub(/Tool$/, '').downcase
+      end
+
+      def to_h
+        {
+          name: tool_name,
+          description: description || 'No description provided',
+          parameters: parameters_schema
+        }
+      end
+
+      def parameters_schema
+        schema = base_schema
+        add_parameters_to_schema(schema) if params_definition
+        schema
+      end
+
+      def base_schema
+        {
+          type: 'object',
+          properties: {},
+          required: []
+        }
+      end
+
+      def add_parameters_to_schema(schema)
+        add_required_params(schema)
+        add_optional_params(schema)
+      end
+
+      def add_required_params(schema)
+        params_definition.required_params.each do |name, config|
+          schema[:properties][name.to_s] = build_property_schema(name, config)
+          schema[:required] << name.to_s
+        end
+      end
+
+      def add_optional_params(schema)
+        params_definition.optional_params.each do |name, config|
+          schema[:properties][name.to_s] = build_property_schema(name, config)
+        end
+      end
+
+      private
+
+      def build_property_schema(_name, config)
+        schema = {
+          type: type_to_json_type(config[:type]),
+          description: config[:desc]
+        }
+
+        schema[:default] = config[:default] if config.key?(:default)
+        schema
+      end
+
+      def type_to_json_type(ruby_type)
+        type_mapping[ruby_type.to_s] || 'string'
+      end
+
+      def type_mapping
+        @type_mapping ||= build_type_mapping
+      end
+
+      def build_type_mapping
+        {
+          'String' => 'string',
+          'Integer' => 'integer', 'Fixnum' => 'integer', 'Bignum' => 'integer',
+          'Float' => 'number', 'Numeric' => 'number',
+          'TrueClass' => 'boolean', 'FalseClass' => 'boolean', 'Boolean' => 'boolean',
+          'Array' => 'array',
+          'Hash' => 'object'
+        }.freeze
+      end
+    end
+
+    def call(**params)
+      raise NotImplementedError, "#{self.class} must implement #call method"
+    end
+
+    def execute(**params)
+      validate_params!(params)
+      call(**params)
+    rescue ToolError
+      raise # Re-raise ToolError without wrapping
+    rescue StandardError => e
+      raise ToolError, "Error executing #{self.class.tool_name}: #{e.message}"
+    end
+
+    # Validation methods are in ParamsValidator module
+  end
+end

data/lib/soka/agent_tools/params_validator.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Soka
+  module AgentTools
+    # Module for parameter validation
+    module ParamsValidator
+      private
+
+      def validate_params!(params)
+        return unless self.class.params_definition
+
+        definition = self.class.params_definition
+        validate_required_params!(params, definition)
+        validate_optional_params!(params, definition)
+        run_validations!(params)
+      end
+
+      def validate_required_params!(params, definition)
+        definition.required_params.each do |name, config|
+          process_required_param(params, name, config)
+        end
+      end
+
+      def process_required_param(params, name, config)
+        unless params.key?(name)
+          raise ToolError, "Missing required parameter: #{name}" unless config.key?(:default)
+
+          params[name] = config[:default]
+        end
+        validate_type!(name, params[name], config[:type])
+      end
+
+      def validate_optional_params!(params, definition)
+        definition.optional_params.each do |name, config|
+          process_optional_param(params, name, config)
+        end
+      end
+
+      def process_optional_param(params, name, config)
+        if params.key?(name)
+          validate_type!(name, params[name], config[:type])
+        elsif config.key?(:default)
+          params[name] = config[:default]
+        end
+      end
+
+      def validate_type!(name, value, expected_type)
+        return if value.nil?
+        return if value.is_a?(expected_type)
+
+        raise ToolError, "Parameter #{name} must be a #{expected_type}, got #{value.class}"
+      end
+
+      def run_validations!(params)
+        return unless self.class.params_definition
+
+        self.class.params_definition.validations.each do |param_name, rules|
+          # Only validate if parameter was provided
+          next unless params.key?(param_name)
+
+          validate_param_rules(param_name, params[param_name], rules)
+        end
+      end
+
+      def validate_param_rules(param_name, value, rules)
+        # Skip validation if parameter wasn't provided and has no presence validation
+        return if value.nil? && !rules[:presence]
+
+        rules.each do |rule, rule_value|
+          apply_validation_rule(param_name, value, rule, rule_value)
+        end
+      end
+
+      def apply_validation_rule(param_name, value, rule, rule_value)
+        case rule
+        when :presence
+          validate_presence!(param_name, value, rule_value)
+        when :length
+          validate_length!(param_name, value, rule_value)
+        when :inclusion
+          validate_inclusion!(param_name, value, rule_value)
+        when :format
+          validate_format!(param_name, value, rule_value)
+        end
+      end
+
+      def validate_presence!(param_name, value, rule_value)
+        return unless rule_value && (value.nil? || value.to_s.empty?)
+
+        raise ToolError, "Parameter #{param_name} can't be blank"
+      end
+
+      def validate_length!(name, value, constraints)
+        return unless value.respond_to?(:length)
+
+        check_minimum_length!(name, value, constraints[:minimum])
+        check_maximum_length!(name, value, constraints[:maximum])
+      end
+
+      def check_minimum_length!(name, value, minimum)
+        return unless minimum && value.length < minimum
+
+        raise ToolError,
+              "Parameter #{name} is too short (minimum is #{minimum} characters)"
+      end
+
+      def check_maximum_length!(name, value, maximum)
+        return unless maximum && value.length > maximum
+
+        raise ToolError,
+              "Parameter #{name} is too long (maximum is #{maximum} characters)"
+      end
+
+      def validate_inclusion!(name, value, constraints)
+        allowed_values = constraints[:in]
+        allow_nil = constraints[:allow_nil]
+
+        return if value.nil? && allow_nil
+        return if allowed_values.include?(value)
+
+        values_string = if allowed_values.is_a?(Range)
+                          "#{allowed_values.min}..#{allowed_values.max}"
+                        else
+                          allowed_values.join(', ')
+                        end
+        raise ToolError, "Parameter #{name} must be one of: #{values_string}"
+      end
+
+      def validate_format!(name, value, constraints)
+        return unless value.is_a?(String)
+
+        pattern = constraints[:with]
+        return if value.match?(pattern)
+
+        raise ToolError, "Parameter #{name} has invalid format"
+      end
+    end
+  end
+end

data/lib/soka/agents/dsl_methods.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Soka
+  module Agents
+    # Module for DSL methods
+    module DSLMethods
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods for DSL
+      module ClassMethods
+        attr_accessor :_provider, :_model, :_api_key, :_max_iterations, :_timeout, :_tools, :_retry_config, :_hooks
+
+        def inherited(subclass)
+          super
+          subclass._tools = []
+          subclass._hooks = { before_action: [], after_action: [], on_error: [] }
+          subclass._retry_config = {}
+        end
+
+        # Define provider for the agent
+        # @param provider [Symbol] The LLM provider (:gemini, :openai, :anthropic)
+        def provider(provider)
+          @_provider = provider
+        end
+
+        # Define model for the agent
+        # @param model [String] The model name (e.g., 'gemini-1.5-pro')
+        def model(model)
+          @_model = model
+        end
+
+        # Define API key for the agent
+        # @param key [String] The API key
+        def api_key(key)
+          @_api_key = key
+        end
+
+        # Define maximum iterations for the agent
+        # @param num [Integer] The maximum number of iterations
+        def max_iterations(num)
+          @_max_iterations = num
+        end
+
+        # Define timeout for the agent
+        # @param duration [Integer] The timeout duration in seconds
+        def timeout(duration)
+          @_timeout = duration
+        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
+        # @param options [Hash] Additional options (if description provided)
+        def tool(tool_class_or_name, description_or_options = nil, options = {})
+          if tool_class_or_name.is_a?(Symbol) || tool_class_or_name.is_a?(String)
+            # Function tool - expects description and options
+            add_function_tool(tool_class_or_name, description_or_options, options)
+          else
+            # Class tool - second parameter is options
+            opts = description_or_options.is_a?(Hash) ? description_or_options : options
+            add_class_tool(tool_class_or_name, opts)
+          end
+        end
+
+        # Register multiple tools at once
+        # @param tool_classes [Array<Class>] The tool classes to register
+        def tools(*tool_classes)
+          tool_classes.each { |tool_class| tool(tool_class) }
+        end
+
+        # Configure retry behavior
+        # @yield Configuration block
+        def retry_config(&)
+          config = Agents::RetryConfig.new
+          config.instance_eval(&)
+          @_retry_config = config.to_h
+        end
+
+        # Register before_action hook
+        # @param method_name [Symbol] The method to call before action
+        def before_action(method_name)
+          @_hooks[:before_action] << method_name
+        end
+
+        # Register after_action hook
+        # @param method_name [Symbol] The method to call after action
+        def after_action(method_name)
+          @_hooks[:after_action] << method_name
+        end
+
+        # Register on_error hook
+        # @param method_name [Symbol] The method to call on error
+        def on_error(method_name)
+          @_hooks[:on_error] << method_name
+        end
+
+        private
+
+        def add_function_tool(name, description, options)
+          @_tools << {
+            type: :function,
+            name: name,
+            description: description,
+            options: options
+          }
+        end
+
+        def add_class_tool(tool_class, options)
+          condition = options[:if]
+          return unless condition.nil? || (condition.respond_to?(:call) ? condition.call : condition)
+
+          @_tools << { type: :class, class: tool_class, options: options }
+        end
+      end
+    end
+
+    # Configuration for retry behavior
+    class RetryConfig
+      attr_accessor :max_retries, :backoff_strategy, :retry_on
+
+      def initialize
+        @max_retries = 3
+        @backoff_strategy = :exponential
+        @retry_on = []
+      end
+
+      # Convert to hash
+      # @return [Hash] The configuration as a hash
+      def to_h
+        {
+          max_retries: max_retries,
+          backoff_strategy: backoff_strategy,
+          retry_on: retry_on
+        }
+      end
+    end
+  end
+end

data/lib/soka/agents/hook_manager.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Soka
+  module Agents
+    # Module for managing hooks and result processing
+    module HookManager
+      private
+
+      # Run registered hooks for the given type
+      # @param hook_type [Symbol] The type of hook (:before_action, :after_action, :on_error)
+      # @param args [Array] Arguments to pass to the hook methods
+      # @return [Object, nil] The result from on_error hooks, or nil
+      def run_hooks(hook_type, *)
+        return unless self.class._hooks && self.class._hooks[hook_type]
+
+        self.class._hooks[hook_type].each do |method_name|
+          if respond_to?(method_name, true)
+            result = send(method_name, *)
+            return result if hook_type == :on_error && result
+          end
+        end
+
+        nil
+      end
+
+      # Convert engine result to final Result object
+      # @param engine_result [Struct] The raw engine result
+      # @return [Result] The converted result
+      def convert_engine_result(engine_result)
+        Result.new(
+          input: engine_result.input,
+          thoughts: engine_result.thoughts,
+          final_answer: engine_result.final_answer,
+          status: engine_result.status,
+          error: engine_result.error,
+          confidence_score: engine_result.confidence_score
+        )
+      end
+
+      # Update conversation and thoughts memories
+      # @param input [String] The original input
+      # @param result [Result] The result to record
+      def update_memories(input, result)
+        # Update conversation memory
+        @memory.add(role: 'user', content: input)
+        @memory.add(role: 'assistant', content: result.final_answer) if result.final_answer
+
+        # Update thoughts memory
+        @thoughts_memory.add(input, result)
+      end
+
+      # Build an error result object
+      # @param input [String] The original input
+      # @param error [StandardError] The error that occurred
+      # @return [Result] An error result
+      def build_error_result(input, error)
+        Result.new(
+          input: input,
+          thoughts: [],
+          final_answer: nil,
+          status: :failed,
+          error: error.message,
+          confidence_score: 0.0
+        )
+      end
+    end
+  end
+end

data/lib/soka/agents/llm_builder.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Soka
+  module Agents
+    # Module for building LLM instances
+    module LLMBuilder
+      private
+
+      # Build LLM instance with configuration
+      # @param options [Hash] Configuration options
+      # @return [LLM] The LLM instance
+      def build_llm(options)
+        provider = get_config_value(:provider, options)
+        model = get_config_value(:model, options)
+        api_key = get_config_value(:api_key, options)
+
+        LLM.new(provider, model: model, api_key: api_key)
+      end
+
+      # Get configuration value with fallback chain
+      # @param key [Symbol] The configuration key
+      # @param options [Hash] Configuration options
+      # @return [Object] The configuration value
+      def get_config_value(key, options)
+        # Check options first, then class settings, finally global config
+        options[key] ||
+          self.class.send("_#{key}") ||
+          Soka.configuration.ai.send(key)
+      end
+    end
+  end
+end

data/lib/soka/agents/retry_handler.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Soka
+  module Agents
+    # Module for handling retry logic
+    module RetryHandler
+      private
+
+      # Execute a block with retry logic
+      # @yield The block to execute with retries
+      # @return [Object] The result of the block
+      def with_retry(&)
+        config = extract_retry_config
+        execute_with_retries(config, &)
+      end
+
+      # Extract retry configuration with defaults
+      # @return [Hash] The retry configuration
+      def extract_retry_config
+        config = self.class._retry_config
+        {
+          max_retries: config[:max_retries] || 3,
+          backoff_strategy: config[:backoff_strategy] || :exponential,
+          retry_on: config[:retry_on] || []
+        }
+      end
+
+      # Execute with retry logic
+      # @param config [Hash] Retry configuration
+      # @yield The block to execute
+      # @return [Object] The result of the block
+      def execute_with_retries(config, &block)
+        retries = 0
+        begin
+          block.call
+        rescue StandardError => e
+          raise e unless should_retry?(e, config[:retry_on]) && retries < config[:max_retries]
+
+          retries += 1
+          sleep(calculate_backoff(retries, config[:backoff_strategy]))
+          retry
+        end
+      end
+
+      # Check if error should trigger retry
+      # @param error [StandardError] The error to check
+      # @param retry_on [Array<Class>] Error classes to retry on
+      # @return [Boolean] True if should retry
+      def should_retry?(error, retry_on)
+        # Never retry ToolError - let it propagate immediately to on_error hook
+        return false if error.is_a?(Soka::ToolError)
+
+        return true if retry_on.empty?
+
+        retry_on.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      # Calculate backoff time
+      # @param retries [Integer] Number of retries
+      # @param strategy [Symbol] Backoff strategy
+      # @return [Integer] Sleep time in seconds
+      def calculate_backoff(retries, strategy)
+        case strategy
+        when :exponential
+          2**(retries - 1)
+        when :linear
+          retries
+        else
+          1 # constant or unknown strategy
+        end
+      end
+    end
+  end
+end

data/lib/soka/agents/tool_builder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Soka
+  module Agents
+    # Module for building tools
+    module ToolBuilder
+      private
+
+      # Build tools from configuration
+      # @return [Array<AgentTool>] Array of tool instances
+      def build_tools
+        tools = build_configured_tools
+        tools.empty? ? build_default_tools : tools
+      end
+
+      # Build tools from class configuration
+      # @return [Array<AgentTool>] Array of configured tools
+      def build_configured_tools
+        self.class._tools.map do |tool_config|
+          create_tool_from_config(tool_config)
+        end
+      end
+
+      # Create tool instance from configuration
+      # @param tool_config [Hash] Tool configuration
+      # @return [AgentTool] The tool instance
+      def create_tool_from_config(tool_config)
+        case tool_config[:type]
+        when :class
+          tool_config[:class].new
+        when :function
+          build_function_tool(tool_config)
+        end
+      end
+
+      # Build default tools from global configuration
+      # @return [Array<AgentTool>] Array of default tools
+      def build_default_tools
+        return [] unless Soka.configuration.tools.any?
+
+        Soka.configuration.tools.map(&:new)
+      end
+
+      # Build a function-based tool
+      # @param config [Hash] Tool configuration
+      # @return [AgentTool] The function tool instance
+      def build_function_tool(config)
+        tool_name = config[:name]
+        description = config[:description]
+
+        # Create a dynamic tool class
+        dynamic_tool = create_dynamic_tool_class(tool_name, description)
+        dynamic_tool.new.tap { |tool| tool.instance_variable_set(:@agent, self) }
+      end
+
+      # Create a dynamic tool class
+      # @param tool_name [Symbol, String] The tool name
+      # @param description [String] The tool description
+      # @return [Class] The dynamic tool class
+      def create_dynamic_tool_class(tool_name, description)
+        Class.new(AgentTool) do
+          desc description
+
+          define_method :call do |**params|
+            # Call the method on the agent instance
+            raise ToolError, "Method #{tool_name} not found on agent" unless @agent.respond_to?(tool_name)
+
+            @agent.send(tool_name, **params)
+          end
+
+          define_singleton_method :tool_name do
+            tool_name.to_s
+          end
+        end
+      end
+    end
+  end
+end