openrouter_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83e60f6533fc86470014efb28c27ba4f714322de55613bb1a990f5c623922f35
+  data.tar.gz: 592ff75e2be878e65655321a402148e6386499176d388de7f0a8fad76bc537d5
+SHA512:
+  metadata.gz: c2dfb5c991c3a135601517d73b30c5eb95466033ee35c1d837ecc262fd6b42c3e21125990359d7e3ce69838395c03bc350369ffdb3861af34401f07d8a7444b0
+  data.tar.gz: 3c1335769301ebb1a617d89a6189b3fadce8b7f7b6cf55256471bf6abc351a36de0a6a96d083cd94c7fdfec52e99af414b9e336c34a8c195734a4d5d49675a9b

data/.env.example

@@ -0,0 +1 @@
+OPENROUTER_API_KEY=

data/.rubocop.yml

@@ -0,0 +1,68 @@
+AllCops:
+  TargetRubyVersion: 3.3.9
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Bundler/OrderedGems:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  SafeAutoCorrect: true
+  EnforcedStyle: always_true
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/AccessorGrouping:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 150
+
+Naming/VariableNumber:
+  Exclude:
+    - "test/**/*_test.rb"
+
+Naming/PredicateMethod:
+  AllowedMethods:
+    - destroy!
+
+Lint/UnusedMethodArgument:
+  Exclude:
+    - "test/**/*_test.rb"
+
+Naming/FileName:
+  Exclude:
+    - "lib/openrouter.rb"
+
+Style/RedundantInitialize:
+  Exclude:
+    - "rbi/**/*.rbi"
+
+Naming/BlockForwarding:
+  Exclude:
+    - "rbi/**/*.rbi"

data/.ruby-version

@@ -0,0 +1,2 @@
+3.3.9
+

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest", "~> 5.0"
+gem "rake", "~> 13.0"
+gem "rubocop", "~> 1.21"
+gem "dotenv"
+gem "sorbet"
+gem "tapioca"
+gem "vcr"
+gem "webmock"

data/Gemfile.lock

@@ -0,0 +1,124 @@
+PATH
+  remote: .
+  specs:
+    openrouter_client (0.1.0)
+      faraday (>= 1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    benchmark (0.5.0)
+    bigdecimal (4.0.1)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    dotenv (3.2.0)
+    erubi (1.13.1)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    hashdiff (1.2.1)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.27.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    netrc (0.11.0)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.7.0)
+    public_suffix (7.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    rbi (0.3.8)
+      prism (~> 1.0)
+      rbs (>= 3.4.4)
+    rbs (3.10.0)
+      logger
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rubocop (1.82.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    sorbet (0.6.12874)
+      sorbet-static (= 0.6.12874)
+    sorbet-runtime (0.6.12874)
+    sorbet-static (0.6.12874-aarch64-linux)
+    sorbet-static (0.6.12874-universal-darwin)
+    sorbet-static (0.6.12874-x86_64-linux)
+    sorbet-static-and-runtime (0.6.12874)
+      sorbet (= 0.6.12874)
+      sorbet-runtime (= 0.6.12874)
+    spoom (1.6.3)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.3.3)
+      rexml (>= 3.2.6)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    tapioca (0.16.11)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.4.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    vcr (6.4.0)
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.38)
+    yard-sorbet (0.9.0)
+      sorbet-runtime
+      yard
+
+PLATFORMS
+  aarch64-linux
+  universal-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  dotenv
+  minitest (~> 5.0)
+  openrouter_client!
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+  sorbet
+  tapioca
+  vcr
+  webmock
+
+BUNDLED WITH
+   2.7.2

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 851 Labs
+
+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,378 @@
+# OpenRouter Client
+
+A Ruby client for the [OpenRouter API](https://openrouter.ai), providing access to hundreds of AI models through a unified interface.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add openrouter_client
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install openrouter_client
+```
+
+## Usage
+
+### Configuration
+
+Configure the client once at boot (e.g., in Rails an initializer) using `OpenRouter.configure`.
+
+```ruby
+OpenRouter.configure do |config|
+  config.api_key = "your-key"           # Optional. Defaults to ENV["OPENROUTER_API_KEY"]
+  config.api_base = "https://openrouter.ai/api/v1"  # Optional (default)
+  config.request_timeout = 120          # Optional (default: 120 seconds)
+  config.site_url = "https://myapp.com" # Optional. For app attribution
+  config.site_name = "My App"           # Optional. For app attribution
+end
+```
+
+### Create a Chat Completion
+
+The simplest way to use OpenRouter is to create a chat completion:
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  messages: [
+    { role: "user", content: "What is the meaning of life?" }
+  ],
+  model: "openai/gpt-4"
+)
+
+puts completion.content  # => "The meaning of life..."
+puts completion.model    # => "openai/gpt-4"
+puts completion.id       # => "gen-xxxxx"
+```
+
+### With System Messages
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Hello!" }
+  ],
+  model: "anthropic/claude-3-opus"
+)
+```
+
+### Streaming Responses
+
+Use `stream!` for SSE streaming. It yields each chunk and returns the final completion:
+
+```ruby
+completion = OpenRouter::Completion.stream!(
+  messages: [{ role: "user", content: "Tell me a story" }],
+  model: "openai/gpt-4"
+) do |chunk|
+  # chunk is a Hash with the streamed data
+  print chunk.dig("choices", 0, "delta", "content")
+end
+
+puts "\n---"
+puts "Final content: #{completion.content}"
+```
+
+### Advanced Parameters
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  messages: [{ role: "user", content: "Write a haiku" }],
+  model: "openai/gpt-4",
+  temperature: 0.7,
+  max_tokens: 100,
+  top_p: 0.9,
+  frequency_penalty: 0.5,
+  presence_penalty: 0.5,
+  stop: ["\n\n"],
+  seed: 42
+)
+```
+
+### Tool Calling
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
+  model: "openai/gpt-4",
+  tools: [
+    {
+      type: "function",
+      function: {
+        name: "get_weather",
+        description: "Get the weather for a location",
+        parameters: {
+          type: "object",
+          properties: {
+            location: { type: "string", description: "City name" }
+          },
+          required: ["location"]
+        }
+      }
+    }
+  ]
+)
+
+if completion.has_tool_calls?
+  completion.tool_calls.each do |tool_call|
+    puts "Function: #{tool_call['function']['name']}"
+    puts "Arguments: #{tool_call['function']['arguments']}"
+  end
+end
+```
+
+### Model Fallbacks
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  messages: [{ role: "user", content: "Hello" }],
+  models: ["openai/gpt-4", "anthropic/claude-3-opus", "google/gemini-pro"],
+  route: "fallback"
+)
+```
+
+### Image Generation
+
+Generate images with models that support image output:
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  model: "google/gemini-2.5-flash-image-preview",
+  messages: [{ role: "user", content: "Generate a beautiful sunset over mountains" }],
+  modalities: ["image", "text"]
+)
+
+# Check if images were generated
+if completion.images?
+  completion.images.each do |image|
+    # Images are base64-encoded data URLs
+    image_url = image.dig("image_url", "url")
+    puts "Generated image: #{image_url[0..50]}..."
+  end
+end
+
+puts completion.content  # Text response (if any)
+```
+
+#### Image Configuration (Gemini models)
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  model: "google/gemini-2.5-flash-image-preview",
+  messages: [{ role: "user", content: "Create a futuristic cityscape" }],
+  modalities: ["image", "text"],
+  image_config: {
+    aspect_ratio: "16:9",  # 1:1, 2:3, 3:2, 4:3, 9:16, 16:9, etc.
+    image_size: "4K"       # 1K, 2K, or 4K
+  }
+)
+```
+
+### Additional API Options
+
+Pass any additional OpenRouter API parameters:
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  messages: [{ role: "user", content: "Hello" }],
+  model: "openai/gpt-4",
+  # Reasoning configuration
+  reasoning: { effort: "high" },
+  # Web search plugin
+  plugins: [{ id: "web", enabled: true }],
+  # Provider preferences
+  provider: {
+    order: ["OpenAI", "Anthropic"],
+    allow_fallbacks: true
+  }
+)
+```
+
+### Models
+
+List, search, and find models:
+
+```ruby
+# Get all models
+models = OpenRouter::Model.all
+puts "Total models: #{models.count}"
+
+# Find a specific model (returns nil if not found)
+model = OpenRouter::Model.find_by(id: "openai/gpt-4")
+
+# Find a model (raises NotFoundError if not found)
+model = OpenRouter::Model.find("openai/gpt-4")
+model = OpenRouter::Model.find_by!(id: "openai/gpt-4")
+
+# Model attributes
+puts model.name           # => "GPT-4"
+puts model.context_length # => 8192
+puts model.input_price    # => 0.00003 (per token)
+puts model.output_price   # => 0.00006 (per token)
+puts model.free?          # => false
+
+# Search models
+results = OpenRouter::Model.search(query: "claude")
+
+# Find by provider
+openai_models = OpenRouter::Model.by_provider(provider: "openai")
+
+# Find free models
+free_models = OpenRouter::Model.free
+
+# Use a model to create a completion
+model = OpenRouter::Model.find("openai/gpt-4")
+completion = model.complete(messages: [{ role: "user", content: "Hello!" }])
+```
+
+### Generation Stats
+
+Query detailed usage information for a completion:
+
+```ruby
+completion = OpenRouter::Completion.create!(
+  messages: [{ role: "user", content: "Hello" }],
+  model: "openai/gpt-4"
+)
+
+# Query generation stats (may take a moment to be available)
+generation = OpenRouter::Generation.find_by(id: completion.id)
+
+if generation
+  puts generation.model                    # => "openai/gpt-4"
+  puts generation.native_prompt_tokens     # => 5
+  puts generation.native_completion_tokens # => 10
+  puts generation.total_cost               # => 0.00045
+  puts generation.provider                 # => "openai"
+  puts generation.tokens_per_second        # => 50.0
+end
+```
+
+### Credits
+
+Check your credit balance:
+
+```ruby
+credit = OpenRouter::Credit.fetch
+puts credit.total_credits  # => 100.0
+puts credit.total_usage    # => 25.0
+puts credit.remaining      # => 75.0
+
+# Convenience method
+remaining = OpenRouter::Credit.remaining
+
+# Check credit status
+credit.low?       # => true if less than 10% remaining
+credit.exhausted? # => true if no credits left
+```
+
+### API Keys
+
+Manage API keys programmatically:
+
+```ruby
+# Get current key info
+current_key = OpenRouter::ApiKey.current
+puts current_key.name
+puts current_key.usage
+
+# List all keys
+keys = OpenRouter::ApiKey.all
+
+# Create a new key
+new_key = OpenRouter::ApiKey.create!(name: "Production Key", limit: 100.0)
+puts new_key.key  # Only shown once!
+
+# Update a key
+new_key.update!(name: "Updated Name", limit: 200.0)
+
+# Delete a key
+new_key.destroy!
+```
+
+### Error Handling
+
+The gem raises typed exceptions for different error conditions:
+
+```ruby
+begin
+  OpenRouter::Completion.create!(
+    messages: [{ role: "user", content: "Hello" }],
+    model: "openai/gpt-4"
+  )
+rescue OpenRouter::UnauthorizedError
+  # Invalid or missing API key (401)
+rescue OpenRouter::ForbiddenError
+  # Access denied (403)
+rescue OpenRouter::NotFoundError
+  # Resource not found (404)
+rescue OpenRouter::RateLimitError
+  # Rate limited (429)
+rescue OpenRouter::PaymentRequiredError
+  # Insufficient credits (402)
+rescue OpenRouter::BadRequestError
+  # Invalid request (400)
+rescue OpenRouter::ServerError
+  # Server error (5xx)
+end
+```
+
+### Response Helpers
+
+Completions have several helper methods:
+
+```ruby
+completion.content           # Message content
+completion.role              # "assistant"
+completion.finish_reason     # "stop", "length", "tool_calls", etc.
+completion.prompt_tokens     # Tokens in prompt
+completion.completion_tokens # Tokens in response
+completion.total_tokens      # Total tokens
+
+completion.stopped?          # Finished due to stop sequence
+completion.truncated?        # Finished due to max_tokens
+completion.tool_calls?       # Contains tool calls
+completion.images?           # Contains generated images
+completion.images            # Array of generated images
+completion.tool_calls        # Array of tool calls
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can run `bin/console` for an interactive prompt that will allow you to experiment.
+
+For local development, copy the example environment file and set your API key so `bin/console` can load it automatically:
+
+```bash
+cp .env.example .env
+echo 'OPENROUTER_API_KEY=your_api_key_here' >> .env
+```
+
+### Available Scripts
+
+```bash
+bin/setup    # Install dependencies
+bin/console  # Interactive Ruby console with gem loaded
+bin/test     # Run tests
+bin/vcr      # Run tests with VCR recording (creates cassettes)
+bin/format   # Run RuboCop with auto-correct
+```
+
+### Running Tests
+
+```bash
+bin/test     # Run all tests
+
+bin/vcr      # Run tests and record VCR cassettes
+```
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to rubygems.org.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]