rails-openrouter 0.2.0

data/lib/openrouter/errors.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Base class for every error raised by this library.
+  class Error < StandardError; end
+
+  # Raised when the client is missing something it needs to make a request.
+  class ConfigurationError < Error; end
+
+  # Raised when the request never produced a response (DNS, TCP, TLS, timeouts).
+  class APIConnectionError < Error
+    attr_reader :original_error
+
+    def initialize(message = "Connection error.", original_error: nil)
+      @original_error = original_error
+      super(message)
+    end
+  end
+
+  class APITimeoutError < APIConnectionError
+    def initialize(message = "Request timed out.", original_error: nil)
+      super
+    end
+  end
+
+  # Raised when a file cannot be read, encoded, or sent in the requested shape.
+  class AttachmentError < Error; end
+
+  # Raised when the stream is consumed after it has been closed.
+  class StreamClosedError < Error; end
+
+  # Raised for any non-2xx response, and for 200 responses whose body is an
+  # OpenRouter error envelope (which happens for mid-stream failures).
+  class APIError < Error
+    attr_reader :status, :body, :headers, :code, :metadata, :request_id
+
+    def initialize(message, status: nil, body: nil, headers: nil, code: nil, metadata: nil)
+      @status = status
+      @body = body
+      @headers = headers || {}
+      @code = code
+      @metadata = metadata
+      @request_id = @headers["x-request-id"] || @headers["X-Request-Id"]
+      super(message)
+    end
+
+    # Builds the most specific error subclass for a response.
+    #
+    # OpenRouter error bodies look like:
+    #   {"error": {"code": 402, "message": "...", "metadata": {...}}}
+    def self.from_response(status:, body:, headers: {})
+      payload = parse_body(body)
+      error = payload.is_a?(Hash) ? payload[:error] : nil
+      error = {} unless error.is_a?(Hash)
+
+      code = error[:code] || status
+      message = error[:message] || default_message(status)
+      message = "#{message} (HTTP #{status})" if status
+
+      # Provider errors are nested under metadata.raw and are the actually
+      # useful part of a 502, so surface them in the message.
+      raw = error.dig(:metadata, :raw)
+      message = "#{message}: #{raw}" if raw.is_a?(String) && !raw.empty?
+
+      klass_for(status || code).new(
+        message,
+        status: status,
+        body: payload || body,
+        headers: headers,
+        code: code,
+        metadata: error[:metadata]
+      )
+    end
+
+    def self.klass_for(status)
+      case status.to_i
+      when 400 then BadRequestError
+      when 401 then AuthenticationError
+      when 402 then InsufficientCreditsError
+      when 403 then ModerationError
+      when 404 then NotFoundError
+      when 408 then RequestTimeoutError
+      when 409 then ConflictError
+      when 422 then UnprocessableEntityError
+      when 429 then RateLimitError
+      when 502 then BadGatewayError
+      when 503 then NoProviderAvailableError
+      when 500..599 then InternalServerError
+      else self
+      end
+    end
+
+    def self.default_message(status)
+      case status.to_i
+      when 400 then "Bad request"
+      when 401 then "Invalid credentials (no auth, or an invalid/expired API key)"
+      when 402 then "Insufficient credits"
+      when 403 then "Input flagged by moderation"
+      when 404 then "Not found"
+      when 408 then "Request timed out"
+      when 429 then "Rate limited"
+      when 502 then "The upstream provider returned an invalid response"
+      when 503 then "No available provider meets your routing requirements"
+      else "Unexpected API error"
+      end
+    end
+
+    def self.parse_body(body)
+      return body if body.is_a?(Hash)
+      return nil if body.nil? || body.to_s.strip.empty?
+
+      JSON.parse(body.to_s, symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+    private_class_method :parse_body
+  end
+
+  class BadRequestError < APIError; end
+  class AuthenticationError < APIError; end
+  class InsufficientCreditsError < APIError; end
+  class ModerationError < APIError; end
+  class NotFoundError < APIError; end
+  class RequestTimeoutError < APIError; end
+  class ConflictError < APIError; end
+  class UnprocessableEntityError < APIError; end
+  class RateLimitError < APIError; end
+  class InternalServerError < APIError; end
+  class BadGatewayError < InternalServerError; end
+  class NoProviderAvailableError < InternalServerError; end
+end

data/lib/openrouter/message.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Small constructors for the message hashes the API expects.
+  #
+  #   Message.system("You are terse.")
+  #   Message.user("What changed?", attach: ["before.png", "after.png"])
+  #   Message.tool(result, tool_call_id: call.id, name: call.function.name)
+  #
+  # Everything returns a plain Hash, so these compose with hand-written
+  # messages and can be inspected or logged without ceremony.
+  module Message
+    module_function
+
+    def user(content = nil, attach: nil, **extra)
+      build("user", content, attach, extra)
+    end
+
+    def system(content = nil, attach: nil, **extra)
+      build("system", content, attach, extra)
+    end
+
+    def assistant(content = nil, attach: nil, **extra)
+      build("assistant", content, attach, extra)
+    end
+
+    def tool(content, tool_call_id:, name: nil)
+      message = { role: "tool", tool_call_id: tool_call_id, content: stringify(content) }
+      message[:name] = name if name
+      message
+    end
+
+    def build(role, content, attach, extra)
+      message = { role: role }.merge(extra)
+
+      if attach.nil? && !content.is_a?(Array)
+        message[:content] = content
+      else
+        message[:content] = Content.build_content(content, attach)
+      end
+
+      message
+    end
+
+    def stringify(content)
+      case content
+      when String then content
+      when nil then ""
+      else JSON.generate(content.is_a?(Structure) ? content.to_h : content)
+      end
+    end
+  end
+end

data/lib/openrouter/resources/chat.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  module Resources
+    # client.chat.completions
+    class Chat
+      def initialize(client)
+        @client = client
+      end
+
+      def completions
+        @completions ||= Completions.new(@client)
+      end
+
+      # POST /chat/completions
+      class Completions
+        PATH = "chat/completions"
+
+        def initialize(client)
+          @client = client
+        end
+
+        # Creates a chat completion.
+        #
+        #   client.chat.completions.create(
+        #     model: "anthropic/claude-sonnet-4.5",
+        #     messages: [{ role: "user", content: "Hi" }]
+        #   )
+        #
+        # With `stream: true` it returns an OpenRouter::Stream. Passing a block
+        # streams too, yielding each chunk and returning the assembled
+        # completion once the stream ends.
+        #
+        # Any other keyword is forwarded to the API untouched, so
+        # provider-specific and newly released parameters (`provider:`,
+        # `reasoning:`, `plugins:`, `transforms:`, `models:`, ...) work without
+        # waiting on a gem release.
+        def create(messages:, model: nil, stream: false, request_options: {}, **params, &block)
+          body = build_body(messages: messages, model: model, **params)
+
+          return create_stream(body, request_options, &block) if stream || block
+
+          Structure.new(@client.post(PATH, body: body, **request_options))
+        end
+
+        # Always streams. Returns an OpenRouter::Stream, or — when a block is
+        # given — the assembled completion after the block has seen every chunk.
+        def stream(messages:, model: nil, request_options: {}, **params, &block)
+          create(messages: messages, model: model, stream: true, request_options: request_options, **params, &block)
+        end
+
+        private
+
+        def create_stream(body, request_options)
+          stream = @client.stream(PATH, body: body.merge(stream: true), **request_options)
+          return stream unless block_given?
+
+          begin
+            stream.each { |chunk| yield chunk }
+            stream.final_completion
+          ensure
+            stream.close
+          end
+        end
+
+        def build_body(messages:, model:, pdf_engine: nil, **params)
+          model ||= @client.default_model
+          raise ArgumentError, "model is required (pass model: or set default_model on the client)" if model.nil?
+          raise ArgumentError, "messages must be a non-empty Array" unless messages.is_a?(Array) && !messages.empty?
+
+          body = @client.extra_body.merge(params)
+          body[:plugins] = file_parser_plugin(body[:plugins], pdf_engine) if pdf_engine
+          body.merge(model: model, messages: Content.normalize_messages(messages))
+        end
+
+        # `pdf_engine:` is sugar for the file-parser plugin, which is how PDF
+        # parsing is selected: "native" (the model reads the file itself),
+        # "mistral-ocr" (scans and images), or "cloudflare-ai" (free, to markdown).
+        def file_parser_plugin(plugins, engine)
+          plugins = Array(plugins).map { |plugin| plugin.is_a?(Structure) ? plugin.to_h : plugin }
+          existing = plugins.find { |plugin| (plugin[:id] || plugin["id"]).to_s == "file-parser" }
+
+          if existing
+            existing[:pdf] = { engine: engine.to_s }
+            plugins
+          else
+            plugins + [{ id: "file-parser", pdf: { engine: engine.to_s } }]
+          end
+        end
+      end
+    end
+
+    # POST /completions — the legacy text-completion shape.
+    class TextCompletions
+      PATH = "completions"
+
+      def initialize(client)
+        @client = client
+      end
+
+      def create(prompt:, model: nil, stream: false, request_options: {}, **params, &block)
+        model ||= @client.default_model
+        raise ArgumentError, "model is required (pass model: or set default_model on the client)" if model.nil?
+
+        body = @client.extra_body.merge(params).merge(model: model, prompt: prompt)
+
+        if stream || block
+          stream = @client.stream(PATH, body: body.merge(stream: true), **request_options)
+          return stream unless block
+
+          begin
+            stream.each { |chunk| block.call(chunk) }
+            stream.final_completion
+          ensure
+            stream.close
+          end
+        else
+          Structure.new(@client.post(PATH, body: body, **request_options))
+        end
+      end
+    end
+  end
+end

data/lib/openrouter/resources/files.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  module Resources
+    # client.files — upload once, then reference the id from any number of
+    # messages instead of re-encoding the same document into every request.
+    #
+    #   file = client.files.upload("report.pdf")
+    #   client.chat.completions.create(
+    #     model: model,
+    #     messages: [Message.user("Summarize it", attach: [{ id: file.id }])]
+    #   )
+    class Files
+      def initialize(client)
+        @client = client
+      end
+
+      # POST /files (multipart). Accepts a path, Pathname, IO or Attachment.
+      # `provider:` stores the file with "openai" or "anthropic" instead of
+      # OpenRouter's own storage.
+      def upload(source, filename: nil, mime_type: nil, provider: nil, workspace_id: nil, request_options: {})
+        attachment = Attachment.from(source, filename: filename, mime_type: mime_type)
+        if attachment.remote?
+          raise AttachmentError, "cannot upload a remote URL; download it first or attach it inline"
+        end
+
+        form = [["file", StringIO.new(attachment.bytes),
+                 { filename: attachment.filename, content_type: attachment.mime_type }]]
+
+        response = @client.upload("files", form: form,
+                                           query: { provider: provider, workspace_id: workspace_id },
+                                           **request_options)
+        Structure.new(response[:data] || response)
+      end
+
+      # GET /files
+      def list(limit: nil, after: nil, workspace_id: nil, request_options: {})
+        response = @client.get("files", query: { limit: limit, after: after, workspace_id: workspace_id },
+                                        **request_options)
+        data = response[:data] || response[:files]
+        data.is_a?(Array) ? data.map { |file| Structure.new(file) } : Structure.new(response)
+      end
+
+      # GET /files/:id
+      def retrieve(id, workspace_id: nil, request_options: {})
+        response = @client.get("files/#{escape(id)}", query: { workspace_id: workspace_id }, **request_options)
+        Structure.new(response[:data] || response)
+      end
+
+      # DELETE /files/:id
+      def delete(id, workspace_id: nil, request_options: {})
+        response = @client.delete("files/#{escape(id)}", query: { workspace_id: workspace_id }, **request_options)
+        Structure.new(response.is_a?(Hash) ? (response[:data] || response) : {})
+      end
+
+      # GET /files/:id/content — raw bytes. Only files created server-side are
+      # downloadable; a file you uploaded yourself returns 400.
+      #
+      # Returns an Attachment, or the path when `to:` is given.
+      def download(id, to: nil, workspace_id: nil, provider: nil, request_options: {})
+        bytes = @client.download(
+          "files/#{escape(id)}/content",
+          query: { workspace_id: workspace_id, provider: provider },
+          **request_options
+        )
+        attachment = Attachment.from_bytes(bytes, filename: id.to_s)
+        to ? attachment.save(to) : attachment
+      end
+
+      private
+
+      def escape(id)
+        URI.encode_www_form_component(id.to_s)
+      end
+    end
+  end
+end

data/lib/openrouter/resources/models.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  module Resources
+    # client.models
+    class Models
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /models — every model OpenRouter can route to.
+      # Returns an Array of OpenRouter::Structure.
+      #
+      #   client.models.list(supported_parameters: "tools")
+      #
+      # `input_modalities:` / `output_modalities:` narrow the list to models
+      # that handle the media you are sending or expecting — the answer to
+      # "which models can read this PDF?".
+      #
+      #   client.models.list(input_modalities: %w[text image])
+      #   client.models.list(output_modalities: "image")
+      def list(category: nil, supported_parameters: nil, input_modalities: nil, output_modalities: nil,
+               request_options: {})
+        query = { category: category, supported_parameters: supported_parameters }
+        response = @client.get("models", query: query, **request_options)
+
+        models = Array(response[:data]).map { |model| Structure.new(model) }
+        models = with_modalities(models, :input_modalities, input_modalities)
+        with_modalities(models, :output_modalities, output_modalities)
+      end
+
+      # GET /models/user — the models available to the authenticated key.
+      def list_available(request_options: {})
+        response = @client.get("models/user", **request_options)
+        Array(response[:data]).map { |model| Structure.new(model) }
+      end
+
+      # GET /models/:author/:slug/endpoints — providers, pricing and limits for
+      # one model. Accepts either "author/slug" or the two parts separately.
+      def endpoints(model_id, slug = nil, request_options: {})
+        author, model_slug = slug ? [model_id, slug] : model_id.to_s.split("/", 2)
+        raise ArgumentError, "expected a model id like \"openai/gpt-4o\"" if model_slug.nil? || model_slug.empty?
+
+        response = @client.get("models/#{author}/#{model_slug}/endpoints", **request_options)
+        Structure.new(response[:data] || response)
+      end
+      alias retrieve endpoints
+
+      private
+
+      # Modality metadata lives under `architecture`; a model that does not
+      # declare the modality is excluded rather than assumed capable.
+      def with_modalities(models, key, wanted)
+        return models if wanted.nil?
+
+        wanted = Array(wanted).map(&:to_s)
+        models.select do |model|
+          available = Array(model.architecture&.public_send(key)).map(&:to_s)
+          (wanted - available).empty?
+        end
+      end
+    end
+
+    # GET /credits — total credits purchased and used on this account.
+    class Credits
+      def initialize(client)
+        @client = client
+      end
+
+      def retrieve(request_options: {})
+        response = @client.get("credits", **request_options)
+        Structure.new(response[:data] || response)
+      end
+      alias get retrieve
+    end
+
+    # GET /key — limits and usage for the API key in use.
+    class Key
+      def initialize(client)
+        @client = client
+      end
+
+      def retrieve(request_options: {})
+        response = @client.get("key", **request_options)
+        Structure.new(response[:data] || response)
+      end
+      alias get retrieve
+    end
+
+    # GET /generation?id= — cost and token accounting for one completion.
+    # The record lands a moment after the completion finishes, so a fresh id can
+    # briefly 404.
+    class Generations
+      def initialize(client)
+        @client = client
+      end
+
+      def retrieve(id, request_options: {})
+        response = @client.get("generation", query: { id: id }, **request_options)
+        Structure.new(response[:data] || response)
+      end
+      alias get retrieve
+    end
+  end
+end

data/lib/openrouter/stream.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # A lazy, re-enumerable iterator over streamed completion chunks.
+  #
+  #   stream = client.chat.completions.stream(model: "openai/gpt-4o", messages: messages)
+  #   stream.each_text { |text| print(text) }
+  #   stream.final_completion.usage.total_tokens
+  #
+  # Nothing is read from the socket until iteration starts, and chunks are
+  # accumulated as they pass through, so #final_completion is available for free
+  # once the stream has been consumed. Iterating a second time replays the
+  # chunks already seen and then continues where the first pass stopped.
+  class Stream
+    include Enumerable
+
+    def initialize(source, connection: nil)
+      @source = source
+      @connection = connection
+      @chunks = []
+      @accumulator = Accumulator.new
+      @finished = false
+      @closed = false
+    end
+
+    # Yields each chunk as an OpenRouter::Structure.
+    def each
+      return enum_for(:each) unless block_given?
+
+      @chunks.each { |chunk| yield chunk }
+      return self if @finished
+
+      while (chunk = pull)
+        yield chunk
+      end
+
+      self
+    end
+
+    # Yields only the text deltas of the given choice, skipping the role-only
+    # and finish_reason chunks that would otherwise force a nil check.
+    def each_text(index: 0)
+      return enum_for(:each_text, index: index) unless block_given?
+
+      each do |chunk|
+        choice = chunk.choices&.find { |c| (c.index || 0) == index }
+        content = choice&.delta&.content
+        yield content if content.is_a?(String) && !content.empty?
+      end
+    end
+
+    # Yields reasoning-token deltas for models that emit them.
+    def each_reasoning(index: 0)
+      return enum_for(:each_reasoning, index: index) unless block_given?
+
+      each do |chunk|
+        choice = chunk.choices&.find { |c| (c.index || 0) == index }
+        reasoning = choice&.delta&.reasoning
+        yield reasoning if reasoning.is_a?(String) && !reasoning.empty?
+      end
+    end
+
+    # Consumes the rest of the stream and returns the assembled completion,
+    # shaped exactly like a non-streaming chat.completions response.
+    def final_completion
+      drain
+      Structure.new(@accumulator.snapshot)
+    end
+    alias completion final_completion
+
+    # Consumes the rest of the stream and returns the full text of a choice.
+    def text
+      drain
+      @accumulator.text
+    end
+
+    def final_message(index: 0)
+      final_completion.choices&.find { |c| (c.index || 0) == index }&.message
+    end
+
+    def usage
+      final_completion.usage
+    end
+
+    # The completion as assembled so far, without consuming anything further.
+    def snapshot
+      Structure.new(@accumulator.snapshot)
+    end
+
+    def chunks
+      drain
+      @chunks
+    end
+
+    # Stops the stream early and releases the underlying connection. Safe to
+    # call more than once, and safe to call from another thread.
+    def close
+      return self if @closed
+
+      @closed = true
+      @finished = true
+      @connection&.close
+      self
+    end
+
+    def closed?
+      @closed
+    end
+
+    def finished?
+      @finished
+    end
+
+    private
+
+    def drain
+      each { |_chunk| } unless @finished
+    end
+
+    def pull
+      raise StreamClosedError, "stream is closed" if @closed
+
+      raw = @source.next
+      @accumulator.add(raw)
+      chunk = Structure.new(raw)
+      @chunks << chunk
+      chunk
+    rescue StopIteration
+      @finished = true
+      nil
+    end
+  end
+end