soka 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb5c0a25160f948f0514c8297166706adef7b1d1921854e95cedef2466b561f0
-  data.tar.gz: afe45e214ea6077f81d3d21a56474213db820124d1bc46652a960d6a8c524e59
+  metadata.gz: 07c69024bab6c364c20dfdea14e2a9b2dddc6248c6c3c741c1d917fdad0e31b2
+  data.tar.gz: f89d4e6f71c833f340dda97dbb281d21b7ff586aa8df3de0ebcda419dc947576
 SHA512:
-  metadata.gz: 687b999469d40246dd5c224ec433d634089b81ee8f46d3ba85b6fa469317f2e1d1b65fba7e196905bee7060f41ab73423d054bce86ee432a3126f6868121dbe4
-  data.tar.gz: fc52a74769adc232e881019aad8b3d4edc9f72e60a42bc2ecf3178f06591f24a7f9a38830f4c98a0f0048783a8b42ac5854a1e8caf0aac6a5baadbb8357d2d77
+  metadata.gz: e10b7c4eb7428b4eec647d26c767af0a9fd87a38f639b5925c12784a3feaad4f9ef2abb907e2eb73e46a271305c14a8d75dca37c0d559758bf5f64d43faf5c1e
+  data.tar.gz: b34810a3566fd70bddbd0b0922f321c2a7a9aecf2b914b2cf08d613e0f3c5ee9aedb0a8e2ae4d8b4cf8b8551db4b2f2d1ff14d4d47b10f0f0b9b825a595e5854

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.6] - 2025-08-12
+
+### Features
+- feat: add OpenAI Responses API support with reasoning (8c81be8)
+- feat: enhance ReAct prompt template with clearer instructions (d371c12)
+- feat(gemini): add thinkingConfig to generationConfig (8e44e63)
+
+### Bug Fixes
+- fix(openai): update default model name from gpt-5-nano to gpt-5-mini (1e5971f)
+- fix: update Final_Answer tag to FinalAnswer across codebase (feb6071)
+
+### Documentation
+- docs: add model testing results and update OpenAI model names (f83b987)
+- docs: add problem solving guidelines for AI assistants (0e99e5f)
+
+### Code Refactoring
+- refactor: reorganize prompt templates into modular structure (0c10e21)
+- refactor: improve format reminder in response processor (a3de6a5)
+- refactor: remove configurable timeout option (7e7e7c3)
+- refactor: reorganize Anthropic LLM class structure (4fc4f90)
+- refactor: extract format helpers from prompt template (d371c12)
+- refactor: simplify AgentTool type mapping with constant (c609949)
+- refactor: standardize Action tag to use single-line JSON format (5ac06f0)
+- refactor(context): simplify iteration handling and improve logging (3e65643)
+- refactor(llms): remove max_tokens parameter from configurations (d7a1fc8)
+
+### Performance
+- perf: replace standard JSON parser with Oj for better performance (3fc969f)
+
+### Chores
+- chore: update gitignore and documentation (8dc5102)
+- chore: adjust HTTP client timeout settings (38f47a7)
+- chore: update .gitignore to include .serena (90e3d41)
+
 ## [0.0.5] - 2025-08-05
 
 ### Bug Fixes

data/CLAUDE.md

@@ -65,7 +65,6 @@ 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
@@ -256,7 +255,6 @@ Soka.setup do |config|
 
   config.performance do |perf|
     perf.max_iterations = 10
-    perf.timeout = 30
   end
 end
 ```
@@ -274,7 +272,6 @@ ANTHROPIC_API_KEY=your_api_key
 
 ### 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
 
@@ -306,7 +303,7 @@ end
 ```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>')
+  double(content: '<Thought>Test</Thought><FinalAnswer>Done</FinalAnswer>')
 )
 ```
 
@@ -352,6 +349,13 @@ The `examples/` directory contains 10 comprehensive examples:
   - Remove duplicate code
   - Avoid over-abstraction
 
+### Ruby Code Organization (Important for AI Assistants)
+- **Always organize Ruby class methods with public methods first, then private methods**
+  - Place all public methods at the beginning of the class
+  - Place all private methods at the end after a single `private` keyword
+  - Never mix public and private sections
+  - Avoid using `public` keyword explicitly unless switching back from private
+
 ### Code Documentation
 - **When adjusting code, add comments and documentation to methods**
   - Use YARD format comments
@@ -363,6 +367,17 @@ The `examples/` directory contains 10 comprehensive examples:
 - Document all public APIs
 - Keep README and CLAUDE.md updated
 
+### Problem Solving Approach (Important for AI Assistants)
+- **Always solve problems directly - never avoid issues or use incorrect workarounds**
+  - Face technical challenges head-on without shortcuts or workarounds
+  - Ensure solutions align with architecture design and best practices
+  - Avoid temporary patches; pursue fundamental solutions
+- **When facing difficult problems or needing more information, provide current status and issues, then pause for discussion before implementation**
+  - Analyze and explain the situation when encountering complex problems
+  - Clearly describe difficulties encountered and information needed
+  - Wait for confirmation and discussion before proceeding with implementation
+  - Maintain transparent communication without assuming or guessing requirements
+
 ## 🤝 Contributing
 
 [Contributing Guidelines]

data/README.md

@@ -175,7 +175,6 @@ Soka.setup do |config|
   # Performance Configuration
   config.performance do |perf|
     perf.max_iterations = 10      # ReAct max iterations
-    perf.timeout = 30             # API call timeout (seconds)
   end
 
   # Default tools
@@ -226,7 +225,6 @@ class WeatherAgent < Soka::Agent
   provider :gemini
   model 'gemini-2.5-flash-lite'
   max_iterations 10
-  timeout 30
 
   # Register tools
   tool SearchTool
@@ -314,7 +312,7 @@ result = agent.run('What is the weather in Tokyo today?')
 # Result object provides rich information
 puts result.final_answer      # Final answer
 puts result.iterations       # Number of iterations used
-puts result.status          # :success, :failed, :timeout, :max_iterations_reached
+puts result.status          # :success, :failed, :max_iterations_reached
 puts result.execution_time  # Execution time (if recorded)
 
 # Check execution status
@@ -322,8 +320,6 @@ if result.successful?
   puts "Success: #{result.final_answer}"
 elsif result.failed?
   puts "Failed: #{result.error}"
-elsif result.timeout?
-  puts "Execution timeout"
 elsif result.max_iterations_reached?
   puts "Max iterations reached"
 end
@@ -445,12 +441,11 @@ Soka uses a tagged ReAct format:
 ```xml
 <Thought>I need to search for weather information in Tokyo</Thought>
 <Action>
-Tool: search
-Parameters: {"query": "Tokyo weather", "location": "Japan"}
+{"tool": "search", "parameters": {"query": "Tokyo weather", "location": "Japan"}}
 </Action>
 <Observation>Tokyo today: Sunny, temperature 28°C, humidity 65%</Observation>
 <Thought>I have obtained the weather information and can answer the user now</Thought>
-<Final_Answer>Today in Tokyo it's sunny with a temperature of 28°C and humidity of 65%.</Final_Answer>
+<FinalAnswer>Today in Tokyo it's sunny with a temperature of 28°C and humidity of 65%.</FinalAnswer>
 ```
 
 ### Result Object Structure
@@ -460,7 +455,7 @@ Parameters: {"query": "Tokyo weather", "location": "Japan"}
 result.input            # User input
 result.thoughts         # Array of thinking steps
 result.final_answer     # Final answer
-result.status          # Status (:success, :failed, :timeout, :max_iterations_reached)
+result.status          # Status (:success, :failed, :max_iterations_reached)
 result.error           # Error message (if any)
 result.execution_time  # Execution time (seconds)
 result.iterations      # Number of iterations
@@ -477,7 +472,7 @@ result.iterations      # Number of iterations
     }
   ],
   final_answer: "Final answer",
-  status: :success,        # :success, :failed, :timeout, :max_iterations_reached
+  status: :success,        # :success, :failed, :max_iterations_reached
   error: nil,             # Error message (if any)
   execution_time: 1.23,   # Execution time (seconds)
   iterations: 2,          # Number of iterations
@@ -663,7 +658,7 @@ ruby examples/1_basic.rb
 - Default model: `gemini-2.5-flash-lite`
 
 #### OpenAI
-- Models: `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`
+- Models: `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
 - Environment variable: `OPENAI_API_KEY`
 - Features: Streaming support, powerful reasoning
 
@@ -672,6 +667,24 @@ ruby examples/1_basic.rb
 - Environment variable: `ANTHROPIC_API_KEY`
 - Features: Long context support, excellent code understanding
 
+### Model Testing Results
+
+Based on extensive testing with the Soka framework, here are the recommended models for optimal performance:
+
+| Provider | ✅ Recommended Models | ⚠️ Not Recommended | Notes |
+|----------|----------------------|-------------------|--------|
+| **Gemini** | `gemini-2.5-flash-lite` ⭐<br>`gemini-2.5-pro` | `gemini-2.5-flash` | **gemini-2.5-flash-lite**: Fast, cost-effective, with good performance<br>**Avoid gemini-2.5-flash**: Often skips thinking process when using tools, directly jumps to tool usage |
+| **OpenAI** | `gpt-5` <br>`gpt-5-mini` ⭐ | `gpt-5-nano` | **gpt-5-mini**: Good balance of price, speed, and effectiveness<br>**Avoid gpt-5-nano**: Can enter infinite tool-calling loops, fails to complete tasks |
+| **Claude** | *To be tested* | - | Testing in progress |
+
+⭐ = Best choice for most use cases
+
+#### Testing Insights
+
+- **Thinking Process**: Models marked as "Not Recommended" often fail to properly follow the ReAct pattern, either skipping the thinking phase or getting stuck in loops
+- **Cost-Performance**: `gemini-2.5-flash-lite` and `gpt-5-mini` offer the best balance for most applications
+- **Reliability**: Recommended models consistently complete tasks without entering error states
+
 ### Configuration Options
 
 | Option | Type | Default | Description |
@@ -682,7 +695,6 @@ ruby examples/1_basic.rb
 | `ai.instructions` | String | nil | Custom agent instructions |
 | `ai.think_in` | String | `"en"` | Thinking language |
 | `performance.max_iterations` | Integer | 10 | Max iterations |
-| `performance.timeout` | Integer | 30 | Timeout (seconds) |
 
 ### Tool Parameter Validation
 
@@ -696,8 +708,8 @@ ruby examples/1_basic.rb
 ## Performance Optimization
 
 1. **Use appropriate models**:
-   - Simple tasks: `gemini-2.5-flash-lite` or `gpt-4.1-mini` or `claude-3-5-haiku-latest`
-   - Complex reasoning: `gemini-2.5-pro` or `gpt-4.1` or `claude-sonnet-4-0`
+   - Simple tasks: `gemini-2.5-flash-lite` or `gpt-5-mini` or `claude-3-5-haiku-latest`
+   - Complex reasoning: `gemini-2.5-pro` or `gpt-5` or `claude-sonnet-4-0`
 
 2. **Control iterations**:
    ```ruby
@@ -715,13 +727,7 @@ ruby examples/1_basic.rb
    ```
    Solution: Ensure correct environment variable is set or provide API key in configuration
 
-2. **Timeout Error**
-   ```
-   Soka::LLMError: Request timed out
-   ```
-   Solution: Increase timeout or use a faster model
-
-3. **Max Iterations Reached**
+2. **Max Iterations Reached**
    ```
    Status: max_iterations_reached
    ```
@@ -795,7 +801,7 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 ## Acknowledgments
 
 - Thanks to the [ReAct paper](https://arxiv.org/abs/2210.03629) for the theoretical foundation
-- Thanks to the [Regent](https://github.com/alextwoods/regent) project for architectural inspiration
+- Thanks to the [Regent](https://github.com/alchaplinsky/regent) project for architectural inspiration
 - Thanks to all contributors for their efforts
 
 ---

data/examples/1_basic.rb

@@ -15,7 +15,6 @@ Soka.setup do |config|
 
   config.performance do |perf|
     perf.max_iterations = 5
-    perf.timeout = 30
   end
 end
 

data/examples/2_event_handling.rb

@@ -16,7 +16,6 @@ Soka.setup do |config|
 
   config.performance do |perf|
     perf.max_iterations = 5
-    perf.timeout = 30
   end
 end
 

data/examples/3_memory.rb

@@ -17,7 +17,6 @@ Soka.setup do |config|
 
   config.performance do |perf|
     perf.max_iterations = 10
-    perf.timeout = 30
   end
 end
 

data/lib/soka/agent.rb

@@ -17,7 +17,6 @@ module Soka
     # @param engine [Class] The engine class to use (defaults to Engine::React)
     # @param options [Hash] Configuration options
     # @option options [Integer] :max_iterations Maximum iterations for reasoning
-    # @option options [Integer] :timeout Timeout in seconds for operations
     # @option options [Symbol] :provider LLM provider override
     # @option options [String] :model LLM model override
     # @option options [String] :api_key LLM API key override
@@ -44,8 +43,9 @@ module Soka
     # Apply performance-related configuration
     # @param options [Hash] Configuration options
     def apply_performance_config(options)
-      @max_iterations = options.fetch(:max_iterations) { self.class._max_iterations } || 10
-      @timeout = options.fetch(:timeout) { self.class._timeout } || 30
+      @max_iterations = options.fetch(:max_iterations) do
+        self.class._max_iterations || Soka.configuration.performance.max_iterations
+      end
     end
 
     # Apply behavior-related configuration

data/lib/soka/agent_tool.rb

@@ -5,6 +5,15 @@ module Soka
   class AgentTool
     include AgentTools::ParamsValidator
 
+    TYPE_MAPPING = {
+      'String' => 'string',
+      'Integer' => 'integer', 'Fixnum' => 'integer', 'Bignum' => 'integer',
+      'Float' => 'number', 'Numeric' => 'number',
+      'TrueClass' => 'boolean', 'FalseClass' => 'boolean', 'Boolean' => 'boolean',
+      'Array' => 'array',
+      'Hash' => 'object', 'Object' => 'object'
+    }.freeze
+
     # Handles parameter definitions for tools
     class ParamsDefinition
       attr_reader :required_params, :optional_params, :validations
@@ -109,22 +118,7 @@ module Soka
       end
 
       def type_to_json_type(ruby_type)
-        type_mapping[ruby_type.to_s] || 'string'
-      end
-
-      def type_mapping
-        @type_mapping ||= build_type_mapping
-      end
-
-      def build_type_mapping
-        {
-          'String' => 'string',
-          'Integer' => 'integer', 'Fixnum' => 'integer', 'Bignum' => 'integer',
-          'Float' => 'number', 'Numeric' => 'number',
-          'TrueClass' => 'boolean', 'FalseClass' => 'boolean', 'Boolean' => 'boolean',
-          'Array' => 'array',
-          'Hash' => 'object', 'Object' => 'object'
-        }.freeze
+        TYPE_MAPPING[ruby_type.to_s] || 'string'
       end
     end
 

data/lib/soka/agents/dsl_methods.rb

@@ -10,7 +10,7 @@ module Soka
 
       # Class methods for DSL
       module ClassMethods
-        attr_accessor :_provider, :_model, :_api_key, :_max_iterations, :_timeout, :_tools, :_retry_config, :_hooks,
+        attr_accessor :_provider, :_model, :_api_key, :_max_iterations, :_tools, :_retry_config, :_hooks,
                       :_instructions, :_think_in
 
         def inherited(subclass)
@@ -44,12 +44,6 @@ module Soka
           @_max_iterations = num
         end
 
-        # Define timeout for the agent
-        # @param duration [Integer] The timeout duration in seconds
-        def timeout(duration)
-          @_timeout = duration
-        end
-
         # Define custom instructions (system prompt) for the agent
         # @param text_or_method [String, Symbol] The custom instructions/system prompt or method name
         # @example Using a string

data/lib/soka/configuration.rb

@@ -5,7 +5,7 @@ module Soka
   class Configuration
     # AI provider configuration
     class AIConfig
-      attr_accessor :provider, :model, :api_key, :fallback_provider, :fallback_model, :fallback_api_key
+      attr_accessor :provider, :model, :api_key
 
       def initialize
         @provider = :gemini
@@ -15,11 +15,10 @@ module Soka
 
     # Performance-related configuration
     class PerformanceConfig
-      attr_accessor :max_iterations, :timeout
+      attr_accessor :max_iterations
 
       def initialize
         @max_iterations = 10
-        @timeout = 30
       end
     end
 

data/lib/soka/engines/concerns/response_parser.rb

@@ -15,7 +15,7 @@ module Soka
           {
             thoughts: extract_tagged_content(text, 'Thought'),
             actions: extract_actions(text),
-            final_answer: extract_tagged_content(text, 'Final_Answer').first
+            final_answer: extract_tagged_content(text, 'FinalAnswer').first
           }
         end
 
@@ -29,30 +29,18 @@ module Soka
           action_blocks.filter_map { |block| parse_action_block(block[0]) }
         end
 
+        # Parse action block from LLM response in JSON format
+        # @param content [String] The action block content containing JSON
+        # @return [Hash, nil] The parsed action with tool and params
         def parse_action_block(content)
           content = content.strip
-          tool_match = content.match(/Tool:\s*(.+)/)
-          params_match = content.match(/Parameters:\s*(.+)/m)
+          action_json = Oj.load(content, symbol_keys: true)
 
-          return unless tool_match && params_match
+          return nil unless action_json[:tool]
 
-          tool_name = tool_match[1].strip
-          params_json = params_match[1].strip
-          params = parse_json_params(params_json)
-
-          { tool: tool_name, params: params }
-        end
-
-        # Parse JSON parameters from action block
-        # @param params_json [String] The JSON string to parse
-        # @return [Hash] The parsed parameters as a hash with symbol keys
-        def parse_json_params(params_json)
-          # Clean up the JSON string - remove any trailing commas or whitespace
-          cleaned_json = params_json.strip.gsub(/,\s*}/, '}').gsub(/,\s*\]/, ']')
-          JSON.parse(cleaned_json, symbolize_names: true)
-        rescue JSON::ParserError
-          # Return empty hash to continue when JSON parsing fails
-          {}
+          { tool: action_json[:tool], params: action_json[:parameters] || {} }
+        rescue Oj::ParseError
+          nil
         end
       end
     end

data/lib/soka/engines/concerns/response_processor.rb

@@ -86,16 +86,27 @@ module Soka
         # @param context [ReasoningContext] The reasoning context
         # @param content [String] The raw response content
         def handle_no_action(context, content)
+          # Important: We still need to add the message to maintain conversation flow
+          # but we should NOT add a new thought since the response was incomplete
           context.add_message(role: 'assistant', content: content)
           context.add_message(
             role: 'user',
-            content: 'Please follow the exact format with <Thought>, <Action>, and <Final_Answer> tags.'
+            content: format_reminder
           )
         end
 
         def format_observation(observation)
           "<Observation>#{observation}</Observation>"
         end
+
+        def format_reminder
+          # Strict mode (default)
+          'CRITICAL: Only responses with proper <Thought>, <Action>, and <FinalAnswer> tags will be processed. ' \
+            'Other formats will fail.'
+          # Normal mode (alternative)
+          # 'Structure your response using these required tags: <Thought> for reasoning, ' \
+          #   '<Action> for tool usage, and <FinalAnswer> for conclusions.'
+        end
       end
     end
   end

data/lib/soka/engines/prompts/base.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Prompts
+      # Base module for prompt generation
+      module Base
+        private
+
+        def system_prompt
+          # Use custom instructions if provided, otherwise use default ReAct prompt
+          if custom_instructions
+            combine_with_react_format(custom_instructions).strip
+          else
+            default_react_prompt.strip
+          end
+        end
+
+        def default_react_prompt
+          tools_description = format_tools_description(tools)
+
+          <<~PROMPT
+            You are an AI assistant that uses the ReAct (Reasoning and Acting) framework to solve problems step by step.
+
+            You have access to the following tools:
+            #{tools_description}
+
+            #{format_instructions}
+          PROMPT
+        end
+
+        def combine_with_react_format(instructions)
+          tools_description = format_tools_description(tools)
+
+          <<~PROMPT
+            #{react_base_prompt}
+
+            #{react_framework_structure}
+
+            You have access to the following tools:
+            #{tools_description}
+
+            #{format_instructions}
+
+            #{custom_instructions_section(instructions)}
+          PROMPT
+        end
+
+        def react_base_prompt
+          'You are an AI assistant that uses the ReAct (Reasoning and Acting) framework to solve problems step by step.'
+        end
+
+        def react_framework_structure
+          <<~STRUCTURE
+            🔧 REACT FRAMEWORK STRUCTURE:
+            You MUST use XML-style tags to structure your response. Each tag has a specific purpose:
+            - <Thought>: Your first-person reasoning (max 30 words)
+            - <Action>: Tool invocation with JSON parameters
+            - <Observation>: Tool results (provided by system)
+            - <FinalAnswer>: Your complete solution (direct & concise)
+
+            These tags are MANDATORY and define the ReAct workflow. The system parses these tags to understand your reasoning process.
+          STRUCTURE
+        end
+
+        def custom_instructions_section(instructions)
+          <<~SECTION
+            📋 CUSTOM BEHAVIOR INSTRUCTIONS:
+            ═══════════════════════════════════════════
+            The following instructions apply to the CONTENT within your XML tags, NOT the ReAct structure itself:
+
+            #{instructions}
+
+            ⚠️ IMPORTANT: These custom instructions modify HOW you think and respond within the tags,
+            but DO NOT change the requirement to use the XML tag structure for ReAct.
+            ═══════════════════════════════════════════
+          SECTION
+        end
+
+        def format_instructions
+          thinking_instruction = build_thinking_instruction(think_in)
+          iteration_limit = build_iteration_limit_warning
+
+          <<~INSTRUCTIONS
+            #{iteration_limit}
+
+            🎯 MANDATORY XML TAG STRUCTURE:
+            You MUST use XML-style tags to wrap your content. This is NOT optional.
+            The system relies on these tags to parse and understand your reasoning.
+
+            #{thinking_instruction}
+
+            #{step_format_example}
+
+            #{action_format_rules}
+
+            #{final_answer_critical_format}
+          INSTRUCTIONS
+        end
+      end
+    end
+  end
+end

data/lib/soka/engines/prompts/format_helpers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Prompts
+      # Helper methods for formatting prompt components
+      module FormatHelpers
+        private
+
+        # Format tools description for prompt
+        # @param tools [Array] The tools available
+        # @return [String] Formatted tools description
+        def format_tools_description(tools)
+          return 'No tools available.' if tools.empty?
+
+          tools.map do |tool|
+            schema = tool.class.to_h
+            params_desc = format_parameters(schema[:parameters])
+
+            "- #{schema[:name]}: #{schema[:description]}\n  Parameters: \n#{params_desc}"
+          end.join("\n")
+        end
+
+        # Format parameters for tool description
+        # @param params_schema [Hash] The parameters schema
+        # @return [String] Formatted parameters description
+        def format_parameters(params_schema)
+          return 'none' if params_schema[:properties].empty?
+
+          properties = params_schema[:properties].map do |name, config|
+            required = params_schema[:required].include?(name.to_s) ? '(required)' : '(optional)'
+            type = config[:type]
+            desc = config[:description]
+
+            "    - #{name} #{required} [#{type}] - #{desc}"
+          end
+
+          properties.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/soka/engines/prompts/instructions.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Prompts
+      # Module for building instruction components
+      module Instructions
+        private
+
+        # Build iteration limit warning
+        # @return [String] The iteration limit warning
+        def build_iteration_limit_warning
+          return '' unless respond_to?(:max_iterations) && max_iterations
+
+          <<~WARNING
+            ⏰ ITERATION LIMIT: You have a maximum of #{max_iterations} iterations to complete this task.
+            - Each Thought/Action cycle counts as one iteration
+            - Plan your approach efficiently to stay within this limit
+            - If you cannot complete the task within #{max_iterations} iterations, provide your best answer with what you have
+          WARNING
+        end
+
+        # Build thinking instruction based on language
+        # @param language [String, nil] The language to use for thinking
+        # @return [String] The thinking instruction
+        def build_thinking_instruction(language)
+          return '' unless language
+
+          <<~INSTRUCTION
+            🌐 THINKING LANGUAGE:
+            Use #{language} for your reasoning WITHIN the <Thought> XML tags.
+            This affects the content inside tags, not the tag structure itself.
+          INSTRUCTION
+        end
+
+        # Step format example
+        # @return [String] The step format example
+        def step_format_example
+          <<~FORMAT
+            📝 XML TAG FORMAT FOR EACH STEP:
+
+            1️⃣ THINKING PHASE (Required):
+            <Thought>
+            MAXIMUM 30 WORDS - Be extremely concise!
+            Use first-person perspective (I, me, my).
+            NEVER mention: "LLM", "AI", "formatting for", "organizing for someone".
+            NEVER say: "I will act as", "I will play the role of", "as an expert".
+            BE DIRECT: "I'll check", "Let me see", "Looking at this".
+            Keep it light and witty within the word limit.
+            </Thought>
+
+            2️⃣ ACTION PHASE (When needed):
+            <Action>
+            {"tool": "tool_name", "parameters": {"param1": "value1", "param2": "value2"}}
+            </Action>
+
+            ⚠️ CRITICAL: Each tag MUST have both opening <TagName> and closing </TagName>.
+            The content between tags follows any custom instructions provided.
+          FORMAT
+        end
+
+        # Critical format for final answer
+        # @return [String] The critical format instructions
+        def final_answer_critical_format
+          <<~CRITICAL
+            ⚠️ CRITICAL - FINAL ANSWER XML TAG FORMAT:
+            When you have the complete answer, YOU MUST use XML-style tags:
+
+            <FinalAnswer>
+            State the result directly without explanation.
+            No justification or reasoning needed - just the answer.
+            Maximum 300 words. Be direct and concise.
+            </FinalAnswer>
+
+            🚨 PARSER REQUIREMENTS:
+            - The system parser REQUIRES both opening <FinalAnswer> and closing </FinalAnswer> tags
+            - Without proper XML tags, the system CANNOT detect task completion
+            - The tags are case-sensitive and must match exactly
+            - Final answer MUST NOT exceed 300 words
+            - NO over-explanation - direct results only
+          CRITICAL
+        end
+      end
+    end
+  end
+end

data/lib/soka/engines/prompts/workflow_rules.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    module Prompts
+      # Module for ReAct workflow rules
+      module WorkflowRules
+        private
+
+        # Action format rules
+        # @return [String] The action format rules
+        def action_format_rules
+          <<~RULES
+            🔄 REACT WORKFLOW WITH XML TAGS:
+
+            STOP HERE after each Action. Do NOT include <Observation> in your response.
+            The system will execute the tool and provide the observation wrapped in <Observation> tags.
+
+            After receiving the observation, you can continue with more Thought/Action cycles or provide a final answer.
+
+            #{react_flow_example}
+
+            #{xml_tag_requirements}
+          RULES
+        end
+
+        # ReAct flow example
+        # @return [String] The ReAct flow example
+        def react_flow_example
+          <<~EXAMPLE
+            📝 EXAMPLE OF COMPLETE REACT FLOW WITH XML TAGS:
+
+            Step 1: Your response
+            <Thought>Math problem! I'll use the calculator tool for 2+2.</Thought>
+            <Action>{"tool": "calculator", "parameters": {"expression": "2+2"}}</Action>
+
+            Step 2: System provides
+            <Observation>4</Observation>
+
+            Step 3: Your response
+            <Thought>Got it - the answer is 4!</Thought>
+            <FinalAnswer>4</FinalAnswer>
+          EXAMPLE
+        end
+
+        # XML tag requirements
+        # @return [String] The XML tag requirements
+        def xml_tag_requirements
+          <<~REQUIREMENTS
+            🚨 XML TAG REQUIREMENTS AND RULES:
+
+            1. 🏷️ MANDATORY XML STRUCTURE:
+               - Always wrap content in appropriate XML tags
+               - Tags: <Thought>, <Action>, <FinalAnswer>
+               - Each tag MUST have matching closing tag
+
+            2. 💭 THINKING PHASE:
+               - Always start with <Thought>...</Thought>
+               - MAXIMUM 30 WORDS per thought
+               - Use first-person perspective (I, me, my)
+               - AVOID: "LLM", "AI", "formatting for", "organizing for"
+               - AVOID: "act as", "play role of", "as an expert", "I will be"
+               - BE DIRECT: Use natural language like "I'll check", "Let me see"
+               - Be concise and witty
+               - Custom instructions affect HOW you think, not WHETHER you use tags
+
+            3. 🔧 ACTION FORMAT:
+               - <Action> content MUST be valid JSON on a single line
+               - Format: {"tool": "name", "parameters": {...}}
+               - Empty parameters: {"tool": "name", "parameters": {}}
+
+            4. 👁️ OBSERVATION:
+               - NEVER create <Observation> tags yourself
+               - System provides these automatically
+
+            5. ✅ FINAL ANSWER:
+               - MUST use <FinalAnswer>...</FinalAnswer> tags
+               - Both opening AND closing tags REQUIRED
+               - System cannot detect completion without these tags
+               - No text after closing </FinalAnswer> tag
+               - Maximum 300 words
+               - Direct results only - NO explanations or justifications
+
+            6. 🎯 EFFICIENCY:
+               - Limited iterations available
+               - Think harder upfront to minimize tool calls
+               - Prioritize essential actions
+
+            7. 📋 CUSTOM INSTRUCTIONS SCOPE:
+               - Custom instructions modify content WITHIN tags
+               - They DO NOT change the XML tag structure requirement
+               - ReAct workflow with XML tags is ALWAYS required
+          REQUIREMENTS
+        end
+      end
+    end
+  end
+end

data/lib/soka/engines/prompts.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Soka
+  module Engines
+    # Main module that combines all prompt components
+    module Prompts
+      include Base
+      include Instructions
+      include WorkflowRules
+      include FormatHelpers
+    end
+  end
+end

data/lib/soka/engines/react.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module Soka
   module Engines
     # ReAct (Reasoning and Acting) engine implementation
     class React < Base
+      include Prompts
       include Concerns::ResponseProcessor
-      include Concerns::PromptTemplate
       include Concerns::ResponseParser
       include Concerns::ResultBuilder
 
@@ -35,12 +33,13 @@ module Soka
       # @param context [ReasoningContext] The reasoning context
       # @return [ReasonResult, nil] The result if found, nil otherwise
       def iterate_reasoning(context)
-        max_iterations.times do
+        max_iterations.times do |index|
+          context.iteration = index # Set current iteration number
           result = process_iteration(context)
           return result if result
-
-          context.increment_iteration!
         end
+        # When max iterations reached, ensure iteration count is correct
+        context.iteration = max_iterations
         nil
       end
 

data/lib/soka/engines/reasoning_context.rb

@@ -37,18 +37,6 @@ module Soka
         @event_handler.call(event)
       end
 
-      # Check if we've reached the maximum number of iterations
-      # @return [Boolean] true if max iterations reached
-      def max_iterations_reached?
-        @iteration >= @max_iterations
-      end
-
-      # Increment the iteration counter
-      # @return [Integer] The new iteration count
-      def increment_iteration!
-        @iteration += 1
-      end
-
       # Get the current iteration number (1-based for display)
       # @return [Integer] The current iteration number for display
       def current_step

data/lib/soka/llms/anthropic.rb

@@ -6,6 +6,21 @@ module Soka
     class Anthropic < Base
       ENV_KEY = 'ANTHROPIC_API_KEY'
 
+      def chat(messages, **params)
+        request_params = build_request_params(messages, params)
+
+        response = connection.post do |req|
+          req.url '/v1/messages'
+          req.headers['x-api-key'] = api_key
+          req.headers['anthropic-version'] = options[:anthropic_version]
+          req.body = request_params
+        end
+
+        parse_response(response)
+      rescue Faraday::Error => e
+        handle_error(e)
+      end
+
       private
 
       def default_model
@@ -21,30 +36,11 @@ module Soka
           temperature: 0.7,
           top_p: 1.0,
           top_k: 1,
-          max_tokens: 2048,
-          anthropic_version: '2023-06-01'
+          anthropic_version: '2023-06-01',
+          max_tokens: 2048
         }
       end
 
-      public
-
-      def chat(messages, **params)
-        request_params = build_request_params(messages, params)
-
-        response = connection.post do |req|
-          req.url '/v1/messages'
-          req.headers['x-api-key'] = api_key
-          req.headers['anthropic-version'] = options[:anthropic_version]
-          req.body = request_params
-        end
-
-        parse_response(response)
-      rescue Faraday::Error => e
-        handle_error(e)
-      end
-
-      private
-
       def build_request_params(messages, params)
         formatted_messages, system_prompt = extract_system_prompt(messages)
         request = build_base_request(formatted_messages, params)

data/lib/soka/llms/base.rb

@@ -57,8 +57,7 @@ module Soka
           faraday.request :json
           faraday.response :json
           faraday.adapter Faraday.default_adapter
-          faraday.options.timeout = options[:timeout] || 30
-          faraday.options.open_timeout = options[:open_timeout] || 10
+          faraday.options.timeout = 60
         end
       end
 

data/lib/soka/llms/gemini.rb

@@ -20,8 +20,7 @@ module Soka
         {
           temperature: 0.7,
           top_p: 1.0,
-          top_k: 1,
-          max_output_tokens: 2048
+          top_k: 1
         }
       end
 
@@ -50,7 +49,7 @@ module Soka
             temperature: params[:temperature] || options[:temperature],
             topP: params[:top_p] || options[:top_p],
             topK: params[:top_k] || options[:top_k],
-            maxOutputTokens: params[:max_output_tokens] || options[:max_output_tokens]
+            thinkingConfig: { thinkingBudget: 512 }
           }
         }
       end

data/lib/soka/llms/openai.rb

@@ -6,33 +6,11 @@ module Soka
     class OpenAI < Base
       ENV_KEY = 'OPENAI_API_KEY'
 
-      private
-
-      def default_model
-        'gpt-4.1-mini'
-      end
-
-      def base_url
-        'https://api.openai.com'
-      end
-
-      def default_options
-        {
-          temperature: 0.7,
-          top_p: 1.0,
-          frequency_penalty: 0,
-          presence_penalty: 0,
-          max_tokens: 2048
-        }
-      end
-
-      public
-
       def chat(messages, **params)
         request_params = build_request_params(messages, params)
 
         response = connection.post do |req|
-          req.url '/v1/chat/completions'
+          req.url '/v1/responses'
           req.headers['Authorization'] = "Bearer #{api_key}"
           req.body = request_params
         end
@@ -44,16 +22,35 @@ module Soka
 
       private
 
+      def default_model
+        'gpt-5-mini'
+      end
+
+      def base_url
+        'https://api.openai.com'
+      end
+
       def build_request_params(messages, params)
-        {
+        request_params = {
           model: model,
-          messages: messages,
-          temperature: params[:temperature] || options[:temperature],
-          top_p: params[:top_p] || options[:top_p],
-          frequency_penalty: params[:frequency_penalty] || options[:frequency_penalty],
-          presence_penalty: params[:presence_penalty] || options[:presence_penalty],
-          max_tokens: params[:max_tokens] || options[:max_tokens]
+          input: messages
         }
+
+        # Add max_output_tokens if provided (Responses API uses max_output_tokens)
+        request_params[:max_output_tokens] = params[:max_tokens] if params[:max_tokens]
+        add_reasoning_effort(request_params)
+
+        request_params
+      end
+
+      def add_reasoning_effort(request_params)
+        return unless allowed_reasoning_prefix_models?
+
+        request_params[:reasoning] = { effort: 'minimal', summary: 'auto' }
+      end
+
+      def allowed_reasoning_prefix_models?
+        model.start_with?('gpt-5') && !model.start_with?('gpt-5-chat-latest')
       end
 
       def parse_response(response)
@@ -70,18 +67,27 @@ module Soka
       end
 
       def build_result_from_response(body)
-        choice = body.dig('choices', 0)
-        message = choice['message']
+        # Extract text from the Responses API format
+        output_text = extract_output_text(body['output'])
+
+        # Get the status to determine finish reason
+        finish_reason = body['status'] == 'completed' ? 'stop' : body['status']
 
         Result.new(
           model: body['model'],
-          content: message['content'],
-          input_tokens: body.dig('usage', 'prompt_tokens'),
-          output_tokens: body.dig('usage', 'completion_tokens'),
-          finish_reason: choice['finish_reason'],
+          content: output_text,
+          input_tokens: body.dig('usage', 'input_tokens'),
+          output_tokens: body.dig('usage', 'output_tokens'),
+          finish_reason: finish_reason,
           raw_response: body
         )
       end
+
+      def extract_output_text(output_items)
+        message = output_items.find { |item| item['type'] == 'message' }
+        content = message['content'].find { |content| content['type'] == 'output_text' }
+        content['text']
+      end
     end
   end
 end

data/lib/soka/result.rb

@@ -37,12 +37,6 @@ module Soka
       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?
@@ -65,8 +59,8 @@ module Soka
 
     # Convert to JSON string
     # @return [String]
-    def to_json(...)
-      to_h.to_json(...)
+    def to_json(*)
+      Oj.dump(to_h, mode: :compat)
     end
 
     # Get a summary of the result
@@ -117,7 +111,6 @@ module Soka
       {
         success: "Success: #{truncate(final_answer)}",
         failed: "Failed: #{error}",
-        timeout: 'Timeout: Execution exceeded time limit',
         max_iterations_reached: "Max iterations reached: #{iterations} iterations"
       }
     end

data/lib/soka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Soka
-  VERSION = '0.0.5'
+  VERSION = '0.0.6'
 end

data/lib/soka.rb

@@ -2,6 +2,7 @@
 
 require 'zeitwerk'
 require 'faraday'
+require 'oj'
 
 # Main module for the Soka ReAct Agent Framework
 # Provides AI agent capabilities with multiple LLM providers support

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: soka
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - jiunjiun
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-05 00:00:00.000000000 Z
+date: 2025-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -76,10 +90,14 @@ files:
 - 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_parser.rb
 - lib/soka/engines/concerns/response_processor.rb
 - lib/soka/engines/concerns/result_builder.rb
+- lib/soka/engines/prompts.rb
+- lib/soka/engines/prompts/base.rb
+- lib/soka/engines/prompts/format_helpers.rb
+- lib/soka/engines/prompts/instructions.rb
+- lib/soka/engines/prompts/workflow_rules.rb
 - lib/soka/engines/react.rb
 - lib/soka/engines/reasoning_context.rb
 - lib/soka/llm.rb

data/lib/soka/engines/concerns/prompt_template.rb

@@ -1,121 +0,0 @@
-# frozen_string_literal: true
-
-module Soka
-  module Engines
-    module Concerns
-      # Module for handling prompt templates in ReAct engine
-      module PromptTemplate
-        private
-
-        def system_prompt
-          # Use custom instructions if provided, otherwise use default ReAct prompt
-          if custom_instructions
-            combine_with_react_format(custom_instructions)
-          else
-            default_react_prompt
-          end
-        end
-
-        def default_react_prompt
-          tools_description = format_tools_description(tools)
-
-          <<~PROMPT
-            You are an AI assistant that uses the ReAct (Reasoning and Acting) framework to solve problems step by step.
-
-            You have access to the following tools:
-            #{tools_description}
-
-            #{format_instructions}
-          PROMPT
-        end
-
-        def combine_with_react_format(instructions)
-          tools_description = format_tools_description(tools)
-
-          <<~PROMPT
-            #{instructions}
-
-            You have access to the following tools:
-            #{tools_description}
-
-            #{format_instructions}
-          PROMPT
-        end
-
-        def format_instructions
-          thinking_instruction = build_thinking_instruction(think_in)
-
-          <<~INSTRUCTIONS
-            You must follow this exact format for each step:
-
-            #{thinking_instruction}
-
-            <Thought>Your reasoning about what to do next</Thought>
-            <Action>
-            Tool: tool_name
-            Parameters: {"param1": "value1", "param2": "value2"}
-            </Action>
-
-            #{action_format_rules}
-          INSTRUCTIONS
-        end
-
-        # Build thinking instruction based on language
-        # @param language [String, nil] The language to use for thinking
-        # @return [String] The thinking instruction
-        def build_thinking_instruction(language)
-          return '' unless language
-
-          "Use #{language} for your reasoning in <Thought> tags."
-        end
-
-        # Action format rules
-        # @return [String] The action format rules
-        def action_format_rules
-          <<~RULES
-            STOP HERE after each Action. Do NOT include <Observation> in your response.
-            The system will execute the tool and provide the observation.
-
-            After receiving the observation, you can continue with more Thought/Action cycles or provide a final answer:
-
-            <Final_Answer>Your complete answer to the user's question</Final_Answer>
-
-            Important rules:
-            1. Always start with a <Thought> to analyze the problem
-            2. Use tools when you need information or to perform actions
-            3. Parameters MUST be valid JSON format (e.g., {"query": "weather"} not {query: "weather"})
-            4. For tools without parameters, use empty JSON object: {}
-            5. NEVER include <Observation> tags - wait for the system to provide them
-            6. Provide a clear and complete <Final_Answer> when done
-            7. If you cannot complete the task, explain why in the <Final_Answer>
-          RULES
-        end
-
-        def format_tools_description(tools)
-          return 'No tools available.' if tools.empty?
-
-          tools.map do |tool|
-            schema = tool.class.to_h
-            params_desc = format_parameters(schema[:parameters])
-
-            "- #{schema[:name]}: #{schema[:description]}\n  Parameters: #{params_desc}"
-          end.join("\n")
-        end
-
-        def format_parameters(params_schema)
-          return 'none' if params_schema[:properties].empty?
-
-          properties = params_schema[:properties].map do |name, config|
-            required = params_schema[:required].include?(name.to_s) ? '(required)' : '(optional)'
-            type = config[:type]
-            desc = config[:description]
-
-            "#{name} #{required} [#{type}] - #{desc}"
-          end
-
-          properties.join(', ')
-        end
-      end
-    end
-  end
-end