open_router_enhanced 1.0.0

data/lib/open_router/prompt_template.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Main prompt template class that handles variable interpolation,
+  # few-shot examples, and chat message formatting
+  class PromptTemplate
+    attr_reader :template, :input_variables, :prefix, :suffix, :examples, :example_template
+
+    # Initialize a new PromptTemplate
+    #
+    # @param template [String, nil] Main template string with {variable} placeholders
+    # @param input_variables [Array<Symbol>] List of required input variables
+    # @param prefix [String, nil] Optional prefix text (for few-shot templates)
+    # @param suffix [String, nil] Optional suffix text (for few-shot templates)
+    # @param examples [Array<Hash>, nil] Optional examples for few-shot learning
+    # @param example_template [String, PromptTemplate, nil] Template for formatting examples
+    # @param partial_variables [Hash] Pre-filled variable values
+    #
+    # @example Basic template
+    #   template = PromptTemplate.new(
+    #     template: "Translate '{text}' to {language}",
+    #     input_variables: [:text, :language]
+    #   )
+    #
+    # @example Few-shot template
+    #   template = PromptTemplate.new(
+    #     prefix: "You are a translator. Here are some examples:",
+    #     suffix: "Now translate: {input}",
+    #     examples: [
+    #       { input: "Hello", output: "Bonjour" },
+    #       { input: "Goodbye", output: "Au revoir" }
+    #     ],
+    #     example_template: "Input: {input}\nOutput: {output}",
+    #     input_variables: [:input]
+    #   )
+    def initialize(template: nil, input_variables: [], prefix: nil, suffix: nil,
+                   examples: nil, example_template: nil, partial_variables: {})
+      @template = template
+      @input_variables = Array(input_variables).map(&:to_sym)
+      @prefix = prefix
+      @suffix = suffix
+      @examples = examples
+      @example_template = build_example_template(example_template)
+      @partial_variables = partial_variables.transform_keys(&:to_sym)
+
+      validate_configuration!
+    end
+
+    # Format the template with provided variables
+    #
+    # @param variables [Hash] Variable values to interpolate
+    # @return [String] Formatted prompt text
+    # @raise [ArgumentError] If required variables are missing
+    def format(variables = {})
+      variables = @partial_variables.merge(variables.transform_keys(&:to_sym))
+      validate_variables!(variables)
+
+      if few_shot_template?
+        format_few_shot(variables)
+      else
+        format_simple(variables)
+      end
+    end
+
+    # Format as chat messages for OpenRouter API
+    #
+    # @param variables [Hash] Variable values to interpolate
+    # @param role [String] Role for the message (user, system, assistant)
+    # @return [Array<Hash>] Messages array for OpenRouter API
+    def to_messages(variables = {})
+      formatted = format(variables)
+
+      # Split by role markers if present (e.g., "System: ... User: ...")
+      if formatted.include?("System:") || formatted.include?("Assistant:") || formatted.include?("User:")
+        parse_chat_format(formatted)
+      else
+        # Default to single user message
+        [{ role: "user", content: formatted }]
+      end
+    end
+
+    # Create a partial template with some variables pre-filled
+    #
+    # @param partial_variables [Hash] Variables to pre-fill
+    # @return [PromptTemplate] New template with partial variables
+    def partial(partial_variables = {})
+      self.class.new(
+        template: @template,
+        input_variables: @input_variables - partial_variables.keys.map(&:to_sym),
+        prefix: @prefix,
+        suffix: @suffix,
+        examples: @examples,
+        example_template: @example_template,
+        partial_variables: @partial_variables.merge(partial_variables.transform_keys(&:to_sym))
+      )
+    end
+
+    # Check if this is a few-shot template
+    #
+    # @return [Boolean]
+    def few_shot_template?
+      !@examples.nil? && !@examples.empty?
+    end
+
+    # Class method for convenient DSL-style creation
+    #
+    # @example DSL usage
+    #   template = PromptTemplate.build do
+    #     template "Translate '{text}' to {language}"
+    #     variables :text, :language
+    #   end
+    def self.build(&block)
+      builder = Builder.new
+      builder.instance_eval(&block)
+      builder.build
+    end
+
+    private
+
+    def validate_configuration!
+      raise ArgumentError, "Either template or suffix must be provided" if @template.nil? && @suffix.nil?
+
+      return unless few_shot_template? && @example_template.nil?
+
+      raise ArgumentError, "example_template is required when examples are provided"
+    end
+
+    def validate_variables!(variables)
+      missing = @input_variables - variables.keys
+      return if missing.empty?
+
+      raise ArgumentError, "Missing required variables: #{missing.join(", ")}"
+    end
+
+    def format_simple(variables)
+      interpolate(@template, variables)
+    end
+
+    def format_few_shot(variables)
+      parts = []
+      parts << interpolate(@prefix, variables) if @prefix
+
+      if @examples && @example_template
+        formatted_examples = @examples.map do |example|
+          # Use only the example data for formatting, not user-provided variables
+          @example_template.format(example)
+        end
+        parts.concat(formatted_examples)
+      end
+
+      parts << interpolate(@suffix, variables) if @suffix
+      parts.join("\n\n")
+    end
+
+    def interpolate(text, variables)
+      return "" if text.nil?
+
+      result = text.dup
+      variables.each do |key, value|
+        # Support both {var} and {var:format} syntax
+        result.gsub!(/\{#{Regexp.escape(key.to_s)}(?::[^}]+)?\}/, value.to_s)
+      end
+      result
+    end
+
+    def build_example_template(template)
+      case template
+      when PromptTemplate
+        template
+      when String
+        PromptTemplate.new(
+          template: template,
+          input_variables: extract_variables(template)
+        )
+      when nil
+        nil
+      else
+        raise ArgumentError, "example_template must be a String or PromptTemplate"
+      end
+    end
+
+    def extract_variables(text)
+      return [] if text.nil?
+
+      # Extract {variable} or {variable:format} patterns
+      text.scan(/\{(\w+)(?::[^}]+)?\}/).flatten.map(&:to_sym).uniq
+    end
+
+    def parse_chat_format(text)
+      messages = []
+      current_role = "user"
+      current_content = []
+
+      text.lines.each do |line|
+        if line.start_with?("System:")
+          unless current_content.empty?
+            messages << { role: current_role, content: current_content.join.strip }
+            current_content = []
+          end
+          current_role = "system"
+          current_content << line.sub("System:", "").strip
+        elsif line.start_with?("Assistant:")
+          unless current_content.empty?
+            messages << { role: current_role, content: current_content.join.strip }
+            current_content = []
+          end
+          current_role = "assistant"
+          current_content << line.sub("Assistant:", "").strip
+        elsif line.start_with?("User:")
+          unless current_content.empty?
+            messages << { role: current_role, content: current_content.join.strip }
+            current_content = []
+          end
+          current_role = "user"
+          current_content << line.sub("User:", "").strip
+        else
+          current_content << "\n" unless current_content.empty?
+          current_content << line
+        end
+      end
+
+      messages << { role: current_role, content: current_content.join.strip } unless current_content.empty?
+
+      messages
+    end
+
+    # Builder class for DSL-style template creation
+    class Builder
+      def initialize
+        @config = {}
+      end
+
+      def template(text)
+        @config[:template] = text
+      end
+
+      def variables(*vars)
+        @config[:input_variables] = vars
+      end
+
+      def prefix(text)
+        @config[:prefix] = text
+      end
+
+      def suffix(text)
+        @config[:suffix] = text
+      end
+
+      def examples(examples_array)
+        @config[:examples] = examples_array
+      end
+
+      def example_template(template)
+        @config[:example_template] = template
+      end
+
+      def partial_variables(vars)
+        @config[:partial_variables] = vars
+      end
+
+      def build
+        PromptTemplate.new(**@config)
+      end
+    end
+  end
+
+  # Convenient factory methods
+  module Prompt
+    # Create a simple prompt template
+    def self.template(template, variables: [])
+      PromptTemplate.new(template: template, input_variables: variables)
+    end
+
+    # Create a few-shot prompt template
+    def self.few_shot(prefix:, suffix:, examples:, example_template:, variables:)
+      PromptTemplate.new(
+        prefix: prefix,
+        suffix: suffix,
+        examples: examples,
+        example_template: example_template,
+        input_variables: variables
+      )
+    end
+
+    # Create a chat-style template
+    def self.chat(&block)
+      PromptTemplate.build(&block)
+    end
+  end
+end

data/lib/open_router/response.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+require "json"
+require "active_support/core_ext/hash/indifferent_access"
+
+module OpenRouter
+  class StructuredOutputError < Error; end
+
+  class Response
+    attr_reader :raw_response, :response_format, :forced_extraction
+    attr_accessor :client
+
+    def initialize(raw_response, response_format: nil, forced_extraction: false)
+      @raw_response = raw_response.is_a?(Hash) ? raw_response.with_indifferent_access : {}
+      @response_format = response_format
+      @forced_extraction = forced_extraction
+      @client = nil
+    end
+
+    # Delegate common hash methods to raw_response for backward compatibility
+    def [](key)
+      @raw_response[key]
+    end
+
+    def dig(*keys)
+      @raw_response.dig(*keys)
+    end
+
+    def fetch(key, default = nil)
+      @raw_response.fetch(key, default)
+    end
+
+    def key?(key)
+      @raw_response.key?(key)
+    end
+
+    def keys
+      @raw_response.keys
+    end
+
+    def has_key?(key)
+      @raw_response.key?(key)
+    end
+
+    def to_h
+      @raw_response.to_h
+    end
+
+    def to_json(*args)
+      @raw_response.to_json(*args)
+    end
+
+    # Tool calling methods
+    def tool_calls
+      @tool_calls ||= parse_tool_calls
+    end
+
+    def has_tool_calls?
+      !tool_calls.empty?
+    end
+
+    # Convert response to message format for conversation continuation
+    def to_message
+      if has_tool_calls?
+        {
+          role: "assistant",
+          content: content,
+          tool_calls: raw_tool_calls
+        }
+      else
+        {
+          role: "assistant",
+          content: content
+        }
+      end
+    end
+
+    # Structured output methods
+    def structured_output(mode: nil, auto_heal: nil)
+      # Use global default mode if not specified
+      if mode.nil?
+        mode = if @client&.configuration.respond_to?(:default_structured_output_mode)
+                 @client.configuration.default_structured_output_mode || :strict
+               else
+                 :strict
+               end
+      end
+      # Validate mode parameter
+      raise ArgumentError, "Invalid mode: #{mode}. Must be :strict or :gentle." unless %i[strict gentle].include?(mode)
+
+      return nil unless structured_output_expected? && has_content?
+
+      case mode
+      when :strict
+        # The existing logic for strict parsing and healing
+        should_heal = if auto_heal.nil?
+                        @client&.configuration&.auto_heal_responses
+                      else
+                        auto_heal
+                      end
+
+        result = parse_and_heal_structured_output(auto_heal: should_heal)
+
+        # Only validate after parsing if healing is disabled (healing handles its own validation)
+        if result && !should_heal
+          schema_obj = extract_schema_from_response_format
+          if schema_obj && !schema_obj.validate(result)
+            validation_errors = schema_obj.validation_errors(result)
+            raise StructuredOutputError, "Schema validation failed: #{validation_errors.join(", ")}"
+          end
+        end
+
+        @structured_output ||= result
+      when :gentle
+        # New gentle mode: best-effort parsing, no healing, no validation
+        content_to_parse = @forced_extraction ? extract_json_from_text(content) : content
+        return nil if content_to_parse.nil?
+
+        begin
+          JSON.parse(content_to_parse)
+        rescue JSON::ParserError
+          nil # Return nil on failure instead of raising an error
+        end
+      end
+    end
+
+    def valid_structured_output?
+      return true unless structured_output_expected?
+
+      schema_obj = extract_schema_from_response_format
+      return true unless schema_obj
+
+      begin
+        parsed_output = structured_output
+        return false unless parsed_output
+
+        schema_obj.validate(parsed_output)
+      rescue StructuredOutputError
+        false
+      end
+    end
+
+    def validation_errors
+      return [] unless structured_output_expected?
+
+      schema_obj = extract_schema_from_response_format
+      return [] unless schema_obj
+
+      begin
+        parsed_output = structured_output
+        return [] unless parsed_output
+
+        schema_obj.validation_errors(parsed_output)
+      rescue StructuredOutputError
+        ["Failed to parse structured output"]
+      end
+    end
+
+    # Content accessors
+    def content
+      choices.first&.dig("message", "content")
+    end
+
+    def choices
+      @raw_response["choices"] || []
+    end
+
+    def usage
+      @raw_response["usage"]
+    end
+
+    def id
+      @raw_response["id"]
+    end
+
+    def model
+      @raw_response["model"]
+    end
+
+    def created
+      @raw_response["created"]
+    end
+
+    def object
+      @raw_response["object"]
+    end
+
+    # Provider information
+    def provider
+      @raw_response["provider"]
+    end
+
+    # System fingerprint (model version identifier)
+    def system_fingerprint
+      @raw_response["system_fingerprint"]
+    end
+
+    # Native finish reason from the provider
+    def native_finish_reason
+      choices.first&.dig("native_finish_reason")
+    end
+
+    # Finish reason (standard OpenRouter format)
+    def finish_reason
+      choices.first&.dig("finish_reason")
+    end
+
+    # Cached tokens (tokens served from cache)
+    def cached_tokens
+      usage&.dig("prompt_tokens_details", "cached_tokens") || 0
+    end
+
+    # Total prompt tokens
+    def prompt_tokens
+      usage&.dig("prompt_tokens") || 0
+    end
+
+    # Total completion tokens
+    def completion_tokens
+      usage&.dig("completion_tokens") || 0
+    end
+
+    # Total tokens (prompt + completion)
+    def total_tokens
+      usage&.dig("total_tokens") || 0
+    end
+
+    # Get estimated cost for this response
+    # Note: This requires an additional API call to /generation endpoint
+    def cost_estimate
+      return nil unless id && client
+
+      @cost_estimate ||= client.query_generation_stats(id)&.dig("cost")
+    rescue StandardError
+      nil
+    end
+
+    # Convenience method to check if response has content
+    def has_content?
+      !content.nil? && !content.empty?
+    end
+
+    # Convenience method to check if response indicates an error
+    def error?
+      @raw_response.key?("error")
+    end
+
+    def error_message
+      @raw_response.dig("error", "message")
+    end
+
+    private
+
+    def parse_tool_calls
+      tool_calls_data = choices.first&.dig("message", "tool_calls")
+      return [] unless tool_calls_data.is_a?(Array)
+
+      tool_calls_data.map { |tc| ToolCall.new(tc) }
+    rescue StandardError => e
+      raise ToolCallError, "Failed to parse tool calls: #{e.message}"
+    end
+
+    def raw_tool_calls
+      choices.first&.dig("message", "tool_calls") || []
+    end
+
+    def parse_and_heal_structured_output(auto_heal: false)
+      return nil unless structured_output_expected?
+      return nil unless has_content?
+
+      content_to_parse = @forced_extraction ? extract_json_from_text(content) : content
+
+      if auto_heal && @client
+        # For forced extraction: always send full content to provide context for healing
+        # For normal responses: send the content as-is
+        healing_content = if @forced_extraction
+                            content # Always send full response for better healing context
+                          else
+                            content_to_parse || content
+                          end
+        heal_structured_response(healing_content, extract_schema_from_response_format)
+      else
+        return nil if content_to_parse.nil? # No JSON found in forced extraction
+
+        begin
+          JSON.parse(content_to_parse)
+        rescue JSON::ParserError => e
+          # For forced extraction, be more lenient and return nil on parse failures
+          # For regular structured outputs, return nil if content looks like it contains markdown
+          # (indicates it's not actually structured JSON output)
+          if @forced_extraction
+            nil
+          elsif content_to_parse&.include?("```")
+            # Content contains markdown blocks - this is not structured output
+            nil
+          else
+            raise StructuredOutputError, "Failed to parse structured output: #{e.message}"
+          end
+        end
+      end
+    end
+
+    # Extract JSON from text content (for forced structured output)
+    def extract_json_from_text(text)
+      return nil if text.nil? || text.empty?
+
+      # First try to find JSON in code blocks
+      if text.include?("```")
+        # Look for ```json or ``` blocks
+        json_match = text.match(/```(?:json)?\s*\n?(.*?)\n?```/m)
+        if json_match
+          candidate = json_match[1].strip
+          return candidate unless candidate.empty?
+        end
+      end
+
+      # Try to parse the entire text as JSON
+      begin
+        JSON.parse(text)
+        return text
+      rescue JSON::ParserError
+        # Look for JSON-like content (starts with { or [)
+        json_match = text.match(/(\{.*\}|\[.*\])/m)
+        return json_match[1] if json_match
+      end
+
+      # No JSON found
+      nil
+    end
+
+    def structured_output_expected?
+      return false unless @response_format
+
+      if @response_format.is_a?(Schema)
+        true
+      elsif @response_format.is_a?(Hash) && @response_format[:type] == "json_schema"
+        true
+      else
+        false
+      end
+    end
+
+    def extract_schema_from_response_format
+      case @response_format
+      when Schema
+        @response_format
+      when Hash
+        schema_def = @response_format[:json_schema]
+        if schema_def.is_a?(Schema)
+          schema_def
+        elsif schema_def.is_a?(Hash) && schema_def[:schema]
+          # Create a temporary schema object for validation
+          Schema.new(
+            schema_def[:name] || "response",
+            schema_def[:schema],
+            strict: schema_def.key?(:strict) ? schema_def[:strict] : true
+          )
+        end
+      end
+    end
+
+    # Backward compatibility method that delegates to JsonHealer
+    def heal_structured_response(content, schema)
+      return JSON.parse(content) unless schema
+
+      healer = JsonHealer.new(@client)
+      context = @forced_extraction ? :forced_extraction : :generic
+      healer.heal(content, schema, context: context)
+    end
+  end
+end