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 +4 -4
- data/.rubocop.yml +25 -0
- data/CHANGELOG.md +38 -0
- data/README.md +167 -19
- data/docs/api_reference.md +76 -16
- data/docs/architecture.md +22 -9
- data/docs/free_model_benchmark_2026-07-12.md +134 -0
- data/docs/v0.4.0_PLAN.md +203 -0
- data/lib/vibe_sort/client.rb +85 -14
- data/lib/vibe_sort/configuration.rb +63 -11
- data/lib/vibe_sort/error.rb +55 -0
- data/lib/vibe_sort/key_detector.rb +31 -0
- data/lib/vibe_sort/provider_resolver.rb +98 -0
- data/lib/vibe_sort/providers/base.rb +15 -1
- data/lib/vibe_sort/providers/jev.rb +72 -0
- data/lib/vibe_sort/providers/open_router.rb +29 -0
- data/lib/vibe_sort/result.rb +37 -0
- data/lib/vibe_sort/settings.rb +79 -0
- data/lib/vibe_sort/sorter.rb +16 -3
- data/lib/vibe_sort/system_one/client.rb +189 -0
- data/lib/vibe_sort/system_one/serializer.rb +118 -0
- data/lib/vibe_sort/system_one/strategies/base.rb +127 -0
- data/lib/vibe_sort/system_one/strategies/bogo_sort.rb +83 -0
- data/lib/vibe_sort/system_one/strategies/choice_sort.rb +113 -0
- data/lib/vibe_sort/system_one/strategies/noul_sort.rb +76 -0
- data/lib/vibe_sort/system_one/strategies/score_sort.rb +128 -0
- data/lib/vibe_sort/version.rb +1 -1
- data/lib/vibe_sort.rb +13 -0
- metadata +21 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4da00322a5e2edf9b700b91c32552a2099a8d9b64b275a48c5fc87a85db29f14
|
|
4
|
+
data.tar.gz: df5e02d86371c783360736912682d54cb286b8b39b190e4a2984a811b35eb858
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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
|
|
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
|
[](https://badge.fury.io/rb/vibe-sort)
|
|
8
8
|
[](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,
|
|
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**:
|
|
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
|
|
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
|
-
|
|
159
|
+
Any supported provider can be selected with the `provider:` option:
|
|
125
160
|
|
|
126
161
|
```ruby
|
|
127
|
-
# OpenAI
|
|
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**:
|
|
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'
|
|
301
|
-
export ANTHROPIC_API_KEY='your-api-key-here'
|
|
302
|
-
export GEMINI_API_KEY='your-api-key-here'
|
|
303
|
-
export GROQ_API_KEY='your-api-key-here'
|
|
304
|
-
export XAI_API_KEY='your-api-key-here'
|
|
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/),
|
|
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
|
---
|
data/docs/api_reference.md
CHANGED
|
@@ -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:
|
|
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
|
|
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
|
|
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
|
-
#
|
|
35
|
-
client = VibeSort::Client.new(api_key: ENV['
|
|
37
|
+
# Provider inferred from the key prefix (sk-ant-... => :anthropic)
|
|
38
|
+
client = VibeSort::Client.new(api_key: ENV['ANTHROPIC_API_KEY'])
|
|
36
39
|
|
|
37
|
-
#
|
|
38
|
-
client = VibeSort::Client.new(provider: :
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
535
|
+
Current version: `0.4.0`
|
|
476
536
|
|
|
477
537
|
```ruby
|
|
478
538
|
VibeSort::VERSION
|
|
479
|
-
# => "0.
|
|
539
|
+
# => "0.4.0"
|
|
480
540
|
```
|