soka 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb5c0a25160f948f0514c8297166706adef7b1d1921854e95cedef2466b561f0
-  data.tar.gz: afe45e214ea6077f81d3d21a56474213db820124d1bc46652a960d6a8c524e59
+  metadata.gz: 484709d85e7835138e502ed9a795257f46289df28f7f3fef31c3e048b62cdc20
+  data.tar.gz: 74fa32be0296709abe5dd18480a6fabb6ae9dd0f17aa608a7e1e9f51f3934b37
 SHA512:
-  metadata.gz: 687b999469d40246dd5c224ec433d634089b81ee8f46d3ba85b6fa469317f2e1d1b65fba7e196905bee7060f41ab73423d054bce86ee432a3126f6868121dbe4
-  data.tar.gz: fc52a74769adc232e881019aad8b3d4edc9f72e60a42bc2ecf3178f06591f24a7f9a38830f4c98a0f0048783a8b42ac5854a1e8caf0aac6a5baadbb8357d2d77
+  metadata.gz: 7665b62bd029b2b29c3cba25c42326160176b5426435fce0e37e4c7929afa33acacb29a5efb431f480efb7e94960d9406feb3467c30b8f284f7ef94cf8e8e5c7
+  data.tar.gz: 1af86f19c9d89d156826e676816908f8c56a443586281a744c75a3ba9f0f1c461989a223c82e79204042801147f81710cbb5224059d988de984f18a595c95aac

data/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.7] - 2025-08-15
+
+### Features
+- feat: add execution time tracking to ReAct engine (eea5efb)
+
+### Code Refactoring
+- refactor: reduce thought tag word limit for better conciseness (7b3290c)
+
+## [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/agents/hook_manager.rb

@@ -32,7 +32,8 @@ module Soka
           thoughts: engine_result.thoughts,
           final_answer: engine_result.final_answer,
           status: engine_result.status,
-          error: engine_result.error
+          error: engine_result.error,
+          execution_time: engine_result.execution_time
         )
       end
 

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 20 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