open_router_enhanced 1.0.0

data/lib/open_router/tool_call.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenRouter
+  class ToolCallError < Error; end
+
+  class ToolCall
+    attr_reader :id, :type, :function_name, :arguments_string
+
+    def initialize(tool_call_data)
+      @id = tool_call_data["id"]
+      @type = tool_call_data["type"]
+
+      raise ToolCallError, "Invalid tool call data: missing function" unless tool_call_data["function"]
+
+      @function_name = tool_call_data["function"]["name"]
+      @arguments_string = tool_call_data["function"]["arguments"]
+    end
+
+    # Parse the arguments JSON string into a Ruby hash
+    def arguments
+      @arguments ||= begin
+        JSON.parse(@arguments_string)
+      rescue JSON::ParserError => e
+        raise ToolCallError, "Failed to parse tool call arguments: #{e.message}"
+      end
+    end
+
+    # Get the function name (alias for consistency)
+    def name
+      @function_name
+    end
+
+    # Execute the tool call with a provided block
+    # The block should accept (name, arguments) and return the result
+    def execute(&block)
+      raise ArgumentError, "Block required for tool execution" unless block_given?
+
+      begin
+        result = block.call(@function_name, arguments)
+        ToolResult.new(self, result)
+      rescue StandardError => e
+        ToolResult.new(self, nil, e.message)
+      end
+    end
+
+    # Convert this tool call to a message format for conversation continuation
+    def to_message
+      {
+        role: "assistant",
+        content: nil,
+        tool_calls: [
+          {
+            id: @id,
+            type: @type,
+            function: {
+              name: @function_name,
+              arguments: @arguments_string
+            }
+          }
+        ]
+      }
+    end
+
+    # Convert a tool result to a tool message for the conversation
+    def to_result_message(result)
+      content = case result
+                when String then result
+                when nil then ""
+                else result.to_json
+                end
+
+      {
+        role: "tool",
+        tool_call_id: @id,
+        content: content
+      }
+    end
+
+    def to_h
+      {
+        id: @id,
+        type: @type,
+        function: {
+          name: @function_name,
+          arguments: @arguments_string
+        }
+      }
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Validate against a provided array of tools (Tool instances or hashes)
+    def valid?(tools:)
+      # tools is now a required keyword argument
+
+      schema = find_schema_for_call(tools)
+      return true unless schema # No validation if tool not found
+
+      return JSON::Validator.validate(schema, arguments) if validation_available?
+
+      # Fallback: shallow required check
+      required = Array(schema[:required]).map(&:to_s)
+      required.all? { |k| arguments.key?(k) }
+    rescue StandardError
+      false
+    end
+
+    def validation_errors(tools:)
+      # tools is now a required keyword argument
+
+      schema = find_schema_for_call(tools)
+      return [] unless schema # No errors if tool not found
+
+      return JSON::Validator.fully_validate(schema, arguments) if validation_available?
+
+      # Fallback: check required fields
+      required = Array(schema[:required]).map(&:to_s)
+      missing = required.reject { |k| arguments.key?(k) }
+      missing.any? ? ["Missing required keys: #{missing.join(", ")}"] : []
+    rescue StandardError => e
+      ["Validation error: #{e.message}"]
+    end
+
+    private
+
+    # Check if JSON schema validation is available
+    def validation_available?
+      !!defined?(JSON::Validator)
+    end
+
+    def find_schema_for_call(tools)
+      tool = Array(tools).find do |t|
+        t_name = t.is_a?(OpenRouter::Tool) ? t.name : t.dig(:function, :name)
+        t_name == @function_name
+      end
+      return nil unless tool
+
+      params = tool.is_a?(OpenRouter::Tool) ? tool.parameters : tool.dig(:function, :parameters)
+      params.is_a?(Hash) ? params : nil
+    end
+  end
+
+  # Represents the result of executing a tool call
+  class ToolResult
+    attr_reader :tool_call, :result, :error
+
+    def initialize(tool_call, result = nil, error = nil)
+      @tool_call = tool_call
+      @result = result
+      @error = error
+    end
+
+    def success?
+      @error.nil?
+    end
+
+    def failure?
+      !success?
+    end
+
+    # Convert to message format for conversation continuation
+    def to_message
+      @tool_call.to_result_message(@error || @result)
+    end
+
+    # Create a failed result
+    def self.failure(tool_call, error)
+      new(tool_call, nil, error)
+    end
+
+    # Create a successful result
+    def self.success(tool_call, result)
+      new(tool_call, result, nil)
+    end
+  end
+end

data/lib/open_router/usage_tracker.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Tracks token usage and costs across API calls
+  class UsageTracker
+    attr_reader :total_prompt_tokens, :total_completion_tokens, :total_cached_tokens,
+                :total_cost, :request_count, :model_usage, :session_start
+
+    def initialize
+      reset!
+    end
+
+    # Reset all tracking counters
+    def reset!
+      @total_prompt_tokens = 0
+      @total_completion_tokens = 0
+      @total_cached_tokens = 0
+      @total_cost = 0.0
+      @request_count = 0
+      @model_usage = Hash.new { |h, k| h[k] = create_model_stats }
+      @session_start = Time.now
+      @request_history = []
+    end
+
+    # Track usage from a response
+    #
+    # @param response [Response] The response object to track
+    # @param model [String] The model used (optional, will try to get from response)
+    def track(response, model: nil)
+      return unless response
+
+      model ||= response.model
+      prompt_tokens = response.prompt_tokens
+      completion_tokens = response.completion_tokens
+      cached_tokens = response.cached_tokens
+      cost = response.cost_estimate || estimate_cost(model, prompt_tokens, completion_tokens)
+
+      # Update totals
+      @total_prompt_tokens += prompt_tokens
+      @total_completion_tokens += completion_tokens
+      @total_cached_tokens += cached_tokens
+      @total_cost += cost if cost
+      @request_count += 1
+
+      # Update per-model stats
+      if model
+        @model_usage[model][:prompt_tokens] += prompt_tokens
+        @model_usage[model][:completion_tokens] += completion_tokens
+        @model_usage[model][:cached_tokens] += cached_tokens
+        @model_usage[model][:cost] += cost if cost
+        @model_usage[model][:requests] += 1
+      end
+
+      # Store in history
+      @request_history << {
+        timestamp: Time.now,
+        model: model,
+        prompt_tokens: prompt_tokens,
+        completion_tokens: completion_tokens,
+        cached_tokens: cached_tokens,
+        cost: cost,
+        response_id: response.id
+      }
+
+      self
+    end
+
+    # Get total tokens used
+    def total_tokens
+      @total_prompt_tokens + @total_completion_tokens
+    end
+
+    # Get average tokens per request
+    def average_tokens_per_request
+      return 0 if @request_count.zero?
+
+      total_tokens.to_f / @request_count
+    end
+
+    # Get average cost per request
+    def average_cost_per_request
+      return 0 if @request_count.zero?
+
+      @total_cost / @request_count
+    end
+
+    # Get session duration in seconds
+    def session_duration
+      Time.now - @session_start
+    end
+
+    # Get tokens per second
+    def tokens_per_second
+      duration = session_duration
+      return 0 if duration.zero?
+
+      total_tokens.to_f / duration
+    end
+
+    # Get most used model
+    def most_used_model
+      return nil if @model_usage.empty?
+
+      @model_usage.max_by { |_, stats| stats[:requests] }&.first
+    end
+
+    # Get most expensive model
+    def most_expensive_model
+      return nil if @model_usage.empty?
+
+      @model_usage.max_by { |_, stats| stats[:cost] }&.first
+    end
+
+    # Get cache hit rate
+    def cache_hit_rate
+      return 0 if @total_prompt_tokens.zero?
+
+      (@total_cached_tokens.to_f / @total_prompt_tokens) * 100
+    end
+
+    # Get usage summary
+    def summary
+      {
+        session: {
+          start: @session_start,
+          duration_seconds: session_duration,
+          requests: @request_count
+        },
+        tokens: {
+          total: total_tokens,
+          prompt: @total_prompt_tokens,
+          completion: @total_completion_tokens,
+          cached: @total_cached_tokens,
+          cache_hit_rate: "#{cache_hit_rate.round(2)}%"
+        },
+        cost: {
+          total: @total_cost.round(4),
+          average_per_request: average_cost_per_request.round(4)
+        },
+        performance: {
+          tokens_per_second: tokens_per_second.round(2),
+          average_tokens_per_request: average_tokens_per_request.round(0)
+        },
+        models: {
+          most_used: most_used_model,
+          most_expensive: most_expensive_model,
+          breakdown: model_breakdown
+        }
+      }
+    end
+
+    # Get model usage breakdown
+    def model_breakdown
+      @model_usage.transform_values do |stats|
+        {
+          requests: stats[:requests],
+          tokens: stats[:prompt_tokens] + stats[:completion_tokens],
+          cost: stats[:cost].round(4),
+          cached_tokens: stats[:cached_tokens]
+        }
+      end
+    end
+
+    # Export usage history as CSV
+    def export_csv
+      require "csv"
+
+      CSV.generate do |csv|
+        csv << ["Timestamp", "Model", "Prompt Tokens", "Completion Tokens", "Cached Tokens", "Cost", "Response ID"]
+        @request_history.each do |entry|
+          csv << [
+            entry[:timestamp].iso8601,
+            entry[:model],
+            entry[:prompt_tokens],
+            entry[:completion_tokens],
+            entry[:cached_tokens],
+            entry[:cost]&.round(4),
+            entry[:response_id]
+          ]
+        end
+      end
+    end
+
+    # Get request history
+    def history(limit: nil)
+      limit ? @request_history.last(limit) : @request_history
+    end
+
+    # Pretty print summary to console
+    def print_summary
+      summary_data = summary
+
+      puts "\n#{"=" * 60}"
+      puts " OpenRouter Usage Summary"
+      puts "=" * 60
+
+      puts "\n📊 Session"
+      puts "  Started: #{summary_data[:session][:start].strftime("%Y-%m-%d %H:%M:%S")}"
+      puts "  Duration: #{format_duration(summary_data[:session][:duration_seconds])}"
+      puts "  Requests: #{summary_data[:session][:requests]}"
+
+      puts "\n🔤 Tokens"
+      puts "  Total: #{format_number(summary_data[:tokens][:total])}"
+      puts "  Prompt: #{format_number(summary_data[:tokens][:prompt])}"
+      puts "  Completion: #{format_number(summary_data[:tokens][:completion])}"
+      puts "  Cached: #{format_number(summary_data[:tokens][:cached])} (#{summary_data[:tokens][:cache_hit_rate]})"
+
+      puts "\n💰 Cost"
+      puts "  Total: $#{summary_data[:cost][:total]}"
+      puts "  Average/Request: $#{summary_data[:cost][:average_per_request]}"
+
+      puts "\n⚡ Performance"
+      puts "  Tokens/Second: #{summary_data[:performance][:tokens_per_second]}"
+      puts "  Average Tokens/Request: #{summary_data[:performance][:average_tokens_per_request]}"
+
+      if summary_data[:models][:breakdown].any?
+        puts "\n🤖 Models Used"
+        summary_data[:models][:breakdown].each do |model, stats|
+          puts "  #{model}:"
+          puts "    Requests: #{stats[:requests]}"
+          puts "    Tokens: #{format_number(stats[:tokens])}"
+          puts "    Cost: $#{stats[:cost]}"
+        end
+      end
+
+      puts "\n#{"=" * 60}"
+    end
+
+    private
+
+    def create_model_stats
+      {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        cached_tokens: 0,
+        cost: 0.0,
+        requests: 0
+      }
+    end
+
+    # Estimate cost if not available from response
+    def estimate_cost(model, prompt_tokens, completion_tokens)
+      return 0 unless model
+
+      # Try to get pricing from model registry
+      model_data = ModelRegistry.get_model(model)
+      return 0 unless model_data
+
+      pricing = model_data["pricing"]
+      return 0 unless pricing
+
+      prompt_cost = (prompt_tokens / 1_000_000.0) * pricing["prompt"].to_f
+      completion_cost = (completion_tokens / 1_000_000.0) * pricing["completion"].to_f
+
+      prompt_cost + completion_cost
+    rescue StandardError
+      0
+    end
+
+    def format_number(num)
+      num.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+
+    def format_duration(seconds)
+      hours = seconds / 3600
+      minutes = (seconds % 3600) / 60
+      seconds %= 60
+
+      parts = []
+      parts << "#{hours.to_i}h" if hours >= 1
+      parts << "#{minutes.to_i}m" if minutes >= 1
+      parts << "#{seconds.to_i}s"
+
+      parts.join(" ")
+    end
+  end
+end

data/lib/open_router/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  VERSION = "1.0.0"
+end

data/lib/open_router.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+
+begin
+  require "faraday_middleware"
+  module OpenRouter; HAS_JSON_MW = true; end
+rescue LoadError
+  module OpenRouter; HAS_JSON_MW = false; end
+end
+
+module OpenRouter
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class CapabilityError < Error; end
+end
+
+require_relative "open_router/http"
+require_relative "open_router/tool"
+require_relative "open_router/tool_call"
+require_relative "open_router/schema"
+require_relative "open_router/json_healer"
+require_relative "open_router/response"
+require_relative "open_router/model_registry"
+require_relative "open_router/model_selector"
+require_relative "open_router/prompt_template"
+require_relative "open_router/usage_tracker"
+require_relative "open_router/client"
+require_relative "open_router/streaming_client"
+require_relative "open_router/version"
+
+module OpenRouter
+  class Configuration
+    attr_writer :access_token
+    attr_accessor :api_version, :extra_headers, :faraday_config, :log_errors, :request_timeout, :uri_base
+
+    # Healing configuration
+    attr_accessor :auto_heal_responses, :healer_model, :max_heal_attempts
+
+    # Cache configuration
+    attr_accessor :cache_ttl
+
+    # Model registry configuration
+    attr_accessor :model_registry_timeout, :model_registry_retries
+
+    # Capability validation configuration
+    attr_accessor :strict_mode
+
+    # Automatic forcing configuration
+    attr_accessor :auto_force_on_unsupported_models
+
+    # Default structured output mode configuration
+    attr_accessor :default_structured_output_mode
+
+    DEFAULT_API_VERSION = "v1"
+    DEFAULT_REQUEST_TIMEOUT = 120
+    DEFAULT_URI_BASE = "https://openrouter.ai/api"
+    DEFAULT_CACHE_TTL = 7 * 24 * 60 * 60 # 7 days in seconds
+    DEFAULT_MODEL_REGISTRY_TIMEOUT = 30
+    DEFAULT_MODEL_REGISTRY_RETRIES = 3
+
+    def initialize
+      self.access_token = nil
+      self.api_version = DEFAULT_API_VERSION
+      self.extra_headers = {}
+      self.log_errors = false
+      self.request_timeout = DEFAULT_REQUEST_TIMEOUT
+      self.uri_base = DEFAULT_URI_BASE
+
+      # Healing defaults
+      self.auto_heal_responses = false
+      self.healer_model = "openai/gpt-4o-mini"
+      self.max_heal_attempts = 2
+
+      # Cache defaults
+      self.cache_ttl = ENV.fetch("OPENROUTER_CACHE_TTL", DEFAULT_CACHE_TTL).to_i
+
+      # Model registry defaults
+      self.model_registry_timeout = ENV.fetch("OPENROUTER_REGISTRY_TIMEOUT", DEFAULT_MODEL_REGISTRY_TIMEOUT).to_i
+      self.model_registry_retries = ENV.fetch("OPENROUTER_REGISTRY_RETRIES", DEFAULT_MODEL_REGISTRY_RETRIES).to_i
+
+      # Capability validation defaults
+      self.strict_mode = ENV.fetch("OPENROUTER_STRICT_MODE", "false").downcase == "true"
+
+      # Auto forcing defaults
+      self.auto_force_on_unsupported_models = ENV.fetch("OPENROUTER_AUTO_FORCE", "true").downcase == "true"
+
+      # Default structured output mode
+      self.default_structured_output_mode = ENV.fetch("OPENROUTER_DEFAULT_MODE", "strict").to_sym
+    end
+
+    def access_token
+      return @access_token if @access_token
+
+      raise ConfigurationError, "OpenRouter access token missing!"
+    end
+
+    def faraday(&block)
+      self.faraday_config = block
+    end
+
+    def site_name=(value)
+      @extra_headers["X-Title"] = value
+    end
+
+    def site_url=(value)
+      @extra_headers["HTTP-Referer"] = value
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= OpenRouter::Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/sig/open_router.rbs

@@ -0,0 +1,20 @@
+module OpenRouter
+  class Client
+    include OpenRouter::HTTP
+
+    def initialize: () { (OpenRouter::Configuration) -> void } -> void
+
+    def complete: (
+      messages: Array[Hash[Symbol, String]],
+      ?model: String,
+      ?providers: Array[String],
+      ?transforms: Array[String],
+      ?extras: Hash[Symbol, untyped],
+      ?stream: Proc
+    ) -> Hash[String, untyped]
+
+    def models: () -> Array[Hash[String, untyped]]
+
+    def query_generation_stats: (generation_id: String) -> Hash[String, untyped]
+  end
+end