soka-rails 0.0.1.beta4

data/lib/generators/soka/tool/tool_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+
+module Soka
+  module Generators
+    # Generator for creating new Soka tool classes with configurable parameters
+    class ToolGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :params, type: :array, default: [], banner: 'param1:type param2:type'
+
+      def create_tool_file
+        @tool_class_name = tool_class_name
+        @params_list = parse_params
+
+        template 'tool.rb.tt',
+                 File.join('app/soka/tools', class_path, "#{tool_file_name}.rb")
+      end
+
+      def create_test_file
+        return unless rspec_installed?
+
+        @tool_class_name = tool_class_name
+        @params_list = parse_params
+
+        template 'tool_spec.rb.tt',
+                 File.join('spec/soka/tools', class_path, "#{tool_file_name}_spec.rb")
+      end
+
+      private
+
+      # Normalize the tool file name to always end with _tool
+      def tool_file_name
+        base_name = file_name.to_s
+
+        # Remove existing _tool suffix if present to avoid duplication
+        base_name = base_name.sub(/_tool\z/, '')
+
+        # Add _tool suffix
+        "#{base_name}_tool"
+      end
+
+      # Normalize the tool class name to always end with Tool
+      def tool_class_name
+        base_class = class_name.to_s
+
+        # Remove existing Tool suffix if present to avoid duplication
+        base_class = base_class.sub(/Tool\z/, '')
+
+        # Add Tool suffix
+        "#{base_class}Tool"
+      end
+
+      def parse_params
+        params.map do |param|
+          name, type = param.split(':')
+          { name: name, type: type.capitalize || 'String' }
+        end
+      end
+
+      def rspec_installed?
+        File.exist?(::Rails.root.join('spec/spec_helper.rb')) ||
+          File.exist?(::Rails.root.join('spec/rails_helper.rb'))
+      end
+    end
+  end
+end

data/lib/soka/rails/agent_extensions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Soka
+  module Rails
+    # Extensions for Soka::Agent to integrate with Rails configuration
+    module AgentExtensions
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods for agent configuration
+      module ClassMethods
+        def inherited(subclass)
+          super
+          apply_rails_configuration(subclass)
+        end
+
+        private
+
+        def apply_rails_configuration(subclass)
+          return unless defined?(Soka::Rails.configuration)
+
+          rails_config = Soka::Rails.configuration
+          apply_configuration_values(subclass, rails_config)
+        end
+
+        def apply_configuration_values(subclass, config)
+          return unless config
+
+          subclass.provider config.ai_provider if config.ai_provider
+          subclass.model config.ai_model if config.ai_model
+          subclass.api_key config.ai_api_key if config.ai_api_key
+          subclass.max_iterations config.max_iterations if config.max_iterations
+          subclass.timeout config.timeout if config.timeout
+        end
+      end
+    end
+  end
+end
+
+# Apply extensions to Soka::Agent
+Soka::Agent.include(Soka::Rails::AgentExtensions) if defined?(Soka::Agent)

data/lib/soka/rails/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Soka
+  module Rails
+    # Main configuration class for Soka Rails settings
+    class Configuration
+      attr_accessor :ai_provider, :ai_model, :ai_api_key, :max_iterations, :timeout
+
+      def initialize
+        # Use ENV.fetch to set default values
+        @ai_provider = ENV.fetch('SOKA_PROVIDER', :gemini).to_sym
+        @ai_model = ENV.fetch('SOKA_MODEL', 'gemini-2.0-flash-exp')
+        @ai_api_key = ENV.fetch('SOKA_API_KEY', nil)
+
+        # Performance settings
+        @max_iterations = defined?(::Rails) && ::Rails.env.production? ? 10 : 5
+        @timeout = 30
+      end
+
+      # DSL configuration methods
+      def ai
+        yield(AIConfig.new(self)) if block_given?
+      end
+
+      def performance
+        yield(PerformanceConfig.new(self)) if block_given?
+      end
+
+      # Internal configuration classes
+      # DSL class for AI-specific configuration settings
+      class AIConfig
+        def initialize(config)
+          @config = config
+        end
+
+        def provider=(value)
+          @config.ai_provider = value
+        end
+
+        def model=(value)
+          @config.ai_model = value
+        end
+
+        def api_key=(value)
+          @config.ai_api_key = value
+        end
+      end
+
+      # DSL class for performance-related configuration settings
+      class PerformanceConfig
+        def initialize(config)
+          @config = config
+        end
+
+        def max_iterations=(value)
+          @config.max_iterations = value
+        end
+
+        def timeout=(value)
+          @config.timeout = value.is_a?(Numeric) ? value : value.to_i
+        end
+      end
+    end
+  end
+end

data/lib/soka/rails/errors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Soka
+  module Rails
+    # Base error class for Soka Rails
+    class Error < StandardError; end
+
+    # Configuration related errors
+    # Raised when there are configuration-related issues
+    class ConfigurationError < Error; end
+
+    # Agent related errors
+    # Raised when agent execution encounters problems
+    class AgentError < Error; end
+
+    # Tool related errors
+    # Raised when tool execution or validation fails
+    class ToolError < Error; end
+
+    # Generator related errors
+    # Raised when generator operations fail
+    class GeneratorError < Error; end
+
+    # Specific error classes
+    # Raised when API key is missing for the configured provider
+    class MissingApiKeyError < ConfigurationError
+      def initialize(provider = nil)
+        message = if provider
+                    "Missing API key for provider: #{provider}. " \
+                      "Please set SOKA_API_KEY or SOKA_#{provider.to_s.upcase}_API_KEY environment variable."
+                  else
+                    'Missing API key. Please set SOKA_API_KEY environment variable.'
+                  end
+        super(message)
+      end
+    end
+
+    # Raised when an unsupported AI provider is specified
+    class InvalidProviderError < ConfigurationError
+      def initialize(provider)
+        super("Invalid AI provider: #{provider}. Supported providers: :gemini, :openai, :anthropic")
+      end
+    end
+
+    # Raised when agent execution exceeds the configured timeout
+    class AgentTimeoutError < AgentError
+      def initialize(timeout)
+        super("Agent execution timeout after #{timeout} seconds")
+      end
+    end
+
+    # Raised when agent exceeds maximum allowed iterations
+    class MaxIterationsExceededError < AgentError
+      def initialize(max_iterations)
+        super("Agent exceeded maximum iterations limit of #{max_iterations}")
+      end
+    end
+
+    # Raised when a requested tool cannot be found
+    class ToolNotFoundError < ToolError
+      def initialize(tool_name)
+        super("Tool not found: #{tool_name}")
+      end
+    end
+
+    # Raised when tool is called with invalid parameters
+    class InvalidToolParametersError < ToolError
+      def initialize(tool_name, errors)
+        super("Invalid parameters for tool #{tool_name}: #{errors.join(', ')}")
+      end
+    end
+  end
+end

data/lib/soka/rails/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Soka
+  module Rails
+    # Rails integration for Soka, configuring autoloading and initializers
+    class Railtie < ::Rails::Railtie
+      # Configure autoloading - executed after Rails completes basic setup
+      initializer 'soka.setup_autoloading', before: :set_autoload_paths do |app|
+        # Add app/soka to autoload paths
+        # eager_load: true will automatically include all subdirectories
+        app.config.paths.add 'app/soka', eager_load: true
+      end
+    end
+  end
+end

data/lib/soka/rails/rspec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'soka/rails/test_helpers'
+
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include Soka::Rails::TestHelpers, type: :agent
+    config.include Soka::Rails::TestHelpers, type: :tool
+
+    config.before(:each, type: :agent) do
+      # Reset Soka configuration
+      Soka.configuration = Soka::Configuration.new if defined?(Soka) && Soka.respond_to?(:configuration=)
+    end
+
+    config.before(:each, type: :tool) do
+      # Ensure Rails environment is available
+      allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new('test')) if defined?(Rails)
+    end
+
+    # Automatically tag tests under spec/soka directory
+    config.define_derived_metadata(file_path: %r{/spec/soka/agents/}) do |metadata|
+      metadata[:type] = :agent
+    end
+
+    config.define_derived_metadata(file_path: %r{/spec/soka/tools/}) do |metadata|
+      metadata[:type] = :tool
+    end
+  end
+end

data/lib/soka/rails/test_helpers.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Soka
+  module Rails
+    # Test helpers for RSpec tests with Soka agents and tools
+    module TestHelpers
+      extend ActiveSupport::Concern
+
+      included do
+        let(:mock_llm) { instance_double('Soka::LLM') }
+      end
+
+      # Mock AI response
+      def mock_ai_response(response_attrs = {})
+        response = build_mock_response(response_attrs)
+        setup_llm_mock(response)
+      end
+
+      def build_mock_response(attrs)
+        default_response = {
+          final_answer: 'Mocked answer',
+          confidence_score: 0.95,
+          status: :completed,
+          iterations: 1,
+          thought_process: []
+        }
+        default_response.merge(attrs)
+      end
+
+      def setup_llm_mock(response)
+        return unless defined?(Soka::LLM)
+
+        allow(Soka::LLM).to receive(:new).and_return(mock_llm)
+        allow(mock_llm).to receive(:chat).and_return(
+          Struct.new(:content).new(build_react_response(response))
+        )
+      end
+
+      # Mock tool execution
+      def mock_tool_execution(tool_class, result)
+        allow_any_instance_of(tool_class).to receive(:call).and_return(result)
+      end
+
+      # Build ReAct format response
+      def build_react_response(attrs)
+        thoughts = attrs[:thought_process].presence ||
+                   ['Analyzing the request']
+
+        response = thoughts.map { |t| "<Thought>#{t}</Thought>" }.join("\n")
+        response += "\n<Final_Answer>#{attrs[:final_answer]}</Final_Answer>"
+        response
+      end
+
+      # Agent test helper methods
+      def run_agent(agent, input, &)
+        result = if block_given?
+                   agent.run(input, &)
+                 else
+                   agent.run(input)
+                 end
+
+        expect(result).to be_a(Struct)
+        result
+      end
+
+      # Event collector
+      def collect_agent_events(agent, input)
+        events = []
+
+        agent.run(input) do |event|
+          events << event
+        end
+
+        events
+      end
+
+      # Test configuration
+      def with_test_configuration
+        original_config = Soka::Rails.configuration.dup
+
+        Soka::Rails.configure do |config|
+          config.ai_provider = :mock
+          config.max_iterations = 3
+          config.timeout = 5
+          yield config if block_given?
+        end
+
+        yield
+      ensure
+        Soka::Rails.configuration = original_config
+      end
+
+      # Helper method: create successful result
+      def successful_result(attrs = {})
+        default_attrs = {
+          status: :completed,
+          final_answer: 'Success',
+          confidence_score: 0.95,
+          iterations: 1
+        }
+
+        Struct.new(*default_attrs.keys).new(*default_attrs.merge(attrs).values)
+      end
+
+      # Helper method: check if result is successful
+      RSpec::Matchers.define :be_successful do
+        match do |actual|
+          actual.respond_to?(:status) && actual.status == :completed
+        end
+
+        failure_message do |actual|
+          "expected result to be successful, but status was #{actual.status}"
+        end
+      end
+    end
+  end
+end

data/lib/soka/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Soka
+  module Rails
+    VERSION = '0.0.1.beta4'
+  end
+end

data/lib/soka/rails.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'rails/version'
+require_relative 'rails/configuration'
+require_relative 'rails/errors'
+require_relative 'rails/railtie'
+require_relative 'rails/agent_extensions'
+
+module Soka
+  # Rails integration for Soka AI Agent Framework
+  module Rails
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+    end
+  end
+end

data/lib/soka_rails.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file serves as the entry point for the soka-rails gem
+# It ensures proper loading order for Rails integration
+
+require 'rails'
+require 'soka'
+require 'zeitwerk'
+
+# Load the main Soka::Rails module
+require_relative 'soka/rails'

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: soka-rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1.beta4
+platform: ruby
+authors:
+- jiunjiun
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: soka
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+- !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 Rails provides seamless integration between the Soka AI Agent Framework
+  and Ruby on Rails applications, following Rails conventions for easy adoption.
+email:
+- imjiunjiun@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- DESIGN.md
+- LICENSE
+- README.md
+- REQUIREMENT.md
+- Rakefile
+- SPEC.md
+- app/soka/agents/application_agent.rb
+- app/soka/tools/application_tool.rb
+- lib/generators/soka/agent/agent_generator.rb
+- lib/generators/soka/agent/templates/agent.rb.tt
+- lib/generators/soka/agent/templates/agent_spec.rb.tt
+- lib/generators/soka/install/install_generator.rb
+- lib/generators/soka/install/templates/application_agent.rb
+- lib/generators/soka/install/templates/application_tool.rb
+- lib/generators/soka/install/templates/soka.rb
+- lib/generators/soka/tool/templates/tool.rb.tt
+- lib/generators/soka/tool/templates/tool_spec.rb.tt
+- lib/generators/soka/tool/tool_generator.rb
+- lib/soka/rails.rb
+- lib/soka/rails/agent_extensions.rb
+- lib/soka/rails/configuration.rb
+- lib/soka/rails/errors.rb
+- lib/soka/rails/railtie.rb
+- lib/soka/rails/rspec.rb
+- lib/soka/rails/test_helpers.rb
+- lib/soka/rails/version.rb
+- lib/soka_rails.rb
+homepage: https://github.com/jiunjiun/soka-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jiunjiun/soka-rails
+  source_code_uri: https://github.com/jiunjiun/soka-rails
+  changelog_uri: https://github.com/jiunjiun/soka-rails/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: Rails integration for Soka AI Agent Framework
+test_files: []