vibe-sort 0.4.0 → 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 +20 -0
- data/README.md +99 -7
- data/docs/api_reference.md +13 -3
- data/docs/architecture.md +2 -1
- data/docs/v0.4.0_PLAN.md +203 -0
- data/lib/vibe_sort/client.rb +65 -8
- data/lib/vibe_sort/configuration.rb +37 -9
- 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/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 +15 -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 +11 -0
- metadata +20 -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,26 @@ 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
|
+
|
|
10
30
|
## [0.4.0] - 2026-07-12
|
|
11
31
|
|
|
12
32
|
### Added
|
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, SpaceXAI Grok, 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, SpaceXAI (xAI), and OpenRouter 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
|
[](https://badge.fury.io/rb/vibe-sort)
|
|
8
8
|
[](https://opensource.org/licenses/MIT)
|
|
@@ -11,9 +11,43 @@ 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
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
|
|
18
52
|
- **Key Format Detection**: Omit `provider:` and VibeSort infers it from your API key's prefix
|
|
19
53
|
- **Simple Interface**: Clean, intuitive API with a single `sort` method
|
|
@@ -21,13 +55,13 @@ This is a **proof-of-concept** and educational project. It is not intended for p
|
|
|
21
55
|
- **Error Handling**: Comprehensive error handling with clear error messages
|
|
22
56
|
- **Structured Output**: Uses JSON mode for reliable, parsable responses
|
|
23
57
|
- **Type Validation**: Validates input and output to ensure data integrity
|
|
24
|
-
- **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)
|
|
25
59
|
|
|
26
60
|
## Requirements
|
|
27
61
|
|
|
28
62
|
- Ruby **3.0** or newer (MRI)
|
|
29
63
|
- Bundler **2.0+**
|
|
30
|
-
- An API key for at least one supported provider (OpenAI, Anthropic, Google Gemini, Groq, SpaceXAI, or
|
|
64
|
+
- An API key for at least one supported provider (OpenAI, Anthropic, Google Gemini, Groq, SpaceXAI, OpenRouter, or TypeSafe)
|
|
31
65
|
- Internet connectivity (each sort performs a remote API call)
|
|
32
66
|
|
|
33
67
|
## Installation
|
|
@@ -152,6 +186,7 @@ client = VibeSort::Client.new(provider: :openrouter, api_key: ENV['OPENROUTER_AP
|
|
|
152
186
|
| `:groq` | Chat Completions (OpenAI-compatible) | `llama-3.3-70b-versatile` | any Groq-hosted model |
|
|
153
187
|
| `:spacexai` | Chat Completions (OpenAI-compatible) | `grok-4` | e.g. `grok-4.5` |
|
|
154
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) |
|
|
155
190
|
|
|
156
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.
|
|
157
192
|
|
|
@@ -183,8 +218,63 @@ VibeSort::Client.new(api_key: 'sk-...') # => :openai
|
|
|
183
218
|
Key prefixes are conventions, not contracts, so detection is deliberately soft:
|
|
184
219
|
|
|
185
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
|
|
186
222
|
- An explicit `provider:` always wins; if it disagrees with the detected format you get a one-line stderr warning, never an error
|
|
187
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
|
+
|
|
188
278
|
### Extra Request Parameters
|
|
189
279
|
|
|
190
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:
|
|
@@ -243,7 +333,7 @@ result = client.sort([5, :symbol, 12])
|
|
|
243
333
|
puts result[:error]
|
|
244
334
|
# => "Input must be an array of numbers or strings"
|
|
245
335
|
|
|
246
|
-
# Empty array
|
|
336
|
+
# Empty array (generative providers; Jev accepts it and returns [] without an API call)
|
|
247
337
|
result = client.sort([])
|
|
248
338
|
puts result[:error]
|
|
249
339
|
# => "Input must be an array of numbers or strings"
|
|
@@ -257,7 +347,7 @@ puts result[:error]
|
|
|
257
347
|
|
|
258
348
|
### Return Value Structure
|
|
259
349
|
|
|
260
|
-
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`):
|
|
261
351
|
|
|
262
352
|
```ruby
|
|
263
353
|
{
|
|
@@ -272,6 +362,7 @@ The `sort` method always returns a hash with the following structure:
|
|
|
272
362
|
- **Numbers only**: Sorted in ascending numerical order
|
|
273
363
|
- **Strings only**: Sorted in ascending alphabetical order (case-sensitive)
|
|
274
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
|
|
275
366
|
|
|
276
367
|
## Architecture
|
|
277
368
|
|
|
@@ -283,6 +374,7 @@ VibeSort follows a clean, modular architecture:
|
|
|
283
374
|
- **`VibeSort::Sorter`**: Dispatches to the configured provider adapter
|
|
284
375
|
- **`VibeSort::Providers::Base`**: Shared prompt, HTTP plumbing (Faraday), and response validation
|
|
285
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
|
|
286
378
|
- **`VibeSort::ApiError`**: Custom exception for API-related errors
|
|
287
379
|
|
|
288
380
|
See the [Architecture Documentation](docs/architecture.md) for more details.
|
|
@@ -334,7 +426,7 @@ This gem was created as an educational exercise to:
|
|
|
334
426
|
|
|
335
427
|
## Performance Considerations
|
|
336
428
|
|
|
337
|
-
- **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
|
|
338
430
|
- **Cost**: LLM API usage is metered and costs money
|
|
339
431
|
- **Reliability**: Depends on API availability and internet connection
|
|
340
432
|
- **Accuracy**: Generally accurate, but not guaranteed (unlike algorithmic sorting)
|
data/docs/api_reference.md
CHANGED
|
@@ -19,7 +19,7 @@ Creates a new VibeSort client instance.
|
|
|
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
21
|
- `provider` (Symbol or String, optional): LLM provider
|
|
22
|
-
- Supported: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, `:openrouter`
|
|
22
|
+
- Supported: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, `:openrouter`, `:jev` (alias `:typesafe`)
|
|
23
23
|
- When omitted, inferred from the `api_key` prefix via `VibeSort::KeyDetector`; unrecognized formats default to `:openai`
|
|
24
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
|
|
25
25
|
- `model` (String, optional): Model ID override (default: the provider's default model)
|
|
@@ -129,7 +129,7 @@ Creates a new configuration object.
|
|
|
129
129
|
|
|
130
130
|
- `api_key` (String, required): API key for the selected provider
|
|
131
131
|
- `temperature` (Float, optional): Model temperature (default: 0.0)
|
|
132
|
-
- `provider` (Symbol, String, or nil, optional): `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, 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`
|
|
133
133
|
- `model` (String, optional): Model ID override (nil uses the provider's default)
|
|
134
134
|
- `extra_params` (Hash, optional): Provider-native request parameters deep-merged into the payload last (default: `{}`)
|
|
135
135
|
|
|
@@ -245,7 +245,7 @@ Performs the sorting operation via the configured provider's API.
|
|
|
245
245
|
|
|
246
246
|
Maps provider symbols to adapter classes.
|
|
247
247
|
|
|
248
|
-
**Value:** `{ openai:, anthropic:, gemini:, groq:, spacexai:, openrouter: }`
|
|
248
|
+
**Value:** `{ openai:, anthropic:, gemini:, groq:, spacexai:, openrouter:, jev: }`
|
|
249
249
|
|
|
250
250
|
---
|
|
251
251
|
|
|
@@ -261,6 +261,7 @@ Internal provider adapters. `Providers::Base` holds the shared prompt, Faraday H
|
|
|
261
261
|
| `Providers::Groq` | `https://api.groq.com/openai/v1/chat/completions` | `llama-3.3-70b-versatile` |
|
|
262
262
|
| `Providers::SpaceXAI` | `https://api.x.ai/v1/chat/completions` | `grok-4` |
|
|
263
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) |
|
|
264
265
|
|
|
265
266
|
Notes:
|
|
266
267
|
|
|
@@ -271,6 +272,14 @@ Notes:
|
|
|
271
272
|
|
|
272
273
|
---
|
|
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.
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
274
283
|
## VibeSort::ApiError
|
|
275
284
|
|
|
276
285
|
Custom exception class for API-related errors.
|
|
@@ -510,6 +519,7 @@ export GEMINI_API_KEY='your-key-here' # provider: :gemini
|
|
|
510
519
|
export GROQ_API_KEY='your-key-here' # provider: :groq
|
|
511
520
|
export XAI_API_KEY='your-key-here' # provider: :spacexai
|
|
512
521
|
export OPENROUTER_API_KEY='your-key-here' # provider: :openrouter
|
|
522
|
+
export TYPESAFE_API_KEY='your-key-here' # provider: :jev (optional TYPESAFE_BASE_URL)
|
|
513
523
|
```
|
|
514
524
|
|
|
515
525
|
**Usage:**
|
data/docs/architecture.md
CHANGED
|
@@ -97,7 +97,7 @@ VibeSort follows a layered architecture with clear separation of concerns:
|
|
|
97
97
|
|
|
98
98
|
**Attributes**:
|
|
99
99
|
- `api_key`: Provider API key (String)
|
|
100
|
-
- `provider`: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, or `:
|
|
100
|
+
- `provider`: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`, `:openrouter`, or `:jev` / `:typesafe` (Symbol). Routing between these is decided by `VibeSort::ProviderResolver`
|
|
101
101
|
- `model`: Model ID override, or nil for the provider default (String or nil)
|
|
102
102
|
- `temperature`: Model temperature (Float, 0.0-2.0; not sent to Anthropic)
|
|
103
103
|
- `extra_params`: Provider-native request parameters deep-merged into the payload last (Hash)
|
|
@@ -136,6 +136,7 @@ Prefixes are conventions, not contracts — providers ship multiple key formats
|
|
|
136
136
|
- `Providers::Groq`: OpenAI-compatible (subclasses `Providers::OpenAI`), `llama-3.3-70b-versatile`
|
|
137
137
|
- `Providers::SpaceXAI`: OpenAI-compatible (subclasses `Providers::OpenAI`), `grok-4`
|
|
138
138
|
- `Providers::OpenRouter`: OpenAI-compatible (subclasses `Providers::OpenAI`), `openai/gpt-4o-mini`, adds OpenRouter's recommended attribution headers
|
|
139
|
+
- `Providers::Jev`: TypeSafe System One (does not subclass `Providers::Base`). Builds a `SystemOne::Client` (`POST /v1/systemone`, TypeSafe Direct or OpenRouter) and runs one of `SystemOne::Strategies::{ChoiceSort, ScoreSort, NoulSort, BogoSort}`, which work on item indices and return the original objects as a `VibeSort::Result`. `SystemOne::Serializer` sanitises values for TypeSafe's JSON rules
|
|
139
140
|
|
|
140
141
|
### VibeSort::ApiError
|
|
141
142
|
|
data/docs/v0.4.0_PLAN.md
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# v0.4.0 Plan: OpenRouter, Key Detection, and Extra Params
|
|
2
|
+
|
|
3
|
+
## Executive Summary
|
|
4
|
+
|
|
5
|
+
This document outlines the plan for VibeSort v0.4.0, which adds three related features:
|
|
6
|
+
|
|
7
|
+
1. **OpenRouter provider** — a sixth provider adapter, OpenAI-compatible
|
|
8
|
+
2. **API key format detection** — infer the provider from the key prefix when `provider:` is omitted; warn (never fail) on mismatch when it is explicit
|
|
9
|
+
3. **`extra_params` escape hatch** — a single hash of provider-native request parameters deep-merged into the payload, instead of enumerating every model knob as first-class config
|
|
10
|
+
|
|
11
|
+
**Status:** Implemented — shipped in v0.4.0
|
|
12
|
+
|
|
13
|
+
**Target Version:** 0.4.0 (minor bump — provider auto-detection is a behavior change, see Compatibility Notes)
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Motivation
|
|
18
|
+
|
|
19
|
+
- OpenRouter gives access to hundreds of models through one OpenAI-compatible endpoint — maximum flavour for a gem whose whole point is sorting arrays with unreasonable amounts of AI.
|
|
20
|
+
- Provider key prefixes are distinctive enough that `VibeSort::Client.new(api_key: key)` can usually "just work" without a `provider:` argument. That fits the gem's vibe.
|
|
21
|
+
- Users routing through OpenRouter (or tuning any provider) need occasional knobs (`max_tokens`, `top_p`, OpenRouter `provider` routing preferences). One passthrough hash covers all of them without a config matrix to maintain.
|
|
22
|
+
|
|
23
|
+
## Non-Goals
|
|
24
|
+
|
|
25
|
+
- First-class config attributes for every model parameter (`top_p`, `max_tokens`, penalties, …) — `extra_params` covers these
|
|
26
|
+
- Validating API keys against provider formats (prefixes are conventions, not contracts — OpenAI already changed theirs once with `sk-proj-`)
|
|
27
|
+
- Cross-provider normalization of `extra_params` keys (they are provider-native by design)
|
|
28
|
+
- Streaming, retries, or any other transport changes
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Feature 1: OpenRouter Provider
|
|
33
|
+
|
|
34
|
+
### Design
|
|
35
|
+
|
|
36
|
+
`Providers::OpenRouter < OpenAI`, mirroring `groq.rb` and `space_x_ai.rb`:
|
|
37
|
+
|
|
38
|
+
```ruby
|
|
39
|
+
module VibeSort
|
|
40
|
+
module Providers
|
|
41
|
+
# Adapter for the OpenRouter API (OpenAI-compatible Chat Completions)
|
|
42
|
+
class OpenRouter < OpenAI
|
|
43
|
+
ENDPOINT = "https://openrouter.ai/api/v1/chat/completions"
|
|
44
|
+
DEFAULT_MODEL = "openai/gpt-4o-mini"
|
|
45
|
+
|
|
46
|
+
private
|
|
47
|
+
|
|
48
|
+
def provider_name
|
|
49
|
+
"OpenRouter"
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
def endpoint
|
|
53
|
+
ENDPOINT
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
def headers
|
|
57
|
+
super.merge(
|
|
58
|
+
"HTTP-Referer" => "https://github.com/chayuto/vibe-sort",
|
|
59
|
+
"X-Title" => "vibe-sort"
|
|
60
|
+
)
|
|
61
|
+
end
|
|
62
|
+
end
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Decisions
|
|
68
|
+
|
|
69
|
+
- **Default model:** `openai/gpt-4o-mini` for parity with the OpenAI adapter's default. OpenRouter is the provider where users are most likely to pass `model:` anyway (already supported).
|
|
70
|
+
- **Attribution headers:** `HTTP-Referer` / `X-Title` are optional but recommended by OpenRouter; they cost nothing and get the gem listed on openrouter.ai rankings.
|
|
71
|
+
- **JSON mode caveat:** OpenRouter forwards `response_format: { type: "json_object" }` but only some underlying models honor it. The existing `JSON::ParserError → ApiError` path already handles models that ignore it; document the caveat in the README and note that `extra_params` can override `response_format` if needed.
|
|
72
|
+
|
|
73
|
+
### Checklist
|
|
74
|
+
|
|
75
|
+
- [x] `lib/vibe_sort/providers/open_router.rb`
|
|
76
|
+
- [x] Add `:openrouter` to `Configuration::PROVIDERS`
|
|
77
|
+
- [x] Add `openrouter: Providers::OpenRouter` to `Sorter::PROVIDER_CLASSES`
|
|
78
|
+
- [x] Require the new file from `lib/vibe_sort.rb`
|
|
79
|
+
- [x] `spec/vibe_sort/providers/open_router_spec.rb` (mirror `groq_spec.rb`: endpoint, default model, headers, payload, error prefix)
|
|
80
|
+
- [x] README: provider table row + usage example + JSON-mode caveat
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Feature 2: Key Format Detection
|
|
85
|
+
|
|
86
|
+
### Design
|
|
87
|
+
|
|
88
|
+
A small module with an ordered prefix map (order matters — specific prefixes before `sk-`):
|
|
89
|
+
|
|
90
|
+
```ruby
|
|
91
|
+
module VibeSort
|
|
92
|
+
# Best-effort provider inference from API key prefixes.
|
|
93
|
+
# Prefixes are conventions, not contracts — used only as a default
|
|
94
|
+
# and for non-fatal mismatch warnings, never for validation.
|
|
95
|
+
module KeyDetector
|
|
96
|
+
PREFIXES = {
|
|
97
|
+
"sk-ant-" => :anthropic,
|
|
98
|
+
"sk-or-" => :openrouter,
|
|
99
|
+
"sk-" => :openai,
|
|
100
|
+
"gsk_" => :groq,
|
|
101
|
+
"AIza" => :gemini, # classic Google API key
|
|
102
|
+
"AQ." => :gemini, # newer Gemini API key format (observed in the wild, 2026)
|
|
103
|
+
"xai-" => :spacexai
|
|
104
|
+
}.freeze
|
|
105
|
+
|
|
106
|
+
# @return [Symbol, nil] detected provider, or nil if unrecognized
|
|
107
|
+
def self.detect(api_key)
|
|
108
|
+
PREFIXES.each { |prefix, provider| return provider if api_key.start_with?(prefix) }
|
|
109
|
+
nil
|
|
110
|
+
end
|
|
111
|
+
end
|
|
112
|
+
end
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Wiring in `Configuration`
|
|
116
|
+
|
|
117
|
+
`provider:` defaults change from `:openai` to `nil` in both `Client` and `Configuration`:
|
|
118
|
+
|
|
119
|
+
- `provider: nil` (omitted) → `KeyDetector.detect(api_key) || :openai`
|
|
120
|
+
- `provider:` explicit and detection disagrees → `Kernel#warn` one line (e.g. `vibe-sort: api_key looks like an anthropic key but provider is :openai`) and proceed with the explicit provider
|
|
121
|
+
- `provider:` explicit and detection returns `nil` → silent (unknown formats are normal: proxies, Azure, self-hosted gateways)
|
|
122
|
+
|
|
123
|
+
Providers ship multiple key formats concurrently (Google: classic `AIza…` and newer `AQ.…`; OpenAI: `sk-…` and `sk-proj-…`), and new formats appear without notice — another reason detection must stay a soft default, never validation. An unrecognized prefix simply means "no inference", not "bad key".
|
|
124
|
+
|
|
125
|
+
### Behavior Matrix
|
|
126
|
+
|
|
127
|
+
| `provider:` arg | Key prefix | Result |
|
|
128
|
+
|-----------------|-------------------|---------------------------------|
|
|
129
|
+
| omitted | `sk-ant-…` | `:anthropic` (detected) |
|
|
130
|
+
| omitted | unrecognized | `:openai` (unchanged fallback) |
|
|
131
|
+
| `:openai` | `sk-…` | `:openai`, no warning |
|
|
132
|
+
| `:openai` | `sk-ant-…` | `:openai`, one-line warning |
|
|
133
|
+
| `:groq` | unrecognized | `:groq`, no warning |
|
|
134
|
+
|
|
135
|
+
### Checklist
|
|
136
|
+
|
|
137
|
+
- [x] `lib/vibe_sort/key_detector.rb`
|
|
138
|
+
- [x] `Configuration`: `provider: nil` default, detection fallback, mismatch warning
|
|
139
|
+
- [x] `Client`: `provider: nil` default passthrough, doc examples updated
|
|
140
|
+
- [x] `spec/vibe_sort/key_detector_spec.rb` (each prefix, ordering — `sk-ant-` and `sk-or-` beat `sk-`, unknown → nil)
|
|
141
|
+
- [x] `configuration_spec.rb`: detection fallback, explicit-provider precedence, warning emission (capture stderr), unknown-key → `:openai`
|
|
142
|
+
- [x] README: "provider is optional — detected from your key" section
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Feature 3: `extra_params` Escape Hatch
|
|
147
|
+
|
|
148
|
+
### Design
|
|
149
|
+
|
|
150
|
+
One new optional config attribute, deep-merged into the request payload **last** so it can override anything:
|
|
151
|
+
|
|
152
|
+
```ruby
|
|
153
|
+
# Configuration
|
|
154
|
+
def initialize(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
In `Providers::Base`:
|
|
158
|
+
|
|
159
|
+
```ruby
|
|
160
|
+
def perform(array)
|
|
161
|
+
response = connection.post do |req|
|
|
162
|
+
req.body = deep_merge(build_payload(array), config.extra_params)
|
|
163
|
+
end
|
|
164
|
+
handle_response(response)
|
|
165
|
+
end
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
with a private `deep_merge` helper (recursive for nested hashes, e.g. Gemini's `generationConfig`; arrays and scalars replace).
|
|
169
|
+
|
|
170
|
+
### Decisions
|
|
171
|
+
|
|
172
|
+
- **Provider-native keys, no translation.** `{ max_tokens: 100 }` means what OpenAI/Groq/OpenRouter/xAI say it means; Gemini users write `{ generationConfig: { maxOutputTokens: 100 } }`. Documented explicitly.
|
|
173
|
+
- **Merged last** so users can override `response_format`, `temperature`, even `model` — full escape hatch semantics.
|
|
174
|
+
- **Symbol keys** in examples; deep_merge treats the hash as-is (payloads are built with symbol keys throughout).
|
|
175
|
+
|
|
176
|
+
### Checklist
|
|
177
|
+
|
|
178
|
+
- [x] `Configuration`: `extra_params` attr + default `{}`
|
|
179
|
+
- [x] `Client`: passthrough kwarg + doc example
|
|
180
|
+
- [x] `Base#perform`: merge step + `deep_merge` helper
|
|
181
|
+
- [x] Specs: merge adds new keys, overrides existing (`response_format`), deep-merges nested hashes, empty hash is a no-op (existing payload specs unchanged)
|
|
182
|
+
- [x] README: examples — `max_tokens` on OpenAI, `generationConfig` on Gemini, `provider` routing prefs on OpenRouter
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Compatibility Notes
|
|
187
|
+
|
|
188
|
+
- **Behavior change:** an Anthropic/Gemini/Groq/xAI/OpenRouter-prefixed key with **no** `provider:` argument previously hit the OpenAI API and failed; it now routes to the detected provider and works. Strictly an improvement, but observable — hence 0.4.0, not 0.3.2.
|
|
189
|
+
- Unrecognized keys with no `provider:` still default to `:openai` (unchanged).
|
|
190
|
+
- All existing explicit-provider call sites behave identically (worst case: a new one-line stderr warning on a mismatched key).
|
|
191
|
+
- No new runtime dependencies.
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Implementation Order
|
|
196
|
+
|
|
197
|
+
1. `extra_params` (self-contained, touches `Base` — land first so the OpenRouter spec can cover interplay)
|
|
198
|
+
2. OpenRouter provider
|
|
199
|
+
3. Key detection (depends on `:openrouter` existing for the `sk-or-` mapping)
|
|
200
|
+
4. Docs sweep: README, CHANGELOG, `docs/api_reference.md`, `docs/architecture.md` provider list
|
|
201
|
+
5. Version bump to 0.4.0
|
|
202
|
+
|
|
203
|
+
Each step is independently green (rubocop + rspec) and committable.
|
data/lib/vibe_sort/client.rb
CHANGED
|
@@ -35,9 +35,23 @@ module VibeSort
|
|
|
35
35
|
# model: 'meta-llama/llama-3.3-70b-instruct',
|
|
36
36
|
# extra_params: { max_tokens: 200 }
|
|
37
37
|
# )
|
|
38
|
-
|
|
38
|
+
#
|
|
39
|
+
# @example TypeSafe Jev (System One) with the pairwise merge-sort strategy
|
|
40
|
+
# client = VibeSort::Client.new(api_key: ENV['TYPESAFE_API_KEY'], provider: :jev, strategy: :noul)
|
|
41
|
+
#
|
|
42
|
+
# @example Jev through OpenRouter (an sk-or- key plus a jev model or a strategy: routes there)
|
|
43
|
+
# client = VibeSort::Client.new(api_key: ENV['OPENROUTER_API_KEY'], model: 'jev-latest')
|
|
44
|
+
#
|
|
45
|
+
# System One accepts extra keywords (+strategy:+, +by:+, +order:+, +long_context:+, ...), all
|
|
46
|
+
# of which can also be passed per call to #sort / #sort_with_metadata. +api_key+ may be omitted
|
|
47
|
+
# when TYPESAFE_API_KEY is set. See VibeSort::Providers::Jev for the full list.
|
|
48
|
+
#
|
|
49
|
+
# @param base_url [String, nil] System One gateway root override (Jev only)
|
|
50
|
+
def initialize(api_key: nil, temperature: 0.0, provider: nil, model: nil, extra_params: {}, base_url: nil, **jev_options)
|
|
51
|
+
validate_jev_options!(jev_options)
|
|
39
52
|
@config = Configuration.new(api_key: api_key, temperature: temperature, provider: provider, model: model,
|
|
40
|
-
extra_params: extra_params)
|
|
53
|
+
extra_params: extra_params, base_url: base_url, jev_options: jev_options)
|
|
54
|
+
reject_jev_options_for_llm!(jev_options)
|
|
41
55
|
end
|
|
42
56
|
|
|
43
57
|
# Sort an array of numbers and/or strings using the configured provider's API
|
|
@@ -68,20 +82,27 @@ module VibeSort
|
|
|
68
82
|
# result = client.sort([1, 2, 3]) # with invalid API key
|
|
69
83
|
# #=> { success: false, sorted_array: [], error: "OpenAI API error: Invalid API key" }
|
|
70
84
|
# # The error prefix names the configured provider (OpenAI, Anthropic, Gemini, ...)
|
|
71
|
-
|
|
72
|
-
|
|
85
|
+
#
|
|
86
|
+
# With a System One (Jev) provider the array may hold any objects (the originals are
|
|
87
|
+
# returned, never rebuilt from model text), an empty array is valid, and per-call
|
|
88
|
+
# options such as +strategy:+, +by:+ and +order:+ are accepted.
|
|
89
|
+
#
|
|
90
|
+
# @example Jev, descending, by a custom criterion
|
|
91
|
+
# client.sort(%w[ghost-pepper jalapeno habanero], by: "spiciness", order: :desc)
|
|
92
|
+
# #=> { success: true, sorted_array: ["ghost-pepper", "habanero", "jalapeno"] }
|
|
93
|
+
def sort(array, **options)
|
|
73
94
|
unless valid_input?(array)
|
|
74
95
|
return {
|
|
75
96
|
success: false,
|
|
76
97
|
sorted_array: [],
|
|
77
|
-
error: "Input must be an array of numbers or strings"
|
|
98
|
+
error: config.jev? ? "Input must be an array" : "Input must be an array of numbers or strings"
|
|
78
99
|
}
|
|
79
100
|
end
|
|
80
101
|
|
|
81
102
|
# Perform the sort via API
|
|
82
103
|
sorter = Sorter.new(config)
|
|
83
|
-
sorter.perform(array)
|
|
84
|
-
rescue ApiError => e
|
|
104
|
+
sorter.perform(array, **options)
|
|
105
|
+
rescue ApiError, ConfigurationError, BogoExhaustedError => e
|
|
85
106
|
{
|
|
86
107
|
success: false,
|
|
87
108
|
sorted_array: [],
|
|
@@ -95,14 +116,50 @@ module VibeSort
|
|
|
95
116
|
}
|
|
96
117
|
end
|
|
97
118
|
|
|
119
|
+
# Sort with a System One (Jev) provider and get the full picture back.
|
|
120
|
+
#
|
|
121
|
+
# Unlike #sort this raises on failure (VibeSort::ApiError subclasses,
|
|
122
|
+
# ConfigurationError, BogoExhaustedError) and returns a VibeSort::Result carrying the
|
|
123
|
+
# sorted items, resolved model, API call count, token usage, per-item scores /
|
|
124
|
+
# confidences / probabilities, and warnings.
|
|
125
|
+
#
|
|
126
|
+
# @param array [Array] any objects
|
|
127
|
+
# @param options [Hash] per-call System One options (+strategy:+, +by:+, +order:+, +rubric:+, ...)
|
|
128
|
+
# @return [VibeSort::Result]
|
|
129
|
+
#
|
|
130
|
+
# @example
|
|
131
|
+
# result = client.sort_with_metadata(%w[pizza kale cake], by: "tastiness", strategy: :score)
|
|
132
|
+
# result.items #=> ["kale", "pizza", "cake"]
|
|
133
|
+
# result.item_metadata #=> [{ index: 1, score: 1.2, confidence: 0.8, ... }, ...]
|
|
134
|
+
def sort_with_metadata(array, **options)
|
|
135
|
+
raise ArgumentError, "Input must be an array" unless array.is_a?(Array)
|
|
136
|
+
|
|
137
|
+
Sorter.new(config).perform_with_metadata(array, **options)
|
|
138
|
+
end
|
|
139
|
+
|
|
98
140
|
private
|
|
99
141
|
|
|
100
|
-
|
|
142
|
+
def validate_jev_options!(jev_options)
|
|
143
|
+
unknown = jev_options.keys - Providers::Jev::CLIENT_OPTIONS
|
|
144
|
+
return if unknown.empty?
|
|
145
|
+
|
|
146
|
+
raise ConfigurationError, "Unknown option(s): #{unknown.join(", ")}"
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
def reject_jev_options_for_llm!(jev_options)
|
|
150
|
+
return if config.jev? || jev_options.empty?
|
|
151
|
+
|
|
152
|
+
raise ConfigurationError, "#{jev_options.keys.join(", ")}: only supported by System One (:jev) providers, not :#{config.provider}"
|
|
153
|
+
end
|
|
154
|
+
|
|
155
|
+
# Validate the input array: Jev accepts any array; generative providers need a
|
|
156
|
+
# non-empty array of numbers and/or strings
|
|
101
157
|
#
|
|
102
158
|
# @param array [Object] Input to validate
|
|
103
159
|
# @return [Boolean] true if valid, false otherwise
|
|
104
160
|
def valid_input?(array)
|
|
105
161
|
return false unless array.is_a?(Array)
|
|
162
|
+
return true if config.jev?
|
|
106
163
|
return false if array.empty?
|
|
107
164
|
|
|
108
165
|
array.all? { |item| item.is_a?(Numeric) || item.is_a?(String) }
|