openrouter_client 0.1.0

data/lib/openrouter/generation.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Represents generation metadata and statistics from the OpenRouter API.
+  # Provides access to detailed usage information, cost, and timing data.
+  class Generation
+    GENERATION_PATH = "/generation"
+
+    # @return [String] The generation identifier
+    attr_reader :id
+    # @return [String, nil] The model used
+    attr_reader :model
+    # @return [Integer, nil] Total generation time in milliseconds
+    attr_reader :total_time
+    # @return [Integer, nil] Time to first token in milliseconds
+    attr_reader :time_to_first_token
+    # @return [Integer, nil] Native prompt tokens (from model's tokenizer)
+    attr_reader :native_prompt_tokens
+    # @return [Integer, nil] Native completion tokens (from model's tokenizer)
+    attr_reader :native_completion_tokens
+    # @return [Integer, nil] Native total tokens
+    attr_reader :native_total_tokens
+    # @return [Float, nil] Total cost in USD
+    attr_reader :total_cost
+    # @return [String, nil] Provider that served the request
+    attr_reader :provider
+    # @return [String, nil] Generation status
+    attr_reader :status
+    # @return [Hash, nil] Raw response data
+    attr_reader :raw
+
+    # @param attributes [Hash] Raw attributes from OpenRouter API
+    # @param client [OpenRouter::Client] HTTP client
+    def initialize(attributes, client: OpenRouter.client)
+      @client = client
+      @raw = attributes
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Find generation metadata by ID.
+      # @param id [String] The generation identifier (from completion response)
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::Generation, nil]
+      def find_by(id:, client: OpenRouter.client)
+        response = client.get(GENERATION_PATH, query: { id: id })
+        return nil unless response && response["data"]
+
+        new(response["data"], client: client)
+      end
+    end
+
+    # Get the cost per prompt token.
+    # @return [Float, nil]
+    def prompt_cost
+      return nil unless @total_cost && @native_prompt_tokens && @native_completion_tokens
+      return nil if @native_total_tokens.nil? || @native_total_tokens.zero?
+
+      # Estimate prompt cost based on typical pricing ratios
+      @total_cost * (@native_prompt_tokens.to_f / @native_total_tokens)
+    end
+
+    # Get the cost per completion token.
+    # @return [Float, nil]
+    def completion_cost
+      return nil unless @total_cost && @native_prompt_tokens && @native_completion_tokens
+      return nil if @native_total_tokens.nil? || @native_total_tokens.zero?
+
+      @total_cost * (@native_completion_tokens.to_f / @native_total_tokens)
+    end
+
+    # Get tokens per second for generation.
+    # @return [Float, nil]
+    def tokens_per_second
+      return nil unless @native_completion_tokens && @total_time&.positive?
+
+      @native_completion_tokens.to_f / (@total_time / 1000.0)
+    end
+
+    # Check if the generation is complete.
+    # @return [Boolean]
+    def complete?
+      @status == "complete" || @status == "completed"
+    end
+
+    # Check if the generation failed.
+    # @return [Boolean]
+    def failed?
+      @status == "failed" || @status == "error"
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @id = attributes["id"]
+      @model = attributes["model"]
+      @total_time = attributes["total_time"]
+      @time_to_first_token = attributes["time_to_first_token"]
+      @native_prompt_tokens = attributes["native_prompt_tokens"] || attributes["tokens_prompt"]
+      @native_completion_tokens = attributes["native_completion_tokens"] || attributes["tokens_completion"]
+      @native_total_tokens = (@native_prompt_tokens || 0) + (@native_completion_tokens || 0) if @native_prompt_tokens || @native_completion_tokens
+      @total_cost = attributes["total_cost"] || attributes["usage"]
+      @provider = attributes["provider_name"] || attributes["provider"]
+      @status = attributes["status"] || attributes["generation_status"]
+    end
+  end
+end

data/lib/openrouter/model.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Represents a model available through the OpenRouter API.
+  # Provides helpers to list, search, and get model details.
+  class Model
+    MODELS_PATH = "/models"
+
+    # @return [String] The model identifier (e.g., "openai/gpt-4")
+    attr_reader :id
+    # @return [String, nil] Human-readable name
+    attr_reader :name
+    # @return [String, nil] Model description
+    attr_reader :description
+    # @return [Integer, nil] Context length in tokens
+    attr_reader :context_length
+    # @return [Hash, nil] Pricing information
+    attr_reader :pricing
+    # @return [Integer, nil] Top provider information
+    attr_reader :top_provider
+    # @return [String, nil] Model architecture
+    attr_reader :architecture
+    # @return [Array<String>, nil] Supported parameters
+    attr_reader :supported_parameters
+    # @return [Hash, nil] Per-request limits
+    attr_reader :per_request_limits
+    # @return [String, nil] Created timestamp
+    attr_reader :created
+
+    # @param attributes [Hash] Raw attributes from OpenRouter API
+    # @param client [OpenRouter::Client] HTTP client
+    def initialize(attributes, client: OpenRouter.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    # Get the input price per million tokens.
+    # @return [Float, nil]
+    def input_price
+      @pricing&.dig("prompt")&.to_f
+    end
+
+    # Get the output price per million tokens.
+    # @return [Float, nil]
+    def output_price
+      @pricing&.dig("completion")&.to_f
+    end
+
+    # Get the image input price per million tokens.
+    # @return [Float, nil]
+    def image_price
+      @pricing&.dig("image")&.to_f
+    end
+
+    # Check if the model is free to use.
+    # @return [Boolean]
+    def free?
+      input_price&.zero? && output_price&.zero?
+    end
+
+    # Run a completion using this model.
+    # @param messages [Array<Hash>] The messages to send
+    # @param options [Hash] Additional completion options
+    # @return [OpenRouter::Completion]
+    def complete(messages:, **)
+      OpenRouter::Completion.create!(messages: messages, model: @id, client: @client, **)
+    end
+
+    class << self
+      # Find a specific model by ID. Raises NotFoundError if not found.
+      # @param id [String] The model identifier
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::Model]
+      # @raise [OpenRouter::NotFoundError] if model not found
+      def find(id, client: OpenRouter.client)
+        model = find_by(id: id, client: client)
+        raise NotFoundError, "Model not found: #{id}" unless model
+
+        model
+      end
+
+      # Find a specific model by ID. Returns nil if not found.
+      # @param id [String] The model identifier
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::Model, nil]
+      def find_by(id:, client: OpenRouter.client)
+        response = client.get(MODELS_PATH)
+        models = Array(response && response["data"])
+        entry = models.find { |model| model["id"] == id }
+        entry ? new(entry, client: client) : nil
+      end
+
+      # Find a specific model by ID. Raises NotFoundError if not found.
+      # @param id [String] The model identifier
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::Model]
+      # @raise [OpenRouter::NotFoundError] if model not found
+      def find_by!(id:, client: OpenRouter.client)
+        find(id, client: client)
+      end
+
+      # Iterate through all available models.
+      # @param client [OpenRouter::Client] HTTP client
+      # @yield [OpenRouter::Model]
+      # @return [void]
+      def each(client: OpenRouter.client, &block)
+        response = client.get(MODELS_PATH)
+        models = Array(response && response["data"])
+        models.each { |attributes| block.call(new(attributes, client: client)) }
+      end
+
+      # Return an array of all models.
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [Array<OpenRouter::Model>]
+      def all(client: OpenRouter.client)
+        results = []
+        each(client: client) { |model| results << model }
+        results
+      end
+
+      # Search models by name or description.
+      # @param query [String] Search query
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [Array<OpenRouter::Model>]
+      def search(query:, client: OpenRouter.client)
+        all(client: client).select do |model|
+          model.name&.downcase&.include?(query.downcase) ||
+            model.description&.downcase&.include?(query.downcase) ||
+            model.id.downcase.include?(query.downcase)
+        end
+      end
+
+      # Find models by provider.
+      # @param provider [String] Provider name (e.g., "openai", "anthropic")
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [Array<OpenRouter::Model>]
+      def by_provider(provider:, client: OpenRouter.client)
+        all(client: client).select { |model| model.id.start_with?("#{provider}/") }
+      end
+
+      # Find free models.
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [Array<OpenRouter::Model>]
+      def free(client: OpenRouter.client)
+        all(client: client).select(&:free?)
+      end
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @id = attributes["id"]
+      @name = attributes["name"]
+      @description = attributes["description"]
+      @context_length = attributes["context_length"]
+      @pricing = attributes["pricing"]
+      @top_provider = attributes["top_provider"]
+      @architecture = attributes["architecture"]
+      @supported_parameters = attributes["supported_parameters"]
+      @per_request_limits = attributes["per_request_limits"]
+      @created = attributes["created"]
+    end
+  end
+end

data/lib/openrouter/stream.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Streaming helper for Server-Sent Events from OpenRouter API.
+  # It parses SSE lines and yields decoded event hashes.
+  class Stream
+    # @return [String] endpoint path
+    attr_reader :path
+
+    # @param path [String] API endpoint path
+    # @param input [Hash] request payload
+    # @param client [OpenRouter::Client] HTTP client
+    def initialize(path:, input:, client: OpenRouter.client)
+      @path = path
+      @input = input
+      @client = client
+    end
+
+    # Stream events; yields a Hash for each event data chunk. Blocks until stream ends.
+    # @yield [event] yields decoded event hash
+    # @yieldparam event [Hash]
+    # @return [void]
+    def each(&block)
+      buffer = ""
+      decoder = SSEDecoder.new
+
+      @client.post_stream(@path, @input, on_data: proc do |chunk, _total_bytes|
+        buffer = (buffer + chunk).gsub(/\r\n?/, "\n")
+        lines = buffer.split("\n", -1)
+        buffer = lines.pop || ""
+        lines.each do |line|
+          event = decoder.decode(line)
+          block.call(event) if event
+        end
+      end)
+    end
+
+    # Minimal SSE decoder for parsing standard server-sent event stream lines.
+    class SSEDecoder
+      def initialize
+        @event = ""
+        @data = ""
+        @id = nil
+        @retry = nil
+      end
+
+      # @param line [String]
+      # @return [Hash, nil]
+      def decode(line)
+        return flush_event if line.empty?
+        return if line.start_with?(":")
+
+        field, _, value = line.partition(":")
+        value = value.lstrip
+
+        case field
+        when "event"
+          @event = value
+        when "data"
+          @data += "#{value}\n"
+        when "id"
+          @id = value
+        when "retry"
+          @retry = value.to_i
+        end
+
+        nil
+      end
+
+      private
+
+      def flush_event
+        return if @data.empty?
+
+        data = @data.chomp
+
+        # Handle [DONE] message which signals end of stream
+        return reset_state if data == "[DONE]"
+
+        begin
+          parsed = JSON.parse(data)
+        rescue JSON::ParserError
+          reset_state
+          return nil
+        end
+
+        event = { "data" => parsed }
+        event["event"] = @event unless @event.empty?
+        event["id"] = @id if @id
+        event["retry"] = @retry if @retry
+
+        reset_state
+        event
+      end
+
+      def reset_state
+        @event = ""
+        @data = ""
+        @id = nil
+        @retry = nil
+        nil
+      end
+    end
+  end
+end

data/lib/openrouter/version.rb

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

data/lib/openrouter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "time"
+require "json"
+require "cgi"
+require "uri"
+
+require_relative "openrouter/version"
+
+module OpenRouter
+  # Base error class for all OpenRouter-related errors.
+  class Error < StandardError; end
+  # Raised when a request is unauthorized (HTTP 401).
+  class UnauthorizedError < Error; end
+  # Raised when a requested resource is not found (HTTP 404).
+  class NotFoundError < Error; end
+  # Raised when the server returns an unexpected error (HTTP 5xx or others).
+  class ServerError < Error; end
+  # Raised when the client is misconfigured.
+  class ConfigurationError < Error; end
+  # Raised when access is forbidden (HTTP 403).
+  class ForbiddenError < Error; end
+  # Raised when rate limited (HTTP 429).
+  class RateLimitError < Error; end
+  # Raised when request validation fails (HTTP 400).
+  class BadRequestError < Error; end
+  # Raised when payment is required (HTTP 402).
+  class PaymentRequiredError < Error; end
+
+  # Global configuration for the OpenRouter client.
+  class Configuration
+    DEFAULT_API_BASE = "https://openrouter.ai/api/v1"
+    DEFAULT_REQUEST_TIMEOUT = 120
+
+    # API key used for authenticating with OpenRouter endpoints.
+    # Defaults to ENV["OPENROUTER_API_KEY"].
+    # @return [String]
+    attr_accessor :api_key
+
+    # Base URL for OpenRouter API endpoints.
+    # @return [String]
+    attr_accessor :api_base
+
+    # Timeout in seconds for opening and processing HTTP requests.
+    # @return [Integer]
+    attr_accessor :request_timeout
+
+    # Optional HTTP-Referer header for app attribution.
+    # @return [String, nil]
+    attr_accessor :site_url
+
+    # Optional X-Title header for app attribution.
+    # @return [String, nil]
+    attr_accessor :site_name
+
+    # Initialize configuration with sensible defaults.
+    # @return [OpenRouter::Configuration]
+    def initialize
+      @api_key = ENV.fetch("OPENROUTER_API_KEY", nil)
+      @api_base = DEFAULT_API_BASE
+      @request_timeout = DEFAULT_REQUEST_TIMEOUT
+      @site_url = nil
+      @site_name = nil
+    end
+  end
+
+  class << self
+    # The global configuration instance.
+    # @return [OpenRouter::Configuration]
+    attr_accessor :configuration
+
+    # Configure the OpenRouter client.
+    # @yield [OpenRouter::Configuration] the configuration object to mutate
+    # @return [void]
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    # Global client accessor using the configured settings.
+    # @return [OpenRouter::Client]
+    def client
+      configuration = self.configuration || Configuration.new
+      @client ||= OpenRouter::Client.new(configuration)
+    end
+
+    # Reset the client (useful for reconfiguration).
+    # @return [void]
+    def reset_client!
+      @client = nil
+    end
+
+    # Deep symbolize keys of a Hash or Array.
+    # @param object [Hash, Array]
+    # @return [Hash, Array]
+    def deep_symbolize_keys(object)
+      case object
+      when Hash
+        object.each_with_object({}) do |(key, value), result|
+          symbolized_key = key.is_a?(String) ? key.to_sym : key
+          result[symbolized_key] = deep_symbolize_keys(value)
+        end
+      when Array
+        object.map { |element| deep_symbolize_keys(element) }
+      else
+        object
+      end
+    end
+  end
+end
+
+require_relative "openrouter/client"
+require_relative "openrouter/completion"
+require_relative "openrouter/stream"
+require_relative "openrouter/model"
+require_relative "openrouter/generation"
+require_relative "openrouter/credit"
+require_relative "openrouter/api_key"

data/openrouter_client.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/openrouter/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "openrouter_client"
+  spec.version = OpenRouter::VERSION
+  spec.authors = ["Dylan Player"]
+  spec.email = ["dylan@851.sh"]
+
+  spec.summary = "Ruby client for OpenRouter API."
+  spec.description = "A comprehensive Ruby client for the OpenRouter API, providing access to hundreds of AI models through a unified interface."
+  spec.homepage = "https://github.com/851-labs/openrouter_client"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.license = "MIT"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("faraday", ">= 1")
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/rbi/openrouter/api_key.rbi

@@ -0,0 +1,85 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenRouter
+  class ApiKey
+    KEYS_PATH = T.let(T.unsafe(nil), String)
+    AUTH_KEY_PATH = T.let(T.unsafe(nil), String)
+
+    sig { returns(String) }
+    def id; end
+
+    sig { returns(T.nilable(String)) }
+    def name; end
+
+    sig { returns(T.nilable(String)) }
+    def key; end
+
+    sig { returns(T.nilable(Float)) }
+    def limit; end
+
+    sig { returns(T.nilable(Float)) }
+    def usage; end
+
+    sig { returns(T.nilable(T::Boolean)) }
+    def disabled; end
+
+    sig { returns(T.nilable(String)) }
+    def created_at; end
+
+    sig { returns(T.nilable(String)) }
+    def updated_at; end
+
+    sig { params(attributes: T.untyped, client: OpenRouter::Client).void }
+    def initialize(attributes, client: OpenRouter.client); end
+
+    class << self
+      sig { params(client: OpenRouter::Client).returns(OpenRouter::ApiKey) }
+      def current(client: OpenRouter.client); end
+
+      sig { params(client: OpenRouter::Client).returns(T::Array[OpenRouter::ApiKey]) }
+      def all(client: OpenRouter.client); end
+
+      sig { params(id: String, client: OpenRouter::Client).returns(T.nilable(OpenRouter::ApiKey)) }
+      def find_by(id:, client: OpenRouter.client); end
+
+      sig do
+        params(
+          name: String,
+          limit: T.nilable(Float),
+          client: OpenRouter::Client
+        ).returns(OpenRouter::ApiKey)
+      end
+      def create!(name:, limit: nil, client: OpenRouter.client); end
+    end
+
+    sig do
+      params(
+        name: T.nilable(String),
+        limit: T.nilable(Float),
+        disabled: T.nilable(T::Boolean)
+      ).returns(OpenRouter::ApiKey)
+    end
+    def update!(name: nil, limit: nil, disabled: nil); end
+
+    sig { returns(T::Boolean) }
+    def destroy!; end
+
+    sig { returns(T::Boolean) }
+    def active?; end
+
+    sig { returns(T::Boolean) }
+    def limited?; end
+
+    sig { returns(T::Boolean) }
+    def exceeded_limit?; end
+
+    sig { returns(T.nilable(Float)) }
+    def remaining; end
+
+    private
+
+    sig { params(attributes: T.untyped).void }
+    def reset_attributes(attributes); end
+  end
+end

data/rbi/openrouter/client.rbi

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenRouter
+  class Client
+    sig { returns(OpenRouter::Configuration) }
+    def configuration; end
+
+    sig { params(value: OpenRouter::Configuration).returns(OpenRouter::Configuration) }
+    def configuration=(value); end
+
+    sig { params(configuration: T.nilable(OpenRouter::Configuration)).void }
+    def initialize(configuration = nil); end
+
+    sig { params(path: String, payload: T.untyped, headers: T.untyped).returns(T.untyped) }
+    def post(path, payload = {}, headers: {}); end
+
+    sig do
+      params(
+        path: String,
+        payload: T.untyped,
+        on_data: T.proc.params(arg0: String, arg1: T.untyped).void
+      ).void
+    end
+    def post_stream(path, payload = {}, on_data:); end
+
+    sig { params(path: String, query: T.untyped, headers: T.untyped).returns(T.untyped) }
+    def get(path, query: nil, headers: {}); end
+
+    sig { params(path: String, headers: T.untyped).returns(T.untyped) }
+    def delete(path, headers: {}); end
+
+    sig { params(path: String, payload: T.untyped, headers: T.untyped).returns(T.untyped) }
+    def patch(path, payload = {}, headers: {}); end
+
+    sig { params(response: T.untyped).void }
+    def handle_error(response); end
+
+    private
+
+    sig { params(request: T.untyped, custom_headers: T.untyped).void }
+    def configure_request_headers(request, custom_headers); end
+
+    sig { params(response: T.untyped).returns(String) }
+    def extract_error_message(response); end
+
+    sig { params(body: T.untyped).returns(T.untyped) }
+    def parse_json(body); end
+
+    sig { params(path: String).returns(String) }
+    def build_url(path); end
+
+    sig { returns(T.untyped) }
+    def connection; end
+  end
+end