soka 0.0.1.beta2

data/lib/soka/result.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+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
+
+    # 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
+    def initialize(attributes = {})
+      @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]
+      @created_at = Time.now
+    end
+
+    # Status check methods
+
+    # Check if the result is successful
+    # @return [Boolean]
+    def successful?
+      status == :success
+    end
+
+    # Check if the result failed
+    # @return [Boolean]
+    def failed?
+      status == :failed
+    end
+
+    # Check if the result timed out
+    # @return [Boolean]
+    def timeout?
+      status == :timeout
+    end
+
+    # Check if max iterations were reached
+    # @return [Boolean]
+    def max_iterations_reached?
+      status == :max_iterations_reached
+    end
+
+    # Data access methods
+
+    # Get the number of iterations (thoughts)
+    # @return [Integer]
+    def iterations
+      thoughts.length
+    end
+
+    # Convert to hash representation
+    # @return [Hash]
+    def to_h
+      build_hash.compact
+    end
+
+    # Convert to JSON string
+    # @return [String]
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Get a summary of the result
+    # @return [String]
+    def summary
+      status_message_for(status)
+    end
+
+    # Get execution details
+    # @return [Hash]
+    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
+      }
+    end
+
+    private
+
+    def build_hash
+      base_attributes.merge(execution_attributes)
+    end
+
+    def base_attributes
+      {
+        input: input,
+        thoughts: thoughts,
+        final_answer: final_answer,
+        confidence_score: confidence_score,
+        status: status
+      }
+    end
+
+    def execution_attributes
+      {
+        error: error,
+        execution_time: execution_time,
+        iterations: iterations,
+        created_at: @created_at
+      }
+    end
+
+    def status_message_for(current_status)
+      message_mapping[current_status] || "Status: #{current_status}"
+    end
+
+    def message_mapping
+      {
+        success: "Success: #{truncate(final_answer)}",
+        failed: "Failed: #{error}",
+        timeout: 'Timeout: Execution exceeded time limit',
+        max_iterations_reached: "Max iterations reached: #{iterations} iterations"
+      }
+    end
+
+    def truncate(text, length = 100)
+      return nil if text.nil?
+      return text if text.length <= length
+
+      "#{text[0..length]}..."
+    end
+  end
+end

data/lib/soka/test_helpers.rb

@@ -0,0 +1,162 @@
+# 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

data/lib/soka/thoughts_memory.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Soka
+  # Stores and manages the thinking process history
+  class ThoughtsMemory
+    attr_reader :sessions
+
+    def initialize
+      @sessions = []
+    end
+
+    def add(input, result)
+      session = {
+        input: input,
+        thoughts: result.thoughts || [],
+        final_answer: result.final_answer,
+        status: result.status,
+        confidence_score: result.confidence_score,
+        timestamp: Time.now
+      }
+
+      session[:error] = result.error if result.error
+
+      @sessions << session
+    end
+
+    def last_session
+      @sessions.last
+    end
+
+    def all_sessions
+      @sessions
+    end
+
+    def clear
+      @sessions.clear
+    end
+
+    def size
+      @sessions.size
+    end
+
+    def empty?
+      @sessions.empty?
+    end
+
+    def successful_sessions
+      @sessions.select { |s| s[:status] == :success }
+    end
+
+    def failed_sessions
+      @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?
+
+      total = @sessions.sum { |s| s[:thoughts].size }
+      total.to_f / @sessions.size
+    end
+
+    def to_s
+      return '<Soka::ThoughtsMemory> (0 sessions)' if empty?
+
+      stats = build_stats
+
+      format_stats_string(stats)
+    end
+
+    def build_stats
+      {
+        total: size,
+        successful: successful_sessions.size,
+        failed: failed_sessions.size,
+        avg_confidence: format('%.2f', average_confidence_score),
+        avg_iterations: format('%.1f', average_iterations)
+      }
+    end
+
+    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
+
+    def inspect
+      to_s
+    end
+
+    def to_h
+      {
+        sessions: @sessions,
+        stats: {
+          total_sessions: size,
+          successful_sessions: successful_sessions.size,
+          failed_sessions: failed_sessions.size,
+          average_confidence_score: average_confidence_score,
+          average_iterations: average_iterations
+        }
+      }
+    end
+  end
+end

data/lib/soka/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Soka
+  VERSION = '0.0.1.beta2'
+end

data/lib/soka.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+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
+module Soka
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class LLMError < Error; end
+  class ToolError < Error; end
+  class AgentError < Error; end
+  class MemoryError < Error; end
+
+  class << self
+    attr_accessor :configuration
+
+    def setup
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def configure(&)
+      setup(&)
+    end
+
+    def reset!
+      self.configuration = Configuration.new
+    end
+  end
+
+  loader = Zeitwerk::Loader.for_gem
+  loader.inflector.inflect(
+    'llm' => 'LLM',
+    'llms' => 'LLMs',
+    'ai' => 'AI',
+    'openai' => 'OpenAI',
+    'dsl_methods' => 'DSLMethods',
+    'llm_builder' => 'LLMBuilder'
+  )
+  loader.setup
+end
+
+# Initialize default configuration
+Soka.setup

data/sig/soka.rbs

@@ -0,0 +1,4 @@
+module Soka
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: soka
+version: !ruby/object:Gem::Version
+  version: 0.0.1.beta2
+platform: ruby
+authors:
+- jiunjiun
+bindir: exe
+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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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,
+  OpenAI, and Anthropic.
+email:
+- imjiunjiun@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE
+- README.md
+- Rakefile
+- examples/1_basic.rb
+- examples/2_event_handling.rb
+- examples/3_memory.rb
+- examples/4_hooks.rb
+- examples/5_error_handling.rb
+- examples/6_retry.rb
+- examples/7_tool_conditional.rb
+- examples/8_multi_provider.rb
+- lib/soka.rb
+- lib/soka/agent.rb
+- lib/soka/agent_tool.rb
+- lib/soka/agent_tools/params_validator.rb
+- lib/soka/agents/dsl_methods.rb
+- lib/soka/agents/hook_manager.rb
+- lib/soka/agents/llm_builder.rb
+- lib/soka/agents/retry_handler.rb
+- lib/soka/agents/tool_builder.rb
+- lib/soka/configuration.rb
+- lib/soka/engines/base.rb
+- lib/soka/engines/concerns/prompt_template.rb
+- lib/soka/engines/concerns/response_processor.rb
+- lib/soka/engines/react.rb
+- lib/soka/engines/reasoning_context.rb
+- lib/soka/llm.rb
+- lib/soka/llms/anthropic.rb
+- lib/soka/llms/base.rb
+- lib/soka/llms/concerns/response_parser.rb
+- lib/soka/llms/concerns/streaming_handler.rb
+- lib/soka/llms/gemini.rb
+- 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
+homepage: https://github.com/jiunjiun/soka
+licenses: []
+metadata:
+  homepage_uri: https://github.com/jiunjiun/soka
+  source_code_uri: https://github.com/jiunjiun/soka
+  changelog_uri: https://github.com/jiunjiun/soka/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Ruby ReAct Agent Framework with multi-LLM support
+test_files: []