soka 0.0.4 → 0.0.6

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,17 +1,15 @@
 # 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
 
-      ReasonResult = Struct.new(:input, :thoughts, :final_answer, :status, :error, :confidence_score,
+      ReasonResult = Struct.new(:input, :thoughts, :final_answer, :status, :error,
                                 keyword_init: true) do
         def successful?
           status == :success
@@ -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/llm.rb

@@ -69,14 +69,14 @@ module Soka
     # @param provider_name [Symbol] Provider type
     # @param options [Hash] Provider options
     # @return [LLMs::Base] Provider instance
-    def create_provider(provider_name, **)
+    def create_provider(provider_name, ...)
       case provider_name.to_sym
       when :gemini
-        LLMs::Gemini.new(**)
+        LLMs::Gemini.new(...)
       when :openai
-        LLMs::OpenAI.new(**)
+        LLMs::OpenAI.new(...)
       when :anthropic
-        LLMs::Anthropic.new(**)
+        LLMs::Anthropic.new(...)
       else
         raise LLMError, "Unknown LLM provider: #{provider_name}"
       end

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?
@@ -66,7 +60,7 @@ module Soka
     # Convert to JSON string
     # @return [String]
     def to_json(*)
-      to_h.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.4'
+  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,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: soka
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: ruby
 authors:
 - jiunjiun
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -23,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
@@ -75,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
@@ -98,6 +117,7 @@ metadata:
   source_code_uri: https://github.com/jiunjiun/soka
   changelog_uri: https://github.com/jiunjiun/soka/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -105,14 +125,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: A Ruby ReAct Agent Framework with multi-LLM support
 test_files: []