ruby-openrouter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40e456245000d212db0fb5c0c4eec0aa832d090a18b6b3b716065dd46145b303
+  data.tar.gz: 1fbb0f12e01b79875184a02ddd8419da8a56338d10d6cf97c369590a7f4c9094
+SHA512:
+  metadata.gz: 8284009feb1cfdd07cddd1e465639e162552e89aed58e47a8c07eeed10198e86ee888372fb53574a33248e06c82e9f52e9dd841df11d7ceef174e5526a65ef73
+  data.tar.gz: 439e38643558e050df3d598f961993e08350b18836665296feb00b75ebf8a6e5ac9a5d2eeabb80abe42914a94b49dda7324a08c3518899f38b42d45f57f6623b

data/README.md

@@ -0,0 +1,230 @@
+# ruby-openrouter
+
+A minimal, conversational Ruby client for the [OpenRouter](https://openrouter.ai) API — access hundreds of LLMs (Claude, GPT-4, Gemini, Llama, and more) through a single, clean interface.
+
+```ruby
+client = RubyOpenrouter::Client.new(model: "anthropic/claude-3.5-sonnet")
+client.system("You are a concise assistant.")
+
+puts client.user("What is Ruby?")
+#=> "Ruby is a dynamic, open-source programming language..."
+```
+
+---
+
+## Features
+
+- **Conversational by default** — message history is maintained automatically across turns
+- **Streaming support** — receive tokens in real time via a simple block
+- **Multi-turn context** — system, user, and assistant messages compose naturally
+- **Error hierarchy** — typed exceptions for auth, rate limits, and server errors
+- **Zero magic** — one client, one model, clear methods
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ruby-openrouter"
+```
+
+Or install directly:
+
+```sh
+gem install ruby-openrouter
+```
+
+---
+
+## Quick Start
+
+```ruby
+require "ruby_openrouter"
+
+client = RubyOpenrouter::Client.new(
+  model:   "openai/gpt-4o",
+  api_key: ENV["OPENROUTER_API_KEY"]
+)
+
+reply = client.user("Explain quantum entanglement in one sentence.")
+puts reply
+```
+
+---
+
+## Configuration
+
+### Per-client
+
+Pass options directly when instantiating:
+
+```ruby
+client = RubyOpenrouter::Client.new(
+  model:     "anthropic/claude-3.5-sonnet",
+  api_key:   ENV["OPENROUTER_API_KEY"],
+  site_url:  "https://myapp.com",   # sent as HTTP-Referer for attribution
+  site_name: "MyApp",               # sent as X-Title
+  timeout:   60
+)
+```
+
+### Global
+
+Set defaults once at startup (e.g., in an initializer):
+
+```ruby
+RubyOpenrouter.configure do |config|
+  config.api_key   = ENV["OPENROUTER_API_KEY"]
+  config.site_url  = "https://myapp.com"
+  config.site_name = "MyApp"
+  config.timeout   = 30
+end
+
+# All clients created afterwards will use these defaults
+client = RubyOpenrouter::Client.new(model: "openai/gpt-4o-mini")
+```
+
+---
+
+## Usage
+
+### System prompt
+
+```ruby
+client.system("You are a Ruby expert. Keep answers short.")
+```
+
+Calling `#system` again replaces the existing system message — there is always at most one.
+
+### Chat
+
+```ruby
+reply = client.user("What is a Proc?")
+puts reply  #=> "A Proc is a block of code..."
+
+# Continue the conversation — history is kept automatically
+reply = client.user("How does it differ from a lambda?")
+puts reply  #=> "Unlike a lambda, a Proc does not..."
+```
+
+### Streaming
+
+Pass a block to `#user` to receive tokens as they arrive:
+
+```ruby
+client.user("Write a haiku about Ruby.") do |chunk|
+  print chunk
+end
+# Streams: "Elegant syntax flows / Objects dance in harmony / Matz smiles warmly"
+puts
+```
+
+The full response is appended to conversation history even when streaming.
+
+### Few-shot examples
+
+Seed the conversation with pre-written assistant turns using `#assistant`:
+
+```ruby
+client.user("Translate: hello")
+client.assistant("Hola")
+
+client.user("Translate: goodbye")
+client.assistant("Adiós")
+
+puts client.user("Translate: thank you")
+#=> "Gracias"
+```
+
+### Reset
+
+Clear the conversation history while keeping the system prompt:
+
+```ruby
+client.system("You are a chef.")
+client.user("What is mise en place?")
+
+client.reset  # clears user/assistant turns, keeps system prompt
+
+client.user("What is a roux?")  # fresh start, still a chef
+```
+
+### List available models
+
+```ruby
+# From a client instance
+models = client.models
+models.each { |m| puts m["id"] }
+
+# Or at the module level
+models = RubyOpenrouter.models(api_key: ENV["OPENROUTER_API_KEY"])
+models.first(5).each { |m| puts "#{m["id"]} — #{m["name"]}" }
+```
+
+---
+
+## Error Handling
+
+```ruby
+begin
+  reply = client.user("Hello!")
+rescue RubyOpenrouter::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue RubyOpenrouter::RateLimitError => e
+  puts "Rate limited (status #{e.status}), retry later"
+rescue RubyOpenrouter::ServerError => e
+  puts "OpenRouter server error: #{e.message}"
+rescue RubyOpenrouter::APIError => e
+  puts "API error #{e.status}: #{e.message}"
+rescue RubyOpenrouter::ConfigurationError => e
+  puts "Configuration problem: #{e.message}"
+end
+```
+
+| Exception | HTTP status |
+|---|---|
+| `AuthenticationError` | 401 |
+| `BadRequestError` | 400 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `APIError` | any other 4xx/5xx |
+| `ConfigurationError` | — (missing `api_key`) |
+
+---
+
+## Model IDs
+
+OpenRouter uses `provider/model` identifiers. Some popular ones:
+
+| Model | ID |
+|---|---|
+| Claude 3.5 Sonnet | `anthropic/claude-3.5-sonnet` |
+| GPT-4o | `openai/gpt-4o` |
+| GPT-4o mini | `openai/gpt-4o-mini` |
+| Gemini 1.5 Pro | `google/gemini-pro-1.5` |
+| Llama 3.3 70B | `meta-llama/llama-3.3-70b-instruct` |
+
+See all available models at [openrouter.ai/models](https://openrouter.ai/models) or via `client.models`.
+
+---
+
+## Development
+
+```sh
+git clone https://github.com/deyvin/ruby-openrouter
+cd ruby-openrouter
+bundle install
+
+bundle exec rspec       # run tests
+bundle exec rubocop     # lint
+```
+
+Tests use [WebMock](https://github.com/bblimke/webmock) — no real API calls are made.
+
+---
+
+## License
+
+MIT

data/lib/ruby_openrouter/client.rb

@@ -0,0 +1,72 @@
+module RubyOpenrouter
+  class Client
+    def initialize(model:, api_key: nil, site_url: nil, site_name: nil, timeout: nil)
+      @model    = model
+      @config   = build_config(api_key: api_key, site_url: site_url, site_name: site_name, timeout: timeout)
+      @messages = []
+    end
+
+    def system(content)
+      @messages.reject! { |m| m[:role] == "system" }
+      @messages.unshift(role: "system", content: content)
+      self
+    end
+
+    def user(content, &block)
+      @messages << { role: "user", content: content }
+      if block
+        accumulated = ""
+        Http.stream("/chat/completions", body: request_body(stream: true), config: @config) do |chunk|
+          accumulated += chunk
+          block.call(chunk)
+        end
+        @messages << { role: "assistant", content: accumulated } unless accumulated.empty?
+        nil
+      else
+        text = complete
+        @messages << { role: "assistant", content: text }
+        text
+      end
+    end
+
+    def assistant(content)
+      @messages << { role: "assistant", content: content }
+      self
+    end
+
+    def reset
+      system_msg = @messages.find { |m| m[:role] == "system" }
+      @messages  = system_msg ? [system_msg] : []
+      self
+    end
+
+    def models
+      Http.get("/models", config: @config).fetch("data", [])
+    end
+
+    private
+
+    def complete
+      body = request_body
+      resp = Http.post("/chat/completions", body: body, config: @config)
+      resp.dig("choices", 0, "message", "content").to_s
+    end
+
+    def request_body(stream: false)
+      body = { model: @model, messages: @messages }
+      body[:stream] = true if stream
+      body
+    end
+
+    def build_config(api_key:, site_url:, site_name:, timeout:)
+      base = RubyOpenrouter.configuration
+      cfg  = Configuration.new
+      cfg.api_key   = api_key   || base.api_key   || raise(ConfigurationError, "api_key is required")
+      cfg.base_url  = base.base_url
+      cfg.timeout   = timeout   || base.timeout
+      cfg.site_url  = site_url  || base.site_url
+      cfg.site_name = site_name || base.site_name
+      cfg
+    end
+  end
+end

data/lib/ruby_openrouter/configuration.rb

@@ -0,0 +1,10 @@
+module RubyOpenrouter
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :site_url, :site_name
+
+    def initialize
+      @base_url = "https://openrouter.ai/api/v1"
+      @timeout  = 30
+    end
+  end
+end

data/lib/ruby_openrouter/error.rb

@@ -0,0 +1,20 @@
+module RubyOpenrouter
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class APIError < Error
+    attr_reader :status, :code
+
+    def initialize(message, status: nil, code: nil)
+      super(message)
+      @status = status
+      @code   = code
+    end
+  end
+
+  class AuthenticationError < APIError; end
+  class BadRequestError < APIError; end
+  class RateLimitError < APIError; end
+  class ServerError < APIError; end
+end

data/lib/ruby_openrouter/http.rb

@@ -0,0 +1,96 @@
+require "faraday"
+require "faraday/retry"
+require "net/http"
+require "uri"
+require "json"
+
+module RubyOpenrouter
+  module Http
+    def self.connection(config)
+      Faraday.new(url: config.base_url.chomp("/") + "/") do |conn|
+        conn.request  :retry, max: 2, interval: 0.5, retry_statuses: [429, 500, 502, 503]
+        conn.request  :json
+        conn.response :json
+        conn.headers["Authorization"]  = "Bearer #{config.api_key}"
+        conn.headers["Content-Type"]   = "application/json"
+        conn.headers["HTTP-Referer"]   = config.site_url  if config.site_url
+        conn.headers["X-Title"]        = config.site_name if config.site_name
+        conn.options.timeout = config.timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def self.post(path, body:, config:)
+      resp = connection(config).post(relative(path), body)
+      handle_error(resp)
+      resp.body
+    end
+
+    def self.get(path, config:)
+      resp = connection(config).get(relative(path))
+      handle_error(resp)
+      resp.body
+    end
+
+    def self.relative(path)
+      path.sub(%r{^/}, "")
+    end
+    private_class_method :relative
+
+    def self.stream(path, body:, config:, &block)
+      uri = URI.join(config.base_url + "/", path.sub(%r{^/}, ""))
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = uri.scheme == "https"
+      http.read_timeout = config.timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Authorization"] = "Bearer #{config.api_key}"
+      request["Content-Type"]  = "application/json"
+      request["HTTP-Referer"]  = config.site_url  if config.site_url
+      request["X-Title"]       = config.site_name if config.site_name
+      request.body = JSON.generate(body)
+
+      buffer = ""
+      http.request(request) do |response|
+        raise_for_status(response.code.to_i, nil)
+        response.read_body do |raw_chunk|
+          buffer += raw_chunk
+          while (line_end = buffer.index("\n"))
+            line   = buffer.slice!(0..line_end).strip
+            buffer = buffer.lstrip
+            next unless line.start_with?("data: ")
+
+            payload = line.delete_prefix("data: ")
+            next if payload == "[DONE]"
+
+            chunk = JSON.parse(payload) rescue next
+            text  = chunk.dig("choices", 0, "delta", "content")
+            block.call(text) if text && !text.empty?
+          end
+        end
+      end
+    end
+
+    def self.handle_error(resp)
+      raise_for_status(resp.status, resp.body)
+    end
+    private_class_method :handle_error
+
+    def self.raise_for_status(status, body)
+      return if status < 400
+
+      message = body.is_a?(Hash) ? body.dig("error", "message").to_s : body.to_s
+      code    = body.is_a?(Hash) ? body.dig("error", "code") : nil
+
+      klass = case status
+              when 401 then AuthenticationError
+              when 400 then BadRequestError
+              when 429 then RateLimitError
+              when 500..599 then ServerError
+              else APIError
+              end
+      raise klass.new(message, status: status, code: code)
+    end
+    private_class_method :raise_for_status
+  end
+end

data/lib/ruby_openrouter/version.rb

@@ -0,0 +1,3 @@
+module RubyOpenrouter
+  VERSION = "0.1.0"
+end

data/lib/ruby_openrouter.rb

@@ -0,0 +1,25 @@
+require_relative "ruby_openrouter/version"
+require_relative "ruby_openrouter/configuration"
+require_relative "ruby_openrouter/error"
+require_relative "ruby_openrouter/http"
+require_relative "ruby_openrouter/client"
+
+module RubyOpenrouter
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def models(api_key: nil)
+      cfg          = Configuration.new
+      cfg.api_key  = api_key || configuration.api_key || raise(ConfigurationError, "api_key is required")
+      cfg.base_url = configuration.base_url
+      cfg.timeout  = configuration.timeout
+      Http.get("/models", config: cfg).fetch("data", [])
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: ruby-openrouter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Deyvin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+description: A minimal conversational Ruby client for OpenRouter — chat completions
+  with streaming, model listing, and multi-turn history.
+email:
+- deyvin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ruby_openrouter.rb
+- lib/ruby_openrouter/client.rb
+- lib/ruby_openrouter/configuration.rb
+- lib/ruby_openrouter/error.rb
+- lib/ruby_openrouter/http.rb
+- lib/ruby_openrouter/version.rb
+homepage: https://github.com/deyvin/ruby-openrouter
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the OpenRouter API
+test_files: []