soka-rails 0.0.1.beta4

data/REQUIREMENT.md

@@ -0,0 +1,308 @@
+# Soka Rails Requirements Specification
+
+## 1. Project Overview
+
+### 1.1 Project Name
+Soka Rails - Rails Integration Package for Soka AI Agent Framework
+
+### 1.2 Project Goals
+Provide seamless integration between Soka AI Agent Framework and Ruby on Rails, following Rails conventions, allowing developers to easily use AI Agent functionality in Rails applications.
+
+### 1.3 Target Users
+- Rails developers
+- Teams needing to integrate AI Agent functionality in Rails applications
+- Existing users of Soka Framework
+
+## 2. Functional Requirements
+
+### 2.1 Core Features
+
+#### 2.1.1 Native Rails Integration
+- **Requirement ID**: FR-001
+- **Priority**: High
+- **Description**: Fully comply with Rails conventions and best practices
+- **Acceptance Criteria**:
+  - Follow Rails directory structure conventions
+  - Support Rails configuration system
+  - Integrate Rails logging system
+  - Support Rails error handling mechanism
+
+#### 2.1.2 Autoloading Support
+- **Requirement ID**: FR-002
+- **Priority**: High
+- **Description**: Automatically load all Agents and Tools in app/soka directory
+- **Acceptance Criteria**:
+  - Support Rails autoload_paths
+  - Support hot reload in development environment
+  - Properly handle namespaces
+
+#### 2.1.3 Generator Support
+- **Requirement ID**: FR-003
+- **Priority**: High
+- **Description**: Provide Rails Generators to quickly generate Agent and Tool templates
+- **Acceptance Criteria**:
+  - Provide install generator
+  - Provide agent generator
+  - Provide tool generator
+  - Generated code follows Rails conventions
+
+#### 2.1.4 Rails Configuration Integration
+- **Requirement ID**: FR-004
+- **Priority**: High
+- **Description**: Use Rails configuration system to manage Soka settings
+- **Acceptance Criteria**:
+  - Support initializer configuration
+  - Support environment variable configuration
+  - Support configuration overrides for different environments
+
+#### 2.1.5 Rails Testing Integration
+- **Requirement ID**: FR-005
+- **Priority**: High
+- **Description**: Seamless integration with RSpec
+- **Acceptance Criteria**:
+  - Provide RSpec test helpers
+  - Support Agent and Tool testing
+  - Provide mock and stub functionality
+
+### 2.2 Agent System Requirements
+
+#### 2.2.1 ApplicationAgent Base Class
+- **Requirement ID**: FR-006
+- **Priority**: High
+- **Description**: Provide Rails-specific Agent base class
+- **Acceptance Criteria**:
+  - Inherit from Soka::Agent
+  - Include Rails-specific default configuration
+  - Integrate Rails lifecycle hooks
+  - Support Rails error tracking
+
+#### 2.2.2 Rails Integration Hooks
+- **Requirement ID**: FR-007
+- **Priority**: Medium
+- **Description**: Support Rails-specific lifecycle hooks
+- **Acceptance Criteria**:
+  - Support Rails logging integration
+  - Support error tracking service integration
+  - Support performance monitoring integration
+
+### 2.3 Tool System Requirements
+
+#### 2.3.1 ApplicationTool Base Class
+- **Requirement ID**: FR-008
+- **Priority**: High
+- **Description**: Provide Rails-specific Tool base class
+- **Acceptance Criteria**:
+  - Inherit from Soka::AgentTool
+  - Include Rails-specific helper methods
+  - Support standardized error handling
+
+#### 2.3.2 Rails-specific Tools
+- **Requirement ID**: FR-009
+- **Priority**: Medium
+- **Description**: Provide Rails environment information tool
+- **Acceptance Criteria**:
+  - RailsInfoTool can query route information
+  - RailsInfoTool can query version information
+  - RailsInfoTool can query environment configuration
+  - Only return safe configuration values
+
+### 2.4 Configuration System Requirements
+
+#### 2.4.1 Initializer Configuration
+- **Requirement ID**: FR-010
+- **Priority**: High
+- **Description**: Provide standard Rails initializer configuration file
+- **Acceptance Criteria**:
+  - Support AI provider configuration
+  - Support performance parameter configuration
+  - Use ENV.fetch() to handle environment variables
+  - Support block-style configuration DSL
+
+#### 2.4.2 Environment-specific Configuration
+- **Requirement ID**: FR-011
+- **Priority**: Medium
+- **Description**: Support configuration for different Rails environments
+- **Acceptance Criteria**:
+  - Development environment has reasonable defaults
+  - Production environment has optimized settings
+  - Test environment supports testing needs
+
+## 3. Non-functional Requirements
+
+### 3.1 Performance Requirements
+- **Requirement ID**: NFR-001
+- **Description**: System performance requirements
+- **Acceptance Criteria**:
+  - Agent execution does not affect main Rails application functionality
+  - Support asynchronous execution mode
+  - Reasonable memory usage
+
+### 3.2 Compatibility Requirements
+- **Requirement ID**: NFR-002
+- **Description**: Version compatibility requirements
+- **Acceptance Criteria**:
+  - Ruby >= 3.0
+  - Rails >= 7.0
+  - Soka >= 1.0
+  - Compatible with mainstream Rails gems
+
+### 3.3 Security Requirements
+- **Requirement ID**: NFR-003
+- **Description**: Security requirements
+- **Acceptance Criteria**:
+  - API keys managed through environment variables
+  - No exposure of sensitive configuration information
+  - Follow Rails security best practices
+
+### 3.4 Maintainability Requirements
+- **Requirement ID**: NFR-004
+- **Description**: Code quality and maintainability
+- **Acceptance Criteria**:
+  - Follow Rails code conventions
+  - Provide complete YARD documentation
+  - Test coverage > 90%
+  - Pass RuboCop checks
+
+## 4. Technical Requirements
+
+### 4.1 Dependency Management
+- **Requirement ID**: TR-001
+- **Description**: Gem dependency requirements
+- **Specifications**:
+  - Depend on soka gem
+  - Depend on rails gem
+  - Minimize additional dependencies
+
+### 4.2 Testing Framework
+- **Requirement ID**: TR-002
+- **Description**: Testing framework support
+- **Specifications**:
+  - Full RSpec support
+  - Provide test helper modules
+  - Support mock AI responses
+
+### 4.3 File Structure
+- **Requirement ID**: TR-003
+- **Description**: Standard file structure
+- **Specifications**:
+  ```
+  app/soka/
+  ├── agents/
+  │   └── application_agent.rb
+  └── tools/
+      └── application_tool.rb
+  config/initializers/
+  └── soka.rb
+  ```
+
+## 5. Use Cases
+
+### 5.1 Basic Agent Usage
+- **Case ID**: UC-001
+- **Actor**: Rails Developer
+- **Precondition**: soka-rails gem installed
+- **Main Flow**:
+  1. Developer instantiates Agent in Controller
+  2. Call Agent.run() method
+  3. Get result and return to frontend
+- **Postcondition**: Successfully executed and returned result
+
+### 5.2 Generator Usage
+- **Case ID**: UC-002
+- **Actor**: Rails Developer
+- **Precondition**: soka-rails gem installed
+- **Main Flow**:
+  1. Execute rails generate soka:install
+  2. Execute rails generate soka:agent [name]
+  3. Execute rails generate soka:tool [name]
+- **Postcondition**: Generate corresponding file structure
+
+### 5.3 Test Writing
+- **Case ID**: UC-003
+- **Actor**: Rails Developer
+- **Precondition**: RSpec configured
+- **Main Flow**:
+  1. Import test helpers
+  2. Mock AI responses
+  3. Execute Agent tests
+  4. Verify results
+- **Postcondition**: Tests pass
+
+## 6. Deliverables
+
+### 6.1 Code Deliverables
+- soka-rails gem source code
+- Complete test suite
+- Example application
+
+### 6.2 Documentation Deliverables
+- API documentation
+- Usage guide
+- Example code
+- Upgrade guide
+
+### 6.3 Tool Deliverables
+- Rails Generators
+- RSpec test helpers
+- Development tool integration
+
+## 7. Acceptance Criteria
+
+### 7.1 Functional Acceptance
+- All functional requirements implemented and tested
+- Generators work properly
+- Test integration fully functional
+
+### 7.2 Quality Acceptance
+- Test coverage above 90%
+- Pass RuboCop checks
+- Documentation complete and accurate
+
+### 7.3 Performance Acceptance
+- Agent execution does not block main thread
+- Reasonable memory usage
+- Response time meets expectations
+
+## 8. Risk Assessment
+
+### 8.1 Technical Risks
+- **Risk**: Rails version updates may cause incompatibility
+- **Mitigation**: Build CI/CD to test multi-version compatibility
+
+### 8.2 Integration Risks
+- **Risk**: Conflicts with other Rails gems
+- **Mitigation**: Minimize dependencies, follow Rails standards
+
+### 8.3 Performance Risks
+- **Risk**: AI calls may affect application performance
+- **Mitigation**: Support asynchronous execution, optimize connection pool management
+
+## 9. Timeline
+
+### 9.1 Development Phase
+- Week 1-2: Core integration development
+- Week 3-4: Generator development
+- Week 5-6: Test integration development
+- Week 7-8: Documentation writing and optimization
+
+### 9.2 Testing Phase
+- Week 9-10: Unit and integration testing
+- Week 11: Performance testing and optimization
+- Week 12: User acceptance testing
+
+## 10. Maintenance Plan
+
+### 10.1 Version Release
+- Follow semantic versioning
+- Regular security updates
+- Provide upgrade guides
+
+### 10.2 Support Plan
+- Provide GitHub Issues support
+- Maintain detailed changelog
+- Regular documentation updates
+
+### 10.3 Community Management
+- Build user community
+- Collect user feedback
+- Regular publication of use cases

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]