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.
@@ -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
@@ -0,0 +1,118 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "date"
4
+ require "time"
5
+
6
+ module VibeSort
7
+ module SystemOne
8
+ # Prepares arbitrary Ruby values for TypeSafe's strict JSON rules (no NaN or
9
+ # Infinity, valid UTF-8, nesting depth <= 64) without mutating the originals.
10
+ module Serializer
11
+ # TypeSafe rejects nesting deeper than 64; leave headroom for the wrapper keys
12
+ # vibe-sort adds around each value (state -> candidates -> i_0 -> ...).
13
+ MAX_DEPTH = 50
14
+ MAX_SAFE_INTEGER = (2**53) - 1
15
+ BOM = ""
16
+ CIRCULAR = "[Circular]"
17
+
18
+ module_function
19
+
20
+ # @param value [Object] any Ruby value
21
+ # @return [Object] a JSON-safe copy (Hash with String keys, Array, String, Integer, Float, true/false/nil)
22
+ def call(value)
23
+ serialize(value, 0, {})
24
+ end
25
+
26
+ def serialize(value, depth, stack)
27
+ case value
28
+ when nil, true, false then value
29
+ when String then clean_string(value)
30
+ when Symbol then clean_string(value.to_s)
31
+ when Integer then integer(value)
32
+ when Float then float(value)
33
+ when Hash, Array then container(value, depth, stack)
34
+ else scalar_or_object(value, depth, stack)
35
+ end
36
+ end
37
+
38
+ def integer(value)
39
+ value.abs > MAX_SAFE_INTEGER ? value.to_s : value
40
+ end
41
+
42
+ def float(value)
43
+ return "NaN" if value.nan?
44
+ return value.positive? ? "Infinity" : "-Infinity" if value.infinite?
45
+
46
+ value
47
+ end
48
+
49
+ def container(value, depth, stack)
50
+ id = value.object_id
51
+ return CIRCULAR if stack.key?(id)
52
+ return clean_string(value.inspect) if depth >= MAX_DEPTH
53
+
54
+ stack[id] = true
55
+ begin
56
+ if value.is_a?(Hash)
57
+ value.each_with_object({}) { |(k, v), out| out[clean_string(k.to_s)] = serialize(v, depth + 1, stack) }
58
+ else
59
+ value.map { |v| serialize(v, depth + 1, stack) }
60
+ end
61
+ ensure
62
+ stack.delete(id)
63
+ end
64
+ end
65
+
66
+ def scalar_or_object(value, depth, stack)
67
+ return big_decimal(value) if big_decimal?(value)
68
+ return clean_string(value.iso8601) if value.is_a?(Time) || value.is_a?(Date)
69
+ return clean_string(value.to_s) if value.is_a?(Numeric) # Rational, Complex, ...
70
+
71
+ if value.respond_to?(:to_h)
72
+ hash = begin
73
+ value.to_h
74
+ rescue StandardError
75
+ nil
76
+ end
77
+ return serialize(hash, depth, stack) if hash.is_a?(Hash)
78
+ end
79
+ clean_string(safe_to_s(value))
80
+ end
81
+
82
+ def big_decimal?(value)
83
+ defined?(::BigDecimal) && value.is_a?(::BigDecimal)
84
+ end
85
+
86
+ def big_decimal(value)
87
+ return "NaN" if value.nan?
88
+ return value.positive? ? "Infinity" : "-Infinity" if value.infinite?
89
+
90
+ value.to_s("F")
91
+ end
92
+
93
+ def safe_to_s(value)
94
+ value.to_s
95
+ rescue StandardError
96
+ value.inspect
97
+ end
98
+
99
+ # Strip a leading BOM and replace invalid/undefined byte sequences.
100
+ def clean_string(string)
101
+ utf8 = to_utf8(string)
102
+ utf8 = utf8.delete_prefix(BOM) if utf8.start_with?(BOM)
103
+ utf8
104
+ end
105
+
106
+ def to_utf8(string)
107
+ copy = if [Encoding::UTF_8, Encoding::BINARY].include?(string.encoding)
108
+ string.dup.force_encoding(Encoding::UTF_8)
109
+ else
110
+ string.encode("UTF-8", invalid: :replace, undef: :replace)
111
+ end
112
+ copy.scrub
113
+ rescue EncodingError
114
+ string.dup.force_encoding(Encoding::BINARY).force_encoding(Encoding::UTF_8).scrub
115
+ end
116
+ end
117
+ end
118
+ end
@@ -0,0 +1,127 @@
1
+ # frozen_string_literal: true
2
+
3
+ module VibeSort
4
+ module SystemOne
5
+ module Strategies
6
+ # Shared plumbing for the System One sorting strategies.
7
+ #
8
+ # Every strategy works on Entry structs (index + original object) and returns
9
+ # the original objects, so identity is preserved and nothing is ever rebuilt
10
+ # from model text. Only arrays of length 0 or 1 short-circuit; numbers and
11
+ # dates are deliberately NOT sorted with <=> (model jaggedness is a feature).
12
+ class Base
13
+ Entry = Struct.new(:index, :value, :serialized)
14
+
15
+ # Mutable per-sort accounting shared by the strategy and its helpers
16
+ attr_reader :warnings, :api_calls, :usage, :resolved_model
17
+
18
+ # @param client [SystemOne::Client]
19
+ # @param gateway [Symbol] :typesafe or :openrouter (reported in the Result)
20
+ # @param by [String, nil] sorting criterion
21
+ # @param order [Symbol] :asc or :desc
22
+ # @param options [Hash] strategy options (see subclasses)
23
+ def initialize(client:, gateway: nil, by: nil, order: :asc, **options)
24
+ @client = client
25
+ @gateway = gateway
26
+ @by = by
27
+ @order = validate_order(order)
28
+ @options = options
29
+ @warnings = []
30
+ @api_calls = 0
31
+ @usage = { input_tokens: 0, output_tokens: 0, cost: nil }
32
+ @resolved_model = nil
33
+ @metadata = {}
34
+ end
35
+
36
+ # @param array [Array] any objects
37
+ # @return [VibeSort::Result]
38
+ def sort(array)
39
+ entries = array.each_with_index.map { |value, i| Entry.new(i, value, Serializer.call(value)) }
40
+ sorted = entries.size <= 1 ? entries : perform(entries)
41
+ build_result(sorted)
42
+ end
43
+
44
+ def self.strategy_name
45
+ name.split("::").last.sub(/Sort\z/, "").downcase.to_sym
46
+ end
47
+
48
+ private
49
+
50
+ # @param _entries [Array<Entry>] two or more entries
51
+ # @return [Array<Entry>] the entries in sorted order
52
+ def perform(_entries)
53
+ raise NotImplementedError
54
+ end
55
+
56
+ def option(key)
57
+ @options.fetch(key)
58
+ end
59
+
60
+ def desc?
61
+ @order == :desc
62
+ end
63
+
64
+ def goal
65
+ @by || default_goal
66
+ end
67
+
68
+ def default_goal
69
+ desc? ? "natural descending order" : "natural ascending order"
70
+ end
71
+
72
+ def direction_label
73
+ desc? ? "highest / first to lowest / last" : "lowest / first to highest / last"
74
+ end
75
+
76
+ def record(entry, **data)
77
+ @metadata[entry.index] = (@metadata[entry.index] || {}).merge(data)
78
+ end
79
+
80
+ # Issue one System One request, accumulating usage and call counts.
81
+ #
82
+ # @return [Hash{String => Hash}] answers keyed by question id
83
+ def ask(state:, questions:)
84
+ response = @client.query(state: state, questions: questions)
85
+ @api_calls += 1
86
+ @resolved_model = response.model
87
+ tally_usage(response.usage)
88
+ response.answers
89
+ end
90
+
91
+ def tally_usage(raw)
92
+ @usage[:input_tokens] += raw["input_tokens"].to_i
93
+ @usage[:output_tokens] += raw["output_tokens"].to_i
94
+ cost = raw["cost"]
95
+ @usage[:cost] = (@usage[:cost] || 0.0) + cost.to_f if cost.is_a?(Numeric)
96
+ end
97
+
98
+ def answer_for(answers, id, type)
99
+ answer = answers[id]
100
+ raise ApiError, "System One response is missing a #{type.inspect} answer for question #{id.inspect}" unless answer.is_a?(Hash) && answer.key?(type)
101
+
102
+ answer
103
+ end
104
+
105
+ def build_result(sorted)
106
+ Result.new(
107
+ items: sorted.map(&:value),
108
+ strategy: self.class.strategy_name,
109
+ model: @resolved_model,
110
+ gateway: @gateway,
111
+ api_calls: @api_calls,
112
+ usage: @usage,
113
+ item_metadata: sorted.map { |e| { index: e.index }.merge(@metadata.fetch(e.index, {})) },
114
+ warnings: @warnings
115
+ )
116
+ end
117
+
118
+ def validate_order(order)
119
+ sym = order.to_s.to_sym
120
+ return sym if %i[asc desc].include?(sym)
121
+
122
+ raise ConfigurationError, "order: must be :asc or :desc, got #{order.inspect}"
123
+ end
124
+ end
125
+ end
126
+ end
127
+ end
@@ -0,0 +1,83 @@
1
+ # frozen_string_literal: true
2
+
3
+ module VibeSort
4
+ module SystemOne
5
+ module Strategies
6
+ # :bogo - Vibe Bogosort.
7
+ #
8
+ # Shuffle, then ask Jev whether the array "looks sorted". Stop when the
9
+ # probability clears +threshold+; otherwise give up after +max_attempts+ and
10
+ # return the most convincing shuffle (or raise, with strict: true).
11
+ #
12
+ # Options: max_attempts (Integer >= 1 or Float::INFINITY), threshold (0..1),
13
+ # strict (Boolean), rng (Random, for deterministic specs).
14
+ class BogoSort < Base
15
+ def initialize(**kwargs)
16
+ super
17
+ @max_attempts = @options.fetch(:max_attempts, 25)
18
+ @threshold = @options.fetch(:threshold, 0.90)
19
+ validate!
20
+ end
21
+
22
+ private
23
+
24
+ def validate!
25
+ raise ArgumentError, "max_attempts must be an Integer >= 1 (or Float::INFINITY)" unless @max_attempts == Float::INFINITY || (@max_attempts.is_a?(Integer) && @max_attempts >= 1)
26
+ return if @threshold.is_a?(Numeric) && @threshold.between?(0, 1)
27
+
28
+ raise ArgumentError, "threshold must be a number between 0 and 1"
29
+ end
30
+
31
+ def perform(entries)
32
+ rng = @options[:rng] || Random
33
+ best = entries
34
+ best_probability = -1.0
35
+ attempts = 0
36
+
37
+ while attempts < @max_attempts
38
+ attempts += 1
39
+ candidate = entries.shuffle(random: rng)
40
+ probability = sortedness(candidate)
41
+ if probability > best_probability
42
+ best = candidate
43
+ best_probability = probability
44
+ end
45
+ return finish(best, best_probability, attempts) if probability >= @threshold
46
+ end
47
+
48
+ give_up(best, best_probability, attempts)
49
+ end
50
+
51
+ def sortedness(candidate)
52
+ state = { "sorting_goal" => goal, "direction" => direction_label, "array" => candidate.map(&:serialized) }
53
+ answers = ask(state: state, questions: { "is_sorted" => question })
54
+ answer_for(answers, "is_sorted", "noul")["noul"].to_f
55
+ end
56
+
57
+ def question
58
+ {
59
+ "type" => "noul",
60
+ "instructions" => "Is `array` completely sorted from first element to last element according to " \
61
+ "`sorting_goal` (#{direction_label})?",
62
+ "criteria" => {
63
+ "true" => "Every element is in the correct sorted position with no out-of-order elements",
64
+ "false" => "At least one element is out of order"
65
+ }
66
+ }
67
+ end
68
+
69
+ def finish(best, probability, attempts)
70
+ best.each { |e| record(e, sortedness_probability: probability, attempts: attempts) }
71
+ best
72
+ end
73
+
74
+ def give_up(best, probability, attempts)
75
+ raise BogoExhaustedError.new(attempts: attempts, best_probability: probability) if @options[:strict]
76
+
77
+ @warnings << "Vibe bogosort hit its #{attempts}-attempt cap; returning the best shuffle (sortedness probability #{probability.round(3)})"
78
+ finish(best, probability, attempts)
79
+ end
80
+ end
81
+ end
82
+ end
83
+ end
@@ -0,0 +1,113 @@
1
+ # frozen_string_literal: true
2
+
3
+ module VibeSort
4
+ module SystemOne
5
+ module Strategies
6
+ # :choice - Draft Pick Selection Sort.
7
+ #
8
+ # Repeatedly asks Jev to pick which remaining item comes NEXT, so N items take
9
+ # N-1 calls. Items live in +state+ and the question's +criteria+ values are
10
+ # null, which keeps the per-option token cost low. Arrays above the 255-option
11
+ # limit are narrowed with tournament chunking before each pick.
12
+ #
13
+ # Options: shuffle_options (Boolean), rng (Random, for deterministic specs).
14
+ class ChoiceSort < Base
15
+ MAX_OPTIONS = 255
16
+ TAIL_SIZE = 5
17
+ CHUNKS_PER_REQUEST = 8
18
+
19
+ private
20
+
21
+ def perform(entries)
22
+ remaining = entries.to_h { |e| [key(e), e] }
23
+ sorted = []
24
+
25
+ while remaining.size > 1
26
+ winner_key, answer = pick_next(remaining, sorted)
27
+ entry = remaining.delete(winner_key)
28
+ record(entry, pick_round: sorted.size + 1, confidence: answer["confidence"],
29
+ probability: answer.dig("probabilities", winner_key))
30
+ sorted << entry
31
+ end
32
+ sorted << remaining.values.first
33
+ end
34
+
35
+ def key(entry)
36
+ "i_#{entry.index}"
37
+ end
38
+
39
+ def pick_next(remaining, sorted)
40
+ tail = sorted.last(TAIL_SIZE).map(&:serialized)
41
+ if remaining.size <= MAX_OPTIONS
42
+ ask_for_winner(remaining, tail)
43
+ else
44
+ tournament(remaining, tail)
45
+ end
46
+ end
47
+
48
+ # One choice question over <= 255 candidates held in state (null criteria).
49
+ def ask_for_winner(remaining, tail)
50
+ keys = shuffled(remaining.keys)
51
+ state = base_state(tail).merge("candidates" => keys.to_h { |k| [k, remaining[k].serialized] })
52
+ questions = { "pick_next" => choice_question(keys.to_h { |k| [k, nil] }) }
53
+ extract_winner(ask(state: state, questions: questions)["pick_next"], keys)
54
+ end
55
+
56
+ # Above 255 candidates: fan out one question per chunk of <= 255 (descriptions
57
+ # live in the criteria so each question only carries its own chunk), then run
58
+ # a final choice over the chunk winners.
59
+ def tournament(remaining, tail)
60
+ winners = shuffled(remaining.keys).each_slice(MAX_OPTIONS).each_slice(CHUNKS_PER_REQUEST).flat_map do |batch|
61
+ chunk_winners(batch, remaining, tail)
62
+ end
63
+ return winners.first if winners.size == 1
64
+
65
+ final = winners.to_h { |k| [k, remaining[k].serialized] }
66
+ answer = ask(state: base_state(tail), questions: { "pick_next" => choice_question(final) })["pick_next"]
67
+ extract_winner(answer, winners)
68
+ end
69
+
70
+ def chunk_winners(batch, remaining, tail)
71
+ questions = batch.each_with_index.to_h do |keys, i|
72
+ ["chunk_#{i}", choice_question(keys.to_h { |k| [k, remaining[k].serialized] })]
73
+ end
74
+ answers = ask(state: base_state(tail), questions: questions)
75
+ batch.each_with_index.map { |keys, i| extract_winner(answers["chunk_#{i}"], keys).first }
76
+ end
77
+
78
+ def base_state(tail)
79
+ { "sorting_goal" => goal, "direction" => direction_label, "already_selected_tail" => tail }
80
+ end
81
+
82
+ def choice_question(criteria)
83
+ {
84
+ "type" => "choice",
85
+ "instructions" => "Select the single candidate key that should come NEXT in the sorted order " \
86
+ "for `sorting_goal` (#{direction_label}).",
87
+ "criteria" => criteria
88
+ }
89
+ end
90
+
91
+ # @return [Array(String, Hash)] the winning key and its answer. Falls back to
92
+ # the most probable valid key if the model names an unknown one.
93
+ def extract_winner(answer, valid_keys)
94
+ raise ApiError, "System One response is missing a choice answer" unless answer.is_a?(Hash)
95
+
96
+ chosen = answer["choice"]
97
+ return [chosen, answer] if valid_keys.include?(chosen)
98
+
99
+ probabilities = answer["probabilities"].is_a?(Hash) ? answer["probabilities"] : {}
100
+ fallback = probabilities.slice(*valid_keys).max_by { |_, p| p.to_f }&.first
101
+ @warnings << "Jev picked an unknown candidate (#{chosen.inspect}); used #{fallback ? "its most probable valid option" : "the first option"}"
102
+ [fallback || valid_keys.first, answer]
103
+ end
104
+
105
+ def shuffled(keys)
106
+ return keys unless @options.fetch(:shuffle_options, true)
107
+
108
+ keys.shuffle(random: @options[:rng] || Random)
109
+ end
110
+ end
111
+ end
112
+ end
113
+ end