rails-openrouter 0.2.0

data/lib/openrouter/attachment.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "stringio"
+require "uri"
+
+module OpenRouter
+  # A file on its way to (or back from) the API.
+  #
+  # Wraps a path, an IO, raw bytes, an https URL or a data URL, works out the
+  # MIME type, and renders itself as the content part shape the API expects for
+  # that kind of media.
+  #
+  #   OpenRouter::Attachment.new("chart.png").to_part
+  #   #=> {type: "image_url", image_url: {url: "data:image/png;base64,..."}}
+  class Attachment
+    DATA_URL = %r{\Adata:([^;,]+)(;[^,]*)?,}.freeze
+    REMOTE_URL = %r{\Ahttps?://}i.freeze
+
+    EXTENSION_TYPES = {
+      # images
+      "png" => "image/png", "jpg" => "image/jpeg", "jpeg" => "image/jpeg",
+      "webp" => "image/webp", "gif" => "image/gif", "bmp" => "image/bmp",
+      "heic" => "image/heic", "heif" => "image/heif", "svg" => "image/svg+xml",
+      # documents
+      "pdf" => "application/pdf", "txt" => "text/plain", "md" => "text/markdown",
+      "csv" => "text/csv", "json" => "application/json", "xml" => "application/xml",
+      "html" => "text/html", "yaml" => "application/yaml", "yml" => "application/yaml",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      # audio
+      "wav" => "audio/wav", "mp3" => "audio/mpeg", "aiff" => "audio/aiff", "aif" => "audio/aiff",
+      "aac" => "audio/aac", "ogg" => "audio/ogg", "oga" => "audio/ogg", "opus" => "audio/ogg",
+      "flac" => "audio/flac", "m4a" => "audio/mp4", "pcm" => "audio/pcm",
+      # video
+      "mp4" => "video/mp4", "mpeg" => "video/mpeg", "mpg" => "video/mpeg",
+      "mov" => "video/quicktime", "webm" => "video/webm", "avi" => "video/x-msvideo",
+      "mkv" => "video/x-matroska"
+    }.freeze
+
+    # OpenRouter's `input_audio.format` vocabulary.
+    AUDIO_FORMATS = {
+      "audio/wav" => "wav", "audio/x-wav" => "wav", "audio/wave" => "wav",
+      "audio/mpeg" => "mp3", "audio/mp3" => "mp3",
+      "audio/aiff" => "aiff", "audio/x-aiff" => "aiff",
+      "audio/aac" => "aac",
+      "audio/ogg" => "ogg",
+      "audio/flac" => "flac", "audio/x-flac" => "flac",
+      "audio/mp4" => "m4a", "audio/m4a" => "m4a", "audio/x-m4a" => "m4a",
+      "audio/pcm" => "pcm16"
+    }.freeze
+
+    DEFAULT_TYPE = "application/octet-stream"
+
+    attr_reader :mime_type
+
+    class << self
+      # Coerces anything attachment-shaped into an Attachment.
+      def from(source, filename: nil, mime_type: nil)
+        return source if source.is_a?(Attachment)
+
+        new(source, filename: filename, mime_type: mime_type)
+      end
+
+      # Raw bytes already in memory. `mime_type` is sniffed when omitted.
+      def from_bytes(bytes, mime_type: nil, filename: nil)
+        allocate.send(:initialize_from_bytes, bytes.to_s, mime_type, filename)
+      end
+
+      # Decodes a `data:<mime>;base64,<payload>` URL, e.g. an image a model
+      # generated and returned inside a message.
+      def from_data_url(url, filename: nil)
+        match = DATA_URL.match(url.to_s)
+        raise ArgumentError, "not a data URL" unless match
+
+        payload = url.to_s[match.end(0)..].to_s
+        bytes = match[2].to_s.include?("base64") ? payload.unpack1("m") : URI.decode_www_form_component(payload)
+        from_bytes(bytes, mime_type: match[1], filename: filename)
+      end
+
+      def mime_type_for(path)
+        EXTENSION_TYPES[File.extname(path.to_s).delete_prefix(".").downcase]
+      end
+    end
+
+    def initialize(source, filename: nil, mime_type: nil)
+      @url = nil
+      @bytes = nil
+
+      case source
+      when Attachment
+        initialize_copy_of(source, filename, mime_type)
+      when Pathname
+        initialize_from_path(source.to_s, mime_type, filename)
+      when URI::Generic
+        initialize_from_url(source.to_s, mime_type, filename)
+      when IO, StringIO
+        initialize_from_io(source, mime_type, filename)
+      when String
+        initialize_from_string(source, mime_type, filename)
+      else
+        raise ArgumentError, "cannot attach a #{source.class}; pass a path, Pathname, IO, URL, or data URL"
+      end
+
+      check_size!
+    end
+
+    # True when the file stays where it is and only its URL is sent.
+    def remote?
+      !@url.nil?
+    end
+
+    def bytes
+      raise AttachmentError, "#{@url} is remote; download it before reading its bytes" if remote?
+
+      @bytes
+    end
+
+    def size
+      remote? ? nil : @bytes.bytesize
+    end
+
+    def filename
+      @filename ||= default_filename
+    end
+
+    def base64
+      [bytes].pack("m0")
+    end
+
+    # What goes in the wire format: either the original https URL or a data URL.
+    def url
+      @url || "data:#{mime_type};base64,#{base64}"
+    end
+    alias data_url url
+
+    # :image, :video, :audio or :file — decides which content part shape is used.
+    def kind
+      case mime_type
+      when %r{\Aimage/} then :image
+      when %r{\Avideo/} then :video
+      when %r{\Aaudio/} then :audio
+      else :file
+      end
+    end
+
+    def audio_format
+      AUDIO_FORMATS[mime_type] ||
+        AUDIO_FORMATS[Attachment.mime_type_for(filename)] ||
+        raise(AttachmentError, "unsupported audio type #{mime_type.inspect}; " \
+                               "OpenRouter accepts #{AUDIO_FORMATS.values.uniq.join(', ')}")
+    end
+
+    # Renders the content part for this file. `as:` forces a shape when the
+    # MIME type would pick the wrong one.
+    def to_part(as: nil)
+      case as || kind
+      when :image then { type: "image_url", image_url: { url: url } }
+      when :video then { type: "video_url", video_url: { url: url } }
+      when :audio then audio_part
+      when :file then { type: "file", file: { filename: filename, file_data: url } }
+      else raise ArgumentError, "unknown content kind #{as.inspect}"
+      end
+    end
+
+    def save(path)
+      File.binwrite(path, bytes)
+      path
+    end
+
+    def inspect
+      "#<#{self.class.name} #{filename.inspect} #{mime_type} #{remote? ? @url : "#{size} bytes"}>"
+    end
+
+    private
+
+    # Audio has no URL form in the API, so a remote source has to be fetched by
+    # the caller first — better an explicit error than a silently ignored file.
+    def audio_part
+      if remote?
+        raise AttachmentError,
+              "audio must be sent as base64; download #{@url} and attach the bytes or a local path"
+      end
+
+      { type: "input_audio", input_audio: { data: base64, format: audio_format } }
+    end
+
+    def initialize_copy_of(other, filename, mime_type)
+      @url = other.remote? ? other.url : nil
+      @bytes = other.remote? ? nil : other.bytes
+      @mime_type = mime_type || other.mime_type
+      @filename = filename || other.filename
+    end
+
+    def initialize_from_string(source, mime_type, filename)
+      if source.match?(DATA_URL)
+        decoded = Attachment.from_data_url(source, filename: filename)
+        @bytes = decoded.bytes
+        @mime_type = mime_type || decoded.mime_type
+        @filename = filename
+      elsif source.match?(REMOTE_URL)
+        initialize_from_url(source, mime_type, filename)
+      else
+        initialize_from_path(source, mime_type, filename)
+      end
+    end
+
+    def initialize_from_path(path, mime_type, filename)
+      unless File.file?(path)
+        raise AttachmentError, "no such file: #{path}"
+      end
+
+      @bytes = File.binread(path)
+      @filename = filename || File.basename(path)
+      @mime_type = mime_type || Attachment.mime_type_for(path) || sniff(@bytes) || DEFAULT_TYPE
+    end
+
+    def initialize_from_url(url, mime_type, filename)
+      @url = url
+      @bytes = nil
+      @filename = filename || File.basename(URI.parse(url).path.to_s)
+      @filename = nil if @filename.empty? || @filename == "/"
+      @mime_type = mime_type || Attachment.mime_type_for(@filename.to_s) || DEFAULT_TYPE
+    end
+
+    def initialize_from_io(io, mime_type, filename)
+      io.rewind if io.respond_to?(:rewind)
+      io.binmode if io.respond_to?(:binmode)
+      @bytes = io.read.to_s
+      path = io.respond_to?(:path) ? io.path : nil
+      @filename = filename || (path && File.basename(path))
+      @mime_type = mime_type || (path && Attachment.mime_type_for(path)) || sniff(@bytes) || DEFAULT_TYPE
+    end
+
+    def initialize_from_bytes(bytes, mime_type, filename)
+      @url = nil
+      @bytes = bytes
+      @filename = filename
+      @mime_type = mime_type || sniff(bytes) || DEFAULT_TYPE
+      check_size!
+      self
+    end
+
+    def default_filename
+      extension = EXTENSION_TYPES.key(mime_type)
+      extension ? "file.#{extension}" : "file"
+    end
+
+    def check_size!
+      limit = OpenRouter.config.max_attachment_bytes
+      return if limit.nil? || remote? || @bytes.bytesize <= limit
+
+      raise AttachmentError,
+            "#{filename} is #{@bytes.bytesize} bytes, over the configured max_attachment_bytes (#{limit})"
+    end
+
+    # Enough magic bytes to identify anything that arrives without a filename.
+    def sniff(bytes)
+      return nil if bytes.nil? || bytes.bytesize < 12
+
+      head = bytes.byteslice(0, 12).b
+
+      case head
+      when /\A\x89PNG\r\n\x1a\n/n then "image/png"
+      when /\A\xff\xd8\xff/n then "image/jpeg"
+      when /\AGIF8[79]a/n then "image/gif"
+      when /\A%PDF-/n then "application/pdf"
+      when /\AOggS/n then "audio/ogg"
+      when /\AfLaC/n then "audio/flac"
+      when /\AID3/n, /\A\xff[\xe0-\xff]/n then "audio/mpeg"
+      when /\AFORM....AIFF/n then "audio/aiff"
+      when /\A\x1a\x45\xdf\xa3/n then "video/webm"
+      when /\ARIFF/n then head.byteslice(8, 4) == "WEBP" ? "image/webp" : "audio/wav"
+      else sniff_iso_media(head)
+      end
+    end
+
+    # MP4/MOV/M4A all start with an `ftyp` box; the brand says which.
+    def sniff_iso_media(head)
+      return nil unless head.byteslice(4, 4) == "ftyp"
+
+      case head.byteslice(8, 4).to_s
+      when /qt/ then "video/quicktime"
+      when /M4A/ then "audio/mp4"
+      else "video/mp4"
+      end
+    end
+
+  end
+end

data/lib/openrouter/client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Entry point for the API.
+  #
+  #   client = OpenRouter::Client.new(api_key: ENV["OPENROUTER_API_KEY"])
+  #   client.chat.completions.create(model: "openai/gpt-4o-mini", messages: messages)
+  #
+  # Clients are thread-safe: every request builds its own connection, and the
+  # only shared state is configuration.
+  class Client
+    DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+
+    attr_reader :api_key, :base_url, :default_model, :extra_body, :default_query, :transport
+
+    def initialize(api_key: nil, base_url: nil, site_url: nil, app_name: nil, default_model: nil,
+                   timeout: nil, open_timeout: nil, write_timeout: nil, max_retries: nil,
+                   default_headers: nil, default_query: nil, extra_body: nil,
+                   logger: nil, debug_output: nil, sleeper: nil)
+      config = OpenRouter.config
+
+      @api_key = api_key || config.api_key || ENV["OPENROUTER_API_KEY"]
+      if @api_key.nil? || @api_key.to_s.strip.empty?
+        raise ConfigurationError,
+              "No API key. Pass api_key:, set OPENROUTER_API_KEY, or call OpenRouter.configure."
+      end
+
+      @base_url = base_url || config.base_url || ENV["OPENROUTER_BASE_URL"] || DEFAULT_BASE_URL
+      @default_model = default_model || config.default_model
+      @extra_body = symbolize(extra_body || config.extra_body || {})
+      @default_query = default_query || config.default_query || {}
+
+      @transport = Transport.new(
+        base_url: @base_url,
+        headers: build_headers(site_url || config.site_url, app_name || config.app_name,
+                               default_headers || config.default_headers || {}),
+        timeout: timeout || config.timeout,
+        open_timeout: open_timeout || config.open_timeout,
+        write_timeout: write_timeout || config.write_timeout,
+        max_retries: max_retries || config.max_retries,
+        logger: logger || config.logger,
+        debug_output: debug_output || config.debug_output,
+        sleeper: sleeper
+      )
+    end
+
+    def chat
+      @chat ||= Resources::Chat.new(self)
+    end
+
+    def completions
+      @completions ||= Resources::TextCompletions.new(self)
+    end
+
+    def models
+      @models ||= Resources::Models.new(self)
+    end
+
+    def credits
+      @credits ||= Resources::Credits.new(self)
+    end
+
+    def key
+      @key ||= Resources::Key.new(self)
+    end
+
+    def generations
+      @generations ||= Resources::Generations.new(self)
+    end
+
+    def files
+      @files ||= Resources::Files.new(self)
+    end
+
+    # --- low-level escape hatches -------------------------------------------
+    # Useful for endpoints this gem has not wrapped yet.
+
+    def get(path, query: nil, headers: {}, timeout: nil)
+      @transport.request(:get, path, query: merge_query(query), headers: headers, timeout: timeout)
+    end
+
+    def post(path, body:, query: nil, headers: {}, timeout: nil)
+      @transport.request(:post, path, body: body, query: merge_query(query), headers: headers, timeout: timeout)
+    end
+
+    def delete(path, query: nil, headers: {}, timeout: nil)
+      @transport.request(:delete, path, query: merge_query(query), headers: headers, timeout: timeout)
+    end
+
+    # multipart/form-data, for file uploads.
+    def upload(path, form:, query: nil, headers: {}, timeout: nil)
+      @transport.request(:post, path, form: form, query: merge_query(query), headers: headers, timeout: timeout)
+    end
+
+    # Returns the response body as bytes instead of parsed JSON.
+    def download(path, query: nil, headers: {}, timeout: nil)
+      @transport.request(:get, path, query: merge_query(query), headers: headers, timeout: timeout, raw: true)
+    end
+
+    # Opens a server-sent-event stream. Returns an OpenRouter::Stream; the
+    # request is not sent until the stream is iterated.
+    def stream(path, body:, query: nil, headers: {}, timeout: nil)
+      enumerator, connection = @transport.stream_request(
+        :post, path, body: body, query: merge_query(query), headers: headers, timeout: timeout
+      )
+      Stream.new(enumerator, connection: connection)
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect} api_key=#{redacted_key.inspect}>"
+    end
+
+    private
+
+    def redacted_key
+      key = @api_key.to_s
+      key.length > 8 ? "#{key[0, 6]}...#{key[-4, 4]}" : "***"
+    end
+
+    def merge_query(query)
+      return @default_query if query.nil?
+      return query if @default_query.empty?
+
+      @default_query.merge(query)
+    end
+
+    def build_headers(site_url, app_name, extra)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "openrouter-ruby/#{VERSION} ruby/#{RUBY_VERSION}",
+        # Attribution headers: these are what put an app on the OpenRouter
+        # leaderboards and in the model's usage breakdown.
+        "HTTP-Referer" => site_url,
+        "X-Title" => app_name
+      }
+      headers.reject! { |_key, value| value.nil? || value.to_s.empty? }
+      headers.merge(extra)
+    end
+
+    def symbolize(hash)
+      hash.each_with_object({}) { |(key, value), memo| memo[key.to_sym] = value }
+    end
+  end
+end

data/lib/openrouter/content.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Builders for multimodal message content.
+  #
+  #   Content.text("What is in this?")
+  #   Content.image("chart.png")
+  #   Content.file("report.pdf")
+  #   Content.audio("note.m4a")
+  #   Content.video("https://example.com/clip.mp4")
+  #   Content.attach("anything.ext")   # picks the shape from the MIME type
+  #
+  # Also normalizes whole messages, so a content array can hold Pathnames, IOs,
+  # URIs and Attachments alongside plain strings.
+  module Content
+    PART_TYPES = %w[text image_url file input_audio video_url].freeze
+
+    module_function
+
+    def text(value)
+      { type: "text", text: value.to_s }
+    end
+
+    def image(source, filename: nil, mime_type: nil)
+      Attachment.from(source, filename: filename, mime_type: mime_type).to_part(as: :image)
+    end
+
+    def video(source, filename: nil, mime_type: nil)
+      Attachment.from(source, filename: filename, mime_type: mime_type).to_part(as: :video)
+    end
+
+    def audio(source, filename: nil, mime_type: nil, format: nil)
+      part = Attachment.from(source, filename: filename, mime_type: mime_type).to_part(as: :audio)
+      part[:input_audio][:format] = format.to_s if format
+      part
+    end
+
+    # A document part. Pass `id:` to reference a file already uploaded through
+    # client.files, otherwise the file is inlined as a data URL (or its https
+    # URL, which OpenRouter will fetch itself).
+    def file(source = nil, id: nil, filename: nil, mime_type: nil)
+      if id
+        part = { type: "file", file: { file_id: id } }
+        part[:file][:filename] = filename if filename
+        return part
+      end
+
+      raise ArgumentError, "pass a file source or id:" if source.nil?
+
+      Attachment.from(source, filename: filename, mime_type: mime_type).to_part(as: :file)
+    end
+
+    # Builds whichever part suits the file: images become image_url, video
+    # becomes video_url, audio becomes input_audio, everything else a file part.
+    def attach(source, as: nil, filename: nil, mime_type: nil)
+      Attachment.from(source, filename: filename, mime_type: mime_type).to_part(as: as)
+    end
+
+    # Decodes a data URL — e.g. an image a model returned — into an Attachment
+    # you can inspect or #save.
+    def decode(source)
+      url = source.is_a?(Hash) || source.is_a?(Structure) ? extract_url(source) : source
+      Attachment.from_data_url(url)
+    end
+
+    # Coerces one item into a content part. Strings stay text: a string is never
+    # guessed to be a path, because a user's own words must never be read off
+    # the filesystem. Attach files explicitly, or with non-String types.
+    def part(item)
+      case item
+      when Hash then item
+      when Structure then item.to_h
+      when String then text(item)
+      when Symbol, Numeric then text(item.to_s)
+      when Attachment then item.to_part
+      when Pathname, IO, StringIO, URI::Generic then attach(item)
+      when nil then nil
+      else
+        raise ArgumentError, "cannot turn a #{item.class} into message content"
+      end
+    end
+
+    def parts(*items)
+      items.flatten(1).filter_map { |item| part(item) }
+    end
+
+    # Normalizes one message: expands an `attachments:` shorthand and converts
+    # every element of a content array into a content part.
+    def normalize_message(message)
+      message = message.to_h if message.is_a?(Structure)
+      return message unless message.is_a?(Hash)
+
+      attachments = message[:attachments] || message["attachments"]
+      content = message.key?(:content) ? message[:content] : message["content"]
+
+      return message if attachments.nil? && !content.is_a?(Array)
+
+      normalized = message.reject { |key, _| key.to_s == "attachments" }
+      normalized = symbolize(normalized)
+      normalized[:content] = build_content(content, attachments)
+      normalized
+    end
+
+    def normalize_messages(messages)
+      Array(messages).map { |message| normalize_message(message) }
+    end
+
+    # --- internals ----------------------------------------------------------
+
+    def build_content(content, attachments)
+      parts =
+        case content
+        when Array then parts(*content)
+        when nil then []
+        else [part(content)].compact
+        end
+
+      parts + Array(attachments).map { |attachment| part_for_attachment(attachment) }
+    end
+
+    # Inside `attachments:` a String IS a path or URL — that is what the key
+    # means, so the ambiguity that applies to content strings does not arise.
+    def part_for_attachment(item)
+      case item
+      when Hash
+        PART_TYPES.include?((item[:type] || item["type"]).to_s) ? item : attach_from_hash(item)
+      when Structure then part_for_attachment(item.to_h)
+      when String then attach(item)
+      else part(item)
+      end
+    end
+
+    def attach_from_hash(options)
+      options = symbolize(options)
+      source = options.delete(:source) || options.delete(:path) || options.delete(:url)
+      id = options.delete(:id) || options.delete(:file_id)
+      return file(id: id, filename: options[:filename]) if id
+
+      attach(source, **options.slice(:as, :filename, :mime_type))
+    end
+
+    def extract_url(item)
+      item = item.to_h if item.is_a?(Structure)
+      item[:url] || item["url"] ||
+        dig_url(item[:image_url] || item["image_url"]) ||
+        dig_url(item[:video_url] || item["video_url"]) ||
+        raise(ArgumentError, "no url found in #{item.inspect}")
+    end
+
+    def dig_url(value)
+      return nil if value.nil?
+
+      value = value.to_h if value.is_a?(Structure)
+      value.is_a?(Hash) ? (value[:url] || value["url"]) : value
+    end
+
+    def symbolize(hash)
+      hash.each_with_object({}) { |(key, value), memo| memo[key.to_sym] = value }
+    end
+  end
+end