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.
@@ -6,7 +6,7 @@ module VibeSort
6
6
  class Configuration
7
7
  PROVIDERS = %i[openai anthropic gemini groq spacexai openrouter].freeze
8
8
 
9
- attr_reader :api_key, :temperature, :provider, :model, :extra_params
9
+ attr_reader :api_key, :temperature, :provider, :model, :extra_params, :base_url, :gateway, :jev_options
10
10
 
11
11
  # Initialize a new Configuration
12
12
  #
@@ -19,19 +19,49 @@ module VibeSort
19
19
  # @param model [String, nil] Model ID override (nil uses the provider's default)
20
20
  # @param extra_params [Hash] Provider-native request parameters deep-merged into
21
21
  # the payload last, so they can override anything (e.g. { max_tokens: 100 })
22
+ # @param base_url [String, nil] System One gateway root (Jev only)
23
+ # @param jev_options [Hash] System One options (strategy:, long_context:, ...); see Providers::Jev
22
24
  # @raise [ArgumentError] if api_key is nil or empty, or provider is unknown
23
- def initialize(api_key:, temperature: 0.0, provider: nil, model: nil, extra_params: {})
24
- raise ArgumentError, "API key cannot be nil or empty" if api_key.nil? || api_key.empty?
25
-
26
- @provider = resolve_provider(provider, api_key)
27
- @api_key = api_key
25
+ # @raise [ConfigurationError] for contradictory options (e.g. strategy: with a generative provider)
26
+ def initialize(api_key: nil, temperature: 0.0, provider: nil, model: nil, extra_params: {}, base_url: nil, jev_options: {})
27
+ validate_provider_name!(provider)
28
+ resolution = ProviderResolver.resolve(api_key: api_key, provider: provider, model: model,
29
+ strategy: jev_options[:strategy], base_url: base_url)
28
30
  @temperature = temperature
29
- @model = model
30
31
  @extra_params = extra_params
32
+ @jev_options = jev_options
33
+ apply(resolution, provider, model)
34
+ end
35
+
36
+ # @return [Boolean] true when routed to TypeSafe System One (Jev)
37
+ def jev?
38
+ provider == :jev
31
39
  end
32
40
 
33
41
  private
34
42
 
43
+ def apply(resolution, requested_provider, model)
44
+ @api_key = resolution.api_key
45
+ @base_url = resolution.base_url
46
+ @gateway = resolution.gateway
47
+ if resolution.jev?
48
+ @provider = :jev
49
+ @model = resolution.model
50
+ else
51
+ @provider = resolve_provider(requested_provider, @api_key)
52
+ @model = model
53
+ end
54
+ end
55
+
56
+ def validate_provider_name!(provider)
57
+ return if provider.nil?
58
+
59
+ explicit = provider.to_s.to_sym
60
+ return if PROVIDERS.include?(explicit) || ProviderResolver::JEV_PROVIDERS.include?(explicit)
61
+
62
+ raise ArgumentError, "Unknown provider: #{provider.inspect} (supported: #{(PROVIDERS + ProviderResolver::JEV_PROVIDERS).join(", ")})"
63
+ end
64
+
35
65
  # Resolve the provider: explicit argument wins (with a non-fatal warning if the
36
66
  # key prefix suggests a different provider); otherwise infer from the key prefix,
37
67
  # defaulting to :openai for unrecognized formats.
@@ -45,8 +75,6 @@ module VibeSort
45
75
  return detected || :openai if provider.nil?
46
76
 
47
77
  explicit = provider.to_s.to_sym
48
- raise ArgumentError, "Unknown provider: #{provider.inspect} (supported: #{PROVIDERS.join(", ")})" unless PROVIDERS.include?(explicit)
49
-
50
78
  warn "vibe-sort: api_key format suggests :#{detected} but provider is :#{explicit}" if detected && detected != explicit
51
79
  explicit
52
80
  end
@@ -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
@@ -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
@@ -9,7 +9,8 @@ module VibeSort
9
9
  gemini: Providers::Gemini,
10
10
  groq: Providers::Groq,
11
11
  spacexai: Providers::SpaceXAI,
12
- openrouter: Providers::OpenRouter
12
+ openrouter: Providers::OpenRouter,
13
+ jev: Providers::Jev
13
14
  }.freeze
14
15
 
15
16
  attr_reader :config
@@ -24,10 +25,21 @@ module VibeSort
24
25
  # Perform the sorting operation via the configured provider's API
25
26
  #
26
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
27
29
  # @return [Hash] Result hash with :success, :sorted_array, and optional :error keys
28
30
  # @raise [VibeSort::ApiError] if the API request fails
29
- def perform(array)
30
- 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)
31
43
  end
32
44
  end
33
45
  end