ruby_decision_model 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40caeb94a3a1a8365e7719753591173b6a8b89f8b0431579ac1df3f6b731caeb
-  data.tar.gz: 3fd04d44ed5083947c79921aa2fe2c05e9616294104e351ffbea3a47448e7dd7
+  metadata.gz: 2bea0fe1efb5046f07952098626ed15f1dcd28fc80f56fe1810b3a7cd1050bab
+  data.tar.gz: ebd51acc65df870cce1cd567033116d262424a2e38f3a86c41403c329a0dea31
 SHA512:
-  metadata.gz: dc8ba08eaf6fa210ef58809c7b3e8e585e835dc4bbaa09b7d65956b39d2168cd47d4812dabe7a6c72420fa93ebc0d9f2716e9d33a17d076f0a709ab5a573bd0c
-  data.tar.gz: 47260e6b68ae8bf8dafec39aae852460281d4423285116f33f8a097da0556e2f0a52327503964310018561e69a3f3cd66fc9b9cb5d51f2dbca6c1bd8c5f9a7c1
+  metadata.gz: 5f883f0e2cc526cdbf75b12632359670a70795caa030770c69b9c7af77ebc3cbe2054416f4900e3a5ed3773a507dc53246d1389e04714bc9e45d093b8b7184f8
+  data.tar.gz: b4fbb04f181c347fc28ae0c040da2f074d9ada571581cdb2c8d96097e43391d8955ab370dd3f09451ae1fe08a666b68881503ddadddca5979abf633f1b89faef

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.1.0 - 2026-09-18
+
+Provider-neutral release. One `Client`, two providers behind it.
+
+- Added `RubyDecisionModel::Providers` with `Base`, `OpenRouter`, and
+  `Typesafe`. A provider owns base URL, endpoint path, auth, default model,
+  model aliases, and usage parsing. `Client` delegates to it.
+- `Client.new` takes `provider:` (`:open_router`, `:typesafe`, or a
+  `Providers::Base` instance). With no provider and no `api_key:`, the
+  environment decides: `TYPESAFE_API_KEY` first, then `OPENROUTER_API_KEY`,
+  otherwise `ConfigurationError` naming both. `api_key:` alone still means
+  OpenRouter. `model:` defaults to the provider's model. `base_url:` overrides
+  the provider base. `client.provider` and `client.model` are readable.
+- Added `RubyDecisionModel.client`, a memoized default client, and
+  `RubyDecisionModel.client = nil` to reset it.
+- Model aliases: `jev` and `jev-latest` resolve to `typesafe/jev-1.13` on
+  OpenRouter; `typesafe/jev-1.13` and `jev` resolve to `jev-latest` on
+  Typesafe. Other names pass through.
+- Both providers send `User-Agent: ruby_decision_model/<version>`.
+- Added `RubyDecisionModel::RetryPolicy` matching the official Typesafe SDKs:
+  `max_retries: 2`, exponential backoff from 0.5s capped at 5s with 25%
+  jitter, retry on 408, 429, and 5xx, `Retry-After` and `retry-after-ms`
+  honored up to 60s, connection errors and timeouts retried, and a
+  `total_timeout: 30.0` budget across attempts and delays. `Client` accepts
+  `retry:` as a policy or a Hash of overrides. Jitter uses an injectable
+  `random:`. Invalid settings raise `ConfigurationError` at construction.
+- Transport contract now returns `[status, body, headers]`. Two-element
+  returns are still accepted.
+- Added `Response#request_id` (from `x-typesafe-request-id`, nil on
+  OpenRouter) and `Response#nouls`, `#choices`, `#scores`.
+- Added `UnprocessableEntity` (422) and `Overloaded` (529). `ApiError` now
+  carries `#headers`.
+- Usage `cost` is `nil` on Typesafe, which does not report it.
+- `Client::DEFAULT_BASE_URL`, `DEFAULT_MODEL`, `MAX_ATTEMPTS`, `RETRYABLE_STATUSES`,
+  and `RETRYABLE_EXCEPTIONS` remain as compatibility aliases. They now read from
+  the OpenRouter provider and the default `RetryPolicy`, so `MAX_ATTEMPTS` is 3
+  and `RETRYABLE_STATUSES` covers 408, 429, and every 5xx.
+
 ## 0.0.1 - 2026-09-18
 
 Initial release. Client and question builders for OpenRouter's `/decisions`

data/README.md

@@ -1,8 +1,10 @@
 # ruby_decision_model
 
-Decision models answer typed questions about a state with calibrated probabilities,
-instead of generating text. This gem is a dependency-free Ruby client for them,
-starting with OpenRouter's `/decisions` endpoint and Typesafe Jev.
+The decision-model interface for Ruby. Decision models answer typed questions
+about a state with calibrated probabilities instead of generating text. This gem
+talks to them through one `Client` with a provider behind it: OpenRouter by
+default, Typesafe's native API as a second door, more providers as labs ship
+them. No runtime dependencies beyond the standard library.
 
 ## Install
 
@@ -10,12 +12,12 @@ starting with OpenRouter's `/decisions` endpoint and Typesafe Jev.
 gem "ruby_decision_model"
 ```
 
-## Usage
+## Quick start
 
 ```ruby
 require "ruby_decision_model"
 
-client = RubyDecisionModel::Client.new(api_key: ENV["OPENROUTER_API_KEY"])
+client = RubyDecisionModel::Client.new
 
 response = client.ask(
   state: { title: "Server returns 500 on checkout", reporter: "support" },
@@ -30,20 +32,157 @@ response = client.ask(
 
 response["urgent"].noul       # => 0.87
 response["severity"].score    # => 2.4
-response.usage.cost           # => 0.0012
+response.usage.input_tokens   # => 120
 ```
 
+`Client.new` with no arguments reads the environment: `TYPESAFE_API_KEY` selects
+Typesafe, otherwise `OPENROUTER_API_KEY` selects OpenRouter. With neither set it
+raises `ConfigurationError` naming both. `RubyDecisionModel.client` memoizes one
+such default client; assign `nil` to reset it.
+
+## Providers
+
+### OpenRouter (default)
+
+```ruby
+# ENV["OPENROUTER_API_KEY"]
+client = RubyDecisionModel::Client.new(provider: :open_router)
+
+# or pass the key directly; api_key: alone still means OpenRouter
+client = RubyDecisionModel::Client.new(api_key: "sk-or-...")
+```
+
+Requests go to `https://openrouter.ai/api/alpha/decisions`. The default model is
+`typesafe/jev-1.13`. Usage reports `input_tokens`, `output_tokens`, and `cost`.
+
+### Typesafe native API
+
+```ruby
+# ENV["TYPESAFE_API_KEY"]
+client = RubyDecisionModel::Client.new(provider: :typesafe)
+```
+
+Requests go to `https://api.typesafe.ai/v1/systemone`. The default model is
+`jev-latest`. Usage reports `input_tokens` and `output_tokens`; `cost` is `nil`.
+Typesafe returns an `x-typesafe-request-id` header, exposed as
+`response.request_id` (nil on OpenRouter). Quote it when reporting a problem
+to Typesafe.
+
+### Options
+
+```ruby
+RubyDecisionModel::Client.new(
+  provider: :typesafe,        # :open_router, :typesafe, or a Providers::Base instance
+  api_key: nil,               # overrides the provider's env var
+  model: nil,                 # nil means the provider default; see aliases below
+  base_url: nil,              # overrides the provider base URL
+  timeout: 5,                 # open and read timeout in seconds
+  retry: { max_retries: 2 },  # RetryPolicy or a Hash of overrides
+  transport: nil              # see Transport
+)
+
+client.provider   # => #<RubyDecisionModel::Providers::Typesafe ...>
+client.model      # => "jev-latest" (resolved after aliasing)
+```
+
+Both providers send `User-Agent: ruby_decision_model/<version>`.
+
+### Model aliases
+
+Each provider resolves a few friendly names to its own canonical model name.
+Anything not listed passes through untouched. The `model` field on a response
+is whatever the provider returned.
+
+| You pass | OpenRouter sends | Typesafe sends |
+| --- | --- | --- |
+| `nil` | `typesafe/jev-1.13` | `jev-latest` |
+| `"jev"` | `typesafe/jev-1.13` | `jev-latest` |
+| `"jev-latest"` | `typesafe/jev-1.13` | `jev-latest` |
+| `"typesafe/jev-1.13"` | `typesafe/jev-1.13` | `jev-latest` |
+| anything else | as given | as given |
+
+### Writing a provider
+
+Subclass `RubyDecisionModel::Providers::Base` and define `name`, `env_var`,
+`default_base_url`, `endpoint_path`, `default_model`, and optionally `aliases`
+and `reports_cost?`. Override `headers`, `request_body`, or `usage` when the
+wire format differs. Pass an instance as `provider:`.
+
+## Questions and answers
+
+Three question types, built with `RubyDecisionModel::Questions`:
+
+```ruby
+Questions.noul("Is this spam?")                                  # yes/no probability
+Questions.choice("Which team?", criteria: { "billing" => "...", "auth" => "..." })  # up to 255 options
+Questions.score("How severe?", criteria: ["cosmetic", "minor", "major"])            # 2 to 10 levels
+```
+
+Answers come back typed: `Answers::Noul` (`noul`, `probabilities`),
+`Answers::Choice` (`choice`, `confidence`, `probabilities`), and
+`Answers::Score` (`score`, `confidence`, `probabilities`, `legend`).
+`response.nouls`, `response.choices`, and `response.scores` return the answers
+of one type keyed the same way as `response.answers`.
+
+Score `probabilities` and `legend` are keyed by the wire's string level keys
+(`"0"`, `"1"`, ...), not by the criteria labels. Choice `probabilities` sum to
+approximately 1; treat them as calibrated, not normalized.
+
+## Retries
+
+Retry behaviour follows the official Typesafe SDKs and lives in
+`RubyDecisionModel::RetryPolicy`. Pass a policy or a Hash of overrides as
+`retry:`.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `max_retries` | `2` | Retries after the initial attempt |
+| `backoff_initial` | `0.5` | First backoff in seconds, doubling each retry |
+| `backoff_max` | `5.0` | Backoff ceiling in seconds |
+| `backoff_jitter` | `0.25` | Fraction of the backoff randomly subtracted |
+| `http_statuses` | `[408, 429] + (500..599)` | Statuses that trigger a retry |
+| `respect_retry_after` | `true` | Honor `Retry-After` and `retry-after-ms` |
+| `max_retry_after` | `60.0` | Ceiling for a server-supplied delay |
+| `retry_connection_errors` | `true` | Retry socket and connection failures |
+| `retry_timeouts` | `true` | Retry open and read timeouts |
+| `total_timeout` | `30.0` | Budget in seconds across attempts and delays; `nil` disables |
+
+When the next delay would push past `total_timeout`, the client stops and
+raises the last error instead of sleeping. The budget governs whether another
+attempt starts; an attempt already in flight still runs to its own `timeout`.
+
+Invalid settings (a negative duration, a non-integer `max_retries`, a jitter
+outside 0..1, a NaN budget) raise `ConfigurationError` when the client is built.
+
+```ruby
+RubyDecisionModel::Client.new(retry: { max_retries: 4, total_timeout: 60.0 })
+RubyDecisionModel::Client.new(retry: RubyDecisionModel::RetryPolicy.new(max_retries: 0))
+```
+
+## Transport
+
+The client uses `Net::HTTP` by default. Inject `transport:` with any callable
+that accepts `url:`, `headers:`, `body:` and returns
+`[status, body_string, headers_hash]`. A two-element `[status, body_string]`
+return is still accepted and treated as having no headers, which means no
+`Retry-After` support and a nil `request_id`.
+
 ## Errors
 
 | Error | Meaning |
 | --- | --- |
-| `ConfigurationError` | Missing api_key, model, or base_url |
+| `ConfigurationError` | No provider could be resolved, missing api_key, unknown provider, or bad `retry:` value |
 | `RequestError` | Questions hash was empty |
-| `TransportError` (`TimeoutError`) | Network or timeout failure |
-| `ApiError` (`Unauthorized`, `PayloadTooLarge`, `RateLimited`) | Non-2xx response, carries `#status` and `#body` |
+| `TransportError` (`TimeoutError`) | Network or timeout failure after retries, carries `#cause_error` |
+| `ApiError` | Non-2xx response, carries `#status`, `#body`, and `#headers` |
+| `Unauthorized` | 401 |
+| `PayloadTooLarge` | 413 |
+| `UnprocessableEntity` | 422 (never retried) |
+| `RateLimited` | 429 (retried) |
+| `Overloaded` | 529 (retried) |
 | `InvalidResponse` | Body wasn't JSON, wasn't a Hash, or an answer was malformed |
 | `MissingAnswers` | One or more question ids came back missing or wrong-typed, carries `#missing` |
 
-Status: 0.0.1, API may change.
+Status: 0.1.0, API may change.
 
-The companion gem `ruby_dm` builds decisions and verdicts on top of this client.
+The companion gem `decide` builds decisions and verdicts on top of this client.

data/lib/ruby_decision_model/client.rb

@@ -2,54 +2,92 @@
 
 require "json"
 require "net/http"
+require "openssl"
 require "uri"
 
 module RubyDecisionModel
   class Client
-    DEFAULT_BASE_URL = "https://openrouter.ai/api/alpha"
-    DEFAULT_MODEL = "typesafe/jev-1.13"
-    MAX_ATTEMPTS = 2
-    RETRYABLE_STATUSES = [429, 500, 502, 503, 504, 524, 529].freeze
-    RETRYABLE_EXCEPTIONS = [
-      Net::OpenTimeout,
-      Net::ReadTimeout,
-      Errno::ECONNRESET,
-      Errno::ECONNREFUSED,
-      Errno::EPIPE,
-      SocketError,
-      IOError
-    ].freeze
-
-    def initialize(api_key:, model: DEFAULT_MODEL, base_url: DEFAULT_BASE_URL, timeout: 5,
-                    transport: nil, sleeper: ->(seconds) { sleep(seconds) })
-      raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.to_s.strip.empty?
-      raise ConfigurationError, "model is required" if model.nil? || model.to_s.strip.empty?
-      raise ConfigurationError, "base_url is required" if base_url.nil? || base_url.to_s.strip.empty?
-
-      @api_key = api_key
-      @model = model
-      @base_url = base_url.to_s.chomp("/")
+    REQUEST_ID_HEADER = "x-typesafe-request-id"
+
+    # Kept from 0.0.1 for callers that referenced them. They describe the
+    # OpenRouter provider and the default RetryPolicy; prefer those directly.
+    DEFAULT_BASE_URL = Providers::OpenRouter.new.default_base_url
+    DEFAULT_MODEL = Providers::OpenRouter.new.default_model
+    MAX_ATTEMPTS = RetryPolicy.new.max_retries + 1
+    RETRYABLE_STATUSES = RetryPolicy::DEFAULT_STATUSES
+    RETRYABLE_EXCEPTIONS = (RetryPolicy::TIMEOUT_EXCEPTIONS + RetryPolicy::CONNECTION_EXCEPTIONS).freeze
+
+    attr_reader :provider, :model, :retry_policy, :timeout
+
+    # provider:  :open_router, :typesafe, or a Providers::Base instance. When
+    #            nil, api_key: alone selects OpenRouter; otherwise the
+    #            environment decides (TYPESAFE_API_KEY, then OPENROUTER_API_KEY).
+    # api_key:   overrides the provider's env var.
+    # model:     nil means the provider default; aliases resolve per provider.
+    # base_url:  overrides the provider base URL.
+    # transport: callable(url:, headers:, body:) returning
+    #            [status, body_string, headers_hash] (a 2-element return is
+    #            still accepted and treated as having no headers).
+    # retry:     a RetryPolicy or a Hash of overrides.
+    # random:    callable returning a Float in 0...1, used for backoff jitter.
+    # clock:     callable returning monotonic seconds, used for total_timeout.
+    def initialize(provider: nil, api_key: nil, model: nil, base_url: nil, timeout: 5,
+                   transport: nil, sleeper: ->(seconds) { sleep(seconds) }, retry: {},
+                   random: -> { rand }, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @provider = resolve_provider(provider, api_key: api_key, base_url: base_url)
+      unless @provider.api_key?
+        raise ConfigurationError,
+              "api_key is required for #{@provider.name}: pass api_key: or set #{@provider.env_var}"
+      end
+
+      @model = @provider.resolve_model(model)
       @timeout = timeout
       @transport = transport || default_transport
       @sleeper = sleeper
+      @retry_policy = RetryPolicy.from(binding.local_variable_get(:retry))
+      @random = random
+      @clock = clock
+    end
+
+    def base_url
+      @provider.base_url
     end
 
     def ask(state:, questions:)
       raise RequestError, "questions must not be empty" if questions.nil? || questions.empty?
 
-      body = JSON.generate({ "model" => @model, "state" => state, "questions" => questions })
-      headers = {
-        "Authorization" => "Bearer #{@api_key}",
-        "Content-Type" => "application/json",
-        "Accept" => "application/json"
-      }
-
-      status, response_body = perform_with_retry(url: "#{@base_url}/decisions", headers: headers, body: body)
-      handle_response(status, response_body, questions)
+      body = @provider.request_body(model: @model, state: state, questions: questions)
+      status, response_body, response_headers = perform_with_retry(
+        url: @provider.url, headers: @provider.headers, body: body
+      )
+      handle_response(status, response_body, response_headers, questions)
     end
 
     private
 
+    def resolve_provider(provider, api_key:, base_url:)
+      case provider
+      when Providers::Base
+        return provider if api_key.nil? && base_url.nil?
+
+        # Never mutate a provider the caller may share between clients.
+        provider.dup.configure(api_key: api_key, base_url: base_url)
+      when Symbol, String
+        Providers.build(provider, api_key: api_key, base_url: base_url)
+      when nil
+        if api_key.nil?
+          Providers.from_env&.configure(base_url: base_url) || raise(
+            ConfigurationError,
+            "no provider configured: pass provider: or api_key:, or set one of #{Providers.env_vars.join(', ')}"
+          )
+        else
+          Providers.build(:open_router, api_key: api_key, base_url: base_url)
+        end
+      else
+        raise ConfigurationError, "provider must be a Symbol or a Providers::Base, got #{provider.class}"
+      end
+    end
+
     def default_transport
       lambda do |url:, headers:, body:|
         uri = URI.parse(url)
@@ -63,64 +101,93 @@ module RubyDecisionModel
         request.body = body
 
         response = http.request(request)
-        [response.code.to_i, response.body]
+        [response.code.to_i, response.body, response.each_header.to_h]
       end
     end
 
     def perform_with_retry(url:, headers:, body:)
-      attempts = 0
+      policy = @retry_policy
+      started_at = @clock.call
+      retries = 0
 
       loop do
-        attempts += 1
         begin
-          status, response_body = @transport.call(url: url, headers: headers, body: body)
-        rescue *RETRYABLE_EXCEPTIONS => e
-          raise_transport_error(e) if attempts >= MAX_ATTEMPTS
-
-          @sleeper.call(backoff_seconds)
-          next
+          status, response_body, response_headers = normalize_transport_result(
+            @transport.call(url: url, headers: headers, body: body)
+          )
         rescue Error
           raise
         rescue StandardError => e
-          raise_transport_error(e)
+          raise_transport_error(e) unless policy.retryable_exception?(e) && retries < policy.max_retries
+
+          delay = policy.backoff(retries, random: @random)
+          raise_transport_error(e) if budget_exceeded?(policy, started_at, delay)
+
+          @sleeper.call(delay)
+          raise_transport_error(e) if budget_exceeded?(policy, started_at, 0.0)
+
+          retries += 1
+          next
         end
 
-        return [status, response_body] unless RETRYABLE_STATUSES.include?(status) && attempts < MAX_ATTEMPTS
+        result = [status, response_body, response_headers]
+        return result unless policy.retryable_status?(status) && retries < policy.max_retries
+
+        delay = policy.delay(retries, headers: response_headers, random: @random)
+        return result if budget_exceeded?(policy, started_at, delay)
 
-        @sleeper.call(backoff_seconds)
+        @sleeper.call(delay)
+        return result if budget_exceeded?(policy, started_at, 0.0)
+
+        retries += 1
       end
     end
 
-    def backoff_seconds
-      0.5 + (rand * 0.25)
+    def budget_exceeded?(policy, started_at, delay)
+      return false if policy.total_timeout.nil?
+
+      (@clock.call - started_at) + delay > policy.total_timeout
+    end
+
+    def normalize_transport_result(result)
+      status, response_body, response_headers = Array(result)
+      [status, response_body, response_headers.is_a?(Hash) ? response_headers : {}]
     end
 
     def raise_transport_error(exception)
-      if exception.is_a?(Net::OpenTimeout) || exception.is_a?(Net::ReadTimeout)
+      if @retry_policy.timeout_exception?(exception)
         raise TimeoutError.new("request timed out: #{exception.message}", cause_error: exception)
       end
 
       raise TransportError.new("transport error: #{exception.message}", cause_error: exception)
     end
 
-    def handle_response(status, response_body, questions)
+    def handle_response(status, response_body, response_headers, questions)
       case status
       when 200..299
-        parse_success(response_body, questions)
+        parse_success(response_body, response_headers, questions)
       when 401
-        raise Unauthorized.new("unauthorized", status: status, body: response_body)
+        raise Unauthorized.new("unauthorized", status: status, body: response_body, headers: response_headers)
       when 413
-        raise PayloadTooLarge.new("payload too large", status: status, body: response_body)
+        raise PayloadTooLarge.new("payload too large", status: status, body: response_body, headers: response_headers)
+      when 422
+        raise UnprocessableEntity.new("unprocessable entity", status: status, body: response_body,
+                                                              headers: response_headers)
       when 429
-        raise RateLimited.new("rate limited", status: status, body: response_body)
+        raise RateLimited.new("rate limited", status: status, body: response_body, headers: response_headers)
+      when 529
+        raise Overloaded.new("overloaded", status: status, body: response_body, headers: response_headers)
       else
-        raise ApiError.new("api error (status #{status})", status: status, body: response_body)
+        raise ApiError.new("api error (status #{status})", status: status, body: response_body,
+                                                            headers: response_headers)
       end
     end
 
-    def parse_success(response_body, questions)
+    def parse_success(response_body, response_headers, questions)
+      raise InvalidResponse, "response body was empty" if response_body.nil? || response_body.to_s.strip.empty?
+
       parsed = begin
-        JSON.parse(response_body)
+        JSON.parse(response_body.to_s)
       rescue JSON::ParserError => e
         raise InvalidResponse, "response body was not valid JSON: #{e.message}"
       end
@@ -167,13 +234,25 @@ module RubyDecisionModel
 
       Response.new(
         answers: normalized,
-        usage: normalize_usage(parsed["usage"]),
+        usage: @provider.usage(parsed),
         model: parsed["model"],
         id: parsed["id"],
-        raw: parsed
+        raw: parsed,
+        request_id: request_id_from(response_headers)
       )
     end
 
+    def request_id_from(headers)
+      return nil unless headers.is_a?(Hash)
+
+      headers.each do |key, value|
+        next unless key.to_s.casecmp?(REQUEST_ID_HEADER)
+
+        return value.is_a?(Array) ? value.first : value
+      end
+      nil
+    end
+
     class MalformedAnswer < StandardError; end
 
     def normalize_answer(type, hash)
@@ -218,15 +297,5 @@ module RubyDecisionModel
     def hash_or_empty(value)
       value.is_a?(Hash) ? value : {}
     end
-
-    def normalize_usage(usage)
-      usage = {} unless usage.is_a?(Hash)
-
-      Response::Usage.new(
-        input_tokens: Integer(usage["input_tokens"], exception: false),
-        output_tokens: Integer(usage["output_tokens"], exception: false),
-        cost: Float(usage["cost"], exception: false)
-      )
-    end
   end
 end

data/lib/ruby_decision_model/errors.rb

@@ -19,12 +19,13 @@ module RubyDecisionModel
   class TimeoutError < TransportError; end
 
   class ApiError < Error
-    attr_reader :status, :body
+    attr_reader :status, :body, :headers
 
-    def initialize(message, status:, body:)
+    def initialize(message, status:, body:, headers: {})
       super(message)
       @status = status
       @body = body
+      @headers = headers || {}
     end
   end
 
@@ -32,8 +33,12 @@ module RubyDecisionModel
 
   class PayloadTooLarge < ApiError; end
 
+  class UnprocessableEntity < ApiError; end
+
   class RateLimited < ApiError; end
 
+  class Overloaded < ApiError; end
+
   class InvalidResponse < Error
     attr_reader :answers
 

data/lib/ruby_decision_model/providers/base.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyDecisionModel
+  module Providers
+    # A provider owns everything that differs between decision-model APIs:
+    # where requests go, how they are authenticated, which model is the
+    # default, which model names are aliases, and how usage is read back.
+    # Client keeps the public API and delegates these questions here.
+    class Base
+      attr_reader :api_key
+
+      def initialize(api_key: nil, base_url: nil)
+        @api_key = api_key || ENV.fetch(env_var, nil)
+        @base_url = base_url
+      end
+
+      # Identifier used in error messages and by Client#provider.
+      def name
+        raise NotImplementedError
+      end
+
+      def env_var
+        raise NotImplementedError
+      end
+
+      def default_base_url
+        raise NotImplementedError
+      end
+
+      def endpoint_path
+        raise NotImplementedError
+      end
+
+      def default_model
+        raise NotImplementedError
+      end
+
+      # Map of alias => canonical model name for this provider.
+      def aliases
+        {}
+      end
+
+      # Whether this provider reports a per-request cost in usage.
+      def reports_cost?
+        false
+      end
+
+      def base_url
+        (@base_url || default_base_url).to_s.chomp("/")
+      end
+
+      def url
+        "#{base_url}#{endpoint_path}"
+      end
+
+      def api_key?
+        !(api_key.nil? || api_key.to_s.strip.empty?)
+      end
+
+      # Nil or blank means the provider default. Known aliases resolve to the
+      # provider's canonical name. Anything else passes through untouched.
+      def resolve_model(model)
+        return default_model if model.nil? || model.to_s.strip.empty?
+
+        aliases.fetch(model.to_s, model.to_s)
+      end
+
+      def headers
+        {
+          "Authorization" => "Bearer #{api_key}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "User-Agent" => "ruby_decision_model/#{VERSION}"
+        }
+      end
+
+      def request_body(model:, state:, questions:)
+        JSON.generate({ "model" => model, "state" => state, "questions" => questions })
+      end
+
+      def usage(parsed)
+        raw = parsed.is_a?(Hash) && parsed["usage"].is_a?(Hash) ? parsed["usage"] : {}
+
+        Response::Usage.new(
+          input_tokens: Integer(raw["input_tokens"], exception: false),
+          output_tokens: Integer(raw["output_tokens"], exception: false),
+          cost: reports_cost? ? Float(raw["cost"], exception: false) : nil
+        )
+      end
+
+      # Keeps the API key out of logs and error output.
+      def inspect
+        "#<#{self.class.name} name=#{name.inspect} base_url=#{base_url.inspect} api_key=#{api_key? ? '[REDACTED]' : 'nil'}>"
+      end
+
+      # Applies non-nil overrides in place. Used when a caller hands Client a
+      # provider instance together with api_key: or base_url:.
+      def configure(api_key: nil, base_url: nil)
+        @api_key = api_key unless api_key.nil?
+        @base_url = base_url unless base_url.nil?
+        self
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/open_router.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    class OpenRouter < Base
+      ALIASES = {
+        "jev" => "typesafe/jev-1.13",
+        "jev-latest" => "typesafe/jev-1.13"
+      }.freeze
+
+      def name
+        :open_router
+      end
+
+      def env_var
+        "OPENROUTER_API_KEY"
+      end
+
+      def default_base_url
+        "https://openrouter.ai/api/alpha"
+      end
+
+      def endpoint_path
+        "/decisions"
+      end
+
+      def default_model
+        "typesafe/jev-1.13"
+      end
+
+      def aliases
+        ALIASES
+      end
+
+      def reports_cost?
+        true
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/typesafe.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    class Typesafe < Base
+      ALIASES = {
+        "typesafe/jev-1.13" => "jev-latest",
+        "jev" => "jev-latest"
+      }.freeze
+
+      def name
+        :typesafe
+      end
+
+      def env_var
+        "TYPESAFE_API_KEY"
+      end
+
+      def default_base_url
+        "https://api.typesafe.ai"
+      end
+
+      def endpoint_path
+        "/v1/systemone"
+      end
+
+      def default_model
+        "jev-latest"
+      end
+
+      def aliases
+        ALIASES
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "providers/base"
+require_relative "providers/open_router"
+require_relative "providers/typesafe"
+
+module RubyDecisionModel
+  module Providers
+    REGISTRY = {
+      open_router: OpenRouter,
+      typesafe: Typesafe
+    }.freeze
+
+    module_function
+
+    def names
+      REGISTRY.keys
+    end
+
+    def build(name, api_key: nil, base_url: nil)
+      klass = REGISTRY[name.to_s.to_sym]
+      raise ConfigurationError, "unknown provider #{name.inspect}; known providers: #{names.join(', ')}" if klass.nil?
+
+      klass.new(api_key: api_key, base_url: base_url)
+    end
+
+    # Order in which environment variables are consulted when no provider or
+    # api_key is given. Typesafe wins when both keys are set.
+    ENV_PRIORITY = [Typesafe, OpenRouter].freeze
+
+    # Picks a provider from the environment, or nil when no key is set.
+    def from_env
+      ENV_PRIORITY.each do |klass|
+        provider = klass.new
+        return provider if provider.api_key?
+      end
+      nil
+    end
+
+    def env_vars
+      ENV_PRIORITY.map { |klass| klass.new.env_var }
+    end
+  end
+end

data/lib/ruby_decision_model/response.rb

@@ -4,18 +4,38 @@ module RubyDecisionModel
   class Response
     Usage = Data.define(:input_tokens, :output_tokens, :cost)
 
-    attr_reader :answers, :usage, :model, :id, :raw
+    attr_reader :answers, :usage, :model, :id, :raw, :request_id
 
-    def initialize(answers:, usage:, model:, id:, raw:)
+    def initialize(answers:, usage:, model:, id:, raw:, request_id: nil)
       @answers = answers
       @usage = usage
       @model = model
       @id = id
       @raw = raw
+      @request_id = request_id
     end
 
     def [](id)
       answers[id]
     end
+
+    # Answers filtered by type, keyed the same way as #answers.
+    def nouls
+      answers_of_type("noul")
+    end
+
+    def choices
+      answers_of_type("choice")
+    end
+
+    def scores
+      answers_of_type("score")
+    end
+
+    private
+
+    def answers_of_type(type)
+      answers.select { |_id, answer| answer.type == type }
+    end
   end
 end

data/lib/ruby_decision_model/retry_policy.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "time"
+
+module RubyDecisionModel
+  # Retry rules shared by every provider. Defaults follow the official
+  # Typesafe SDKs: two retries after the initial attempt, exponential
+  # backoff from 0.5s capped at 5s with up to 25% jitter subtracted,
+  # Retry-After honored up to 60s, and a 30s total budget across attempts.
+  class RetryPolicy < Data.define(
+    :max_retries,
+    :backoff_initial,
+    :backoff_max,
+    :backoff_jitter,
+    :http_statuses,
+    :respect_retry_after,
+    :max_retry_after,
+    :retry_connection_errors,
+    :retry_timeouts,
+    :total_timeout
+  )
+    DEFAULT_STATUSES = ([408, 429] + (500..599).to_a).freeze
+
+    TIMEOUT_EXCEPTIONS = [Net::OpenTimeout, Net::ReadTimeout].freeze
+    CONNECTION_EXCEPTIONS = [
+      Errno::ECONNRESET,
+      Errno::ECONNREFUSED,
+      Errno::ECONNABORTED,
+      Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH,
+      Errno::EPIPE,
+      SocketError,
+      IOError,
+      OpenSSL::SSL::SSLError
+    ].freeze
+
+    def initialize(max_retries: 2, backoff_initial: 0.5, backoff_max: 5.0, backoff_jitter: 0.25,
+                   http_statuses: DEFAULT_STATUSES, respect_retry_after: true, max_retry_after: 60.0,
+                   retry_connection_errors: true, retry_timeouts: true, total_timeout: 30.0)
+      super
+      validate!
+    end
+
+    # Accepts a RetryPolicy, a Hash of overrides, or nil (defaults).
+    def self.from(value)
+      case value
+      when RetryPolicy then value
+      when nil then new
+      when Hash then new(**value.transform_keys(&:to_sym))
+      else
+        raise ConfigurationError, "retry must be a RetryPolicy or a Hash of overrides, got #{value.class}"
+      end
+    end
+
+    def retryable_status?(status)
+      http_statuses.include?(status)
+    end
+
+    def timeout_exception?(exception)
+      TIMEOUT_EXCEPTIONS.any? { |klass| exception.is_a?(klass) }
+    end
+
+    def connection_exception?(exception)
+      CONNECTION_EXCEPTIONS.any? { |klass| exception.is_a?(klass) }
+    end
+
+    def retryable_exception?(exception)
+      return retry_timeouts if timeout_exception?(exception)
+      return retry_connection_errors if connection_exception?(exception)
+
+      false
+    end
+
+    # Seconds to wait before the retry numbered `retry_number` (0 for the
+    # first retry). `random` returns a Float in 0...1 and exists so tests can
+    # pin the jitter.
+    def backoff(retry_number, random: -> { rand })
+      base = [backoff_initial * (2**retry_number), backoff_max].min
+      [base * (1.0 - (backoff_jitter * random.call)), 0.0].max
+    end
+
+    # Delay before the next retry: the server's Retry-After when present and
+    # honored (clamped to max_retry_after), otherwise the computed backoff.
+    def delay(retry_number, headers: {}, random: -> { rand })
+      hinted = respect_retry_after ? retry_after_seconds(headers) : nil
+      return [hinted, max_retry_after].min if hinted
+
+      backoff(retry_number, random: random)
+    end
+
+    # Reads retry-after-ms (preferred) or Retry-After (seconds or HTTP date).
+    # Header names are matched case-insensitively. Returns nil when absent
+    # or unparseable.
+    def retry_after_seconds(headers)
+      return nil unless headers.is_a?(Hash)
+
+      ms = header_value(headers, "retry-after-ms")
+      if ms
+        parsed = Float(ms, exception: false)
+        return parsed / 1000.0 if parsed && parsed >= 0
+      end
+
+      raw = header_value(headers, "retry-after")
+      return nil if raw.nil?
+
+      seconds = Float(raw, exception: false)
+      return seconds if seconds && seconds >= 0
+
+      begin
+        [Time.httpdate(raw.to_s) - Time.now, 0.0].max
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    private
+
+    def validate!
+      unless max_retries.is_a?(Integer) && max_retries >= 0
+        raise ConfigurationError, "max_retries must be a non-negative Integer, got #{max_retries.inspect}"
+      end
+
+      { backoff_initial: backoff_initial, backoff_max: backoff_max, max_retry_after: max_retry_after }.each do |name, value|
+        next if finite_non_negative?(value)
+
+        raise ConfigurationError, "#{name} must be a finite non-negative number, got #{value.inspect}"
+      end
+
+      unless finite_non_negative?(backoff_jitter) && backoff_jitter <= 1.0
+        raise ConfigurationError, "backoff_jitter must be a number between 0 and 1, got #{backoff_jitter.inspect}"
+      end
+
+      unless total_timeout.nil? || finite_non_negative?(total_timeout)
+        raise ConfigurationError, "total_timeout must be nil or a finite non-negative number, got #{total_timeout.inspect}"
+      end
+
+      return if http_statuses.respond_to?(:include?)
+
+      raise ConfigurationError, "http_statuses must respond to include?, got #{http_statuses.inspect}"
+    end
+
+    def finite_non_negative?(value)
+      value.is_a?(Numeric) && value.finite? && value >= 0
+    end
+
+    def header_value(headers, name)
+      headers.each do |key, value|
+        next unless key.to_s.casecmp?(name)
+
+        return value.is_a?(Array) ? value.first : value
+      end
+      nil
+    end
+  end
+end

data/lib/ruby_decision_model/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyDecisionModel
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/ruby_decision_model.rb

@@ -1,11 +1,25 @@
 # frozen_string_literal: true
 
+require "net/http"
+require "openssl"
+
 require_relative "ruby_decision_model/version"
 require_relative "ruby_decision_model/errors"
 require_relative "ruby_decision_model/questions"
 require_relative "ruby_decision_model/answers"
 require_relative "ruby_decision_model/response"
+require_relative "ruby_decision_model/providers"
+require_relative "ruby_decision_model/retry_policy"
 require_relative "ruby_decision_model/client"
 
 module RubyDecisionModel
+  class << self
+    # A memoized default client built from the environment. Reset with
+    # `RubyDecisionModel.client = nil`.
+    def client
+      @client ||= Client.new
+    end
+
+    attr_writer :client
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_decision_model
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Obie Fernandez
@@ -40,9 +40,9 @@ dependencies:
         version: '13.0'
 description: Decision models answer typed questions about a state instead of generating
   text. ruby_decision_model builds noul (yes/no probability), choice, and score questions,
-  posts them with a state to a decisions endpoint (OpenRouter's /decisions with Typesafe
-  Jev to start), and returns normalized answers with probabilities, confidence, legends,
-  and usage.
+  posts them with a state to a decision-model provider (OpenRouter by default, Typesafe's
+  native API as a second door), and returns normalized answers with probabilities,
+  confidence, legends, and usage. Retries follow the official Typesafe SDKs.
 email:
 - obiefernandez@gmail.com
 executables: []
@@ -56,8 +56,13 @@ files:
 - lib/ruby_decision_model/answers.rb
 - lib/ruby_decision_model/client.rb
 - lib/ruby_decision_model/errors.rb
+- lib/ruby_decision_model/providers.rb
+- lib/ruby_decision_model/providers/base.rb
+- lib/ruby_decision_model/providers/open_router.rb
+- lib/ruby_decision_model/providers/typesafe.rb
 - lib/ruby_decision_model/questions.rb
 - lib/ruby_decision_model/response.rb
+- lib/ruby_decision_model/retry_policy.rb
 - lib/ruby_decision_model/version.rb
 homepage: https://github.com/obie/ruby_decision_model
 licenses:
@@ -83,5 +88,6 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: Ruby client for decision models such as Typesafe Jev
+summary: 'The decision-model interface for Ruby: OpenRouter and Typesafe behind one
+  client'
 test_files: []