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
data/lib/vibe_sort/error.rb
CHANGED
|
@@ -14,4 +14,59 @@ module VibeSort
|
|
|
14
14
|
@response = response
|
|
15
15
|
end
|
|
16
16
|
end
|
|
17
|
+
|
|
18
|
+
# Spec-friendly alias: the gem has always spelled it +ApiError+
|
|
19
|
+
APIError = ApiError
|
|
20
|
+
|
|
21
|
+
# Raised for invalid or contradictory configuration. Subclasses ArgumentError so
|
|
22
|
+
# callers that already rescue ArgumentError from Client.new keep working.
|
|
23
|
+
class ConfigurationError < ArgumentError; end
|
|
24
|
+
|
|
25
|
+
# --- TypeSafe System One (Jev) errors ---
|
|
26
|
+
|
|
27
|
+
# HTTP 400 (other than context overflow) or 422: the request was malformed
|
|
28
|
+
class ValidationError < ApiError; end
|
|
29
|
+
|
|
30
|
+
# HTTP 400 +max_tokens_exceeded+: state + questions exceeded the context window
|
|
31
|
+
class ContextLengthError < ApiError; end
|
|
32
|
+
|
|
33
|
+
# Payload over TypeSafe's 32 MiB body limit (raised client-side, or on HTTP 413)
|
|
34
|
+
class PayloadTooLargeError < ApiError; end
|
|
35
|
+
|
|
36
|
+
# HTTP 401: invalid or missing API key
|
|
37
|
+
class AuthenticationError < ApiError; end
|
|
38
|
+
|
|
39
|
+
# HTTP 402 (OpenRouter): insufficient credits
|
|
40
|
+
class PaymentRequiredError < ApiError; end
|
|
41
|
+
|
|
42
|
+
# HTTP 403 with a JSON body
|
|
43
|
+
class AuthorizationError < ApiError; end
|
|
44
|
+
|
|
45
|
+
# HTTP 403 served as HTML by the Cloudflare edge (TypeSafe's WAF), usually because
|
|
46
|
+
# the sorted values look like shell commands or URLs.
|
|
47
|
+
class EdgeFirewallError < ApiError
|
|
48
|
+
attr_reader :cf_ray
|
|
49
|
+
|
|
50
|
+
def initialize(message, response = nil, cf_ray: nil)
|
|
51
|
+
super(message, response)
|
|
52
|
+
@cf_ray = cf_ray
|
|
53
|
+
end
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
# HTTP 429 after retries were exhausted
|
|
57
|
+
class RateLimitError < ApiError; end
|
|
58
|
+
|
|
59
|
+
# HTTP 529 after retries were exhausted
|
|
60
|
+
class OverloadedError < ApiError; end
|
|
61
|
+
|
|
62
|
+
# Raised by the :bogo strategy in strict mode when no shuffle clears the threshold
|
|
63
|
+
class BogoExhaustedError < StandardError
|
|
64
|
+
attr_reader :attempts, :best_probability
|
|
65
|
+
|
|
66
|
+
def initialize(attempts:, best_probability:)
|
|
67
|
+
@attempts = attempts
|
|
68
|
+
@best_probability = best_probability
|
|
69
|
+
super("Vibe bogosort gave up after #{attempts} attempts (best sortedness probability: #{best_probability.round(3)})")
|
|
70
|
+
end
|
|
71
|
+
end
|
|
17
72
|
end
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module VibeSort
|
|
4
|
+
# Best-effort provider inference from API key prefixes.
|
|
5
|
+
#
|
|
6
|
+
# Prefixes are conventions, not contracts — providers ship multiple key
|
|
7
|
+
# formats concurrently (Google: "AIza..." and "AQ...."; OpenAI: "sk-..."
|
|
8
|
+
# and "sk-proj-...") and new formats appear without notice. Detection is
|
|
9
|
+
# therefore only a soft default and a source of non-fatal mismatch
|
|
10
|
+
# warnings, never validation: an unrecognized prefix means "no inference",
|
|
11
|
+
# not "bad key".
|
|
12
|
+
module KeyDetector
|
|
13
|
+
# Ordered: more specific prefixes must come before "sk-"
|
|
14
|
+
PREFIXES = {
|
|
15
|
+
"sk-ant-" => :anthropic,
|
|
16
|
+
"sk-or-" => :openrouter,
|
|
17
|
+
"sk-" => :openai,
|
|
18
|
+
"gsk_" => :groq,
|
|
19
|
+
"AIza" => :gemini,
|
|
20
|
+
"AQ." => :gemini,
|
|
21
|
+
"xai-" => :spacexai
|
|
22
|
+
}.freeze
|
|
23
|
+
|
|
24
|
+
# @param api_key [String] API key to inspect
|
|
25
|
+
# @return [Symbol, nil] detected provider, or nil if the prefix is unrecognized
|
|
26
|
+
def self.detect(api_key)
|
|
27
|
+
PREFIXES.each { |prefix, provider| return provider if api_key.start_with?(prefix) }
|
|
28
|
+
nil
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
end
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module VibeSort
|
|
4
|
+
# Deterministic routing between the generative LLM providers and TypeSafe
|
|
5
|
+
# System One (Jev), over either gateway (TypeSafe Direct or OpenRouter).
|
|
6
|
+
#
|
|
7
|
+
# Priority order (first match wins):
|
|
8
|
+
# 1. provider: :jev/:typesafe + OpenRouter key -> Jev via OpenRouter
|
|
9
|
+
# 2. provider: :jev/:typesafe -> Jev via TypeSafe Direct
|
|
10
|
+
# 3. OpenRouter key + a jev model id -> Jev via OpenRouter
|
|
11
|
+
# 4. OpenRouter key + explicit strategy: -> Jev via OpenRouter
|
|
12
|
+
# 5. explicit provider, or a recognised key prefix -> existing LLM provider
|
|
13
|
+
# 6. no key, TYPESAFE_API_KEY set -> Jev via TypeSafe Direct
|
|
14
|
+
# 7. unrecognised key + jev model or strategy: -> Jev via TypeSafe Direct
|
|
15
|
+
# otherwise -> :openai (0.4.0 behaviour)
|
|
16
|
+
module ProviderResolver
|
|
17
|
+
JEV_PROVIDERS = %i[jev typesafe].freeze
|
|
18
|
+
OPENROUTER_BASE_URL = "https://openrouter.ai/api"
|
|
19
|
+
OPENROUTER_JEV_MODEL = "~typesafe/jev-latest"
|
|
20
|
+
TYPESAFE_JEV_MODEL = "jev-latest"
|
|
21
|
+
OPENROUTER_JEV_MODEL_PATTERN = %r{\A(~?typesafe/)?jev(-|\z)}i
|
|
22
|
+
STRATEGIES = %i[choice score noul bogo].freeze
|
|
23
|
+
|
|
24
|
+
Resolution = Struct.new(:provider, :gateway, :api_key, :base_url, :model, keyword_init: true) do
|
|
25
|
+
def jev?
|
|
26
|
+
provider == :jev
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
module_function
|
|
31
|
+
|
|
32
|
+
# @return [Resolution] +provider+ is :jev or one of Configuration::PROVIDERS
|
|
33
|
+
# @raise [ConfigurationError] for strategy: combined with a generative provider
|
|
34
|
+
def resolve(api_key:, provider: nil, model: nil, strategy: nil, base_url: nil, settings: VibeSort.settings)
|
|
35
|
+
key = clean(api_key)
|
|
36
|
+
explicit = provider&.to_s&.to_sym
|
|
37
|
+
openrouter_key = key&.start_with?("sk-or-") || false
|
|
38
|
+
strategy = validate_strategy!(strategy)
|
|
39
|
+
guard_strategy!(explicit, strategy)
|
|
40
|
+
|
|
41
|
+
return jev(key || settings.typesafe_api_key, base_url, model, settings, openrouter: openrouter_key) if JEV_PROVIDERS.include?(explicit)
|
|
42
|
+
|
|
43
|
+
return llm(key, explicit) if explicit
|
|
44
|
+
|
|
45
|
+
return jev(key, base_url, model, settings, openrouter: true) if openrouter_key && (jev_model_id?(model) || strategy)
|
|
46
|
+
return llm(key, nil) if key && KeyDetector.detect(key)
|
|
47
|
+
|
|
48
|
+
if key.nil?
|
|
49
|
+
env_key = settings.typesafe_api_key
|
|
50
|
+
return jev(env_key, base_url, model, settings, openrouter: false) if env_key
|
|
51
|
+
elsif strategy || model.to_s.downcase.start_with?("jev")
|
|
52
|
+
return jev(key, base_url, model, settings, openrouter: false)
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
llm(key, nil)
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
def jev(key, base_url, model, settings, openrouter:)
|
|
59
|
+
raise ConfigurationError, "API key cannot be nil or empty" if key.nil?
|
|
60
|
+
|
|
61
|
+
url = base_url || (openrouter ? OPENROUTER_BASE_URL : settings.typesafe_base_url)
|
|
62
|
+
gateway = url.to_s.include?("openrouter.ai") ? :openrouter : :typesafe
|
|
63
|
+
default_model = settings.jev_model || (gateway == :openrouter ? OPENROUTER_JEV_MODEL : TYPESAFE_JEV_MODEL)
|
|
64
|
+
Resolution.new(provider: :jev, gateway: gateway, api_key: key, base_url: url, model: model || default_model)
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
def llm(key, explicit)
|
|
68
|
+
raise ConfigurationError, "API key cannot be nil or empty" if key.nil?
|
|
69
|
+
|
|
70
|
+
Resolution.new(provider: explicit || KeyDetector.detect(key) || :openai, api_key: key, model: nil)
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
def jev_model_id?(model)
|
|
74
|
+
!model.nil? && OPENROUTER_JEV_MODEL_PATTERN.match?(model.to_s)
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
def validate_strategy!(strategy)
|
|
78
|
+
return nil if strategy.nil?
|
|
79
|
+
|
|
80
|
+
sym = strategy.to_s.to_sym
|
|
81
|
+
return sym if STRATEGIES.include?(sym)
|
|
82
|
+
|
|
83
|
+
raise ConfigurationError, "Unknown strategy: #{strategy.inspect} (supported: #{STRATEGIES.join(", ")})"
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
def guard_strategy!(explicit, strategy)
|
|
87
|
+
return unless strategy && explicit && !JEV_PROVIDERS.include?(explicit)
|
|
88
|
+
|
|
89
|
+
raise ConfigurationError,
|
|
90
|
+
"strategy: is only supported by System One (:jev) providers, not :#{explicit}"
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
def clean(value)
|
|
94
|
+
stripped = value&.to_s&.strip
|
|
95
|
+
stripped.nil? || stripped.empty? ? nil : stripped
|
|
96
|
+
end
|
|
97
|
+
end
|
|
98
|
+
end
|
|
@@ -25,7 +25,7 @@ module VibeSort
|
|
|
25
25
|
# @raise [VibeSort::ApiError] if the API request fails
|
|
26
26
|
def perform(array)
|
|
27
27
|
response = connection.post do |req|
|
|
28
|
-
req.body = build_payload(array)
|
|
28
|
+
req.body = deep_merge(build_payload(array), config.extra_params)
|
|
29
29
|
end
|
|
30
30
|
|
|
31
31
|
handle_response(response)
|
|
@@ -33,6 +33,20 @@ module VibeSort
|
|
|
33
33
|
|
|
34
34
|
private
|
|
35
35
|
|
|
36
|
+
# Merge the user's extra_params into the adapter payload last, so they can
|
|
37
|
+
# override anything (response_format, temperature, even model). Nested
|
|
38
|
+
# hashes merge recursively (e.g. Gemini's generationConfig); arrays and
|
|
39
|
+
# scalars replace.
|
|
40
|
+
#
|
|
41
|
+
# @param base [Hash] Adapter-built payload
|
|
42
|
+
# @param extra [Hash] User-supplied provider-native parameters
|
|
43
|
+
# @return [Hash] Merged payload
|
|
44
|
+
def deep_merge(base, extra)
|
|
45
|
+
base.merge(extra) do |_key, old_val, new_val|
|
|
46
|
+
old_val.is_a?(Hash) && new_val.is_a?(Hash) ? deep_merge(old_val, new_val) : new_val
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
|
|
36
50
|
# Model to use: explicit override from config, or the provider default
|
|
37
51
|
#
|
|
38
52
|
# @return [String] Model ID
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module VibeSort
|
|
4
|
+
module Providers
|
|
5
|
+
# Adapter for TypeSafe's Jev (System One) decision model. Unlike the generative
|
|
6
|
+
# providers it never writes an array: it answers typed questions about item
|
|
7
|
+
# indices, and the sorted result is assembled from the original objects.
|
|
8
|
+
class Jev
|
|
9
|
+
STRATEGIES = {
|
|
10
|
+
choice: SystemOne::Strategies::ChoiceSort,
|
|
11
|
+
score: SystemOne::Strategies::ScoreSort,
|
|
12
|
+
noul: SystemOne::Strategies::NoulSort,
|
|
13
|
+
bogo: SystemOne::Strategies::BogoSort
|
|
14
|
+
}.freeze
|
|
15
|
+
|
|
16
|
+
# Per-sort options accepted by #sort_with_metadata / #perform
|
|
17
|
+
SORT_OPTIONS = %i[by prompt order strategy rubric tie_break tie_epsilon confidence_floor max_attempts threshold
|
|
18
|
+
strict long_context shuffle_options rng].freeze
|
|
19
|
+
# Options that may also be set once on Client.new
|
|
20
|
+
CLIENT_OPTIONS = (SORT_OPTIONS + %i[max_retries timeout openrouter_referer openrouter_title sleeper]).freeze
|
|
21
|
+
|
|
22
|
+
attr_reader :config
|
|
23
|
+
|
|
24
|
+
# @param config [VibeSort::Configuration] resolved Jev configuration
|
|
25
|
+
def initialize(config)
|
|
26
|
+
@config = config
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
# Drop-in counterpart of the generative providers' #perform
|
|
30
|
+
#
|
|
31
|
+
# @return [Hash] { success: true, sorted_array: [...] }
|
|
32
|
+
def perform(array, **overrides)
|
|
33
|
+
{ success: true, sorted_array: sort_with_metadata(array, **overrides).items }
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# @return [VibeSort::Result]
|
|
37
|
+
def sort_with_metadata(array, **overrides)
|
|
38
|
+
opts = effective_options(overrides)
|
|
39
|
+
strategy = opts[:strategy].to_sym
|
|
40
|
+
klass = STRATEGIES.fetch(strategy) do
|
|
41
|
+
raise ConfigurationError, "Unknown strategy: #{strategy.inspect} (supported: #{STRATEGIES.keys.join(", ")})"
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
klass.new(client: build_client(opts), gateway: config.gateway, by: opts[:by] || opts[:prompt],
|
|
45
|
+
order: opts[:order] || :asc, **strategy_options(opts)).sort(array)
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
private
|
|
49
|
+
|
|
50
|
+
def effective_options(overrides)
|
|
51
|
+
unknown = overrides.keys - SORT_OPTIONS
|
|
52
|
+
raise ConfigurationError, "Unknown sort option(s): #{unknown.join(", ")}" unless unknown.empty?
|
|
53
|
+
|
|
54
|
+
VibeSort.settings.to_options.merge(config.jev_options).merge(overrides.compact)
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
def strategy_options(opts)
|
|
58
|
+
opts.slice(:rubric, :tie_break, :tie_epsilon, :confidence_floor, :max_attempts, :threshold,
|
|
59
|
+
:strict, :shuffle_options, :rng)
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
def build_client(opts)
|
|
63
|
+
SystemOne::Client.new(
|
|
64
|
+
api_key: config.api_key, base_url: config.base_url, model: config.model,
|
|
65
|
+
long_context: opts[:long_context], max_retries: opts[:max_retries], timeout: opts[:timeout],
|
|
66
|
+
referer: opts[:openrouter_referer], title: opts[:openrouter_title],
|
|
67
|
+
**opts.slice(:sleeper)
|
|
68
|
+
)
|
|
69
|
+
end
|
|
70
|
+
end
|
|
71
|
+
end
|
|
72
|
+
end
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module VibeSort
|
|
4
|
+
module Providers
|
|
5
|
+
# Adapter for the OpenRouter API (OpenAI-compatible Chat Completions)
|
|
6
|
+
class OpenRouter < OpenAI
|
|
7
|
+
ENDPOINT = "https://openrouter.ai/api/v1/chat/completions"
|
|
8
|
+
DEFAULT_MODEL = "openai/gpt-4o-mini"
|
|
9
|
+
|
|
10
|
+
private
|
|
11
|
+
|
|
12
|
+
def provider_name
|
|
13
|
+
"OpenRouter"
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
def endpoint
|
|
17
|
+
ENDPOINT
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
# Optional attribution headers recommended by OpenRouter
|
|
21
|
+
def headers
|
|
22
|
+
super.merge(
|
|
23
|
+
"HTTP-Referer" => "https://github.com/chayuto/vibe-sort",
|
|
24
|
+
"X-Title" => "vibe-sort"
|
|
25
|
+
)
|
|
26
|
+
end
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
end
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module VibeSort
|
|
4
|
+
# Value object returned by Client#sort_with_metadata for System One (Jev) providers.
|
|
5
|
+
#
|
|
6
|
+
# +items+ holds the original Ruby objects (same identities as the input), never
|
|
7
|
+
# values reconstructed from model output.
|
|
8
|
+
class Result
|
|
9
|
+
attr_reader :items, :strategy, :model, :gateway, :api_calls, :usage, :item_metadata, :warnings
|
|
10
|
+
|
|
11
|
+
def initialize(items:, strategy:, model: nil, gateway: nil, api_calls: 0, usage: nil, item_metadata: [], warnings: [])
|
|
12
|
+
@items = items
|
|
13
|
+
@strategy = strategy
|
|
14
|
+
@model = model
|
|
15
|
+
@gateway = gateway
|
|
16
|
+
@api_calls = api_calls
|
|
17
|
+
@usage = usage || { input_tokens: 0, output_tokens: 0, cost: nil }
|
|
18
|
+
@item_metadata = item_metadata
|
|
19
|
+
@warnings = warnings
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
def to_a
|
|
23
|
+
items
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def size
|
|
27
|
+
items.size
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
def to_h
|
|
31
|
+
{
|
|
32
|
+
items: items, strategy: strategy, model: model, gateway: gateway, api_calls: api_calls,
|
|
33
|
+
usage: usage, item_metadata: item_metadata, warnings: warnings
|
|
34
|
+
}
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
end
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module VibeSort
|
|
4
|
+
# Process-wide defaults for System One (Jev) sorting. Individual clients and
|
|
5
|
+
# individual sort calls override these.
|
|
6
|
+
#
|
|
7
|
+
# VibeSort.configure do |c|
|
|
8
|
+
# c.jev_max_retries = 5
|
|
9
|
+
# c.jev_long_context = true
|
|
10
|
+
# end
|
|
11
|
+
class Settings
|
|
12
|
+
DEFAULT_TYPESAFE_URL = "https://api.typesafe.ai"
|
|
13
|
+
|
|
14
|
+
attr_writer :typesafe_api_key, :typesafe_base_url
|
|
15
|
+
attr_accessor :jev_model, :jev_strategy, :jev_long_context, :jev_max_retries, :jev_timeout,
|
|
16
|
+
:jev_shuffle_options, :jev_tie_break, :jev_tie_epsilon, :jev_confidence_floor,
|
|
17
|
+
:jev_bogo_max_attempts, :jev_bogo_threshold, :openrouter_referer, :openrouter_title
|
|
18
|
+
|
|
19
|
+
def initialize
|
|
20
|
+
@typesafe_api_key = nil
|
|
21
|
+
@typesafe_base_url = nil
|
|
22
|
+
@jev_model = nil # nil = the gateway's own default (jev-latest / ~typesafe/jev-latest)
|
|
23
|
+
@jev_strategy = :choice
|
|
24
|
+
@jev_long_context = false
|
|
25
|
+
@jev_max_retries = 3
|
|
26
|
+
@jev_timeout = 30
|
|
27
|
+
@jev_shuffle_options = true
|
|
28
|
+
@jev_tie_break = true
|
|
29
|
+
@jev_tie_epsilon = 0.15
|
|
30
|
+
@jev_confidence_floor = 0.60
|
|
31
|
+
@jev_bogo_max_attempts = 25
|
|
32
|
+
@jev_bogo_threshold = 0.90
|
|
33
|
+
@openrouter_referer = nil
|
|
34
|
+
@openrouter_title = "vibe-sort"
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
# Falls back to ENV at read time so late-set environment variables are honoured.
|
|
38
|
+
def typesafe_api_key
|
|
39
|
+
blank_to_nil(@typesafe_api_key || ENV.fetch("TYPESAFE_API_KEY", nil))
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
def typesafe_base_url
|
|
43
|
+
blank_to_nil(@typesafe_base_url || ENV.fetch("TYPESAFE_BASE_URL", nil)) || DEFAULT_TYPESAFE_URL
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# @return [Hash] the per-sort option names used by the System One strategies
|
|
47
|
+
def to_options
|
|
48
|
+
{
|
|
49
|
+
strategy: jev_strategy, long_context: jev_long_context, max_retries: jev_max_retries,
|
|
50
|
+
timeout: jev_timeout, shuffle_options: jev_shuffle_options, tie_break: jev_tie_break,
|
|
51
|
+
tie_epsilon: jev_tie_epsilon, confidence_floor: jev_confidence_floor,
|
|
52
|
+
max_attempts: jev_bogo_max_attempts, threshold: jev_bogo_threshold,
|
|
53
|
+
openrouter_referer: openrouter_referer, openrouter_title: openrouter_title
|
|
54
|
+
}
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
private
|
|
58
|
+
|
|
59
|
+
def blank_to_nil(value)
|
|
60
|
+
stripped = value&.to_s&.strip
|
|
61
|
+
stripped.nil? || stripped.empty? ? nil : stripped
|
|
62
|
+
end
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
class << self
|
|
66
|
+
def settings
|
|
67
|
+
@settings ||= Settings.new
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
def configure
|
|
71
|
+
yield settings
|
|
72
|
+
settings
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
def reset_settings!
|
|
76
|
+
@settings = Settings.new
|
|
77
|
+
end
|
|
78
|
+
end
|
|
79
|
+
end
|
data/lib/vibe_sort/sorter.rb
CHANGED
|
@@ -8,7 +8,9 @@ module VibeSort
|
|
|
8
8
|
anthropic: Providers::Anthropic,
|
|
9
9
|
gemini: Providers::Gemini,
|
|
10
10
|
groq: Providers::Groq,
|
|
11
|
-
spacexai: Providers::SpaceXAI
|
|
11
|
+
spacexai: Providers::SpaceXAI,
|
|
12
|
+
openrouter: Providers::OpenRouter,
|
|
13
|
+
jev: Providers::Jev
|
|
12
14
|
}.freeze
|
|
13
15
|
|
|
14
16
|
attr_reader :config
|
|
@@ -23,10 +25,21 @@ module VibeSort
|
|
|
23
25
|
# Perform the sorting operation via the configured provider's API
|
|
24
26
|
#
|
|
25
27
|
# @param array [Array] Array of numbers and/or strings to sort
|
|
28
|
+
# @param options [Hash] System One (Jev) per-sort options; not accepted by generative providers
|
|
26
29
|
# @return [Hash] Result hash with :success, :sorted_array, and optional :error keys
|
|
27
30
|
# @raise [VibeSort::ApiError] if the API request fails
|
|
28
|
-
def perform(array)
|
|
29
|
-
PROVIDER_CLASSES.fetch(config.provider).new(config)
|
|
31
|
+
def perform(array, **options)
|
|
32
|
+
provider = PROVIDER_CLASSES.fetch(config.provider).new(config)
|
|
33
|
+
raise ConfigurationError, "#{options.keys.join(", ")}: only supported by System One (:jev) providers, not :#{config.provider}" unless options.empty? || config.jev?
|
|
34
|
+
|
|
35
|
+
options.empty? ? provider.perform(array) : provider.perform(array, **options)
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
# @return [VibeSort::Result] System One providers only
|
|
39
|
+
def perform_with_metadata(array, **options)
|
|
40
|
+
raise ConfigurationError, "sort_with_metadata requires a System One (:jev) provider, not :#{config.provider}" unless config.jev?
|
|
41
|
+
|
|
42
|
+
PROVIDER_CLASSES.fetch(:jev).new(config).sort_with_metadata(array, **options)
|
|
30
43
|
end
|
|
31
44
|
end
|
|
32
45
|
end
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module VibeSort
|
|
4
|
+
module SystemOne
|
|
5
|
+
# HTTP transport for TypeSafe's POST /v1/systemone, which is wire-compatible
|
|
6
|
+
# across TypeSafe Direct and OpenRouter.
|
|
7
|
+
class Client
|
|
8
|
+
MAX_BODY_BYTES = 32 * 1024 * 1024
|
|
9
|
+
RETRYABLE_STATUSES = [429, 524, 529].freeze
|
|
10
|
+
MAX_RETRY_AFTER = 30
|
|
11
|
+
LONG_CONTEXT_HEADER = "TypeSafe-Danger-Zone-Long-Context"
|
|
12
|
+
|
|
13
|
+
# Parsed System One response
|
|
14
|
+
Response = Struct.new(:model, :answers, :usage, keyword_init: true)
|
|
15
|
+
|
|
16
|
+
attr_reader :base_url, :model
|
|
17
|
+
|
|
18
|
+
# @param api_key [String] bearer token
|
|
19
|
+
# @param base_url [String] gateway root, e.g. https://api.typesafe.ai or https://openrouter.ai/api
|
|
20
|
+
# @param model [String] System One model id
|
|
21
|
+
# @param long_context [Boolean] opt in to the 262k context window
|
|
22
|
+
# @param max_retries [Integer] retries for 429/524/529 and transient network errors
|
|
23
|
+
# @param timeout [Numeric] per-request timeout in seconds
|
|
24
|
+
# @param referer [String, nil] OpenRouter HTTP-Referer attribution header
|
|
25
|
+
# @param title [String, nil] OpenRouter X-Title attribution header
|
|
26
|
+
# @param sleeper [#call] receives seconds to wait between retries (injectable for tests)
|
|
27
|
+
# @param jitter [#call] returns a multiplier in 0.5..1.0 for backoff (injectable for tests)
|
|
28
|
+
def initialize(api_key:, base_url:, model:, long_context: false, max_retries: 3, timeout: 30,
|
|
29
|
+
referer: nil, title: nil, sleeper: ->(seconds) { sleep(seconds) }, jitter: -> { rand(0.5..1.0) })
|
|
30
|
+
@api_key = api_key.to_s.strip
|
|
31
|
+
raise ConfigurationError, "API key cannot be nil or empty" if @api_key.empty?
|
|
32
|
+
|
|
33
|
+
@base_url = base_url
|
|
34
|
+
@model = model
|
|
35
|
+
@long_context = long_context
|
|
36
|
+
@max_retries = max_retries
|
|
37
|
+
@timeout = timeout
|
|
38
|
+
@referer = referer
|
|
39
|
+
@title = title
|
|
40
|
+
@sleeper = sleeper
|
|
41
|
+
@jitter = jitter
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def url
|
|
45
|
+
"#{base_url.to_s.sub(%r{/+\z}, "")}/v1/systemone"
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
# Ask one or more typed questions about a shared state.
|
|
49
|
+
#
|
|
50
|
+
# @param state [Object] anything JSON-serialisable (sanitised by Serializer)
|
|
51
|
+
# @param questions [Hash{String => Hash}] opaque question id => question
|
|
52
|
+
# @return [Response]
|
|
53
|
+
def query(state:, questions:)
|
|
54
|
+
body = JSON.generate(
|
|
55
|
+
"model" => model,
|
|
56
|
+
"state" => Serializer.call(state),
|
|
57
|
+
"questions" => Serializer.call(questions)
|
|
58
|
+
)
|
|
59
|
+
raise PayloadTooLargeError, "System One request is #{body.bytesize} bytes, over the 32 MiB limit" if body.bytesize > MAX_BODY_BYTES
|
|
60
|
+
|
|
61
|
+
parse(post_with_retries(body))
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
private
|
|
65
|
+
|
|
66
|
+
def post_with_retries(body)
|
|
67
|
+
attempt = 0
|
|
68
|
+
loop do
|
|
69
|
+
begin
|
|
70
|
+
response = connection.post(url, body)
|
|
71
|
+
rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
|
|
72
|
+
raise ApiError, "System One request failed: #{e.message}" if attempt >= @max_retries
|
|
73
|
+
|
|
74
|
+
wait(nil, attempt)
|
|
75
|
+
attempt += 1
|
|
76
|
+
next
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
return response if response.success?
|
|
80
|
+
|
|
81
|
+
if RETRYABLE_STATUSES.include?(response.status) && attempt < @max_retries
|
|
82
|
+
wait(response.headers["retry-after"], attempt)
|
|
83
|
+
attempt += 1
|
|
84
|
+
next
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
raise_for(response)
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
def wait(retry_after, attempt)
|
|
92
|
+
seconds = Float(retry_after, exception: false) if retry_after
|
|
93
|
+
seconds = (0.5 * (2**attempt)) * @jitter.call unless seconds && seconds >= 0 && seconds <= MAX_RETRY_AFTER
|
|
94
|
+
@sleeper.call(seconds)
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
def connection
|
|
98
|
+
@connection ||= Faraday.new do |f|
|
|
99
|
+
f.options.timeout = @timeout
|
|
100
|
+
f.options.open_timeout = @timeout
|
|
101
|
+
request_headers.each { |name, value| f.headers[name] = value }
|
|
102
|
+
f.adapter Faraday.default_adapter
|
|
103
|
+
end
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
def request_headers
|
|
107
|
+
headers = {
|
|
108
|
+
"Authorization" => "Bearer #{@api_key}",
|
|
109
|
+
"Content-Type" => "application/json",
|
|
110
|
+
"Accept" => "application/json",
|
|
111
|
+
"User-Agent" => "vibe-sort/#{VibeSort::VERSION} (Ruby/#{RUBY_VERSION})"
|
|
112
|
+
}
|
|
113
|
+
headers[LONG_CONTEXT_HEADER] = "true" if @long_context
|
|
114
|
+
if base_url.to_s.include?("openrouter.ai")
|
|
115
|
+
headers["HTTP-Referer"] = @referer if @referer
|
|
116
|
+
headers["X-Title"] = @title if @title
|
|
117
|
+
end
|
|
118
|
+
headers
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
def parse(response)
|
|
122
|
+
data = JSON.parse(response.body.to_s)
|
|
123
|
+
raise ApiError.new("System One returned an unexpected response shape", response) unless data.is_a?(Hash) && data["answers"].is_a?(Hash)
|
|
124
|
+
|
|
125
|
+
usage = data["usage"].is_a?(Hash) ? data["usage"] : {}
|
|
126
|
+
Response.new(model: data["model"] || model, answers: data["answers"], usage: usage)
|
|
127
|
+
rescue JSON::ParserError => e
|
|
128
|
+
raise ApiError.new("System One returned invalid JSON: #{e.message}", response)
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
def raise_for(response)
|
|
132
|
+
status = response.status
|
|
133
|
+
detail = error_detail(response)
|
|
134
|
+
message = "System One API error (HTTP #{status}): #{detail}"
|
|
135
|
+
|
|
136
|
+
case status
|
|
137
|
+
when 400 then raise_bad_request(message, response)
|
|
138
|
+
when 401 then raise AuthenticationError.new(message, response)
|
|
139
|
+
when 402 then raise PaymentRequiredError.new(message, response)
|
|
140
|
+
when 403 then raise_forbidden(message, response)
|
|
141
|
+
when 413 then raise PayloadTooLargeError.new(message, response)
|
|
142
|
+
when 422 then raise ValidationError.new(message, response)
|
|
143
|
+
when 429 then raise RateLimitError.new(message, response)
|
|
144
|
+
when 529 then raise OverloadedError.new(message, response)
|
|
145
|
+
else raise ApiError.new(message, response)
|
|
146
|
+
end
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
def raise_bad_request(message, response)
|
|
150
|
+
raise ContextLengthError.new("#{message}. Try `long_context: true` or sort fewer items at once.", response) if response.body.to_s.include?("max_tokens_exceeded")
|
|
151
|
+
|
|
152
|
+
raise ValidationError.new(message, response)
|
|
153
|
+
end
|
|
154
|
+
|
|
155
|
+
def raise_forbidden(message, response)
|
|
156
|
+
headers = response.headers
|
|
157
|
+
content_type = headers["content-type"].to_s
|
|
158
|
+
cf_ray = headers["cf-ray"]
|
|
159
|
+
if content_type.include?("text/html") || (cf_ray && !json?(response.body))
|
|
160
|
+
raise EdgeFirewallError.new(
|
|
161
|
+
"Blocked by the TypeSafe edge firewall (Cloudflare#{", cf-ray #{cf_ray}" if cf_ray}). " \
|
|
162
|
+
"This usually means a sorted value looks like a shell command or URL.",
|
|
163
|
+
response, cf_ray: cf_ray
|
|
164
|
+
)
|
|
165
|
+
end
|
|
166
|
+
|
|
167
|
+
raise AuthorizationError.new(message, response)
|
|
168
|
+
end
|
|
169
|
+
|
|
170
|
+
def json?(body)
|
|
171
|
+
JSON.parse(body.to_s)
|
|
172
|
+
true
|
|
173
|
+
rescue JSON::ParserError
|
|
174
|
+
false
|
|
175
|
+
end
|
|
176
|
+
|
|
177
|
+
def error_detail(response)
|
|
178
|
+
body = response.body.to_s
|
|
179
|
+
parsed = JSON.parse(body)
|
|
180
|
+
return body[0, 300] unless parsed.is_a?(Hash)
|
|
181
|
+
|
|
182
|
+
error = parsed["error"]
|
|
183
|
+
(error.is_a?(Hash) ? error["message"] : error) || parsed["message"] || body[0, 300]
|
|
184
|
+
rescue JSON::ParserError
|
|
185
|
+
body[0, 300]
|
|
186
|
+
end
|
|
187
|
+
end
|
|
188
|
+
end
|
|
189
|
+
end
|