vibe-sort 0.3.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2f7d0e027ef929afd808fecba7f64a697a87ff6be489bce20bf9a8da73334847
4
- data.tar.gz: b59cb7de762f093a8a5c0ac702841b4bad42d68599a346135a69867af54b6407
3
+ metadata.gz: 4da00322a5e2edf9b700b91c32552a2099a8d9b64b275a48c5fc87a85db29f14
4
+ data.tar.gz: df5e02d86371c783360736912682d54cb286b8b39b190e4a2984a811b35eb858
5
5
  SHA512:
6
- metadata.gz: 53ac2db8b8b227fd151542ed86a350aab7bf6e3a740347cef034348f175465f3e17b7f32b6ca868da4c300bc0ad7b681b5fcdc84375e58838115e0f0d34ec0ac
7
- data.tar.gz: 604e37c539b045cf9ecc3ff12a88fa467514506fb9149a2e02d85278f5a2dbd468ecf0cacf9259922dca87d21cdff4fd7f247cfad8dcf5752e5289ae82a2662c
6
+ metadata.gz: addeba17cca2ccf6fd3c06bddc308d845ed26d597c65f770a8a6e1b251949b9496bef513a29c3f464c7c24494bce600dcc22cb6cb8c19885afc5296972d3d015
7
+ data.tar.gz: a07983b3d89ab83d71c55ababa747e2de49f442ef3ef4e5b6bdc01bfea82fffb9d11d7044a4202d571fbfe0a3e0a9d63a01f2ba1c1105035508f87a9b248774d
data/.rubocop.yml CHANGED
@@ -25,3 +25,28 @@ Metrics/MethodLength:
25
25
 
26
26
  Layout/LineLength:
27
27
  Enabled: false
28
+
29
+ # The System One strategies are small state machines around a remote model; splitting
30
+ # them further to satisfy size metrics hurts readability more than it helps.
31
+ Metrics/AbcSize:
32
+ Exclude:
33
+ - 'lib/vibe_sort/system_one/**/*'
34
+ - 'lib/vibe_sort/provider_resolver.rb'
35
+ - 'lib/vibe_sort/providers/jev.rb'
36
+ Metrics/CyclomaticComplexity:
37
+ Exclude:
38
+ - 'lib/vibe_sort/system_one/**/*'
39
+ - 'lib/vibe_sort/provider_resolver.rb'
40
+ - 'lib/vibe_sort/providers/jev.rb'
41
+ Metrics/PerceivedComplexity:
42
+ Exclude:
43
+ - 'lib/vibe_sort/system_one/**/*'
44
+ - 'lib/vibe_sort/provider_resolver.rb'
45
+ - 'lib/vibe_sort/providers/jev.rb'
46
+ Metrics/ClassLength:
47
+ Exclude:
48
+ - 'lib/vibe_sort/system_one/**/*'
49
+
50
+ # Keyword arguments are the idiomatic way to take many options in Ruby
51
+ Metrics/ParameterLists:
52
+ CountKeywordArgs: false
data/CHANGELOG.md CHANGED
@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.5.0] - 2026-11-22
11
+
12
+ ### Added
13
+
14
+ - **TypeSafe Jev (System One) support** (`provider: :jev`, alias `:typesafe`): a discriminative decision model that answers typed `choice` / `score` / `noul` questions instead of generating text, so results are always the caller's original objects (any Ruby objects, not just numbers and strings)
15
+ - **Dual-gateway routing**: TypeSafe Direct (`https://api.typesafe.ai/v1/systemone`, `TYPESAFE_API_KEY`, `TYPESAFE_BASE_URL`) and OpenRouter (`https://openrouter.ai/api/v1/systemone`), through one wire-compatible client. `sk-or-` keys with a `jev` model or a `strategy:` route to System One; plain `sk-or-` keys still use OpenRouter chat
16
+ - **Four strategies** via `strategy:`: `:choice` (draft-pick selection sort, default), `:score` (one-call normalized batch scoring with optional adjacent tie-break), `:noul` (pairwise merge sort robust to non-transitive judgments, with a symmetric pair cache) and `:bogo` (vibe bogosort with a `max_attempts` safety cap and `strict:` mode)
17
+ - `VibeSort::Client#sort_with_metadata` returning a `VibeSort::Result` (items, strategy, resolved model, gateway, API call count, token usage, per-item scores/confidence/probabilities, warnings)
18
+ - Per-call and per-client options `by:` (alias `prompt:`), `order:`, `strategy:`, `rubric:`, `tie_break:`, `max_attempts:`, `threshold:`, `strict:`, `long_context:`; process-wide defaults via `VibeSort.configure`
19
+ - Typed errors: `ConfigurationError`, `AuthenticationError`, `PaymentRequiredError`, `AuthorizationError`, `ValidationError`, `ContextLengthError`, `PayloadTooLargeError`, `EdgeFirewallError` (Cloudflare WAF 403, exposes `cf_ray`), `RateLimitError`, `OverloadedError`, `BogoExhaustedError`; retries on 429/524/529 and transient network failures with exponential backoff, full jitter and `Retry-After`
20
+ - JSON sanitising for System One (NaN/Infinity, unsafe integers, BigDecimal, invalid UTF-8, nesting depth, circular references) and a client-side 32 MiB payload guard
21
+ - Opt-in live smoke specs (`LIVE_JEV_TESTS=1`)
22
+
23
+ ### Notes
24
+
25
+ - Fully backwards compatible: generative providers, key-prefix detection, `Client#sort` return shape and every 0.4.0 spec are unchanged. `Client.new(api_key:)` now defaults `api_key:` to `nil` so `TYPESAFE_API_KEY` can supply it; `strategy:` and other Jev-only options raise `ConfigurationError` with a generative provider
26
+ - Jev treats numbers and dates as text, and `<=>` is deliberately never used as a fallback
27
+ - Still no runtime dependencies beyond Faraday
28
+ - Deferred to 0.6.0: image sorting (`box`), hybrid LLM-rubric + Jev pipelines
29
+
30
+ ## [0.4.0] - 2026-07-12
31
+
32
+ ### Added
33
+
34
+ - **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
35
+ - **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
36
+ - **`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)
37
+ - Free-tier model benchmark results (`docs/free_model_benchmark_2026-07-12.md`)
38
+
39
+ ### Changed
40
+
41
+ - Passing an explicit `provider:` that disagrees with the detected key format now prints a one-line warning to stderr; the explicit provider still wins
42
+
43
+ ### Notes
44
+
45
+ - 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
46
+ - Still no runtime dependencies beyond Faraday
47
+
10
48
  ## [0.3.1] - 2026-07-11
11
49
 
12
50
  ### Changed
data/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # VibeSort
2
2
 
3
- > **AI-powered array sorting using OpenAI, Anthropic Claude, Google Gemini, Groq, or SpaceXAI Grok**
3
+ > **AI-powered array sorting using OpenAI, Anthropic Claude, Google Gemini, Groq, SpaceXAI Grok, OpenRouter, or TypeSafe Jev**
4
4
 
5
- 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.
5
+ 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, plus TypeSafe's Jev decision model (System One), with zero dependencies beyond Faraday.
6
6
 
7
7
  [![Gem Version](https://badge.fury.io/rb/vibe-sort.svg)](https://badge.fury.io/rb/vibe-sort)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -11,22 +11,57 @@ VibeSort is a proof-of-concept Ruby gem that demonstrates sorting arrays by leve
11
11
 
12
12
  This is a **proof-of-concept** and educational project. It is not intended for production use. Traditional sorting algorithms are far more efficient, reliable, and cost-effective. Use this gem to explore AI capabilities, not to sort arrays in real applications.
13
13
 
14
+ ## Migrate Your Whole Repo (Copy-Paste for Your Coding Agent)
15
+
16
+ Just here to have fun? Paste this into Claude Code, Cursor, Copilot, or whatever agent you like. It installs the gem and replaces every sort in your repo with a vibe.
17
+
18
+ ````text
19
+ Install the vibe-sort Ruby gem (https://github.com/chayuto/vibe-sort) and replace every sort in this repo with it. This is a joke gem and I know what I'm doing, so please don't lecture me about performance.
20
+
21
+ 1. Add `gem "vibe-sort"` to the Gemfile (Ruby 3.0+) and run `bundle install`.
22
+ 2. Put the API key in the env var VIBE_API_KEY (never commit it). The provider is detected from the key prefix, so a key from OpenAI, Anthropic, Gemini, Groq, SpaceXAI or OpenRouter all work. For TypeSafe Jev (sorts any objects and never rewrites your data) use TYPESAFE_API_KEY instead and see the note below the helper.
23
+ 3. Add one shared helper, for example lib/vibe.rb, so there is a single client:
24
+
25
+ require "vibe_sort"
26
+
27
+ module Vibe
28
+ CLIENT = VibeSort::Client.new(api_key: ENV.fetch("VIBE_API_KEY"))
29
+
30
+ def self.sort(array)
31
+ result = CLIENT.sort(array)
32
+ raise result[:error] unless result[:success]
33
+
34
+ result[:sorted_array]
35
+ end
36
+ end
37
+
38
+ Note: `Client#sort` returns a hash ({ success:, sorted_array:, error: }), not an Array. With the default providers the input must be a non-empty array of numbers and/or strings. For other objects or `sort_by`, use a TypeSafe Jev client (`VibeSort::Client.new(api_key: ENV["TYPESAFE_API_KEY"], provider: :jev)`) and call `client.sort(items, by: "describe the criterion", order: :asc)` or `client.sort_with_metadata(...)`.
39
+ 4. Find every sort: `.sort`, `.sort!`, `.sort_by`, `.min`/`.max` used for ordering, `ORDER BY` done in Ruby, and `<=>` comparators. Replace each with `Vibe.sort(...)`. For `sort_by { ... }`, use a Jev client with `by:` set to a plain-English description of the old block.
40
+ 5. Keep the replacements behind the helper, so reverting later is a one-line change.
41
+ 6. Run the test suite. Failing tests mean the vibes were off, so update the expectations, don't question the vibes.
42
+ 7. Show me a summary of the files changed and the number of API calls each sort now costs.
43
+ ````
44
+
45
+ Heads up: every sort becomes a paid network call, results are not guaranteed, and the [Disclaimer](#disclaimer) is real. See [Choosing a Provider](#choosing-a-provider) and [Sorting with Decision Models](#sorting-with-decision-models-typesafe-jev) for the details your agent will use.
46
+
14
47
  ## Features
15
48
 
16
- - **AI-Powered Sorting**: Uses OpenAI, Anthropic Claude, Google Gemini, Groq, or SpaceXAI Grok models to sort arrays
49
+ - **AI-Powered Sorting**: Uses OpenAI, Anthropic Claude, Google Gemini, Groq, SpaceXAI Grok, or OpenRouter models to sort arrays
50
+ - **Decision-Model Sorting**: TypeSafe's Jev (System One) sorts any Ruby objects through four strategies without ever rewriting your data
17
51
  - **Multi-Provider**: Switch providers with a single `provider:` option, no extra dependencies
52
+ - **Key Format Detection**: Omit `provider:` and VibeSort infers it from your API key's prefix
18
53
  - **Simple Interface**: Clean, intuitive API with a single `sort` method
19
- - **Configurable**: Supports custom model and temperature settings
54
+ - **Configurable**: Custom model, temperature, and an `extra_params:` escape hatch for any provider-native request parameter
20
55
  - **Error Handling**: Comprehensive error handling with clear error messages
21
56
  - **Structured Output**: Uses JSON mode for reliable, parsable responses
22
57
  - **Type Validation**: Validates input and output to ensure data integrity
23
- - **Mixed-Type Support**: Sorts arrays containing integers, floats, and strings
58
+ - **Mixed-Type Support**: Sorts arrays containing integers, floats, and strings (any Ruby objects with Jev)
24
59
 
25
60
  ## Requirements
26
61
 
27
62
  - Ruby **3.0** or newer (MRI)
28
63
  - Bundler **2.0+**
29
- - An API key for at least one supported provider (OpenAI, Anthropic, Google Gemini, Groq, or SpaceXAI)
64
+ - An API key for at least one supported provider (OpenAI, Anthropic, Google Gemini, Groq, SpaceXAI, OpenRouter, or TypeSafe)
30
65
  - Internet connectivity (each sort performs a remote API call)
31
66
 
32
67
  ## Installation
@@ -121,11 +156,11 @@ end
121
156
 
122
157
  ### Choosing a Provider
123
158
 
124
- VibeSort defaults to OpenAI, but any supported provider can be selected with the `provider:` option:
159
+ Any supported provider can be selected with the `provider:` option:
125
160
 
126
161
  ```ruby
127
- # OpenAI (default)
128
- client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
162
+ # OpenAI
163
+ client = VibeSort::Client.new(provider: :openai, api_key: ENV['OPENAI_API_KEY'])
129
164
 
130
165
  # Anthropic Claude
131
166
  client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
@@ -138,6 +173,9 @@ client = VibeSort::Client.new(provider: :groq, api_key: ENV['GROQ_API_KEY'])
138
173
 
139
174
  # SpaceXAI (formerly xAI) Grok
140
175
  client = VibeSort::Client.new(provider: :spacexai, api_key: ENV['XAI_API_KEY'])
176
+
177
+ # OpenRouter (hundreds of models behind one API)
178
+ client = VibeSort::Client.new(provider: :openrouter, api_key: ENV['OPENROUTER_API_KEY'])
141
179
  ```
142
180
 
143
181
  | Provider | API | Default model | Override with `model:` |
@@ -147,9 +185,13 @@ client = VibeSort::Client.new(provider: :spacexai, api_key: ENV['XAI_API_KEY'])
147
185
  | `:gemini` | generateContent | `gemini-2.5-flash` | e.g. `gemini-2.5-pro` |
148
186
  | `:groq` | Chat Completions (OpenAI-compatible) | `llama-3.3-70b-versatile` | any Groq-hosted model |
149
187
  | `:spacexai` | Chat Completions (OpenAI-compatible) | `grok-4` | e.g. `grok-4.5` |
188
+ | `:openrouter` | Chat Completions (OpenAI-compatible) | `openai/gpt-4o-mini` | any OpenRouter model ID |
189
+ | `:jev` (alias `:typesafe`) | System One (`/v1/systemone`) | `jev-latest` (`~typesafe/jev-latest` via OpenRouter) | `jev-1.14.0` etc. See [Sorting with Decision Models](#sorting-with-decision-models-typesafe-jev) |
150
190
 
151
191
  > **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.
152
192
 
193
+ > **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.
194
+
153
195
  ```ruby
154
196
  # Pick a specific model
155
197
  client = VibeSort::Client.new(
@@ -159,6 +201,108 @@ client = VibeSort::Client.new(
159
201
  )
160
202
  ```
161
203
 
204
+ ### Provider Detection (provider: is optional)
205
+
206
+ If you omit `provider:`, VibeSort infers it from your API key's prefix:
207
+
208
+ ```ruby
209
+ VibeSort::Client.new(api_key: 'sk-ant-...') # => :anthropic
210
+ VibeSort::Client.new(api_key: 'sk-or-...') # => :openrouter
211
+ VibeSort::Client.new(api_key: 'gsk_...') # => :groq
212
+ VibeSort::Client.new(api_key: 'AIza...') # => :gemini (classic key)
213
+ VibeSort::Client.new(api_key: 'AQ....') # => :gemini (newer key format)
214
+ VibeSort::Client.new(api_key: 'xai-...') # => :spacexai
215
+ VibeSort::Client.new(api_key: 'sk-...') # => :openai
216
+ ```
217
+
218
+ Key prefixes are conventions, not contracts, so detection is deliberately soft:
219
+
220
+ - Unrecognized key formats (proxies, gateways, self-hosted endpoints) default to `:openai` — same behavior as before v0.4.0
221
+ - System One (Jev) is selected by `provider: :jev`, by an `sk-or-` key combined with a `jev` model or a `strategy:`, or by `TYPESAFE_API_KEY` when no `api_key:` is given. A plain `sk-or-` key still means OpenRouter chat
222
+ - An explicit `provider:` always wins; if it disagrees with the detected format you get a one-line stderr warning, never an error
223
+
224
+ ### Sorting with Decision Models (TypeSafe Jev)
225
+
226
+ [TypeSafe AI's **Jev**](https://docs.typesafe.ai) is a *System One* model: it never writes text or rewrites your array. It answers typed questions (`choice`, `score`, `noul`) about items and returns probabilities, so vibe-sort can only ever return **your original objects**, never hallucinated, duplicated or dropped ones. Any Ruby objects work (not just numbers and strings), and `strategy:` picks how the questions are asked.
227
+
228
+ ```ruby
229
+ # TypeSafe Direct (POST https://api.typesafe.ai/v1/systemone)
230
+ client = VibeSort::Client.new(api_key: ENV["TYPESAFE_API_KEY"], provider: :jev)
231
+ # ...or just set TYPESAFE_API_KEY and omit api_key: entirely
232
+ client = VibeSort::Client.new
233
+
234
+ # Through OpenRouter, no waitlist: an sk-or- key plus a jev model (or a strategy:) routes to System One
235
+ client = VibeSort::Client.new(api_key: ENV["OPENROUTER_API_KEY"], model: "jev-latest")
236
+
237
+ client.sort(%w[jalapeno ghost-pepper habanero], by: "spiciness", order: :desc)
238
+ # => { success: true, sorted_array: ["ghost-pepper", "habanero", "jalapeno"] }
239
+ ```
240
+
241
+ | Strategy | How it sorts | API calls (N items) | Meme factor |
242
+ | :--- | :--- | :--- | :--- |
243
+ | `:choice` (default) | Draft pick: "which item comes NEXT?", repeated | N-1 (tournament chunking above 255 items) | Fantasy football for arrays |
244
+ | `:score` | Rates every item on a relative rubric in one request, sorts by score, optionally settles near-ties | 1 (+1 with `tie_break:`) | Judges' panel |
245
+ | `:noul` | Pairwise "should A come before B?" feeding a merge sort that survives non-transitive opinions | about N log N | A very long committee meeting |
246
+ | `:bogo` | Shuffle, ask "is this sorted?", repeat until convinced or out of attempts (`max_attempts:` defaults to 25) | up to `max_attempts` | Maximum. Sorting by vibes, literally |
247
+
248
+ Per-call options (all of them can also go on `Client.new` or `VibeSort.configure`): `by:` (alias `prompt:`), `order:` (`:asc`/`:desc`), `strategy:`, `rubric:` (2-10 level descriptions, `:score`), `tie_break:`, `max_attempts:`/`threshold:`/`strict:` (`:bogo`), `long_context:` (opt in to Jev's 262k window).
249
+
250
+ `sort` keeps returning the usual `{ success:, sorted_array: }` hash. For the full picture use `sort_with_metadata`, which returns a `VibeSort::Result` and raises on failure:
251
+
252
+ ```ruby
253
+ result = client.sort_with_metadata(%w[pizza kale cake], by: "tastiness", strategy: :score)
254
+ result.items # => ["kale", "pizza", "cake"] (your original objects)
255
+ result.model # => "jev-1.14.0" (the resolved version)
256
+ result.gateway # => :typesafe or :openrouter
257
+ result.api_calls # => 1
258
+ result.usage # => { input_tokens: 214, output_tokens: 12, cost: nil }
259
+ result.item_metadata # => [{ index: 1, score: 0.4, confidence: 0.91, probabilities: {...} }, ...]
260
+ result.warnings # => ["Low confidence (0.41) scoring item 2; its score may be bimodal"]
261
+ ```
262
+
263
+ ```ruby
264
+ VibeSort.configure do |c|
265
+ c.jev_strategy = :score
266
+ c.jev_max_retries = 5 # 429 / 524 / 529 and network errors, with backoff + jitter
267
+ c.jev_long_context = false
268
+ end
269
+ ```
270
+
271
+ Good to know:
272
+
273
+ - **Vibes, not arithmetic.** Jev reads numbers and dates as text, and vibe-sort deliberately does not fall back to `<=>`. `[100, 2, 19]` may not come back in numeric order. Only arrays of 0 or 1 elements skip the API.
274
+ - **The edge firewall.** TypeSafe sits behind a Cloudflare WAF that can block requests whose items look like shell commands or URLs (`curl https://...`). That surfaces as `VibeSort::EdgeFirewallError` (with the `cf_ray`); it is not retried.
275
+ - **Errors** are typed: `AuthenticationError` (401), `PaymentRequiredError` (402, OpenRouter credits), `ContextLengthError` (try `long_context: true`), `ValidationError`, `PayloadTooLargeError` (32 MiB), `RateLimitError`, `OverloadedError`, `BogoExhaustedError` (`strict: true`). All but the last subclass `VibeSort::ApiError`.
276
+ - Live smoke tests are opt-in: `LIVE_JEV_TESTS=1 TYPESAFE_API_KEY=... bundle exec rspec spec/integration`.
277
+
278
+ ### Extra Request Parameters
279
+
280
+ `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:
281
+
282
+ ```ruby
283
+ # Cap completion length (OpenAI/Groq/SpaceXAI/OpenRouter wire format)
284
+ client = VibeSort::Client.new(
285
+ api_key: ENV['OPENAI_API_KEY'],
286
+ extra_params: { max_tokens: 200 }
287
+ )
288
+
289
+ # Gemini uses its own parameter names — nested hashes merge recursively
290
+ client = VibeSort::Client.new(
291
+ provider: :gemini,
292
+ api_key: ENV['GEMINI_API_KEY'],
293
+ extra_params: { generationConfig: { maxOutputTokens: 256 } }
294
+ )
295
+
296
+ # OpenRouter provider-routing preferences
297
+ client = VibeSort::Client.new(
298
+ provider: :openrouter,
299
+ api_key: ENV['OPENROUTER_API_KEY'],
300
+ extra_params: { provider: { sort: 'throughput' } }
301
+ )
302
+ ```
303
+
304
+ 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.
305
+
162
306
  ### Advanced Configuration
163
307
 
164
308
  You can customize the model's behavior using the `temperature` parameter:
@@ -189,7 +333,7 @@ result = client.sort([5, :symbol, 12])
189
333
  puts result[:error]
190
334
  # => "Input must be an array of numbers or strings"
191
335
 
192
- # Empty array
336
+ # Empty array (generative providers; Jev accepts it and returns [] without an API call)
193
337
  result = client.sort([])
194
338
  puts result[:error]
195
339
  # => "Input must be an array of numbers or strings"
@@ -203,7 +347,7 @@ puts result[:error]
203
347
 
204
348
  ### Return Value Structure
205
349
 
206
- The `sort` method always returns a hash with the following structure:
350
+ The `sort` method always returns a hash with the following structure (for every provider, Jev included; `sort_with_metadata` is the Jev-only variant that returns a `VibeSort::Result`):
207
351
 
208
352
  ```ruby
209
353
  {
@@ -218,6 +362,7 @@ The `sort` method always returns a hash with the following structure:
218
362
  - **Numbers only**: Sorted in ascending numerical order
219
363
  - **Strings only**: Sorted in ascending alphabetical order (case-sensitive)
220
364
  - **Mixed types**: Numbers come before strings; each group sorted within itself
365
+ - **Jev (System One)**: Ordering comes from the model's judgments for your `by:` criterion (default: natural order), never from `<=>`; numbers and dates are treated as text
221
366
 
222
367
  ## Architecture
223
368
 
@@ -225,9 +370,11 @@ VibeSort follows a clean, modular architecture:
225
370
 
226
371
  - **`VibeSort::Client`**: Public interface for users
227
372
  - **`VibeSort::Configuration`**: Manages provider, API key, model, and settings
373
+ - **`VibeSort::KeyDetector`**: Best-effort provider inference from API key prefixes
228
374
  - **`VibeSort::Sorter`**: Dispatches to the configured provider adapter
229
375
  - **`VibeSort::Providers::Base`**: Shared prompt, HTTP plumbing (Faraday), and response validation
230
- - **`VibeSort::Providers::{OpenAI, Anthropic, Gemini, Groq, SpaceXAI}`**: Provider-specific request/response mapping
376
+ - **`VibeSort::Providers::{OpenAI, Anthropic, Gemini, Groq, SpaceXAI, OpenRouter}`**: Provider-specific request/response mapping
377
+ - **`VibeSort::Providers::Jev` + `VibeSort::SystemOne::*`**: TypeSafe System One transport, serializer and the four sorting strategies
231
378
  - **`VibeSort::ApiError`**: Custom exception for API-related errors
232
379
 
233
380
  See the [Architecture Documentation](docs/architecture.md) for more details.
@@ -279,7 +426,7 @@ This gem was created as an educational exercise to:
279
426
 
280
427
  ## Performance Considerations
281
428
 
282
- - **Latency**: Each sort requires an API call (typically 1-3 seconds)
429
+ - **Latency**: Generative providers need one API call per sort (typically 1-3 seconds); Jev strategies need 1 (`:score`) to roughly N log N (`:noul`) calls
283
430
  - **Cost**: LLM API usage is metered and costs money
284
431
  - **Reliability**: Depends on API availability and internet connection
285
432
  - **Accuracy**: Generally accurate, but not guaranteed (unlike algorithmic sorting)
@@ -297,11 +444,12 @@ Traditional sorting (e.g., Ruby's `Array#sort`) is:
297
444
  Set the API key for your chosen provider as an environment variable:
298
445
 
299
446
  ```bash
300
- export OPENAI_API_KEY='your-api-key-here' # provider: :openai (default)
301
- export ANTHROPIC_API_KEY='your-api-key-here' # provider: :anthropic
302
- export GEMINI_API_KEY='your-api-key-here' # provider: :gemini
303
- export GROQ_API_KEY='your-api-key-here' # provider: :groq
304
- export XAI_API_KEY='your-api-key-here' # provider: :spacexai
447
+ export OPENAI_API_KEY='your-api-key-here' # provider: :openai (fallback default)
448
+ export ANTHROPIC_API_KEY='your-api-key-here' # provider: :anthropic
449
+ export GEMINI_API_KEY='your-api-key-here' # provider: :gemini
450
+ export GROQ_API_KEY='your-api-key-here' # provider: :groq
451
+ export XAI_API_KEY='your-api-key-here' # provider: :spacexai
452
+ export OPENROUTER_API_KEY='your-api-key-here' # provider: :openrouter
305
453
  ```
306
454
 
307
455
  Or use a `.env` file with the `dotenv` gem:
@@ -322,7 +470,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
322
470
  ## Acknowledgments
323
471
 
324
472
  - Built with [Faraday](https://lostisland.github.io/faraday/) for HTTP requests
325
- - 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
473
+ - 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
326
474
  - Inspired by the absurdity and creativity of the AI era
327
475
 
328
476
  ---
@@ -6,7 +6,7 @@ The main public interface for the VibeSort gem.
6
6
 
7
7
  ### Class Methods
8
8
 
9
- #### `new(api_key:, temperature: 0.0, provider: :openai, model: nil)`
9
+ #### `new(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})`
10
10
 
11
11
  Creates a new VibeSort client instance.
12
12
 
@@ -18,24 +18,27 @@ Creates a new VibeSort client instance.
18
18
  - Lower values (0.0-0.3): More deterministic and consistent
19
19
  - Higher values (0.7-2.0): More random and creative
20
20
  - Ignored by providers whose current models do not accept it (Anthropic)
21
- - `provider` (Symbol or String, optional): LLM provider (default: `:openai`)
22
- - Supported: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`
21
+ - `provider` (Symbol or String, optional): LLM provider
22
+ - Supported: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, `:openrouter`, `:jev` (alias `:typesafe`)
23
+ - When omitted, inferred from the `api_key` prefix via `VibeSort::KeyDetector`; unrecognized formats default to `:openai`
24
+ - When explicit and the key prefix suggests a different provider, a one-line warning is printed to stderr and the explicit provider is used
23
25
  - `model` (String, optional): Model ID override (default: the provider's default model)
26
+ - `extra_params` (Hash, optional): Provider-native request parameters deep-merged into the payload last, so they can override anything the adapter builds (default: `{}`)
24
27
 
25
28
  **Returns:** `VibeSort::Client` instance
26
29
 
27
30
  **Raises:**
28
31
 
29
- - `ArgumentError`: If api_key is nil or empty, or the provider is unknown
32
+ - `ArgumentError`: If api_key is nil or empty, or an explicit provider is unknown
30
33
 
31
34
  **Example:**
32
35
 
33
36
  ```ruby
34
- # Basic initialization (OpenAI, default provider)
35
- client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
37
+ # Provider inferred from the key prefix (sk-ant-... => :anthropic)
38
+ client = VibeSort::Client.new(api_key: ENV['ANTHROPIC_API_KEY'])
36
39
 
37
- # Anthropic Claude
38
- client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
40
+ # Explicit provider
41
+ client = VibeSort::Client.new(provider: :openai, api_key: ENV['OPENAI_API_KEY'])
39
42
 
40
43
  # Google Gemini with a custom model
41
44
  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(
45
48
  api_key: ENV['OPENAI_API_KEY'],
46
49
  temperature: 0.2
47
50
  )
51
+
52
+ # With extra provider-native request parameters
53
+ client = VibeSort::Client.new(
54
+ provider: :openrouter,
55
+ api_key: ENV['OPENROUTER_API_KEY'],
56
+ model: 'meta-llama/llama-3.3-70b-instruct',
57
+ extra_params: { max_tokens: 200 }
58
+ )
48
59
  ```
49
60
 
50
61
  ### Instance Methods
@@ -110,7 +121,7 @@ Configuration object for VibeSort. Usually not used directly by end users.
110
121
 
111
122
  ### Class Methods
112
123
 
113
- #### `new(api_key:, temperature: 0.0, provider: :openai, model: nil)`
124
+ #### `new(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})`
114
125
 
115
126
  Creates a new configuration object.
116
127
 
@@ -118,8 +129,9 @@ Creates a new configuration object.
118
129
 
119
130
  - `api_key` (String, required): API key for the selected provider
120
131
  - `temperature` (Float, optional): Model temperature (default: 0.0)
121
- - `provider` (Symbol or String, optional): `:openai` (default), `:anthropic`, `:gemini`, `:groq`, or `:spacexai`
132
+ - `provider` (Symbol, String, or nil, optional): `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, `:openrouter`, or `:jev` (alias `:typesafe`); nil (default) infers the provider from the api_key prefix (or routes to System One, see the README), falling back to `:openai`
122
133
  - `model` (String, optional): Model ID override (nil uses the provider's default)
134
+ - `extra_params` (Hash, optional): Provider-native request parameters deep-merged into the payload last (default: `{}`)
123
135
 
124
136
  **Raises:**
125
137
 
@@ -161,6 +173,40 @@ Returns the configured model override, or nil when using the provider default (r
161
173
 
162
174
  **Returns:** String or nil
163
175
 
176
+ #### `extra_params`
177
+
178
+ Returns the configured extra request parameters hash (read-only).
179
+
180
+ **Returns:** Hash
181
+
182
+ ---
183
+
184
+ ## VibeSort::KeyDetector
185
+
186
+ 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.
187
+
188
+ ### Class Methods
189
+
190
+ #### `detect(api_key)`
191
+
192
+ **Parameters:**
193
+
194
+ - `api_key` (String, required): API key to inspect
195
+
196
+ **Returns:** Symbol (detected provider) or nil (unrecognized format)
197
+
198
+ **Prefix map (ordered — specific prefixes checked before `sk-`):**
199
+
200
+ | Prefix | Provider |
201
+ |---|---|
202
+ | `sk-ant-` | `:anthropic` |
203
+ | `sk-or-` | `:openrouter` |
204
+ | `sk-` | `:openai` |
205
+ | `gsk_` | `:groq` |
206
+ | `AIza` | `:gemini` (classic key) |
207
+ | `AQ.` | `:gemini` (newer key format) |
208
+ | `xai-` | `:spacexai` |
209
+
164
210
  ---
165
211
 
166
212
  ## VibeSort::Sorter
@@ -199,7 +245,7 @@ Performs the sorting operation via the configured provider's API.
199
245
 
200
246
  Maps provider symbols to adapter classes.
201
247
 
202
- **Value:** `{ openai:, anthropic:, gemini:, groq:, spacexai: }`
248
+ **Value:** `{ openai:, anthropic:, gemini:, groq:, spacexai:, openrouter:, jev: }`
203
249
 
204
250
  ---
205
251
 
@@ -214,11 +260,23 @@ Internal provider adapters. `Providers::Base` holds the shared prompt, Faraday H
214
260
  | `Providers::Gemini` | `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent` | `gemini-2.5-flash` |
215
261
  | `Providers::Groq` | `https://api.groq.com/openai/v1/chat/completions` | `llama-3.3-70b-versatile` |
216
262
  | `Providers::SpaceXAI` | `https://api.x.ai/v1/chat/completions` | `grok-4` |
263
+ | `Providers::OpenRouter` | `https://openrouter.ai/api/v1/chat/completions` | `openai/gpt-4o-mini` |
264
+ | `Providers::Jev` | `https://api.typesafe.ai/v1/systemone` (or `https://openrouter.ai/api/v1/systemone`) | `jev-latest` (`~typesafe/jev-latest` on OpenRouter) |
217
265
 
218
266
  Notes:
219
267
 
220
268
  - The Anthropic adapter uses structured outputs (JSON schema) and does not send `temperature` (rejected by current Claude models)
221
- - The Groq and SpaceXAI adapters subclass `Providers::OpenAI` (OpenAI-compatible APIs)
269
+ - The Groq, SpaceXAI, and OpenRouter adapters subclass `Providers::OpenAI` (OpenAI-compatible APIs)
270
+ - The OpenRouter adapter sends OpenRouter's recommended attribution headers (`HTTP-Referer`, `X-Title`)
271
+ - `Providers::Base` deep-merges `config.extra_params` into every payload last, so it can override anything the adapter builds
272
+
273
+ ---
274
+
275
+ ## System One (Jev)
276
+
277
+ `VibeSort::Client#sort(array, **options)` and `#sort_with_metadata(array, **options)` accept, for `:jev` providers only: `by:` (alias `prompt:`), `order:` (`:asc`/`:desc`), `strategy:` (`:choice`, `:score`, `:noul`, `:bogo`), `rubric:`, `tie_break:`, `tie_epsilon:`, `confidence_floor:`, `max_attempts:`, `threshold:`, `strict:`, `long_context:`, `shuffle_options:`. The same keys (plus `max_retries:`, `timeout:`, `openrouter_referer:`, `openrouter_title:`) may be passed to `Client.new` or set globally with `VibeSort.configure`. `Client.new` also takes `base_url:`.
278
+
279
+ `#sort_with_metadata` returns a `VibeSort::Result` (`items`, `strategy`, `model`, `gateway`, `api_calls`, `usage`, `item_metadata`, `warnings`) and raises on failure. Errors subclass `VibeSort::ApiError` (`AuthenticationError`, `PaymentRequiredError`, `AuthorizationError`, `ValidationError`, `ContextLengthError`, `PayloadTooLargeError`, `EdgeFirewallError`, `RateLimitError`, `OverloadedError`), except `ConfigurationError` (an `ArgumentError`) and `BogoExhaustedError`. See the README for strategies and examples.
222
280
 
223
281
  ---
224
282
 
@@ -307,7 +365,7 @@ All sorting operations return a consistent hash structure:
307
365
 
308
366
  ### API Errors
309
367
 
310
- The `{Provider}` prefix names the configured provider (OpenAI, Anthropic, Gemini, Groq, or SpaceXAI):
368
+ The `{Provider}` prefix names the configured provider (OpenAI, Anthropic, Gemini, Groq, SpaceXAI, or OpenRouter):
311
369
 
312
370
  | Error Message Pattern | Cause | Solution |
313
371
  |----------------------|-------|----------|
@@ -455,11 +513,13 @@ results = threads.map(&:value)
455
513
  Set the API key for whichever provider you use:
456
514
 
457
515
  ```bash
458
- export OPENAI_API_KEY='sk-your-key-here' # provider: :openai (default)
516
+ export OPENAI_API_KEY='sk-your-key-here' # provider: :openai (fallback default)
459
517
  export ANTHROPIC_API_KEY='your-key-here' # provider: :anthropic
460
518
  export GEMINI_API_KEY='your-key-here' # provider: :gemini
461
519
  export GROQ_API_KEY='your-key-here' # provider: :groq
462
520
  export XAI_API_KEY='your-key-here' # provider: :spacexai
521
+ export OPENROUTER_API_KEY='your-key-here' # provider: :openrouter
522
+ export TYPESAFE_API_KEY='your-key-here' # provider: :jev (optional TYPESAFE_BASE_URL)
463
523
  ```
464
524
 
465
525
  **Usage:**
@@ -472,9 +532,9 @@ client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
472
532
 
473
533
  ## Version
474
534
 
475
- Current version: `0.3.0`
535
+ Current version: `0.4.0`
476
536
 
477
537
  ```ruby
478
538
  VibeSort::VERSION
479
- # => "0.3.0"
539
+ # => "0.4.0"
480
540
  ```