vibe-sort 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7d0e027ef929afd808fecba7f64a697a87ff6be489bce20bf9a8da73334847
-  data.tar.gz: b59cb7de762f093a8a5c0ac702841b4bad42d68599a346135a69867af54b6407
+  metadata.gz: 15fa0d0262e797d5c29705f56902c66beb746d438505cd6fbace4a999b6c780a
+  data.tar.gz: 4f407bf5defba0274c43a352b2274899eea9f1579c82b1eae03663ed2ec5cf6f
 SHA512:
-  metadata.gz: 53ac2db8b8b227fd151542ed86a350aab7bf6e3a740347cef034348f175465f3e17b7f32b6ca868da4c300bc0ad7b681b5fcdc84375e58838115e0f0d34ec0ac
-  data.tar.gz: 604e37c539b045cf9ecc3ff12a88fa467514506fb9149a2e02d85278f5a2dbd468ecf0cacf9259922dca87d21cdff4fd7f247cfad8dcf5752e5289ae82a2662c
+  metadata.gz: a3be092377c5248cc964703f289c464cbec676d59e95db6f7c1cd52e7256d17f8dcfeb143b0b980865d3ee03e3d75b75350e8587cb235def5569984bdcd8775d
+  data.tar.gz: 527d7a06f586edb938df467e5ad4e00caf18ea50a5ed14467fb9110a749ee604d49fe79d6fc3e91165858fe7090673610004724f71b91fbc8c2a88ed60e3e532

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-12
+
+### Added
+
+- **OpenRouter provider** (`provider: :openrouter`): access hundreds of models through OpenRouter's OpenAI-compatible API. Default model `openai/gpt-4o-mini`; sends OpenRouter's recommended attribution headers
+- **API key format detection**: when `provider:` is omitted, the provider is inferred from the `api_key` prefix (`sk-ant-` → Anthropic, `sk-or-` → OpenRouter, `gsk_` → Groq, `AIza`/`AQ.` → Gemini, `xai-` → SpaceXAI, `sk-` → OpenAI). Unrecognized key formats still default to OpenAI
+- **`extra_params:` option** on `VibeSort::Client.new`: a hash of provider-native request parameters deep-merged into the payload last, so it can override anything the adapter builds (e.g. `max_tokens`, `response_format`, Gemini's nested `generationConfig`, OpenRouter provider-routing preferences)
+- Free-tier model benchmark results (`docs/free_model_benchmark_2026-07-12.md`)
+
+### Changed
+
+- Passing an explicit `provider:` that disagrees with the detected key format now prints a one-line warning to stderr; the explicit provider still wins
+
+### Notes
+
+- Behavior change (hence the minor bump): a provider-prefixed key with no `provider:` argument previously always hit the OpenAI API and failed; it now routes to the detected provider and works. Unrecognized keys with no `provider:` still default to OpenAI, and all explicit-provider call sites behave identically
+- Still no runtime dependencies beyond Faraday
+
 ## [0.3.1] - 2026-07-11
 
 ### Changed

data/README.md

@@ -1,8 +1,8 @@
 # VibeSort
 
-> **AI-powered array sorting using OpenAI, Anthropic Claude, Google Gemini, Groq, or SpaceXAI Grok**
+> **AI-powered array sorting using OpenAI, Anthropic Claude, Google Gemini, Groq, SpaceXAI Grok, or OpenRouter**
 
-VibeSort is a proof-of-concept Ruby gem that demonstrates sorting arrays by leveraging LLM APIs. Instead of using traditional sorting algorithms, it asks an AI model to do the work. Supports the OpenAI Chat Completions API, the Anthropic Messages API, the Google Gemini API, and the OpenAI-compatible Groq and SpaceXAI (xAI) APIs, with zero dependencies beyond Faraday.
+VibeSort is a proof-of-concept Ruby gem that demonstrates sorting arrays by leveraging LLM APIs. Instead of using traditional sorting algorithms, it asks an AI model to do the work. Supports the OpenAI Chat Completions API, the Anthropic Messages API, the Google Gemini API, and the OpenAI-compatible Groq, SpaceXAI (xAI), and OpenRouter APIs, with zero dependencies beyond Faraday.
 
 [![Gem Version](https://badge.fury.io/rb/vibe-sort.svg)](https://badge.fury.io/rb/vibe-sort)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -13,10 +13,11 @@ This is a **proof-of-concept** and educational project. It is not intended for p
 
 ## Features
 
-- **AI-Powered Sorting**: Uses OpenAI, Anthropic Claude, Google Gemini, Groq, or SpaceXAI Grok models to sort arrays
+- **AI-Powered Sorting**: Uses OpenAI, Anthropic Claude, Google Gemini, Groq, SpaceXAI Grok, or OpenRouter models to sort arrays
 - **Multi-Provider**: Switch providers with a single `provider:` option, no extra dependencies
+- **Key Format Detection**: Omit `provider:` and VibeSort infers it from your API key's prefix
 - **Simple Interface**: Clean, intuitive API with a single `sort` method
-- **Configurable**: Supports custom model and temperature settings
+- **Configurable**: Custom model, temperature, and an `extra_params:` escape hatch for any provider-native request parameter
 - **Error Handling**: Comprehensive error handling with clear error messages
 - **Structured Output**: Uses JSON mode for reliable, parsable responses
 - **Type Validation**: Validates input and output to ensure data integrity
@@ -26,7 +27,7 @@ This is a **proof-of-concept** and educational project. It is not intended for p
 
 - Ruby **3.0** or newer (MRI)
 - Bundler **2.0+**
-- An API key for at least one supported provider (OpenAI, Anthropic, Google Gemini, Groq, or SpaceXAI)
+- An API key for at least one supported provider (OpenAI, Anthropic, Google Gemini, Groq, SpaceXAI, or OpenRouter)
 - Internet connectivity (each sort performs a remote API call)
 
 ## Installation
@@ -121,11 +122,11 @@ end
 
 ### Choosing a Provider
 
-VibeSort defaults to OpenAI, but any supported provider can be selected with the `provider:` option:
+Any supported provider can be selected with the `provider:` option:
 
 ```ruby
-# OpenAI (default)
-client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+# OpenAI
+client = VibeSort::Client.new(provider: :openai, api_key: ENV['OPENAI_API_KEY'])
 
 # Anthropic Claude
 client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
@@ -138,6 +139,9 @@ client = VibeSort::Client.new(provider: :groq, api_key: ENV['GROQ_API_KEY'])
 
 # SpaceXAI (formerly xAI) Grok
 client = VibeSort::Client.new(provider: :spacexai, api_key: ENV['XAI_API_KEY'])
+
+# OpenRouter (hundreds of models behind one API)
+client = VibeSort::Client.new(provider: :openrouter, api_key: ENV['OPENROUTER_API_KEY'])
 ```
 
 | Provider | API | Default model | Override with `model:` |
@@ -147,9 +151,12 @@ client = VibeSort::Client.new(provider: :spacexai, api_key: ENV['XAI_API_KEY'])
 | `:gemini` | generateContent | `gemini-2.5-flash` | e.g. `gemini-2.5-pro` |
 | `:groq` | Chat Completions (OpenAI-compatible) | `llama-3.3-70b-versatile` | any Groq-hosted model |
 | `:spacexai` | Chat Completions (OpenAI-compatible) | `grok-4` | e.g. `grok-4.5` |
+| `:openrouter` | Chat Completions (OpenAI-compatible) | `openai/gpt-4o-mini` | any OpenRouter model ID |
 
 > **Groq is not Grok**: Groq is the independent fast-inference company (`api.groq.com`); Grok is SpaceXAI's model (`api.x.ai`). They are unrelated, and VibeSort supports both.
 
+> **OpenRouter JSON mode caveat**: OpenRouter forwards `response_format: { type: "json_object" }` to the underlying model, but only some models honor it. Models that ignore it produce a "Failed to parse JSON response" error. Stick to models that support JSON mode, or use `extra_params:` to adjust the request.
+
 ```ruby
 # Pick a specific model
 client = VibeSort::Client.new(
@@ -159,6 +166,53 @@ client = VibeSort::Client.new(
 )
 ```
 
+### Provider Detection (provider: is optional)
+
+If you omit `provider:`, VibeSort infers it from your API key's prefix:
+
+```ruby
+VibeSort::Client.new(api_key: 'sk-ant-...')  # => :anthropic
+VibeSort::Client.new(api_key: 'sk-or-...')   # => :openrouter
+VibeSort::Client.new(api_key: 'gsk_...')     # => :groq
+VibeSort::Client.new(api_key: 'AIza...')     # => :gemini (classic key)
+VibeSort::Client.new(api_key: 'AQ....')      # => :gemini (newer key format)
+VibeSort::Client.new(api_key: 'xai-...')     # => :spacexai
+VibeSort::Client.new(api_key: 'sk-...')      # => :openai
+```
+
+Key prefixes are conventions, not contracts, so detection is deliberately soft:
+
+- Unrecognized key formats (proxies, gateways, self-hosted endpoints) default to `:openai` — same behavior as before v0.4.0
+- An explicit `provider:` always wins; if it disagrees with the detected format you get a one-line stderr warning, never an error
+
+### Extra Request Parameters
+
+`extra_params:` deep-merges a hash of provider-native parameters into the request payload **last**, so it can add to or override anything VibeSort builds:
+
+```ruby
+# Cap completion length (OpenAI/Groq/SpaceXAI/OpenRouter wire format)
+client = VibeSort::Client.new(
+  api_key: ENV['OPENAI_API_KEY'],
+  extra_params: { max_tokens: 200 }
+)
+
+# Gemini uses its own parameter names — nested hashes merge recursively
+client = VibeSort::Client.new(
+  provider: :gemini,
+  api_key: ENV['GEMINI_API_KEY'],
+  extra_params: { generationConfig: { maxOutputTokens: 256 } }
+)
+
+# OpenRouter provider-routing preferences
+client = VibeSort::Client.new(
+  provider: :openrouter,
+  api_key: ENV['OPENROUTER_API_KEY'],
+  extra_params: { provider: { sort: 'throughput' } }
+)
+```
+
+Keys are provider-native and passed through untranslated: `max_tokens` means whatever your provider says it means, and Gemini users write Gemini's camelCase names. Overriding core keys (`response_format`, `temperature`, even `model`) is allowed — it's an escape hatch, use with care.
+
 ### Advanced Configuration
 
 You can customize the model's behavior using the `temperature` parameter:
@@ -225,9 +279,10 @@ VibeSort follows a clean, modular architecture:
 
 - **`VibeSort::Client`**: Public interface for users
 - **`VibeSort::Configuration`**: Manages provider, API key, model, and settings
+- **`VibeSort::KeyDetector`**: Best-effort provider inference from API key prefixes
 - **`VibeSort::Sorter`**: Dispatches to the configured provider adapter
 - **`VibeSort::Providers::Base`**: Shared prompt, HTTP plumbing (Faraday), and response validation
-- **`VibeSort::Providers::{OpenAI, Anthropic, Gemini, Groq, SpaceXAI}`**: Provider-specific request/response mapping
+- **`VibeSort::Providers::{OpenAI, Anthropic, Gemini, Groq, SpaceXAI, OpenRouter}`**: Provider-specific request/response mapping
 - **`VibeSort::ApiError`**: Custom exception for API-related errors
 
 See the [Architecture Documentation](docs/architecture.md) for more details.
@@ -297,11 +352,12 @@ Traditional sorting (e.g., Ruby's `Array#sort`) is:
 Set the API key for your chosen provider as an environment variable:
 
 ```bash
-export OPENAI_API_KEY='your-api-key-here'     # provider: :openai (default)
-export ANTHROPIC_API_KEY='your-api-key-here'  # provider: :anthropic
-export GEMINI_API_KEY='your-api-key-here'     # provider: :gemini
-export GROQ_API_KEY='your-api-key-here'       # provider: :groq
-export XAI_API_KEY='your-api-key-here'        # provider: :spacexai
+export OPENAI_API_KEY='your-api-key-here'      # provider: :openai (fallback default)
+export ANTHROPIC_API_KEY='your-api-key-here'   # provider: :anthropic
+export GEMINI_API_KEY='your-api-key-here'      # provider: :gemini
+export GROQ_API_KEY='your-api-key-here'        # provider: :groq
+export XAI_API_KEY='your-api-key-here'         # provider: :spacexai
+export OPENROUTER_API_KEY='your-api-key-here'  # provider: :openrouter
 ```
 
 Or use a `.env` file with the `dotenv` gem:
@@ -322,7 +378,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Acknowledgments
 
 - Built with [Faraday](https://lostisland.github.io/faraday/) for HTTP requests
-- Powered by [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Google Gemini](https://ai.google.dev/), [Groq](https://groq.com/), and [SpaceXAI](https://x.ai/) models
+- Powered by [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Google Gemini](https://ai.google.dev/), [Groq](https://groq.com/), [SpaceXAI](https://x.ai/), and [OpenRouter](https://openrouter.ai/) models
 - Inspired by the absurdity and creativity of the AI era
 
 ---

data/docs/api_reference.md

@@ -6,7 +6,7 @@ The main public interface for the VibeSort gem.
 
 ### Class Methods
 
-#### `new(api_key:, temperature: 0.0, provider: :openai, model: nil)`
+#### `new(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})`
 
 Creates a new VibeSort client instance.
 
@@ -18,24 +18,27 @@ Creates a new VibeSort client instance.
   - Lower values (0.0-0.3): More deterministic and consistent
   - Higher values (0.7-2.0): More random and creative
   - Ignored by providers whose current models do not accept it (Anthropic)
-- `provider` (Symbol or String, optional): LLM provider (default: `:openai`)
-  - Supported: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`
+- `provider` (Symbol or String, optional): LLM provider
+  - Supported: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, `:openrouter`
+  - When omitted, inferred from the `api_key` prefix via `VibeSort::KeyDetector`; unrecognized formats default to `:openai`
+  - When explicit and the key prefix suggests a different provider, a one-line warning is printed to stderr and the explicit provider is used
 - `model` (String, optional): Model ID override (default: the provider's default model)
+- `extra_params` (Hash, optional): Provider-native request parameters deep-merged into the payload last, so they can override anything the adapter builds (default: `{}`)
 
 **Returns:** `VibeSort::Client` instance
 
 **Raises:**
 
-- `ArgumentError`: If api_key is nil or empty, or the provider is unknown
+- `ArgumentError`: If api_key is nil or empty, or an explicit provider is unknown
 
 **Example:**
 
 ```ruby
-# Basic initialization (OpenAI, default provider)
-client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+# Provider inferred from the key prefix (sk-ant-... => :anthropic)
+client = VibeSort::Client.new(api_key: ENV['ANTHROPIC_API_KEY'])
 
-# Anthropic Claude
-client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
+# Explicit provider
+client = VibeSort::Client.new(provider: :openai, api_key: ENV['OPENAI_API_KEY'])
 
 # Google Gemini with a custom model
 client = VibeSort::Client.new(provider: :gemini, api_key: ENV['GEMINI_API_KEY'], model: 'gemini-2.5-pro')
@@ -45,6 +48,14 @@ client = VibeSort::Client.new(
   api_key: ENV['OPENAI_API_KEY'],
   temperature: 0.2
 )
+
+# With extra provider-native request parameters
+client = VibeSort::Client.new(
+  provider: :openrouter,
+  api_key: ENV['OPENROUTER_API_KEY'],
+  model: 'meta-llama/llama-3.3-70b-instruct',
+  extra_params: { max_tokens: 200 }
+)
 ```
 
 ### Instance Methods
@@ -110,7 +121,7 @@ Configuration object for VibeSort. Usually not used directly by end users.
 
 ### Class Methods
 
-#### `new(api_key:, temperature: 0.0, provider: :openai, model: nil)`
+#### `new(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})`
 
 Creates a new configuration object.
 
@@ -118,8 +129,9 @@ Creates a new configuration object.
 
 - `api_key` (String, required): API key for the selected provider
 - `temperature` (Float, optional): Model temperature (default: 0.0)
-- `provider` (Symbol or String, optional): `:openai` (default), `:anthropic`, `:gemini`, `:groq`, or `:spacexai`
+- `provider` (Symbol, String, or nil, optional): `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, or `:openrouter`; nil (default) infers the provider from the api_key prefix, falling back to `:openai`
 - `model` (String, optional): Model ID override (nil uses the provider's default)
+- `extra_params` (Hash, optional): Provider-native request parameters deep-merged into the payload last (default: `{}`)
 
 **Raises:**
 
@@ -161,6 +173,40 @@ Returns the configured model override, or nil when using the provider default (r
 
 **Returns:** String or nil
 
+#### `extra_params`
+
+Returns the configured extra request parameters hash (read-only).
+
+**Returns:** Hash
+
+---
+
+## VibeSort::KeyDetector
+
+Best-effort provider inference from API key prefixes. Prefixes are conventions, not contracts — detection is only a soft default and a source of non-fatal warnings, never validation.
+
+### Class Methods
+
+#### `detect(api_key)`
+
+**Parameters:**
+
+- `api_key` (String, required): API key to inspect
+
+**Returns:** Symbol (detected provider) or nil (unrecognized format)
+
+**Prefix map (ordered — specific prefixes checked before `sk-`):**
+
+| Prefix | Provider |
+|---|---|
+| `sk-ant-` | `:anthropic` |
+| `sk-or-` | `:openrouter` |
+| `sk-` | `:openai` |
+| `gsk_` | `:groq` |
+| `AIza` | `:gemini` (classic key) |
+| `AQ.` | `:gemini` (newer key format) |
+| `xai-` | `:spacexai` |
+
 ---
 
 ## VibeSort::Sorter
@@ -199,7 +245,7 @@ Performs the sorting operation via the configured provider's API.
 
 Maps provider symbols to adapter classes.
 
-**Value:** `{ openai:, anthropic:, gemini:, groq:, spacexai: }`
+**Value:** `{ openai:, anthropic:, gemini:, groq:, spacexai:, openrouter: }`
 
 ---
 
@@ -214,11 +260,14 @@ Internal provider adapters. `Providers::Base` holds the shared prompt, Faraday H
 | `Providers::Gemini` | `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent` | `gemini-2.5-flash` |
 | `Providers::Groq` | `https://api.groq.com/openai/v1/chat/completions` | `llama-3.3-70b-versatile` |
 | `Providers::SpaceXAI` | `https://api.x.ai/v1/chat/completions` | `grok-4` |
+| `Providers::OpenRouter` | `https://openrouter.ai/api/v1/chat/completions` | `openai/gpt-4o-mini` |
 
 Notes:
 
 - The Anthropic adapter uses structured outputs (JSON schema) and does not send `temperature` (rejected by current Claude models)
-- The Groq and SpaceXAI adapters subclass `Providers::OpenAI` (OpenAI-compatible APIs)
+- The Groq, SpaceXAI, and OpenRouter adapters subclass `Providers::OpenAI` (OpenAI-compatible APIs)
+- The OpenRouter adapter sends OpenRouter's recommended attribution headers (`HTTP-Referer`, `X-Title`)
+- `Providers::Base` deep-merges `config.extra_params` into every payload last, so it can override anything the adapter builds
 
 ---
 
@@ -307,7 +356,7 @@ All sorting operations return a consistent hash structure:
 
 ### API Errors
 
-The `{Provider}` prefix names the configured provider (OpenAI, Anthropic, Gemini, Groq, or SpaceXAI):
+The `{Provider}` prefix names the configured provider (OpenAI, Anthropic, Gemini, Groq, SpaceXAI, or OpenRouter):
 
 | Error Message Pattern | Cause | Solution |
 |----------------------|-------|----------|
@@ -455,11 +504,12 @@ results = threads.map(&:value)
 Set the API key for whichever provider you use:
 
 ```bash
-export OPENAI_API_KEY='sk-your-key-here'      # provider: :openai (default)
+export OPENAI_API_KEY='sk-your-key-here'      # provider: :openai (fallback default)
 export ANTHROPIC_API_KEY='your-key-here'      # provider: :anthropic
 export GEMINI_API_KEY='your-key-here'         # provider: :gemini
 export GROQ_API_KEY='your-key-here'           # provider: :groq
 export XAI_API_KEY='your-key-here'            # provider: :spacexai
+export OPENROUTER_API_KEY='your-key-here'     # provider: :openrouter
 ```
 
 **Usage:**
@@ -472,9 +522,9 @@ client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
 
 ## Version
 
-Current version: `0.3.0`
+Current version: `0.4.0`
 
 ```ruby
 VibeSort::VERSION
-# => "0.3.0"
+# => "0.4.0"
 ```

data/docs/architecture.md

@@ -20,9 +20,10 @@ VibeSort follows a layered architecture with clear separation of concerns:
                   ▼
 ┌─────────────────────────────────────────┐
 │    VibeSort::Configuration              │
-│  - Provider selection                   │
+│  - Provider selection (explicit or      │
+│    inferred via KeyDetector)            │
 │  - API key management                   │
-│  - Model override                       │
+│  - Model override, extra_params         │
 │  - Temperature settings                 │
 └─────────────────┬───────────────────────┘
                   │
@@ -37,10 +38,11 @@ VibeSort follows a layered architecture with clear separation of concerns:
 │   VibeSort::Providers::Base             │
 │  - Shared prompt                        │
 │  - HTTP client (Faraday)                │
+│  - extra_params deep merge              │
 │  - Response parsing & validation        │
 ├─────────────────────────────────────────┤
 │  OpenAI │ Anthropic │ Gemini │          │
-│  Groq   │ SpaceXAI                      │
+│  Groq   │ SpaceXAI  │ OpenRouter        │
 │  (request/response wire formats)        │
 └─────────────────┬───────────────────────┘
                   │
@@ -50,6 +52,7 @@ VibeSort follows a layered architecture with clear separation of concerns:
 │  api.openai.com │ api.anthropic.com     │
 │  generativelanguage.googleapis.com      │
 │  api.groq.com   │ api.x.ai              │
+│  openrouter.ai                          │
 └─────────────────────────────────────────┘
 ```
 
@@ -67,7 +70,7 @@ VibeSort follows a layered architecture with clear separation of concerns:
 - Return standardized response hashes
 
 **Key Methods**:
-- `initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)`: Creates client with configuration
+- `initialize(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})`: Creates client with configuration
 - `sort(array)`: Sorts array and returns result hash
 
 **Return Format**:
@@ -84,19 +87,26 @@ VibeSort follows a layered architecture with clear separation of concerns:
 **Purpose**: Encapsulates configuration settings.
 
 **Responsibilities**:
-- Store provider selection and API key
-- Store model override and temperature setting
+- Resolve the provider: explicit argument wins (with a non-fatal stderr warning on a mismatched key prefix); otherwise inferred from the key prefix via `KeyDetector`, defaulting to `:openai`
+- Store API key, model override, temperature, and extra_params
 - Validate API key presence and provider name
 
 **Key Methods**:
-- `initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)`: Creates configuration
-- Raises `ArgumentError` if API key is nil/empty or provider is unknown
+- `initialize(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})`: Creates configuration
+- Raises `ArgumentError` if API key is nil/empty or an explicit provider is unknown
 
 **Attributes**:
 - `api_key`: Provider API key (String)
-- `provider`: `:openai`, `:anthropic`, `:gemini`, `:groq`, or `:spacexai` (Symbol)
+- `provider`: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, or `:openrouter` (Symbol)
 - `model`: Model ID override, or nil for the provider default (String or nil)
 - `temperature`: Model temperature (Float, 0.0-2.0; not sent to Anthropic)
+- `extra_params`: Provider-native request parameters deep-merged into the payload last (Hash)
+
+### VibeSort::KeyDetector
+
+**Purpose**: Best-effort provider inference from API key prefixes (`sk-ant-` → `:anthropic`, `sk-or-` → `:openrouter`, `gsk_` → `:groq`, `AIza`/`AQ.` → `:gemini`, `xai-` → `:spacexai`, `sk-` → `:openai`).
+
+Prefixes are conventions, not contracts — providers ship multiple key formats concurrently and new formats appear without notice. Detection is therefore only a soft default and a source of non-fatal warnings, never validation: `detect` returns nil for unrecognized formats, and callers fall back to `:openai`.
 
 ### VibeSort::Sorter
 
@@ -113,6 +123,7 @@ VibeSort follows a layered architecture with clear separation of concerns:
 **`Providers::Base` responsibilities**:
 - Hold the shared sorting prompt
 - Build the HTTP connection with Faraday
+- Deep-merge `config.extra_params` into the adapter payload last (nested hashes merge recursively; arrays and scalars replace)
 - Parse and validate JSON responses (shared across providers)
 - Raise `ApiError` on failures
 
@@ -124,6 +135,7 @@ VibeSort follows a layered architecture with clear separation of concerns:
 - `Providers::Gemini`: generateContent with JSON response mode, `gemini-2.5-flash`
 - `Providers::Groq`: OpenAI-compatible (subclasses `Providers::OpenAI`), `llama-3.3-70b-versatile`
 - `Providers::SpaceXAI`: OpenAI-compatible (subclasses `Providers::OpenAI`), `grok-4`
+- `Providers::OpenRouter`: OpenAI-compatible (subclasses `Providers::OpenAI`), `openai/gpt-4o-mini`, adds OpenRouter's recommended attribution headers
 
 ### VibeSort::ApiError
 

data/docs/free_model_benchmark_2026-07-12.md

@@ -0,0 +1,134 @@
+# Free-Tier Model Benchmark — 2026-07-12
+
+An empirical snapshot of how free LLM tiers handle vibe-sort's sorting contract, gathered
+while designing v0.4.0 (OpenRouter provider, key-format detection, `extra_params` —
+see [v0.4.0_PLAN.md](v0.4.0_PLAN.md)). All requests used free models / free-tier quota only.
+
+**TL;DR:** Google's current Gemini flash models all sort correctly through the gem's exact
+payload, with `gemini-3.1-flash-lite` the clear free-tier pick. OpenRouter's `:free` pool was
+too congested on a Saturday afternoon (AEST) to be usable — 14 of 17 tested models failed with
+rate limits or upstream errors, and one burned 10 minutes and 20k tokens to return nothing.
+
+---
+
+## Methodology
+
+- **Task:** sort `[42, "banana", 7, "Apple", 3.14, "cherry", 1]`
+  → expected `[1, 3.14, 7, 42, "Apple", "banana", "cherry"]`
+- **Payloads:** byte-for-byte what the gem sends — `Providers::OpenAI#build_payload` for
+  OpenRouter (system prompt + `temperature: 0.0` + `response_format: {type: "json_object"}`),
+  `Providers::Gemini#build_payload` for Gemini (`systemInstruction` +
+  `generationConfig.responseMimeType: "application/json"`).
+- **Success criteria:** HTTP 200, content parses as JSON with a `sorted_array` key
+  (the gem's contract), array exactly matches the expected sort.
+- **Fallbacks tried on rejection:** OpenRouter — retry without `response_format`;
+  Gemini — retry with system prompt folded into the user turn and no JSON mime type.
+- **Pacing/retries:** 3.5–8s between requests; 5xx retried up to 3×; 429 handling varied by
+  pass (see Lessons). Plain Ruby `net/http`, no SDKs.
+- **Cost:** $0. OpenRouter restricted to `$0`-priced models; Gemini restricted to
+  free-tier models with non-zero quota.
+
+---
+
+## Gemini API (free tier)
+
+7 models tested — every model whose free-tier quota is non-zero.
+
+| Model | Outcome | Latency | Tokens in/out (+thinking) | Notes |
+|---|---|---|---|---|
+| gemini-3.1-flash-lite | ✅ correct | **2.08s** | 87/35 (+0) | Fastest; no thinking tokens; best quota (15 RPM / 500 RPD) |
+| gemini-2.5-flash | ✅ correct | 2.66s | 87/49 (+247) | Gem's current `DEFAULT_MODEL` — still works |
+| gemini-3.5-flash | ✅ correct | 5.98s | 87/50 (+418) | Most thinking tokens |
+| gemini-3-flash-preview | ✅ correct | 24.14s | 87/49 (+321) | Correct but slow |
+| gemma-4-26b-a4b-it | ❌ bad JSON | 28.6s | 87/49 (+318) | Ignored JSON mime type; replied with markdown reasoning; 1×500 on the way |
+| gemma-4-31b-it | ❌ bad JSON | 9.8s | 87/30 (+256) | Same failure shape; also 1×500 |
+| gemini-2.5-flash-lite | ❌ HTTP 404 | — | — | "No longer available to new users" (still listed by the models endpoint) |
+
+### Observations
+
+- **All four current Gemini-branded flash models pass the gem's contract as-is** — JSON mode
+  honored, sort correct, numbers-before-strings and case-sensitivity respected.
+- **Gemma models are incompatible with the gem today:** they accept the request but ignore
+  `responseMimeType: "application/json"` and return reasoning-style markdown. They'd need
+  `extra_params` surgery plus response post-processing — not worth it.
+- **The 500s are real:** 2 of 7 models needed a 5xx retry on their very first request.
+  Any Gemini integration should retry 5xx at least once.
+- **429 retries are a trap on the free tier:** every retry counts against RPM *and* RPD, so a
+  retry loop converts one throttled request into three consumed ones. After the daily caps
+  (20 RPD on most flash models) tripped, throttling also turned intermittent — consecutive
+  requests to the same model went 429, 429, 200. Policy that survives: never auto-retry a
+  free-tier 429; skip and move on.
+- An input-length scaling test (5/20/50/100 elements) was attempted but the RPD caps were
+  exhausted before it could run. Future work, pending quota reset — only
+  `gemini-3.1-flash-lite` (500 RPD) realistically supports this kind of testing for free.
+
+---
+
+## OpenRouter (free models)
+
+26 models on openrouter.ai were $0-priced with text input (of 345 listed). 17 were tested
+before the sweep was aborted; 9 were never reached. Tested on a Saturday afternoon AEST —
+peak congestion for the shared free pool, which colours everything below.
+
+| Model | Outcome | Notes |
+|---|---|---|
+| nvidia/nemotron-3-super-120b-a12b:free | ❌ empty content | **600s, 20,673 completion tokens, no answer** — presumably all reasoning |
+| nvidia/nemotron-3.5-content-safety:free | ❌ bad JSON | Replied "User Safety: safe" — it's a classifier, not a chat model |
+| nvidia/nemotron-nano-12b-v2-vl:free | ❌ upstream timeout | "Upstream idle timeout exceeded" after 121s |
+| nvidia/nemotron-3-nano-30b-a3b:free | ❌ upstream error | NVIDIA "ResourceExhausted: worker limit reached" |
+| nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free | ❌ upstream error | Same |
+| nvidia/nemotron-3-ultra-550b-a55b:free | ❌ upstream error | Same |
+| nvidia/nemotron-nano-9b-v2:free | ⏹ aborted | Stalled the sweep twice with a slow-drip connection (>20 min) |
+| liquid/lfm-2.5-1.2b-instruct:free | ❌ HTTP 502 | Upstream down |
+| liquid/lfm-2.5-1.2b-thinking:free | ❌ HTTP 502 | Upstream down |
+| google/lyria-3-clip-preview | ❌ HTTP 400 | Music model; listed as $0 text-input but not a chat model |
+| google/lyria-3-pro-preview | ❌ HTTP 400 | Same |
+| cognitivecomputations/dolphin-mistral-24b-venice-edition:free | ❌ HTTP 429 | Free pool congested (retried in a 2nd pass ~1h later — still 429) |
+| cohere/north-mini-code:free | ❌ HTTP 429 | Explicit "High demand" RPM-limit message |
+| google/gemma-4-26b-a4b-it:free | ❌ HTTP 429 | Congested both passes |
+| google/gemma-4-31b-it:free | ❌ HTTP 429 | Congested both passes |
+| meta-llama/llama-3.2-3b-instruct:free | ❌ HTTP 429 | Congested both passes |
+| meta-llama/llama-3.3-70b-instruct:free | ❌ HTTP 429 | Congested both passes |
+| nousresearch/hermes-3-llama-3.1-405b:free | ❌ HTTP 429 | Congested both passes |
+| openai/gpt-oss-120b:free, openai/gpt-oss-20b:free, openrouter/free, poolside/laguna-m.1:free, poolside/laguna-xs-2.1:free, qwen/qwen3-coder:free, qwen/qwen3-next-80b-a3b-instruct:free, tencent/hy3:free | ⏸ not tested | Sweep aborted before reaching them (blocked behind the stalling Nemotron) |
+
+### Observations
+
+- **Zero of 17 tested free models completed a correct sort** during this window. This is a
+  statement about the free pool's availability on a weekend afternoon, not about the models —
+  nearly every failure was infrastructure (429/5xx/upstream), not model output.
+- **The transport layer of a vibe-sort OpenRouter adapter is validated**, though: auth,
+  routing, the OpenAI-compatible payload, and OpenRouter's error shape
+  (`error.message` — including passed-through upstream provider errors) all behaved exactly
+  as `Providers::Base#extract_error_message` expects.
+- **Free-model quirks to document:** `$0` pricing does not imply chat-usable (Lyria = music,
+  content-safety = classifier); reasoning models can consume enormous token counts and still
+  return empty content; per-request wall time is unbounded in practice (slow-drip responses
+  blow through per-read timeouts), so an overall deadline is the only safe timeout.
+- Free-model requests are also account-capped on OpenRouter (daily request limits tied to
+  credit balance) — fine for smoke tests, unusable for CI.
+
+---
+
+## Implications for vibe-sort v0.4.0
+
+1. **OpenRouter adapter: ship it.** The mechanics are proven even though the free pool was
+   congested; with any paid model (or an off-peak free window) it should behave like the
+   other OpenAI-compatible adapters. Don't default to a `:free` model — congestion would make
+   the gem look broken.
+2. **Gemini `DEFAULT_MODEL`:** `gemini-2.5-flash` still works, but Google has begun retiring
+   2.5-era models for new users (2.5-flash-lite already 404s). `gemini-3.1-flash-lite` is
+   faster here, spends no thinking tokens on this task, and has the widest free quota —
+   a strong candidate for the next default.
+3. **`extra_params` earns its place:** overriding `response_format`, capping `max_tokens` on
+   reasoning models, and OpenRouter provider-routing preferences were all wanted during this
+   exercise.
+4. **Never auto-retry 429s against free tiers** in examples/docs; retries multiply quota
+   consumption and prolong the lockout.
+
+## Reproduction
+
+Standalone Ruby scripts (plain `net/http`, no gem dependencies) sent the exact adapter
+payloads; per-model raw results (latency, token usage, full error messages, returned arrays)
+were captured as JSON. API keys were session-scoped test keys, not committed. Numbers above
+are single-shot measurements on free tiers — directional, not statistical.

data/lib/vibe_sort/client.rb

@@ -10,20 +10,34 @@ module VibeSort
     # @param api_key [String] API key for the selected provider
     # @param temperature [Float] Temperature for the model (default: 0.0).
     #   Ignored by providers whose current models do not accept it (Anthropic).
-    # @param provider [Symbol, String] LLM provider: :openai (default), :anthropic, or :gemini
+    # @param provider [Symbol, String, nil] LLM provider: :openai, :anthropic, :gemini,
+    #   :groq, :spacexai, or :openrouter. When omitted, the provider is inferred from
+    #   the api_key prefix (e.g. "sk-ant-..." routes to Anthropic), falling back to
+    #   :openai for unrecognized key formats.
     # @param model [String, nil] Model ID override (nil uses the provider's default)
+    # @param extra_params [Hash] Provider-native request parameters deep-merged into
+    #   the request payload last, so they can override anything the adapter builds
     # @raise [ArgumentError] if api_key or provider is invalid
     #
-    # @example OpenAI (default provider)
-    #   client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+    # @example Provider inferred from the key prefix
+    #   client = VibeSort::Client.new(api_key: ENV['ANTHROPIC_API_KEY']) # sk-ant-... => :anthropic
     #
-    # @example Anthropic Claude
-    #   client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
+    # @example OpenAI (explicit)
+    #   client = VibeSort::Client.new(provider: :openai, api_key: ENV['OPENAI_API_KEY'])
     #
     # @example Google Gemini with a custom model
     #   client = VibeSort::Client.new(provider: :gemini, api_key: ENV['GEMINI_API_KEY'], model: 'gemini-2.5-pro')
-    def initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)
-      @config = Configuration.new(api_key: api_key, temperature: temperature, provider: provider, model: model)
+    #
+    # @example OpenRouter with extra request parameters
+    #   client = VibeSort::Client.new(
+    #     provider: :openrouter,
+    #     api_key: ENV['OPENROUTER_API_KEY'],
+    #     model: 'meta-llama/llama-3.3-70b-instruct',
+    #     extra_params: { max_tokens: 200 }
+    #   )
+    def initialize(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})
+      @config = Configuration.new(api_key: api_key, temperature: temperature, provider: provider, model: model,
+                                  extra_params: extra_params)
     end
 
     # Sort an array of numbers and/or strings using the configured provider's API
@@ -53,7 +67,7 @@ module VibeSort
     # @example API error
     #   result = client.sort([1, 2, 3]) # with invalid API key
     #   #=> { success: false, sorted_array: [], error: "OpenAI API error: Invalid API key" }
-    #   # The error prefix names the configured provider (OpenAI, Anthropic, or Gemini)
+    #   # The error prefix names the configured provider (OpenAI, Anthropic, Gemini, ...)
     def sort(array)
       # Validate input
       unless valid_input?(array)

data/lib/vibe_sort/configuration.rb

@@ -2,29 +2,53 @@
 
 module VibeSort
   # Configuration class for VibeSort
-  # Holds provider, API key, model, and temperature settings
+  # Holds provider, API key, model, temperature, and extra request parameters
   class Configuration
-    PROVIDERS = %i[openai anthropic gemini groq spacexai].freeze
+    PROVIDERS = %i[openai anthropic gemini groq spacexai openrouter].freeze
 
-    attr_reader :api_key, :temperature, :provider, :model
+    attr_reader :api_key, :temperature, :provider, :model, :extra_params
 
     # Initialize a new Configuration
     #
     # @param api_key [String] API key for the selected provider
     # @param temperature [Float] Temperature for the model (0.0 to 2.0).
     #   Ignored by providers whose current models do not accept it (Anthropic).
-    # @param provider [Symbol, String] LLM provider: :openai (default), :anthropic, :gemini, :groq, or :spacexai
+    # @param provider [Symbol, String, nil] LLM provider: :openai, :anthropic, :gemini,
+    #   :groq, :spacexai, or :openrouter. When nil (default), the provider is inferred
+    #   from the api_key prefix, falling back to :openai for unrecognized keys.
     # @param model [String, nil] Model ID override (nil uses the provider's default)
+    # @param extra_params [Hash] Provider-native request parameters deep-merged into
+    #   the payload last, so they can override anything (e.g. { max_tokens: 100 })
     # @raise [ArgumentError] if api_key is nil or empty, or provider is unknown
-    def initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)
+    def initialize(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})
       raise ArgumentError, "API key cannot be nil or empty" if api_key.nil? || api_key.empty?
 
-      @provider = provider.to_s.to_sym
-      raise ArgumentError, "Unknown provider: #{provider.inspect} (supported: #{PROVIDERS.join(", ")})" unless PROVIDERS.include?(@provider)
-
+      @provider = resolve_provider(provider, api_key)
       @api_key = api_key
       @temperature = temperature
       @model = model
+      @extra_params = extra_params
+    end
+
+    private
+
+    # Resolve the provider: explicit argument wins (with a non-fatal warning if the
+    # key prefix suggests a different provider); otherwise infer from the key prefix,
+    # defaulting to :openai for unrecognized formats.
+    #
+    # @param provider [Symbol, String, nil] Explicit provider argument, if any
+    # @param api_key [String] API key used for prefix inference
+    # @return [Symbol] Resolved provider
+    # @raise [ArgumentError] if an explicit provider is unknown
+    def resolve_provider(provider, api_key)
+      detected = KeyDetector.detect(api_key)
+      return detected || :openai if provider.nil?
+
+      explicit = provider.to_s.to_sym
+      raise ArgumentError, "Unknown provider: #{provider.inspect} (supported: #{PROVIDERS.join(", ")})" unless PROVIDERS.include?(explicit)
+
+      warn "vibe-sort: api_key format suggests :#{detected} but provider is :#{explicit}" if detected && detected != explicit
+      explicit
     end
   end
 end

data/lib/vibe_sort/providers/base.rb

@@ -25,7 +25,7 @@ module VibeSort
       # @raise [VibeSort::ApiError] if the API request fails
       def perform(array)
         response = connection.post do |req|
-          req.body = build_payload(array)
+          req.body = deep_merge(build_payload(array), config.extra_params)
         end
 
         handle_response(response)
@@ -33,6 +33,20 @@ module VibeSort
 
       private
 
+      # Merge the user's extra_params into the adapter payload last, so they can
+      # override anything (response_format, temperature, even model). Nested
+      # hashes merge recursively (e.g. Gemini's generationConfig); arrays and
+      # scalars replace.
+      #
+      # @param base [Hash] Adapter-built payload
+      # @param extra [Hash] User-supplied provider-native parameters
+      # @return [Hash] Merged payload
+      def deep_merge(base, extra)
+        base.merge(extra) do |_key, old_val, new_val|
+          old_val.is_a?(Hash) && new_val.is_a?(Hash) ? deep_merge(old_val, new_val) : new_val
+        end
+      end
+
       # Model to use: explicit override from config, or the provider default
       #
       # @return [String] Model ID

data/lib/vibe_sort/sorter.rb

@@ -8,7 +8,8 @@ module VibeSort
       anthropic: Providers::Anthropic,
       gemini: Providers::Gemini,
       groq: Providers::Groq,
-      spacexai: Providers::SpaceXAI
+      spacexai: Providers::SpaceXAI,
+      openrouter: Providers::OpenRouter
     }.freeze
 
     attr_reader :config

data/lib/vibe_sort/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VibeSort
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/vibe_sort.rb

@@ -5,6 +5,7 @@ require "json"
 
 require_relative "vibe_sort/version"
 require_relative "vibe_sort/error"
+require_relative "vibe_sort/key_detector"
 require_relative "vibe_sort/configuration"
 require_relative "vibe_sort/providers/base"
 require_relative "vibe_sort/providers/openai"
@@ -12,6 +13,7 @@ require_relative "vibe_sort/providers/anthropic"
 require_relative "vibe_sort/providers/gemini"
 require_relative "vibe_sort/providers/groq"
 require_relative "vibe_sort/providers/space_x_ai"
+require_relative "vibe_sort/providers/open_router"
 require_relative "vibe_sort/sorter"
 require_relative "vibe_sort/client"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vibe-sort
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-11 00:00:00.000000000 Z
+date: 2026-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -26,8 +26,8 @@ dependencies:
         version: '2.0'
 description: A proof-of-concept Ruby gem that sorts arrays by leveraging LLM APIs
   (OpenAI Chat Completions, Anthropic Messages, Google Gemini, and the OpenAI-compatible
-  Groq and SpaceXAI Grok APIs). Demonstrates how AI can be used for computational
-  tasks.
+  Groq, SpaceXAI Grok, and OpenRouter APIs). Infers the provider from the API key
+  format. Demonstrates how AI can be used for computational tasks.
 email:
 - chayut_o@hotmail.com
 executables: []
@@ -45,6 +45,7 @@ files:
 - docs/api_reference.md
 - docs/architecture.md
 - docs/development.md
+- docs/free_model_benchmark_2026-07-12.md
 - docs/v0.2.0_UPDATE.md
 - lib/vibe/sort.rb
 - lib/vibe_sort.rb
@@ -88,5 +89,5 @@ rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: AI-powered array sorting using OpenAI, Anthropic Claude, Google Gemini, Groq,
-  or SpaceXAI Grok
+  SpaceXAI Grok, or OpenRouter
 test_files: []