rails-openrouter 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b99e554b9e3425a327fa9ee77856011f116d1af448cadeb9c43785c9aaec1ad
+  data.tar.gz: 18b57554ab254780e7f62ecf537e840c5b94b8e0a1d895b8948693dd242c0094
+SHA512:
+  metadata.gz: ee7a5bc9fd48c9293092783fef65f044307058e44b254e7826828af03bf2b7ba300614f7887a292f17fc06290e830d665edc390758a9e9e25b39c5669c981231
+  data.tar.gz: 1ac4d15260d8e8446076ae7a8a3deeae4c618d2a4a24bef62d36a9e8e09a1182df9eb6e13f6dc87e0a0cdf9879763b5b36ac7059ede3c5d1477bbb1e8a5f3dbf

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [0.2.0] - 2026-09-07
+
+Multimodal input and output.
+
+- `OpenRouter::Attachment` — wraps a path, Pathname, IO, raw bytes, https URL
+  or data URL; detects the MIME type by extension and by magic bytes; encodes
+  to a data URL
+- `OpenRouter::Content` builders (`text`, `image`, `file`, `audio`, `video`,
+  `attach`) producing the right content part per media type, plus whole-message
+  normalization and an `attachments:` shorthand
+- `OpenRouter::Message.user/system/assistant/tool` constructors with `attach:`
+- `pdf_engine:` sugar for the `file-parser` plugin
+- `client.files` — upload (multipart), list, retrieve, delete, download
+- `client.models.list(input_modalities:, output_modalities:)` to find models
+  that accept the media you are sending
+- `Content.decode` turns a returned image data URL into a savable Attachment
+- `config.max_attachment_bytes` guard
+
+## [0.1.0] - 2026-09-07
+
+Initial release.
+
+- `client.chat.completions.create` / `.stream` with server-sent-event streaming
+- Chunk accumulation into a final completion, including tool-call arguments
+  and reasoning tokens
+- `models`, `credits`, `key` and `generations` resources
+- Typed errors mapped from OpenRouter status codes, automatic retries with
+  jittered backoff and `Retry-After` support
+- No runtime dependencies

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afshin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,373 @@
+# rails-openrouter
+
+A Ruby client for the [OpenRouter](https://openrouter.ai) API, built around
+streaming. One API key, 400+ models, and the same ergonomics as OpenRouter's
+official SDKs — `client.chat.completions.create` / `.stream`, chunk iteration,
+and a final completion assembled for you.
+
+Text, images, PDFs, audio and video in; text and images out. No runtime
+dependencies: it is `net/http` and `json` from the standard library.
+
+```ruby
+client = OpenRouter::Client.new(api_key: ENV["OPENROUTER_API_KEY"])
+
+client.chat.completions.stream(
+  model: "anthropic/claude-sonnet-4.5",
+  messages: [{ role: "user", content: "Write a haiku about sockets" }]
+).each_text { |text| print(text) }
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "rails-openrouter"
+```
+
+Or `gem install rails-openrouter`. Requires Ruby 3.0+.
+
+The library is namespaced `OpenRouter` and has no Rails dependency — it works in
+any Ruby program. Bundler loads it for you; outside Bundler, `require "openrouter"`
+and `require "rails-openrouter"` both work.
+
+## Configuration
+
+Pass options per client:
+
+```ruby
+client = OpenRouter::Client.new(
+  api_key: ENV["OPENROUTER_API_KEY"], # defaults to ENV["OPENROUTER_API_KEY"]
+  site_url: "https://example.com",    # sent as HTTP-Referer, for leaderboards
+  app_name: "My App",                 # sent as X-Title
+  default_model: "openai/gpt-4o-mini",
+  timeout: 600,                       # read timeout, seconds
+  open_timeout: 10,
+  max_retries: 2
+)
+```
+
+…or globally, once, for `OpenRouter.client`:
+
+```ruby
+OpenRouter.configure do |config|
+  config.api_key = ENV["OPENROUTER_API_KEY"]
+  config.app_name = "My App"
+  config.default_model = "openai/gpt-4o-mini"
+end
+
+OpenRouter.chat.completions.create(messages: [{ role: "user", content: "Hi" }])
+```
+
+Clients are thread-safe; a single one can be shared across a web app's threads.
+
+## Chat completions
+
+```ruby
+completion = client.chat.completions.create(
+  model: "openai/gpt-4o-mini",
+  messages: [
+    { role: "system", content: "You are terse." },
+    { role: "user", content: "Why is the sky blue?" }
+  ],
+  temperature: 0.2,
+  max_tokens: 200
+)
+
+completion.choices.first.message.content
+completion.usage.total_tokens
+completion.to_h # plain Hash with symbol keys
+```
+
+Responses are `OpenRouter::Structure` objects: dot access, `[]` with strings or
+symbols, `dig`, and `to_h`. Missing keys return `nil` rather than raising, so
+`chunk.choices.first.delta.content` is safe on chunks that carry no text.
+
+Every unrecognised keyword is forwarded to the API as-is, so OpenRouter-specific
+and newly shipped parameters work without a gem upgrade:
+
+```ruby
+client.chat.completions.create(
+  model: "anthropic/claude-sonnet-4.5",
+  models: ["openai/gpt-4o", "google/gemini-2.5-pro"],  # fallbacks
+  provider: { order: ["Anthropic"], allow_fallbacks: false },
+  reasoning: { effort: "high" },
+  transforms: ["middle-out"],
+  plugins: [{ id: "web" }],
+  usage: { include: true },
+  messages: messages
+)
+```
+
+## Streaming
+
+`stream` returns an `OpenRouter::Stream`, a lazy `Enumerable` over chunks.
+Nothing is sent until you start iterating.
+
+```ruby
+stream = client.chat.completions.stream(model: model, messages: messages)
+
+stream.each_text { |text| print(text) }        # only the text deltas
+stream.each { |chunk| p chunk.choices.first }  # raw chunks
+stream.each_reasoning { |text| print(text) }   # reasoning tokens
+```
+
+Chunks are accumulated as they pass through, so once the stream is consumed the
+assembled response is free:
+
+```ruby
+stream.final_completion  # shaped exactly like a non-streaming response
+stream.final_message     # .content, .tool_calls, .reasoning
+stream.text              # the full text of choice 0
+stream.usage             # prompt/completion/total tokens, and cost
+```
+
+`snapshot` gives you the partial completion mid-stream without consuming more.
+
+Passing a block streams and returns the finished completion, which is the
+shortest form when you only want the side effect:
+
+```ruby
+completion = client.chat.completions.create(model: model, messages: messages, stream: true) do |chunk|
+  print(chunk.choices.first.delta.content)
+end
+```
+
+Stop early and release the socket with `close`:
+
+```ruby
+stream.each do |chunk|
+  break if enough?(chunk)
+end
+stream.close
+```
+
+Iterating a stream again replays the chunks already seen and then continues from
+where it stopped — a second pass never issues a second request.
+
+Keep-alive comments (`: OPENROUTER PROCESSING`, sent while a provider is still
+queueing) are handled internally and never surface as chunks.
+
+### Tool calls
+
+Tool-call arguments arrive as fragments spread across chunks. The accumulator
+stitches them back together per call index:
+
+```ruby
+stream = client.chat.completions.stream(messages: messages, tools: tools)
+stream.each_text { |text| print(text) }
+
+stream.final_message.tool_calls&.each do |call|
+  args = JSON.parse(call.function.arguments)
+  # dispatch call.function.name with args, append a role: "tool" message, loop
+end
+```
+
+See `examples/tool_calling.rb` for the full round trip.
+
+## Multimodal: images, PDFs, audio, video
+
+Attach files by handing them to `Message.user(..., attach:)`, or by putting
+non-String objects (`Pathname`, `IO`, `URI`, `Attachment`) in a content array.
+The right content part is chosen from the file's MIME type: `image_url` for
+images, `file` for documents, `input_audio` for audio, `video_url` for video.
+
+```ruby
+client.chat.completions.stream(
+  model: "google/gemini-3-flash-preview",
+  messages: [
+    OpenRouter::Message.user("What changed between these?", attach: [
+      "before.png",                          # local file, inlined as a data URL
+      Pathname("after.png"),
+      "https://example.com/spec.pdf",        # URL: OpenRouter fetches it
+      { id: "or_file_abc" }                  # a file already uploaded
+    ])
+  ]
+).each_text { |text| print(text) }
+```
+
+**Strings in `content` are always text, never paths.** A path is only read from
+disk when it arrives through `attach:`, `Content.attach`, or as a non-String
+type — so a user's own words can never be turned into a file read.
+
+```ruby
+# text, not a file read:
+{ role: "user", content: "please check ./report.pdf" }
+
+# a file read, because you asked for one:
+OpenRouter::Message.user("please check this", attach: ["./report.pdf"])
+```
+
+Build parts explicitly when you want to:
+
+```ruby
+OpenRouter::Content.text("What is this?")
+OpenRouter::Content.image("chart.png")                 # or a URL, IO, Pathname
+OpenRouter::Content.file("report.pdf")
+OpenRouter::Content.file(id: "or_file_abc")            # previously uploaded
+OpenRouter::Content.audio("note.m4a")                  # base64 only, per the API
+OpenRouter::Content.video("https://example.com/clip.mp4")
+OpenRouter::Content.attach("whatever.ext")             # shape picked by MIME type
+```
+
+Supported out of the box: PNG/JPEG/WebP/GIF images; PDF and other documents;
+`wav mp3 aiff aac ogg flac m4a pcm16` audio; `mp4 mpeg mov webm` video. Types
+are detected from the file extension, and from magic bytes when an IO or raw
+bytes arrive without a name. Override either with `mime_type:` / `as:`.
+
+### PDFs
+
+`pdf_engine:` is sugar for the `file-parser` plugin:
+
+```ruby
+client.chat.completions.create(
+  model: model,
+  messages: [OpenRouter::Message.user("Summarize", attach: ["report.pdf"])],
+  pdf_engine: "native"        # model reads the file itself, billed as input tokens
+  # "mistral-ocr"             # scanned pages and images, $2 per 1k pages
+  # "cloudflare-ai"           # PDF to markdown, free
+)
+```
+
+Parsing is charged per request, so for a document you will ask about more than
+once, append the assistant reply — `annotations` and all — to your message
+history and OpenRouter reuses the parse instead of redoing it:
+
+```ruby
+messages << completion.choices.first.message.to_h   # includes annotations
+messages << OpenRouter::Message.user("And the risks section?")
+```
+
+### Uploading files once
+
+```ruby
+file = client.files.upload("report.pdf")            # path, Pathname, IO or Attachment
+file.id                                             # => "or_file_..."
+
+client.files.list
+client.files.retrieve(file.id)
+client.files.download(file.id, to: "copy.pdf")      # server-created files only
+client.files.delete(file.id)
+```
+
+Then reference it by id — no re-encoding on every request:
+
+```ruby
+OpenRouter::Message.user("What is the total?", attach: [{ id: file.id }])
+```
+
+### Which models accept what
+
+```ruby
+client.models.list(input_modalities: %w[text image])   # vision models
+client.models.list(input_modalities: "file")           # models that read documents
+client.models.list(output_modalities: "image")         # models that draw
+```
+
+### Media coming back
+
+Image output arrives as data URLs on the message. `Content.decode` turns one
+into an `Attachment` you can save:
+
+```ruby
+completion = client.chat.completions.create(
+  model: "google/gemini-3-flash-image",
+  messages: [{ role: "user", content: "A cat on a bicycle" }],
+  modalities: %w[image text]
+)
+
+completion.choices.first.message.images.each_with_index do |image, index|
+  OpenRouter::Content.decode(image).save("cat-#{index}.png")
+end
+```
+
+This works on streams too — `stream.final_message.images` is assembled from the
+chunks like everything else.
+
+### Working with attachments directly
+
+```ruby
+attachment = OpenRouter::Attachment.new("clip.mp4")
+attachment.mime_type  # => "video/mp4"
+attachment.kind       # => :video
+attachment.size       # => 2_481_233
+attachment.data_url   # => "data:video/mp4;base64,..."
+attachment.save("copy.mp4")
+```
+
+Base64 inflates a file by about a third, and the whole thing is held in memory
+and in the request body. For anything large, prefer an https URL or
+`client.files.upload`. `config.max_attachment_bytes` sets a ceiling if you want
+one — attachments over it raise `OpenRouter::AttachmentError` rather than
+silently building a huge request. Audio is the one modality with no URL form in
+the API, so it is always inlined.
+
+## Other endpoints
+
+```ruby
+client.models.list                                  # every routable model
+client.models.list(supported_parameters: "tools")   # filtered
+client.models.endpoints("openai/gpt-4o")            # providers, pricing, limits
+client.credits.retrieve                             # purchased vs. used
+client.key.retrieve                                 # limits for the current key
+client.generations.retrieve(completion.id)          # cost accounting for one call
+client.files.list                                   # uploaded files
+```
+
+Anything not wrapped yet is reachable through the low-level methods, which
+return plain hashes:
+
+```ruby
+client.get("some/new/endpoint", query: { foo: "bar" })
+client.post("some/new/endpoint", body: { foo: "bar" })
+client.stream("some/new/endpoint", body: { foo: "bar", stream: true })
+```
+
+## Errors
+
+All errors descend from `OpenRouter::Error`.
+
+| Class | Raised on |
+| --- | --- |
+| `BadRequestError` | 400 |
+| `AuthenticationError` | 401 — missing, invalid or expired key |
+| `InsufficientCreditsError` | 402 |
+| `ModerationError` | 403 — input flagged |
+| `NotFoundError` | 404 |
+| `RequestTimeoutError` | 408 |
+| `RateLimitError` | 429 |
+| `BadGatewayError` | 502 — provider returned garbage |
+| `NoProviderAvailableError` | 503 — no provider matches your routing |
+| `InternalServerError` | other 5xx |
+| `APITimeoutError` | the request timed out locally |
+| `APIConnectionError` | DNS/TCP/TLS failure |
+| `AttachmentError` | a file could not be read, or cannot be sent in that shape |
+
+Each `APIError` carries `status`, `code`, `body`, `headers`, `request_id` and
+`metadata` — provider failures put the upstream message in
+`error.metadata[:raw]`, which is also folded into the exception message.
+
+OpenRouter can also report a failure *inside* a 200 response, and mid-stream
+after chunks have already arrived. Both are raised as the same typed errors, so
+a `rescue` around your iteration is worth having.
+
+## Retries
+
+`408, 409, 429, 500, 502, 503, 504` and connection failures are retried up to
+`max_retries` times (default 2) with exponential backoff and jitter, honouring
+`Retry-After` when the server sends it. Streams are only retried while no chunk
+has reached your code yet — a half-delivered stream is never restarted, because
+that would duplicate output.
+
+## Development
+
+```bash
+rake test
+```
+
+The suite runs against a real in-process HTTP server (`test/test_helper.rb`), so
+chunked transfer encoding, split SSE frames, early disconnects and retries are
+exercised end to end. No network access and no stubbing library required.
+
+## License
+
+MIT.

data/lib/openrouter/accumulator.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Folds streamed chunks back into the single completion object the
+  # non-streaming endpoint would have returned.
+  #
+  # This mirrors what the official SDKs expose as the stream's final message:
+  # deltas for content, reasoning and tool-call arguments are concatenated per
+  # choice index, and the last non-nil value wins for scalar fields.
+  class Accumulator
+    def initialize
+      @meta = {}
+      @choices = {}
+      @usage = nil
+    end
+
+    def add(chunk)
+      chunk = chunk.to_h if chunk.is_a?(Structure)
+      return self unless chunk.is_a?(Hash)
+
+      %i[id model object created provider system_fingerprint citations].each do |key|
+        @meta[key] = chunk[key] unless chunk[key].nil?
+      end
+      @usage = chunk[:usage] unless chunk[:usage].nil?
+
+      Array(chunk[:choices]).each { |choice| add_choice(choice) }
+      self
+    end
+    alias << add
+
+    # The completion assembled so far. Safe to call mid-stream.
+    def snapshot
+      completion = @meta.merge(
+        object: "chat.completion",
+        choices: @choices.keys.sort.map { |index| render_choice(@choices[index]) }
+      )
+      completion[:usage] = @usage if @usage
+      completion
+    end
+
+    def empty?
+      @choices.empty? && @meta.empty?
+    end
+
+    # Concatenated text of the first choice, which is what most callers want.
+    def text
+      choice = @choices[@choices.keys.min]
+      choice ? choice[:content].dup : ""
+    end
+
+    private
+
+    def add_choice(choice)
+      return unless choice.is_a?(Hash)
+
+      index = choice[:index] || 0
+      state = (@choices[index] ||= new_choice(index))
+
+      state[:finish_reason] = choice[:finish_reason] unless choice[:finish_reason].nil?
+      state[:native_finish_reason] = choice[:native_finish_reason] unless choice[:native_finish_reason].nil?
+      state[:logprobs] = choice[:logprobs] unless choice[:logprobs].nil?
+      state[:error] = choice[:error] unless choice[:error].nil?
+
+      # `message` appears instead of `delta` when a non-streaming payload is fed
+      # through the accumulator, and on some providers' final chunk.
+      delta = choice[:delta] || choice[:message]
+      return unless delta.is_a?(Hash)
+
+      state[:role] = delta[:role] if delta[:role]
+      state[:content] << delta[:content] if delta[:content].is_a?(String)
+      state[:reasoning] << delta[:reasoning] if delta[:reasoning].is_a?(String)
+      state[:refusal] = delta[:refusal] if delta[:refusal]
+      state[:annotations].concat(Array(delta[:annotations])) if delta[:annotations]
+      state[:reasoning_details].concat(Array(delta[:reasoning_details])) if delta[:reasoning_details]
+      state[:images].concat(Array(delta[:images])) if delta[:images]
+
+      Array(delta[:tool_calls]).each { |call| add_tool_call(state, call) }
+    end
+
+    def add_tool_call(state, call)
+      return unless call.is_a?(Hash)
+
+      # Providers key partial tool calls by `index`; a few omit it entirely and
+      # only ever emit one call per chunk, so fall back to arrival order.
+      index = call[:index] || state[:tool_calls].size
+      entry = (state[:tool_calls][index] ||= { index: index, type: "function", function: { name: +"", arguments: +"" } })
+
+      entry[:id] = call[:id] if call[:id]
+      entry[:type] = call[:type] if call[:type]
+
+      function = call[:function]
+      return unless function.is_a?(Hash)
+
+      entry[:function][:name] << function[:name] if function[:name].is_a?(String)
+      entry[:function][:arguments] << function[:arguments] if function[:arguments].is_a?(String)
+    end
+
+    def new_choice(index)
+      {
+        index: index,
+        role: nil,
+        content: +"",
+        reasoning: +"",
+        reasoning_details: [],
+        annotations: [],
+        images: [],
+        refusal: nil,
+        tool_calls: {},
+        finish_reason: nil,
+        native_finish_reason: nil,
+        logprobs: nil,
+        error: nil
+      }
+    end
+
+    def render_choice(state)
+      message = { role: state[:role] || "assistant", content: state[:content] }
+      message[:reasoning] = state[:reasoning] unless state[:reasoning].empty?
+      message[:reasoning_details] = state[:reasoning_details] unless state[:reasoning_details].empty?
+      message[:annotations] = state[:annotations] unless state[:annotations].empty?
+      message[:images] = state[:images] unless state[:images].empty?
+      message[:refusal] = state[:refusal] if state[:refusal]
+
+      unless state[:tool_calls].empty?
+        message[:tool_calls] = state[:tool_calls].keys.sort.map do |index|
+          call = state[:tool_calls][index]
+          { id: call[:id], type: call[:type], function: call[:function] }
+        end
+      end
+
+      choice = { index: state[:index], message: message, finish_reason: state[:finish_reason] }
+      choice[:native_finish_reason] = state[:native_finish_reason] if state[:native_finish_reason]
+      choice[:logprobs] = state[:logprobs] if state[:logprobs]
+      choice[:error] = state[:error] if state[:error]
+      choice
+    end
+  end
+end