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.
@@ -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
@@ -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).perform(array)
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