soka 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11429e43f0b571946c8e67e96b18d137b3f5228298ad28b97e0fbd20c798df62
-  data.tar.gz: 870c1fbbda1a2d2031e7210043d54d9cad3e0fcafc699c1c5d36fb99ec2bcae4
+  metadata.gz: b99b5c66b841d01fa4ac0955e3924d5057787027827bdd9794094304ad218fae
+  data.tar.gz: 4343a63fd6057865f9fd03ac7de05e3a12ca1e2ef6e8b4fe2b35e4c088e7cb1a
 SHA512:
-  metadata.gz: 849434f90de4f1fdadc31cf9df1652731bf85cfbb9e097098e644c3b779b6e7efe53bea79c98208b3333b3b654c7fab9ebc5ccc3a0540aedc65b2f1ee7d10676
-  data.tar.gz: b1f88b544efdfbc9f2883c9fee969132eb4b9efa17ccc6f38aca4940892b1b5558b7c872e890c5b8fe06178fb0aaeac2a30d023e72095fa9768482909404fcce
+  metadata.gz: 633bf8b6bece348f71a53ca68229b710cbb0437372eaac0ca8d7b3e1a83baea6f9a31ed3d4cc68267f6cafcd6bbb5aefc28327212cacbc74d1d15437c0faf5ec
+  data.tar.gz: 3c5e8939f02d9ad9804e053b57ae22227c00662a4a57d35b4685e63a980534412c81441d75a46939d94e288b122084f7f612022c95e20ed506c1162114c25d1b

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.3] - 2025-08-03
+
+### Features
+- feat: add think_in feature for multilingual reasoning (2e587f3)
+- feat: add custom instructions support for agents (95c2689)
+- feat: add think_in languages example (505ef60)
+
+### Code Refactoring
+- refactor: optimize think_in feature and improve security (4bcd026)
+- refactor: remove confidence score from result and related components (057cf93)
+- refactor: extract response parsing and result building into separate concerns (0d62388)
+
+### Tests
+- test: fix RSpec violations and restructure tests (17c1af7)
+- test: add RSpec test for think_in feature (759c113)
+- test: remove test_helpers module and update test files (2e587f3)
+
+### Documentation
+- docs: add documentation for custom instructions and multilingual thinking features (151e8e3)
+- docs: add Rails integration documentation (41815e6)
+
+### Chores
+- chore(release): add changelog extraction step for GitHub release (cbb65d8)
+- chore: add .rspec_status to gitignore (0a0ebb3)
+
 ## [0.0.2] - 2025-08-01
 
 ### Features

data/CLAUDE.md

@@ -1,201 +1,349 @@
 # Soka - Ruby ReAct Agent Framework
 
-## Project Overview
+## 🎯 What is Soka?
 
-Soka is a Ruby AI Agent framework based on the ReAct (Reasoning and Acting) pattern. It supports multiple AI providers (Gemini Studio, OpenAI, Anthropic) and provides an object-oriented tool system and intelligent memory management.
+Soka is a Ruby framework for building AI agents using the ReAct (Reasoning and Acting) pattern. It enables your Ruby applications to leverage AI capabilities through a clean, object-oriented interface.
 
-## Core Architecture
+### Key Features
+- **Multi-Provider Support**: Works with Gemini, OpenAI, and Anthropic out of the box
+- **ReAct Pattern**: Implements structured reasoning with Thought → Action → Observation → Final Answer flow
+- **Tool System**: Define custom tools that agents can use to interact with your application
+- **Memory Management**: Built-in conversation and thought process tracking
+- **Minimal Dependencies**: Only requires `faraday` and `zeitwerk` - no heavy frameworks
+
+## 🚀 Quick Start
+
+```ruby
+class MyAgent < Soka::Agent
+  provider :gemini
+  model 'gemini-2.5-flash-lite'
+
+  tool :calculator, 'Performs math calculations' do
+    def call(expression:)
+      # Your tool logic here
+    end
+  end
+end
+
+agent = MyAgent.new
+result = agent.run("Calculate 123 * 456")
+puts result.final_answer
+```
+
+## 📁 Project Structure
 
-### Directory Structure
 ```
 soka/
-├── lib/
-│   ├── soka.rb                    # Main entry point with Zeitwerk autoloading
-│   └── soka/
-│       ├── agent.rb               # Agent base class with DSL and execution logic
-│       ├── agent_tool.rb          # Tool base class with parameter validation
-│       ├── agent_tools/
-│       │   └── params_validator.rb # Parameter validation module
-│       ├── agents/                # Agent feature modules
-│       │   ├── dsl_methods.rb     # DSL method definitions
-│       │   ├── hook_manager.rb    # Lifecycle hook management
-│       │   ├── llm_builder.rb     # LLM instance construction
-│       │   ├── retry_handler.rb   # Retry mechanism
-│       │   └── tool_builder.rb    # Tool construction and management
-│       ├── configuration.rb       # Global configuration system
-│       ├── llm.rb                 # LLM unified interface layer
-│       ├── llms/                  # LLM provider implementations
-│       │   ├── base.rb           # LLM base class
-│       │   ├── concerns/         # Shared functionality modules
-│       │   │   ├── response_parser.rb    # Response parsing
-│       │   │   └── streaming_handler.rb  # Stream processing
-│       │   ├── gemini.rb         # Google Gemini implementation
-│       │   ├── openai.rb         # OpenAI implementation
-│       │   └── anthropic.rb      # Anthropic implementation
-│       ├── engines/              # Reasoning engines
-│       │   ├── base.rb          # Engine base class
-│       │   ├── concerns/        # Engine shared modules
-│       │   │   ├── prompt_template.rb     # Prompt templates
-│       │   │   └── response_processor.rb  # Response processing
-│       │   ├── react.rb         # ReAct reasoning engine
-│       │   └── reasoning_context.rb # Reasoning context management
-│       ├── memory.rb             # Conversation memory management
-│       ├── thoughts_memory.rb    # Thought process memory
-│       ├── result.rb             # Result object encapsulation
-│       ├── test_helpers.rb       # RSpec test helpers
-│       └── version.rb            # Version definition
-├── examples/
-│   ├── 1_basic.rb               # Basic usage example
-│   ├── 2_event_handling.rb      # Event handling example
-│   ├── 3_memory.rb              # Memory usage example
-│   ├── 4_hooks.rb               # Lifecycle hooks example
-│   ├── 5_error_handling.rb      # Error handling example
-│   ├── 6_retry.rb               # Retry mechanism example
-│   ├── 7_tool_conditional.rb    # Conditional tools example
-│   └── 8_multi_provider.rb      # Multi-provider example
-├── spec/                         # RSpec tests
-└── test_soka.rb                 # Quick test script
+├── lib/soka/
+│   ├── agent.rb                 # Core Agent class with DSL
+│   ├── agent_tool.rb            # Base class for tools
+│   ├── agents/                  # Agent components (modular design)
+│   │   ├── dsl_methods.rb       # DSL for agent configuration
+│   │   ├── hook_manager.rb      # Lifecycle hooks
+│   │   ├── llm_builder.rb       # LLM instance creation
+│   │   ├── retry_handler.rb     # Retry logic
+│   │   └── tool_builder.rb      # Tool management
+│   ├── engines/                 # Reasoning engines
+│   │   ├── react.rb             # ReAct implementation
+│   │   └── concerns/            # Shared engine modules
+│   ├── llms/                    # AI provider integrations
+│   │   ├── gemini.rb            # Google Gemini
+│   │   ├── openai.rb            # OpenAI GPT
+│   │   └── anthropic.rb         # Anthropic Claude
+│   └── memory.rb                # Conversation memory
+├── examples/                    # Working examples (1-10)
+└── spec/                        # RSpec tests
+```
+
+## 🔧 Core Components
+
+### Agent System
+The heart of Soka - defines agents with a simple DSL:
+
+```ruby
+class MyAgent < Soka::Agent
+  provider :gemini              # Choose AI provider
+  model 'gemini-2.5-flash-lite' # Specify model
+  max_iterations 10              # Limit reasoning cycles
+  timeout 30                     # Request timeout
+
+  # Define tools
+  tool :my_tool, 'Description' do
+    def call(param:)
+      # Tool implementation
+    end
+  end
+
+  # Lifecycle hooks
+  before_action { |task| log("Starting: #{task}") }
+  after_action { |result| log("Completed: #{result}") }
+  on_error { |error| handle_error(error) }
+end
+```
+
+### Tool System
+Create reusable tools with parameter validation:
+
+```ruby
+class WeatherTool < Soka::AgentTool
+  desc 'Get weather information'
+
+  params do
+    requires :location, String, desc: 'City name'
+    optional :units, String, inclusion: %w[celsius fahrenheit]
+  end
+
+  def call(location:, units: 'celsius')
+    # Fetch weather data
+    "Weather in #{location}: 22°C, Sunny"
+  end
+end
+```
+
+### ReAct Engine
+Implements the reasoning pattern with structured tags:
+
+1. **Thought**: Agent thinks about the task
+2. **Action**: Decides which tool to use
+3. **Observation**: Receives tool results
+4. **Final Answer**: Provides the solution
+
+The engine automatically:
+- Manages iteration loops
+- Calculates confidence scores
+- Handles tool execution
+- Tracks reasoning context
+
+### Memory System
+Two types of memory for different purposes:
+
+- **Conversation Memory**: Tracks dialogue history
+- **Thoughts Memory**: Records complete reasoning processes
+
+```ruby
+# Initialize with existing conversation
+memory = Soka::Memory.new
+memory.add(role: 'user', content: 'Previous question')
+memory.add(role: 'assistant', content: 'Previous answer')
+
+agent = MyAgent.new(memory: memory)
+```
+
+## 🎨 Advanced Features
+
+### Custom Instructions
+Change your agent's personality and response style:
+
+```ruby
+class FriendlyAgent < Soka::Agent
+  provider :gemini
+
+  # Define personality at class level
+  instructions <<~PROMPT
+    You are a friendly, helpful assistant.
+    Use casual language and be encouraging.
+    Add emojis when appropriate.
+  PROMPT
+end
+
+# Or override at runtime
+agent = FriendlyAgent.new(
+  instructions: 'Be more formal and professional.'
+)
+```
+
+### Multilingual Thinking (Think In)
+Optimize reasoning for specific languages:
+
+```ruby
+class GlobalAgent < Soka::Agent
+  provider :gemini
+
+  # Set default thinking language
+  think_in 'zh-TW'  # Think in Traditional Chinese
+end
+
+# Or set dynamically
+agent = GlobalAgent.new(think_in: 'ja-JP')
+result = agent.run("Help me with this task")
+```
+
+**Key Points:**
+- Thinking language affects internal reasoning only
+- Responses adapt to user's input language
+- Default is English (`'en'`)
+- No automatic language detection (explicit setting required)
+
+### Conditional Tools
+Load tools based on conditions:
+
+```ruby
+class SmartAgent < Soka::Agent
+  # Only in development
+  tool DebugTool, if: -> { ENV['RAILS_ENV'] == 'development' }
+
+  # Based on user permissions
+  tool AdminTool, if: -> { current_user.admin? }
+
+  # Feature flags
+  tool BetaFeature, if: -> { feature_enabled?(:beta) }
+end
 ```
 
-## Core Component Descriptions
-
-### 1. Agent System (`agent.rb`)
-- Provides DSL for defining AI settings, tool registration, and retry mechanisms
-- Supports conditional tool loading (`if:` option)
-- Built-in lifecycle hooks (before_action, after_action, on_error)
-- Uses `times` loop instead of `loop` for iteration control
-- Modular design: functionality separated into concern modules
-  - `DSLMethods`: DSL method definitions
-  - `HookManager`: Lifecycle hook management
-  - `LLMBuilder`: LLM instance construction
-  - `RetryHandler`: Retry handling
-  - `ToolBuilder`: Tool construction and management
-
-### 2. Tool System (`agent_tool.rb`)
-- Grape API-like parameter definition system
-- Built-in parameter validation (presence, length, inclusion, format)
-- Supports required and optional parameters
-- Auto-generates tool description schemas
-
-### 3. ReAct Engine (`engines/react.rb`)
-- Implements tagged ReAct flow: `<Thought>`, `<Action>`, `<Observation>`, `<Final_Answer>`
-- Uses Struct instead of OpenStruct (Rubocop compliant)
-- Automatically manages conversation context and tool execution
-- Calculates confidence scores (based on iteration count)
-- Uses `ReasoningContext` to manage reasoning state
-- Shared modules:
-  - `PromptTemplate`: Prompt template management
-  - `ResponseProcessor`: Response processing logic
-
-### 4. LLM Integration
-- **LLM Unified Interface Layer (`llm.rb`)**
-  - Provides unified API interface
-  - Supports streaming and non-streaming modes
-  - Auto-routes to corresponding provider implementation
-- **LLM Provider Implementations (`llms/`)**
-  - Gemini: Uses Google Generative AI API, defaults to `gemini-2.5-flash-lite`
-  - OpenAI: Supports GPT-4 series, includes streaming capabilities
-  - Anthropic: Supports Claude 3 series, handles system prompts
-  - Shared modules:
-    - `ResponseParser`: Unified response parsing
-    - `StreamingHandler`: Stream response handling
-- Built-in error handling and retry mechanisms
-
-### 5. Memory System
-- `Memory`: Manages conversation history
-- `ThoughtsMemory`: Records complete ReAct thought processes
-- Supports initial memory loading
-
-## Design Decisions
-
-### 1. Using Zeitwerk Autoloading
-- Simplifies require management
-- Supports hot reloading (development environment)
-- Automatically handles namespaces
-
-### 2. Dry-rb Ecosystem Integration
-- `dry-validation`: Powerful parameter validation
-- `dry-struct`: Type-safe data structures
-- `dry-types`: Type definitions and coercion
-
-### 3. Configuration System Design
-- Supports global configuration and instance-level overrides
-- Block-style DSL provides intuitive configuration
-- Fallback mechanism ensures service availability
-- Configuration includes AI providers and performance settings
-
-### 4. Error Handling Strategy
-- Layered error class inheritance
-- Tool execution errors don't interrupt entire flow
-- Configurable retry mechanism (exponential backoff)
-
-## Testing Strategy
-
-### Unit Tests
-- Using RSpec 3
-- Provides `TestHelpers` module for mocking AI responses
-- Supports tool mocking and error simulation
-
-### Integration Tests
-- `test_soka.rb`: Quick test without real API keys
-- `examples/1_basic.rb`: Actual API integration test
-
-## Development Guide
-
-### Adding New AI Provider
-1. Create new file in `lib/soka/llms/`
+## 🛠 Development Guide
+
+### Creating a New AI Provider
+
+1. Create file in `lib/soka/llms/your_provider.rb`
 2. Inherit from `Soka::LLMs::Base`
 3. Implement required methods:
-   - `default_model`
-   - `base_url`
-   - `chat(messages, **params)`
-   - `parse_response(response)`
-4. Add new provider to `LLM#create_provider` method
-
-### Adding New Tools
-1. Inherit from `Soka::AgentTool`
-2. Use `desc` to define description
-3. Use `params` block to define parameters
-4. Implement `call` method
-
-### Custom Engines
-1. Inherit from `Soka::Engines::Base`
-2. Implement `reason(task, &block)` method
-3. Use `emit_event` to send events
-4. Return result object inheriting from Struct
-5. Can use concerns modules to share functionality
-
-## Rubocop Compatibility
-- Complies with Ruby 3.0+ standards
-- Major issues fixed:
-  - Using `Struct` instead of `OpenStruct`
-  - Using `format` instead of `String#%`
-  - Using `times` instead of `loop`
-  - Removed unused MODELS constants
-
-## Performance Considerations
-- Maximum iteration limit (default 10)
-- Request timeout settings (default 30 seconds)
-- Memory usage optimization (lazy loading)
-
-## Security
-- API keys managed through environment variables
-- Input parameter validation
-- Error messages don't leak sensitive information
-- Supports `.env` files (not version controlled)
-- Unified error handling hierarchy
-
-## Future Extensions
-- [ ] Support more LLM providers (Cohere, Hugging Face)
-- [ ] Implement caching mechanism
-- [ ] Support vector database integration
-- [ ] Add more built-in tools
-- [ ] WebSocket support for real-time conversations
-- [ ] Support functional tools (use methods directly as tools)
-
-## Development Standards
-
-### Code Quality Checks
+
+```ruby
+module Soka
+  module LLMs
+    class YourProvider < Base
+      def default_model
+        'your-default-model'
+      end
+
+      def base_url
+        'https://api.yourprovider.com'
+      end
+
+      def chat(messages, **params)
+        # Make API request
+        # Return response
+      end
+
+      def parse_response(response)
+        # Parse API response
+        # Return standardized format
+      end
+    end
+  end
+end
+```
+
+### Creating Custom Engines
+
+```ruby
+class MyEngine < Soka::Engines::Base
+  def reason(task, &block)
+    # Implement your reasoning logic
+    emit_event(:thought, "Thinking about: #{task}")
+
+    # Process and return result
+    MyResult.new(
+      input: task,
+      output: "Processed result",
+      status: :success
+    )
+  end
+end
+```
+
+## ⚙️ Configuration
+
+### Global Configuration
+
+```ruby
+Soka.setup do |config|
+  config.ai do |ai|
+    ai.provider = :gemini
+    ai.model = 'gemini-2.5-flash-lite'
+    ai.api_key = ENV['GEMINI_API_KEY']
+  end
+
+  config.performance do |perf|
+    perf.max_iterations = 10
+    perf.timeout = 30
+  end
+end
+```
+
+### Environment Variables
+
+```bash
+# .env file
+GEMINI_API_KEY=your_api_key
+OPENAI_API_KEY=your_api_key
+ANTHROPIC_API_KEY=your_api_key
+```
+
+## 📊 Performance & Security
+
+### Performance Tips
+- Set appropriate `max_iterations` to prevent infinite loops
+- Use `timeout` to handle slow API responses
+- Implement caching for frequently used tools
+- Consider memory limits for long conversations
+
+### Security Best Practices
+- Never commit API keys to version control
+- Use environment variables for sensitive data
+- Validate all tool inputs
+- Sanitize tool outputs before returning
+- Implement rate limiting for production use
+
+## 🧪 Testing
+
+### Unit Testing
+
+```ruby
+RSpec.describe MyAgent do
+  let(:agent) { described_class.new }
+
+  it 'processes tasks correctly' do
+    result = agent.run('Test task')
+    expect(result).to be_successful
+    expect(result.final_answer).to include('expected')
+  end
+end
+```
+
+### Mocking AI Responses
+
+```ruby
+allow(agent).to receive(:llm).and_return(mock_llm)
+allow(mock_llm).to receive(:chat).and_return(
+  double(content: '<Thought>Test</Thought><Final_Answer>Done</Final_Answer>')
+)
+```
+
+## 📚 Examples
+
+The `examples/` directory contains 10 comprehensive examples:
+
+1. **Basic Usage** - Simple agent setup and execution
+2. **Event Handling** - Responding to agent events
+3. **Memory Management** - Using conversation memory
+4. **Lifecycle Hooks** - before/after/error handling
+5. **Error Handling** - Graceful error management
+6. **Retry Logic** - Automatic retry configuration
+7. **Conditional Tools** - Dynamic tool loading
+8. **Multi-Provider** - Switching between AI providers
+9. **Custom Instructions** - Personality customization
+10. **Multilingual Thinking** - Language-specific reasoning
+
+## 🔄 Future Roadmap
+
+- [ ] Additional LLM providers (Cohere, Hugging Face)
+- [ ] Built-in caching mechanism
+- [ ] Vector database integration for RAG
+- [ ] More built-in tools (web search, file operations)
+- [ ] WebSocket support for real-time streaming
+- [ ] Direct method-as-tool support
+
+## 📖 Development Standards
+
+### Code Quality
+- Run `bundle exec rubocop` before committing
+- Ensure all tests pass with `bundle exec rspec`
+- Follow Ruby style guide and conventions
+- Keep methods small and focused
+- Write clear, self-documenting code
+
+### Code Quality Checks (Important for AI Assistants)
 - **When adjusting code, the final step is to run Rubocop to check if the code complies with rules**
 - **When Rubocop has any issues, fix them until all rules are satisfied**
 - **When adjusting code, the final step is to perform a code review to avoid redundant design and ensure code conciseness**
@@ -210,4 +358,15 @@ soka/
   - Include method purpose descriptions
   - Explain parameter types and purposes
   - Explain return value types and meanings
-  - For complex logic, add implementation detail explanations
+  - For complex logic, add implementation detail explanations
+- Include usage examples in comments
+- Document all public APIs
+- Keep README and CLAUDE.md updated
+
+## 🤝 Contributing
+
+[Contributing Guidelines]
+
+---
+
+*Built with ❤️ using Ruby and AI*