open_router_enhanced 1.0.0

data/lib/open_router/json_healer.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenRouter
+  # A dedicated class for extracting, cleaning, and healing malformed JSON
+  # responses from language models.
+  class JsonHealer
+    # Regex to find a JSON object or array within a markdown code block.
+    # It handles optional "json" language identifier. Non-greedy `.*?` is key.
+    CODE_BLOCK_JSON_REGEX = /```(?:json)?\s*\n?(.*?)\n?```/m
+
+    # Regex to find JSON that isn't in a code block. Looks for the first
+    # `{` or `[` and captures until the matching last `}` or `]`. This is
+    # a heuristic and might not be perfect for all cases.
+    LOOSE_JSON_REGEX = /(\{.*\}|\[.*\])/m
+
+    def initialize(client)
+      @client = client
+      @configuration = client.configuration
+    end
+
+    # Enhanced heal method that supports different healing contexts
+    def heal(raw_text, schema, context: :generic)
+      candidate_json = extract_json_candidate(raw_text)
+      raise StructuredOutputError, "No JSON-like content found in the response." if candidate_json.nil?
+
+      attempts = 0
+      max_attempts = @configuration.max_heal_attempts
+      original_content = raw_text # Keep track of original for forced extraction context
+      all_errors = [] # Track all errors encountered during healing
+
+      loop do
+        # Attempt to parse after simple cleanup
+        parsed_json = JSON.parse(cleanup_syntax(candidate_json))
+
+        # If parsing succeeds, validate against the schema
+        if schema.validation_available? && !schema.validate(parsed_json)
+          errors = schema.validation_errors(parsed_json)
+          raise SchemaValidationError, "Schema validation failed: #{errors.join(", ")}"
+        end
+
+        return parsed_json # Success!
+      rescue JSON::ParserError, SchemaValidationError => e
+        attempts += 1
+        all_errors << e.message
+
+        if attempts > max_attempts
+          final_error_message = build_final_error_message(e, schema, candidate_json, max_attempts)
+          raise StructuredOutputError, final_error_message
+        end
+
+        # Escalate to LLM-based healing with proper context
+        candidate_json = fix_with_healer_model(candidate_json, schema, e.message, e.class, original_content, context)
+      end
+    end
+
+    private
+
+    # Stage 1: Intelligently extract the JSON string from raw text.
+    def extract_json_candidate(text)
+      # 1. Prioritize markdown code blocks, as they are the most explicit.
+      match = text.match(CODE_BLOCK_JSON_REGEX)
+      return match[1].strip if match
+
+      # 2. If no code block, look for the text after a "JSON:" label.
+      # This handles "Here is the JSON: {...}"
+      text_after_colon = text.split(/json:/i).last
+      return text_after_colon.strip if text_after_colon && text_after_colon.length < text.length
+
+      # 3. As a fallback, try to find the first balanced JSON-like structure.
+      match = text.match(LOOSE_JSON_REGEX)
+      return match[1].strip if match
+
+      # 4. If nothing else works, check if the whole text looks like JSON before using it.
+      trimmed = text.strip
+      return trimmed if trimmed.start_with?("{", "[")
+
+      # 5. No JSON-like content found
+      nil
+    end
+
+    # Stage 2: Perform simple, deterministic syntax cleanup.
+    def cleanup_syntax(json_string)
+      # Remove trailing commas from objects and arrays, a very common LLM error.
+      json_string
+        .gsub(/,\s*(\}|\])/, '\1') # Remove trailing commas: ",}" -> "}" and ",]" -> "]"
+    end
+
+    # Stage 4: Use an LLM to fix the broken JSON.
+    def fix_with_healer_model(broken_json, schema, error_reason, error_class, original_content, context)
+      healer_model = @configuration.healer_model
+      prompt = build_healing_prompt(broken_json, schema, error_reason, error_class, original_content, context)
+
+      # Trigger on_healing callback with healing context
+      if @client.respond_to?(:trigger_callbacks)
+        @client.trigger_callbacks(:on_healing, {
+                                    broken_json: broken_json,
+                                    error: error_reason,
+                                    schema: schema,
+                                    healer_model: healer_model,
+                                    context: context
+                                  })
+      end
+
+      healing_response = @client.complete(
+        [{ role: "user", content: prompt }],
+        model: healer_model,
+        extras: { temperature: 0.0, max_tokens: 4000 }
+      )
+
+      # The healer's response is now our new best candidate.
+      # We extract it again in case the healer also added fluff.
+      healed_json = extract_json_candidate(healing_response.content)
+
+      # Trigger callback with healing result
+      if @client.respond_to?(:trigger_callbacks)
+        @client.trigger_callbacks(:on_healing, {
+                                    healed: true,
+                                    original: broken_json,
+                                    result: healed_json
+                                  })
+      end
+
+      healed_json
+    rescue StandardError => e
+      # If the healing call itself fails, we can't proceed.
+      # Return the original broken content to let the loop fail naturally.
+      warn "[OpenRouter Warning] JSON healing request failed: #{e.message}"
+
+      # Trigger callback for failed healing
+      if @client.respond_to?(:trigger_callbacks)
+        @client.trigger_callbacks(:on_healing, {
+                                    healed: false,
+                                    error: e.message,
+                                    original: broken_json
+                                  })
+      end
+
+      broken_json
+    end
+
+    def build_healing_prompt(content, schema, error_reason, error_class, original_content, context)
+      # Use schema.to_h instead of pure_schema for consistency with existing tests
+      schema_json = schema.respond_to?(:to_h) ? schema.to_h.to_json : schema.to_json
+
+      case error_class.name
+      when "JSON::ParserError"
+        build_json_parsing_prompt(content, error_reason)
+      when "OpenRouter::SchemaValidationError"
+        if forced_extraction_context?(context, original_content, content)
+          build_forced_extraction_prompt(original_content, schema_json, error_reason)
+        else
+          build_schema_validation_prompt(content, schema_json, error_reason)
+        end
+      else
+        build_generic_prompt(content, schema_json, error_reason)
+      end
+    end
+
+    def build_json_parsing_prompt(content, error_reason)
+      <<~PROMPT
+        Invalid JSON: #{error_reason}
+
+        Content to fix:
+        #{content}
+
+        Please fix this content to be valid JSON. Return ONLY the fixed JSON, no explanations or additional text.
+      PROMPT
+    end
+
+    def build_schema_validation_prompt(content, schema_json, error_reason)
+      <<~PROMPT
+        The following JSON content is invalid because it failed to validate against the provided JSON Schema.
+
+        Validation Errors:
+        #{error_reason}
+
+        Original Content to Fix:
+        ```json
+        #{content}
+        ```
+
+        Required JSON Schema:
+        ```json
+        #{schema_json}
+        ```
+
+        Please correct the content to produce a valid JSON object that strictly conforms to the schema.
+        Return ONLY the fixed, raw JSON object, without any surrounding text or explanations.
+      PROMPT
+    end
+
+    def build_forced_extraction_prompt(original_content, schema_json, error_reason)
+      <<~PROMPT
+        The following response contains explanatory text and JSON that needs to be extracted and fixed to conform to the provided schema.
+
+        Validation Errors:
+        #{error_reason}
+
+        Original Response Content:
+        #{original_content}
+
+        Required JSON Schema:
+        ```json
+        #{schema_json}
+        ```
+
+        Please extract and correct the JSON from the response above to produce a valid JSON object that strictly conforms to the schema.
+        Return ONLY the fixed, raw JSON object, without any surrounding text or explanations.
+      PROMPT
+    end
+
+    def build_generic_prompt(content, schema_json, error_reason)
+      <<~PROMPT
+        You are an expert JSON fixing bot. Your task is to correct a malformed JSON string so that it becomes syntactically valid AND conforms to a given JSON Schema.
+
+        The user's JSON is invalid for the following reason:
+        #{error_reason}
+
+        Here is the malformed JSON content to fix:
+        ```
+        #{content}
+        ```
+
+        It MUST be corrected to strictly conform to the following JSON Schema:
+        ```json
+        #{schema_json}
+        ```
+
+        CRITICAL INSTRUCTIONS:
+        1.  Analyze the error, the broken JSON, and the schema.
+        2.  Correct the JSON so it is syntactically perfect and valid against the schema.
+        3.  Return ONLY the raw, corrected JSON object. Do not include any text, explanations, or markdown fences.
+      PROMPT
+    end
+
+    def forced_extraction_context?(context, original_content, content)
+      context == :forced_extraction ||
+        (original_content != content && (original_content.include?("```") || original_content.length > 200 || original_content.include?("\n")))
+    end
+
+    def build_final_error_message(error, schema, candidate_json, max_attempts)
+      base_message = "Failed to heal JSON after #{max_attempts} healing attempts. Last error: #{error.message}"
+
+      return base_message unless error.is_a?(SchemaValidationError) && schema.validation_available?
+
+      # For schema validation errors, include specific validation details
+      parsed_json_for_errors = safely_parse_json(candidate_json)
+      return base_message unless parsed_json_for_errors
+
+      validation_errors = schema.validation_errors(parsed_json_for_errors)
+      error_details = validation_errors.any? ? ". Last errors: #{validation_errors.join(", ")}" : ""
+      "#{base_message}#{error_details}"
+    end
+
+    def safely_parse_json(candidate_json)
+      JSON.parse(cleanup_syntax(candidate_json))
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/open_router/model_registry.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "tmpdir"
+require "fileutils"
+require "openssl"
+
+module OpenRouter
+  class ModelRegistryError < Error; end
+
+  class ModelRegistry
+    API_BASE = "https://openrouter.ai/api/v1"
+    CACHE_DIR = File.join(Dir.tmpdir, "openrouter_cache")
+    CACHE_DATA_FILE = File.join(CACHE_DIR, "models_data.json")
+    CACHE_METADATA_FILE = File.join(CACHE_DIR, "cache_metadata.json")
+    MAX_CACHE_SIZE_MB = 50 # Maximum cache size in megabytes
+
+    class << self
+      # Fetch models from OpenRouter API
+      def fetch_models_from_api
+        uri = URI("#{API_BASE}/models")
+
+        # Use configurable timeout and SSL settings
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.read_timeout = OpenRouter.configuration.model_registry_timeout
+        http.open_timeout = OpenRouter.configuration.model_registry_timeout
+
+        request = Net::HTTP::Get.new(uri)
+        response = http.request(request)
+
+        unless response.code == "200"
+          raise ModelRegistryError,
+                "Failed to fetch models from OpenRouter API: #{response.message}"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise ModelRegistryError, "Failed to parse OpenRouter API response: #{e.message}"
+      rescue StandardError => e
+        raise ModelRegistryError, "Network error fetching models: #{e.message}"
+      end
+
+      # Ensure cache directory exists and set up cleanup
+      def ensure_cache_dir
+        FileUtils.mkdir_p(CACHE_DIR) unless Dir.exist?(CACHE_DIR)
+        setup_cleanup_hook
+      end
+
+      # Check if cache is stale based on TTL
+      def cache_stale?
+        return true unless File.exist?(CACHE_METADATA_FILE)
+
+        begin
+          metadata = JSON.parse(File.read(CACHE_METADATA_FILE))
+          cache_time = metadata["cached_at"]
+          ttl = OpenRouter.configuration.cache_ttl
+
+          return true unless cache_time
+
+          Time.now.to_i - cache_time.to_i > ttl
+        rescue JSON::ParserError, StandardError
+          true # If we can't read metadata, consider cache stale
+        end
+      end
+
+      # Write cache with timestamp metadata
+      def write_cache_with_timestamp(models_data)
+        ensure_cache_dir
+
+        # Write the actual models data
+        File.write(CACHE_DATA_FILE, JSON.pretty_generate(models_data))
+
+        # Write metadata with timestamp
+        metadata = {
+          "cached_at" => Time.now.to_i,
+          "version" => "1.0",
+          "source" => "openrouter_api"
+        }
+        File.write(CACHE_METADATA_FILE, JSON.pretty_generate(metadata))
+      end
+
+      # Read cache only if it's fresh
+      def read_cache_if_fresh
+        return nil if cache_stale?
+        return nil unless File.exist?(CACHE_DATA_FILE)
+
+        JSON.parse(File.read(CACHE_DATA_FILE))
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Clear local cache (both files and memory)
+      def clear_cache!
+        FileUtils.rm_rf(CACHE_DIR) if Dir.exist?(CACHE_DIR)
+        @processed_models = nil
+        @all_models = nil
+      end
+
+      # Refresh models data from API
+      def refresh!
+        clear_cache!
+        fetch_and_cache_models
+      end
+
+      # Get processed models (fetch if needed)
+      def fetch_and_cache_models
+        # Try cache first (only if fresh)
+        cached_data = read_cache_if_fresh
+
+        if cached_data
+          api_data = cached_data
+        else
+          # Cache is stale or doesn't exist, fetch from API
+          api_data = fetch_models_from_api
+          write_cache_with_timestamp(api_data)
+        end
+
+        @processed_models = process_api_models(api_data["data"])
+      end
+
+      # Find original API model data by model ID
+      def find_original_model_data(model_id)
+        # Get raw models data (not processed)
+        cached_data = read_cache_if_fresh
+
+        if cached_data
+          api_data = cached_data
+        else
+          api_data = fetch_models_from_api
+          write_cache_with_timestamp(api_data)
+        end
+
+        raw_models = api_data["data"] || []
+        raw_models.find { |model| model["id"] == model_id }
+      end
+
+      # Convert API model data to our internal format
+      def process_api_models(api_models)
+        models = {}
+
+        api_models.each do |model_data|
+          model_id = model_data["id"]
+
+          models[model_id] = {
+            name: model_data["name"],
+            cost_per_1k_tokens: {
+              input: model_data.dig("pricing", "prompt").to_f,
+              output: model_data.dig("pricing", "completion").to_f
+            },
+            context_length: model_data["context_length"],
+            capabilities: extract_capabilities(model_data),
+            description: model_data["description"],
+            supported_parameters: model_data["supported_parameters"] || [],
+            architecture: model_data["architecture"],
+            performance_tier: determine_performance_tier(model_data),
+            fallbacks: determine_fallbacks(model_id, model_data),
+            created_at: model_data["created"]
+          }
+        end
+
+        models
+      end
+
+      # Extract capabilities from model data
+      def extract_capabilities(model_data)
+        capabilities = [:chat] # All models support basic chat
+
+        # Check for function calling support
+        supported_params = model_data["supported_parameters"] || []
+        if supported_params.include?("tools") && supported_params.include?("tool_choice")
+          capabilities << :function_calling
+        end
+
+        # Check for structured output support
+        if supported_params.include?("structured_outputs") || supported_params.include?("response_format")
+          capabilities << :structured_outputs
+        end
+
+        # Check for vision support
+        architecture = model_data["architecture"] || {}
+        input_modalities = architecture["input_modalities"] || []
+        capabilities << :vision if input_modalities.include?("image")
+
+        # Check for large context support
+        context_length = model_data["context_length"] || 0
+        capabilities << :long_context if context_length > 100_000
+
+        capabilities
+      end
+
+      # Determine performance tier based on pricing and capabilities
+      def determine_performance_tier(model_data)
+        input_cost = model_data.dig("pricing", "prompt").to_f
+
+        # Higher cost generally indicates premium models
+        # Note: pricing is per token, not per 1k tokens
+        if input_cost > 0.000001 # > $0.001 per 1k tokens (converted from per-token)
+          :premium
+        else
+          :standard
+        end
+      end
+
+      # Determine fallback models (simplified logic)
+      def determine_fallbacks(_model_id, _model_data)
+        # For now, return empty array - could be enhanced with smart fallback logic
+        []
+      end
+
+      # Find the best model matching given requirements
+      def find_best_model(requirements = {})
+        candidates = models_meeting_requirements(requirements)
+        return nil if candidates.empty?
+
+        # If pick_newer is true, prefer newer models over cost
+        if requirements[:pick_newer]
+          candidates.max_by { |_, specs| specs[:created_at] }
+        else
+          # Sort by cost (cheapest first) as default strategy
+          candidates.min_by { |_, specs| calculate_model_cost(specs, requirements) }
+        end
+      end
+
+      # Get all models that meet requirements (without sorting)
+      def models_meeting_requirements(requirements = {})
+        all_models.select do |_model, specs|
+          meets_requirements?(specs, requirements)
+        end
+      end
+
+      # Get fallback models for a given model
+      def get_fallbacks(model)
+        model_info = get_model_info(model)
+        model_info ? model_info[:fallbacks] || [] : []
+      end
+
+      # Check if a model exists in the registry
+      def model_exists?(model)
+        all_models.key?(model)
+      end
+
+      # Check if a model has a specific capability
+      def has_capability?(model, capability)
+        model_info = get_model_info(model)
+        return false unless model_info
+
+        model_info[:capabilities].include?(capability)
+      end
+
+      # Get detailed information about a model
+      def get_model_info(model)
+        all_models[model]
+      end
+
+      # Get all registered models (fetch from API if needed)
+      def all_models
+        @all_models ||= fetch_and_cache_models
+      end
+
+      # Calculate estimated cost for a request
+      def calculate_estimated_cost(model, input_tokens: 0, output_tokens: 0)
+        model_info = get_model_info(model)
+        return 0 unless model_info
+
+        input_cost = (input_tokens / 1000.0) * model_info[:cost_per_1k_tokens][:input]
+        output_cost = (output_tokens / 1000.0) * model_info[:cost_per_1k_tokens][:output]
+
+        input_cost + output_cost
+      end
+
+      private
+
+      # Check if model specs meet the given requirements
+      def meets_requirements?(specs, requirements)
+        # Check capability requirements
+        if requirements[:capabilities]
+          required_caps = Array(requirements[:capabilities])
+          return false unless required_caps.all? { |cap| specs[:capabilities].include?(cap) }
+        end
+
+        # Check cost requirements
+        if requirements[:max_input_cost] && (specs[:cost_per_1k_tokens][:input] > requirements[:max_input_cost])
+          return false
+        end
+
+        if requirements[:max_output_cost] && (specs[:cost_per_1k_tokens][:output] > requirements[:max_output_cost])
+          return false
+        end
+
+        # Check context length requirements
+        if requirements[:min_context_length] && (specs[:context_length] < requirements[:min_context_length])
+          return false
+        end
+
+        # Check performance tier requirements
+        if requirements[:performance_tier]
+          required_tier = requirements[:performance_tier]
+          model_tier = specs[:performance_tier]
+
+          # Premium tier can satisfy premium or standard requirements
+          # Standard tier can only satisfy standard requirements
+          case required_tier
+          when :premium
+            return false unless model_tier == :premium
+          when :standard
+            return false unless %i[standard premium].include?(model_tier)
+          end
+        end
+
+        # Check released after date requirement
+        if requirements[:released_after_date]
+          required_date = requirements[:released_after_date]
+          model_timestamp = specs[:created_at]
+
+          # Convert date to timestamp if needed
+          required_timestamp = case required_date
+                               when Date
+                                 required_date.to_time.to_i
+                               when Time
+                                 required_date.to_i
+                               when Integer
+                                 required_date
+                               else
+                                 return false
+                               end
+
+          return false if model_timestamp < required_timestamp
+        end
+
+        true
+      end
+
+      # Calculate the cost metric for sorting models
+      def calculate_model_cost(specs, _requirements)
+        # Simple cost calculation for sorting - could be made more sophisticated
+        # For now, just use input token cost as the primary metric
+        specs[:cost_per_1k_tokens][:input]
+      end
+
+      # Set up cleanup hook to manage cache size
+      def setup_cleanup_hook
+        return if @cleanup_hook_set
+
+        at_exit { cleanup_oversized_cache }
+        @cleanup_hook_set = true
+      end
+
+      # Clean up cache if it exceeds size limits
+      def cleanup_oversized_cache
+        return unless Dir.exist?(CACHE_DIR)
+
+        cache_size_mb = calculate_cache_size_mb
+        return unless cache_size_mb > MAX_CACHE_SIZE_MB
+
+        # Remove cache files if oversized
+        FileUtils.rm_rf(CACHE_DIR)
+      rescue StandardError
+        # Silently ignore cleanup errors - don't break the application
+      end
+
+      # Calculate current cache size in megabytes
+      def calculate_cache_size_mb
+        total_size = Dir.glob(File.join(CACHE_DIR, "**/*"))
+                        .select { |f| File.file?(f) }
+                        .sum do |f|
+          File.size(f)
+        rescue StandardError
+          0
+        end
+        total_size / (1024.0 * 1024.0)
+      end
+    end
+  end
+end