soka-rails 0.0.1.beta4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: add1e499afcd752fc5052b095add7a9faa0f630e020cdea38a92336d6aac240e
+  data.tar.gz: 73bcb0fd1b70cc2ebc48c39293daa6ba641c8079046ed20846f3ba8ec8485846
+SHA512:
+  metadata.gz: 0ba025e3ad0bf9176098284c2fa7d183c25d817108170f47b50e52edf2528b6c738c92d578ce736c984d8eae97fd405478ec0f96aabe736f507c1d40ec505df8
+  data.tar.gz: fc8003ea01c7aeb6a24f54543fdc04c77a34afd0d04c2c80941929440c235c1333672d702a9060df5218c8b2c5ef9d9f86ff57d80382d8bee69cfac25748212f

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,367 @@
+# Omakase Ruby styling for Rails
+# inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+# Overwrite or add rules to create your own house style
+#
+# # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
+# Layout/SpaceInsideArrayLiteralBrackets:
+#   Enabled: false
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+  NewCops: enable
+
+  Exclude:
+    - 'examples/**/*'
+    - 'vendor/**/*'
+
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false
+
+Gemspec/AddRuntimeDependency: # new in 1.65
+  Enabled: true
+Gemspec/DeprecatedAttributeAssignment: # new in 1.30
+  Enabled: true
+Gemspec/DevelopmentDependencies: # new in 1.44
+  Enabled: true
+Gemspec/RequireMFA: # new in 1.23
+  Enabled: true
+Layout/LineContinuationLeadingSpace: # new in 1.31
+  Enabled: true
+Layout/LineContinuationSpacing: # new in 1.31
+  Enabled: true
+Layout/LineEndStringConcatenationIndentation: # new in 1.18
+  Enabled: true
+Layout/SpaceBeforeBrackets: # new in 1.7
+  Enabled: true
+Lint/AmbiguousAssignment: # new in 1.7
+  Enabled: true
+Lint/AmbiguousOperatorPrecedence: # new in 1.21
+  Enabled: true
+Lint/AmbiguousRange: # new in 1.19
+  Enabled: true
+Lint/ConstantOverwrittenInRescue: # new in 1.31
+  Enabled: true
+Lint/DeprecatedConstants: # new in 1.8
+  Enabled: true
+Lint/DuplicateBranch: # new in 1.3
+  Enabled: true
+Lint/DuplicateMagicComment: # new in 1.37
+  Enabled: true
+Lint/DuplicateMatchPattern: # new in 1.50
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement: # new in 1.1
+  Enabled: true
+Lint/EmptyBlock: # new in 1.1
+  Enabled: true
+Lint/EmptyClass: # new in 1.3
+  Enabled: true
+Lint/EmptyInPattern: # new in 1.16
+  Enabled: true
+Lint/IncompatibleIoSelectWithFiberScheduler: # new in 1.21
+  Enabled: true
+Lint/ItWithoutArgumentsInBlock: # new in 1.59
+  Enabled: true
+Lint/LambdaWithoutLiteralBlock: # new in 1.8
+  Enabled: true
+Lint/LiteralAssignmentInCondition: # new in 1.58
+  Enabled: true
+Lint/MixedCaseRange: # new in 1.53
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks: # new in 1.2
+  Enabled: true
+Lint/NonAtomicFileOperation: # new in 1.31
+  Enabled: true
+Lint/NumberedParameterAssignment: # new in 1.9
+  Enabled: true
+Lint/OrAssignmentToConstant: # new in 1.9
+  Enabled: true
+Lint/RedundantDirGlobSort: # new in 1.8
+  Enabled: true
+Lint/RedundantRegexpQuantifiers: # new in 1.53
+  Enabled: true
+Lint/RefinementImportMethods: # new in 1.27
+  Enabled: true
+Lint/RequireRangeParentheses: # new in 1.32
+  Enabled: true
+Lint/RequireRelativeSelfPath: # new in 1.22
+  Enabled: true
+Lint/SymbolConversion: # new in 1.9
+  Enabled: true
+Lint/ToEnumArguments: # new in 1.1
+  Enabled: true
+Lint/TripleQuotes: # new in 1.9
+  Enabled: true
+Lint/UnexpectedBlockArity: # new in 1.5
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator: # new in 1.1
+  Enabled: true
+Lint/UselessNumericOperation: # new in 1.66
+  Enabled: true
+Lint/UselessRescue: # new in 1.43
+  Enabled: true
+Lint/UselessRuby2Keywords: # new in 1.23
+  Enabled: true
+Metrics/CollectionLiteralLength: # new in 1.47
+  Enabled: true
+Naming/BlockForwarding: # new in 1.24
+  Enabled: true
+Security/CompoundHash: # new in 1.28
+  Enabled: true
+Security/IoMethods: # new in 1.22
+  Enabled: true
+Style/ArgumentsForwarding: # new in 1.1
+  Enabled: true
+Style/ArrayIntersect: # new in 1.40
+  Enabled: true
+Style/CollectionCompact: # new in 1.2
+  Enabled: true
+Style/ComparableClamp: # new in 1.44
+  Enabled: true
+Style/ConcatArrayLiterals: # new in 1.41
+  Enabled: true
+Style/DataInheritance: # new in 1.49
+  Enabled: true
+Style/DirEmpty: # new in 1.48
+  Enabled: true
+Style/DocumentDynamicEvalDefinition: # new in 1.1
+  Enabled: true
+Style/EmptyHeredoc: # new in 1.32
+  Enabled: true
+Style/EndlessMethod: # new in 1.8
+  Enabled: true
+Style/EnvHome: # new in 1.29
+  Enabled: true
+Style/ExactRegexpMatch: # new in 1.51
+  Enabled: true
+Style/FetchEnvVar: # new in 1.28
+  Enabled: true
+Style/FileEmpty: # new in 1.48
+  Enabled: true
+Style/FileRead: # new in 1.24
+  Enabled: true
+Style/FileWrite: # new in 1.24
+  Enabled: true
+Style/HashConversion: # new in 1.10
+  Enabled: true
+Style/HashExcept: # new in 1.7
+  Enabled: true
+Style/IfWithBooleanLiteralBranches: # new in 1.9
+  Enabled: true
+Style/InPatternThen: # new in 1.16
+  Enabled: true
+Style/MagicCommentFormat: # new in 1.35
+  Enabled: true
+Style/MapCompactWithConditionalBlock: # new in 1.30
+  Enabled: true
+Style/MapIntoArray: # new in 1.63
+  Enabled: true
+Style/MapToHash: # new in 1.24
+  Enabled: true
+Style/MapToSet: # new in 1.42
+  Enabled: true
+Style/MinMaxComparison: # new in 1.42
+  Enabled: true
+Style/MultilineInPatternThen: # new in 1.16
+  Enabled: true
+Style/NegatedIfElseCondition: # new in 1.2
+  Enabled: true
+Style/NestedFileDirname: # new in 1.26
+  Enabled: true
+Style/NilLambda: # new in 1.3
+  Enabled: true
+Style/NumberedParameters: # new in 1.22
+  Enabled: true
+Style/NumberedParametersLimit: # new in 1.22
+  Enabled: true
+Style/ObjectThen: # new in 1.28
+  Enabled: true
+Style/OperatorMethodCall: # new in 1.37
+  Enabled: true
+Style/QuotedSymbols: # new in 1.16
+  Enabled: true
+Style/RedundantArgument: # new in 1.4
+  Enabled: true
+Style/RedundantArrayConstructor: # new in 1.52
+  Enabled: true
+Style/RedundantConstantBase: # new in 1.40
+  Enabled: true
+Style/RedundantCurrentDirectoryInPath: # new in 1.53
+  Enabled: true
+Style/RedundantDoubleSplatHashBraces: # new in 1.41
+  Enabled: true
+Style/RedundantEach: # new in 1.38
+  Enabled: true
+Style/RedundantFilterChain: # new in 1.52
+  Enabled: true
+Style/RedundantHeredocDelimiterQuotes: # new in 1.45
+  Enabled: true
+Style/RedundantInitialize: # new in 1.27
+  Enabled: true
+Style/RedundantInterpolationUnfreeze: # new in 1.66
+  Enabled: true
+Style/RedundantLineContinuation: # new in 1.49
+  Enabled: true
+Style/RedundantRegexpArgument: # new in 1.53
+  Enabled: true
+Style/RedundantRegexpConstructor: # new in 1.52
+  Enabled: true
+Style/RedundantSelfAssignmentBranch: # new in 1.19
+  Enabled: true
+Style/RedundantStringEscape: # new in 1.37
+  Enabled: true
+Style/ReturnNilInPredicateMethodDefinition: # new in 1.53
+  Enabled: true
+Style/SelectByRegexp: # new in 1.22
+  Enabled: true
+Style/SendWithLiteralMethodName: # new in 1.64
+  Enabled: true
+Style/SingleLineDoEndBlock: # new in 1.57
+  Enabled: true
+Style/StringChars: # new in 1.12
+  Enabled: true
+Style/SuperArguments: # new in 1.64
+  Enabled: true
+Style/SuperWithArgsParentheses: # new in 1.58
+  Enabled: true
+Style/SwapValues: # new in 1.1
+  Enabled: true
+Style/YAMLFileRead: # new in 1.53
+  Enabled: true
+Lint/DuplicateSetElement: # new in 1.67
+  Enabled: true
+Lint/UnescapedBracketInRegexp: # new in 1.68
+  Enabled: true
+Style/AmbiguousEndlessMethodDefinition: # new in 1.68
+  Enabled: true
+Style/BitwisePredicate: # new in 1.68
+  Enabled: true
+Style/CombinableDefined: # new in 1.68
+  Enabled: true
+Style/KeywordArgumentsMerging: # new in 1.68
+  Enabled: true
+Style/SafeNavigationChainLength: # new in 1.68
+  Enabled: true
+Lint/HashNewWithKeywordArgumentsAsDefault: # new in 1.69
+  Enabled: true
+Lint/NumericOperationWithConstantResult: # new in 1.69
+  Enabled: true
+Lint/UselessDefined: # new in 1.69
+  Enabled: true
+Style/DigChain: # new in 1.69
+  Enabled: true
+Style/FileNull: # new in 1.69
+  Enabled: true
+Style/FileTouch: # new in 1.69
+  Enabled: true
+Lint/ConstantReassignment: # new in 1.70
+  Enabled: true
+Lint/SharedMutableDefault: # new in 1.70
+  Enabled: true
+Style/ItAssignment: # new in 1.70
+  Enabled: true
+Lint/ArrayLiteralInRegexp: # new in 1.71
+  Enabled: true
+Style/HashSlice: # new in 1.71
+  Enabled: true
+Lint/CopDirectiveSyntax: # new in 1.72
+  Enabled: true
+Lint/RedundantTypeConversion: # new in 1.72
+  Enabled: true
+Lint/SuppressedExceptionInNumberConversion: # new in 1.72
+  Enabled: true
+Lint/UselessConstantScoping: # new in 1.72
+  Enabled: true
+Style/RedundantFormat: # new in 1.72
+  Enabled: true
+Style/ComparableBetween: # new in 1.74
+  Enabled: true
+Style/HashFetchChain: # new in 1.75
+  Enabled: true
+Style/ItBlockParameter: # new in 1.75
+  Enabled: true
+Lint/UselessDefaultValueArgument: # new in 1.76
+  Enabled: true
+Lint/UselessOr: # new in 1.76
+  Enabled: true
+Naming/PredicateMethod: # new in 1.76
+  Enabled: true
+Style/EmptyStringInsideInterpolation: # new in 1.76
+  Enabled: true
+Style/RedundantArrayFlatten: # new in 1.76
+  Enabled: true
+Gemspec/AttributeAssignment: # new in 1.77
+  Enabled: true
+Style/CollectionQuerying: # new in 1.77
+  Enabled: true
+Layout/EmptyLinesAfterModuleInclusion: # new in 1.79
+  Enabled: true
+Style/OpenStructUse: # new in 1.23
+  Enabled: true
+# RSpecRails cops have been moved to a separate gem
+# If you need Rails-specific RSpec cops, add rubocop-rspec_rails to your Gemfile
+RSpec/BeEmpty: # new in 2.20
+  Enabled: true
+RSpec/BeEq: # new in 2.9.0
+  Enabled: true
+RSpec/BeNil: # new in 2.9.0
+  Enabled: true
+RSpec/ChangeByZero: # new in 2.11
+  Enabled: true
+RSpec/ContainExactly: # new in 2.19
+  Enabled: true
+RSpec/DuplicatedMetadata: # new in 2.16
+  Enabled: true
+RSpec/EmptyMetadata: # new in 2.24
+  Enabled: true
+RSpec/EmptyOutput: # new in 2.29
+  Enabled: true
+RSpec/Eq: # new in 2.24
+  Enabled: true
+RSpec/ExcessiveDocstringSpacing: # new in 2.5
+  Enabled: true
+RSpec/ExpectInLet: # new in 2.30
+  Enabled: true
+RSpec/IdenticalEqualityAssertion: # new in 2.4
+  Enabled: true
+RSpec/IndexedLet: # new in 2.20
+  Enabled: true
+RSpec/IsExpectedSpecify: # new in 2.27
+  Enabled: true
+RSpec/MatchArray: # new in 2.19
+  Enabled: true
+RSpec/MetadataStyle: # new in 2.24
+  Enabled: true
+RSpec/NoExpectationExample: # new in 2.13
+  Enabled: true
+RSpec/PendingWithoutReason: # new in 2.16
+  Enabled: true
+RSpec/ReceiveMessages: # new in 2.23
+  Enabled: true
+RSpec/RedundantAround: # new in 2.19
+  Enabled: true
+RSpec/RedundantPredicateMatcher: # new in 2.26
+  Enabled: true
+RSpec/RemoveConst: # new in 2.26
+  Enabled: true
+RSpec/RepeatedSubjectCall: # new in 2.27
+  Enabled: true
+RSpec/SkipBlockInsideExample: # new in 2.19
+  Enabled: true
+RSpec/SortMetadata: # new in 2.14
+  Enabled: true
+RSpec/SpecFilePathFormat: # new in 2.24
+  Enabled: false
+RSpec/SpecFilePathSuffix: # new in 2.24
+  Enabled: true
+RSpec/SubjectDeclaration: # new in 2.5
+  Enabled: true
+RSpec/UndescriptiveLiteralsDescription: # new in 2.29
+  Enabled: true
+RSpec/VerifiedDoubleReference: # new in 2.10.0
+  Enabled: true
+# Capybara and FactoryBot cops have been moved to separate gems
+# If you need them, add rubocop-capybara and rubocop-factory_bot to your Gemfile

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1.beta4] - 2025-08-01
+
+### Fixed
+- Correct version constant namespace in release workflow
+
+## [0.0.1.beta3] - 2025-08-01
+
+### Fixed
+- Corrected version file path in release workflow
+
+## [0.0.1.beta2] - 2025-08-01
+
+### Added
+- GitHub Actions workflows for CI/CD
+
+### Changed
+- Initial implementation improvements and refinements
+
+## [0.0.1.beta1] - 2025-07-29
+
+### Added
+- Initial release of Soka Rails
+- Rails integration with automatic loading of agents and tools from `app/soka`
+- Configuration system with DSL support
+- ApplicationAgent base class with Rails hooks integration
+- ApplicationTool base class with helper methods
+- RailsInfoTool for querying Rails application information
+- Rails generators:
+  - `soka:install` - Initial setup generator
+  - `soka:agent` - Agent generator
+  - `soka:tool` - Tool generator
+- RSpec test helpers and integration
+- Comprehensive error handling
+- Full documentation and examples

data/CLAUDE.md

@@ -0,0 +1,243 @@
+# Soka Rails - Rails Integration for Soka AI Agent Framework
+
+## Project Overview
+
+Soka Rails is a Ruby on Rails integration package for the Soka AI Agent Framework. It provides seamless integration between Soka's ReAct-based AI agents and Rails applications, following Rails conventions and best practices for easy adoption by Rails developers.
+
+## Core Architecture
+
+### Directory Structure
+```
+soka-rails/
+├── app/
+│   └── soka/
+│       ├── agents/
+│       │   └── application_agent.rb       # Rails-specific base agent class
+│       └── tools/
+│           ├── application_tool.rb        # Rails-specific base tool class
+│           └── rails_info_tool.rb         # Built-in Rails info tool
+├── lib/
+│   ├── soka_rails.rb                     # Main entry point
+│   ├── soka/
+│   │   └── rails/
+│   │       ├── configuration.rb           # Rails-specific configuration
+│   │       ├── errors.rb                  # Rails-specific error classes
+│   │       ├── railtie.rb                 # Rails integration engine
+│   │       ├── rspec.rb                   # RSpec test helpers
+│   │       ├── test_helpers.rb            # Testing utilities
+│   │       └── version.rb                 # Version information
+│   └── generators/
+│       └── soka/
+│           ├── install/                   # Install generator
+│           │   ├── install_generator.rb
+│           │   └── templates/
+│           │       ├── application_agent.rb
+│           │       ├── application_tool.rb
+│           │       ├── rails_info_tool.rb
+│           │       └── soka.rb           # Initializer template
+│           ├── agent/                     # Agent generator
+│           │   ├── agent_generator.rb
+│           │   └── templates/
+│           │       ├── agent.rb.tt
+│           │       └── agent_spec.rb.tt
+│           └── tool/                      # Tool generator
+│               ├── tool_generator.rb
+│               └── templates/
+│                   ├── tool.rb.tt
+│                   └── tool_spec.rb.tt
+├── spec/                                  # Test suite
+└── soka-rails.gemspec                     # Gem specification
+```
+
+## Core Component Descriptions
+
+### 1. Rails Integration (`lib/soka/rails/railtie.rb`)
+- Integrates with Rails autoloading system
+- Adds `app/soka` to Rails autoload paths
+- Configures Rails-specific logging and error handling
+- Manages Rails lifecycle hooks
+
+### 2. ApplicationAgent (`app/soka/agents/application_agent.rb`)
+- Inherits from `Soka::Agent`
+- Provides Rails-specific defaults and configurations
+- Integrates with Rails error tracking (Rollbar, Sentry, etc.)
+- Supports Rails logging system
+- Includes Rails-specific lifecycle hooks
+
+### 3. ApplicationTool (`app/soka/tools/application_tool.rb`)
+- Inherits from `Soka::AgentTool`
+- Provides Rails-specific helper methods
+- Standardized error handling for Rails applications
+- Integration with Rails I18n for messages
+
+### 4. RailsInfoTool (`app/soka/tools/rails_info_tool.rb`)
+- Built-in tool for accessing Rails application information
+- Supports querying:
+  - Routes information
+  - Rails and Ruby versions
+  - Environment details
+  - Safe configuration values
+- Security-conscious implementation (no sensitive data exposure)
+
+### 5. Configuration System (`lib/soka/rails/configuration.rb`)
+- Rails-style configuration using initializers
+- Environment-specific configurations
+- Supports `Rails.env` based settings
+- ENV variable management with `ENV.fetch`
+
+### 6. Generators
+- **Install Generator**: Sets up initial structure
+- **Agent Generator**: Creates new agent classes with Rails conventions
+- **Tool Generator**: Creates new tool classes with parameter definitions
+- All generators follow Rails naming conventions and file structure
+
+## Design Decisions
+
+### 1. Following Rails Conventions
+- Uses `app/soka` directory for application-specific code
+- Follows Rails naming conventions (e.g., `CustomerSupportAgent`)
+- Integrates with Rails autoloading via Zeitwerk
+- Uses Rails generators for scaffolding
+
+### 2. Rails-Specific Features
+- Session-based memory storage
+- Integration with Rails authentication systems
+- Support for ActionController::Live streaming
+- Rails error tracking integration
+
+### 3. Configuration Philosophy
+- Environment-based configuration (development, test, production)
+- Uses Rails initializer pattern
+- Supports Rails credentials for API keys
+- Follows 12-factor app principles
+
+### 4. Testing Integration
+- Full RSpec integration with custom matchers
+- Test helpers for mocking AI responses
+- Support for Rails test fixtures
+- Integration with Rails testing conventions
+
+## Testing Strategy
+
+### RSpec Integration
+- Custom RSpec configuration in `lib/soka/rails/rspec.rb`
+- Test helpers for agent and tool testing
+- Mock AI response capabilities
+- Support for Rails-specific testing patterns
+
+### Test Coverage
+- Unit tests for all components
+- Integration tests with Rails applications
+- Generator tests
+- Performance tests for async operations
+
+## Development Guide
+
+### Adding New Agents
+1. Use generator: `rails generate soka:agent agent_name`
+2. Inherit from `ApplicationAgent`
+3. Register required tools
+4. Configure AI settings if needed
+5. Implement Rails-specific hooks
+
+### Adding New Tools
+1. Use generator: `rails generate soka:tool tool_name [param:type ...]`
+   - Example: `rails generate soka:tool weather_api location:string units:string`
+2. Inherit from `ApplicationTool`
+3. Define parameters using DSL (auto-generated if params provided)
+4. Implement `call` method
+5. Handle Rails-specific concerns (ActiveRecord, etc.)
+
+### Rails Integration Points
+- **Controllers**: Direct agent usage in actions
+- **Background Jobs**: Agent usage in ActiveJob
+- **ActionCable**: Real-time agent interactions
+- **ViewComponents**: Agent-powered components
+
+## Rails-Specific Considerations
+
+### Performance
+- Non-blocking execution in controllers
+- Background job integration for long-running tasks
+- Connection pooling for AI providers
+- Rails cache integration for responses
+
+### Security
+- API keys in Rails credentials
+- CSRF protection for agent endpoints
+- Authentication integration
+- Rate limiting support
+
+### Monitoring
+- Rails logger integration
+- Performance monitoring (NewRelic, DataDog)
+- Error tracking (Rollbar, Sentry)
+- Custom Rails instrumentation
+
+## Development Standards
+
+### Code Quality
+- **Run RuboCop before committing code**
+- **Follow Rails best practices and conventions**
+- **Ensure all tests pass before merging**
+- **Maintain high test coverage (>90%)**
+
+### Documentation
+- **Use YARD format for method documentation**
+- **Include usage examples in comments**
+- **Document Rails-specific behaviors**
+- **Keep README and guides updated**
+
+### Rails Compatibility
+- Supports Rails 7.0+
+- Ruby 3.4+ required
+- Compatible with major Rails gems
+- Follows Rails upgrade guides
+
+## Future Enhancements
+- [ ] ActiveRecord integration for agent/tool persistence
+- [ ] ActionMailer integration for AI-powered emails
+- [ ] ViewComponent integration for AI-powered components
+- [ ] Hotwire/Turbo integration for real-time updates
+- [ ] Rails Admin interface for agent management
+- [ ] GraphQL integration for agent APIs
+
+## Dependencies
+- Rails >= 7.0
+- Soka >= 0.0.1
+- Ruby >= 3.4
+- Zeitwerk for autoloading
+
+## Common Patterns
+
+### Controller Usage
+```ruby
+class ConversationsController < ApplicationController
+  def create
+    agent = CustomerSupportAgent.new
+    result = agent.run(params[:message])
+    render json: { answer: result.final_answer }
+  end
+end
+```
+
+### Background Job Usage
+```ruby
+class AgentJob < ApplicationJob
+  def perform(message)
+    agent = ProcessingAgent.new
+    agent.run(message)
+  end
+end
+```
+
+### Testing Pattern
+```ruby
+RSpec.describe WeatherAgent, type: :agent do
+  it "responds to weather queries" do
+    mock_ai_response(final_answer: "Sunny, 25°C")
+    result = agent.run("What's the weather?")
+    expect(result).to be_successful
+  end
+end
+```