ruby_decision_model 0.1.0 → 0.2.0

data/lib/ruby_decision_model/providers/openai.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    # OpenAI's Decisions API (public beta, gpt-6-luna). Its wire format
+    # differs from System One in every direction, so this provider
+    # translates both ways:
+    #
+    # - state becomes `input`. Strings pass through; anything else is sent
+    #   as JSON text, since the API has no structured input. Images become
+    #   input_image parts on a single user message.
+    # - questions become a named array. noul is `predicate`; a noul with
+    #   true/false criteria becomes a boolean `choice` so the descriptions
+    #   reach the model, and its answer is read back as a noul. choice
+    #   criteria become `choices`, score criteria become `levels`.
+    # - answers come back as an array of predicate/choice/score/refusal
+    #   objects with probability arrays, and are rebuilt keyed by id with
+    #   probability Hashes and a score legend.
+    class OpenAI < Base
+      ALIASES = {
+        "luna" => "gpt-6-luna",
+        "openai/gpt-6-luna" => "gpt-6-luna",
+        "openai/gpt-6-luna-decisions" => "gpt-6-luna",
+        "gpt-6-luna-decisions" => "gpt-6-luna"
+      }.freeze
+
+      def name
+        :openai
+      end
+
+      def env_var
+        "OPENAI_API_KEY"
+      end
+
+      def default_base_url
+        "https://api.openai.com/v1"
+      end
+
+      def endpoint_path
+        "/decisions"
+      end
+
+      def default_model
+        "gpt-6-luna"
+      end
+
+      def aliases
+        ALIASES
+      end
+
+      # Inputs run to a million tokens, and OpenAI publishes no latency
+      # figures for this endpoint yet.
+      def default_timeout
+        30
+      end
+
+      def supports_images?
+        true
+      end
+
+      def request_id_header
+        "x-request-id"
+      end
+
+      def request_body(model:, state:, questions:, images: nil)
+        JSON.generate(
+          "model" => model,
+          "input" => input(state, images),
+          "questions" => questions.map { |id, question| encode_question(id.to_s, question) }
+        )
+      end
+
+      # Answers are matched by name. An unnamed answer falls back to its
+      # position, since the API answers in question order, but never onto an
+      # id some other answer names. An id answered twice is ambiguous, so it
+      # reads as malformed rather than letting one answer (or a refusal)
+      # silently replace another.
+      def normalize_response(parsed, questions:)
+        by_id = questions.to_h { |id, question| [id.to_s, question] }
+        ids = by_id.keys
+        entries = Array(parsed["answers"])
+        named = entries.filter_map { |answer| answer["name"] if answer.is_a?(Hash) && answer["name"].is_a?(String) }
+        answers = {}
+
+        entries.each_with_index do |answer, index|
+          next unless answer.is_a?(Hash)
+
+          id = answer["name"].is_a?(String) ? answer["name"] : ids[index]
+          next if id.nil? || (!answer["name"].is_a?(String) && named.include?(id))
+
+          answers[id] = answers.key?(id) ? ambiguous(by_id[id]) : decode_answer(answer, by_id[id])
+        end
+
+        { "id" => parsed["id"], "model" => parsed["model"], "answers" => answers, "usage" => parsed["usage"] }
+      end
+
+      private
+
+      def input(state, images)
+        text = state_text(state)
+        return text if images.nil? || images.empty?
+
+        content = []
+        content << { "type" => "input_text", "text" => text } unless text.empty?
+        images.each { |url| content << { "type" => "input_image", "image_url" => url } }
+        [{ "role" => "user", "content" => content }]
+      end
+
+      def state_text(state)
+        case state
+        when String then state
+        when nil then ""
+        else JSON.generate(state)
+        end
+      end
+
+      def encode_question(id, question)
+        question = stringify(question)
+        instructions = question["instructions"]
+        raise RequestError, "question #{id} needs instructions for openai" if instructions.nil?
+
+        instructions = JSON.generate(instructions) unless instructions.is_a?(String)
+        criteria = question["criteria"]
+
+        case question["type"]
+        when "noul"
+          return { "name" => id, "type" => "predicate", "instructions" => instructions } unless criteria.is_a?(Hash)
+
+          descriptions = stringify(criteria)
+          { "name" => id, "type" => "choice", "instructions" => instructions,
+            "choices" => [true, false].map { |value| described({ "value" => value }, descriptions[value.to_s]) } }
+        when "choice"
+          { "name" => id, "type" => "choice", "instructions" => instructions,
+            "choices" => stringify(criteria).map { |value, text| described({ "value" => value }, text) } }
+        when "score"
+          { "name" => id, "type" => "score", "instructions" => instructions,
+            "levels" => Array(criteria).map { |level| encode_level(level) } }
+        else
+          question.merge("name" => id)
+        end
+      end
+
+      # Jev score criteria are descriptions: usually strings, sometimes
+      # objects. A Hash with a label keeps its label and description;
+      # anything else becomes the label as text.
+      def encode_level(level)
+        level = stringify(level) if level.is_a?(Hash)
+        return described({ "label" => level["label"].to_s }, level["description"]) if level.is_a?(Hash) && level.key?("label")
+        return { "label" => level } if level.is_a?(String)
+
+        { "label" => JSON.generate(level) }
+      end
+
+      def described(hash, description)
+        return hash if description.nil?
+
+        hash.merge("description" => description.is_a?(String) ? description : JSON.generate(description))
+      end
+
+      def decode_answer(answer, question)
+        question = stringify(question)
+
+        case answer["type"]
+        when "predicate"
+          { "type" => "noul", "noul" => answer["probability"] }
+        when "choice"
+          question["type"] == "noul" ? decode_boolean_choice(answer) : decode_choice(answer)
+        when "score"
+          decode_score(answer, Array(question["criteria"]))
+        when "refusal"
+          { "type" => "refusal" }
+        else
+          answer
+        end.then { |decoded| noul_probabilities(decoded) }
+      end
+
+      # Carries the expected type with none of its fields, so Client reports
+      # the id as malformed.
+      def ambiguous(question)
+        { "type" => stringify(question)["type"] }
+      end
+
+      def decode_boolean_choice(answer)
+        return { "type" => "noul" } if duplicate_values?(answer)
+
+        entry = probability_entries(answer).find { |item| item["value"] == true }
+        { "type" => "noul", "noul" => entry && entry["probability"] }
+      end
+
+      def decode_choice(answer)
+        return { "type" => "choice" } if duplicate_values?(answer)
+
+        probabilities = probability_entries(answer).to_h { |item| [item["value"].to_s, item["probability"]] }
+        choice = answer["choice"]
+        choice = choice.to_s if [true, false].include?(choice)
+
+        { "type" => "choice", "choice" => choice, "confidence" => answer["confidence"], "probabilities" => probabilities }
+      end
+
+      # The legend maps each level index to the criteria entry the caller
+      # wrote, as Jev does, falling back to the label OpenAI echoes.
+      def decode_score(answer, criteria)
+        return { "type" => "score" } if duplicate_values?(answer)
+
+        entries = probability_entries(answer)
+        legend = entries.to_h do |item|
+          index = item["value"]
+          [index.to_s, index.is_a?(Integer) && index.between?(0, criteria.size - 1) ? criteria[index] : item["label"]]
+        end
+
+        { "type" => "score", "score" => answer["score"], "confidence" => answer["confidence"],
+          "probabilities" => entries.to_h { |item| [item["value"].to_s, item["probability"]] },
+          "legend" => legend }
+      end
+
+      def probability_entries(answer)
+        Array(answer["probabilities"]).select { |item| item.is_a?(Hash) && item.key?("value") }
+      end
+
+      # Two entries for one value make the split ambiguous. The answer then
+      # carries no fields and Client reports it as malformed. Values compare
+      # as the string keys the decoded probabilities use, so true and "true"
+      # (or 1 and "1") count as the same value rather than one silently
+      # replacing the other.
+      def duplicate_values?(answer)
+        values = probability_entries(answer).map { |item| item["value"].to_s }
+        values.uniq.size != values.size
+      end
+
+      def stringify(hash)
+        hash.is_a?(Hash) ? hash.transform_keys(&:to_s) : {}
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/perplexity.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    # Perplexity's Decisions API serving pplx-decider. The body is System One.
+    # Images ride inside state as OpenAI-style image_url parts, so state
+    # becomes an array when images are present.
+    class Perplexity < Base
+      ALIASES = {
+        "pplx-decider" => "pplx-decider-v1.1-27b",
+        "perplexity/pplx-decider-v1-27b" => "pplx-decider-v1-27b"
+      }.freeze
+
+      def name
+        :perplexity
+      end
+
+      def env_var
+        "PERPLEXITY_API_KEY"
+      end
+
+      def default_base_url
+        "https://api.perplexity.ai"
+      end
+
+      def endpoint_path
+        "/v1/decisions"
+      end
+
+      def default_model
+        "pplx-decider-v1.1-27b"
+      end
+
+      def aliases
+        ALIASES
+      end
+
+      # Perplexity documents 5 to 23 seconds for large inputs and uses 30 in
+      # its own examples.
+      def default_timeout
+        30
+      end
+
+      def supports_images?
+        true
+      end
+
+      def request_id_header
+        "x-request-id"
+      end
+
+      def request_body(model:, state:, questions:, images: nil)
+        return super(model: model, state: state, questions: questions) if images.nil? || images.empty?
+
+        parts = images.map { |url| { "type" => "image_url", "image_url" => { "url" => url } } }
+        super(model: model, state: state_parts(state) + parts, questions: questions)
+      end
+
+      private
+
+      def state_parts(state)
+        case state
+        when nil then []
+        when String then state.empty? ? [] : [state]
+        when Array then state
+        else [JSON.generate(state)]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/system_one.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    # Any server that speaks Typesafe's System One API at /v1/systemone:
+    # Ollama, the autojev server that ships with pplx-decider's weights,
+    # strands-decider's local server, and hosted lookalikes. The base URL is
+    # required and has no /v1 suffix. The API key and model are optional,
+    # since local servers often run without auth and some pick their own
+    # model. SYSTEM_ONE_BASE_URL and SYSTEM_ONE_API_KEY follow Pydantic AI.
+    class SystemOne < Base
+      BASE_URL_ENV_VAR = "SYSTEM_ONE_BASE_URL"
+
+      def initialize(api_key: nil, base_url: nil)
+        super
+        @base_url ||= ENV.fetch(BASE_URL_ENV_VAR, nil)
+      end
+
+      def name
+        :system_one
+      end
+
+      def env_var
+        "SYSTEM_ONE_API_KEY"
+      end
+
+      def default_base_url
+        nil
+      end
+
+      def endpoint_path
+        "/v1/systemone"
+      end
+
+      def default_model
+        nil
+      end
+
+      def requires_api_key?
+        false
+      end
+
+      # A local server may load the model on the first request.
+      def default_timeout
+        30
+      end
+
+      # Sent as the System One images extension; servers without image
+      # support reject the request.
+      def supports_images?
+        true
+      end
+
+      def validate!
+        super
+        return unless base_url.empty?
+
+        raise ConfigurationError, "base_url is required for system_one: pass base_url: or set #{BASE_URL_ENV_VAR}"
+      end
+
+      # Checked when a request is built rather than in validate!, so a
+      # client's own base_url: can still replace an unusable
+      # SYSTEM_ONE_BASE_URL. Ollama hosts are often written as
+      # localhost:11434, and whether the server speaks http or https is not
+      # ours to guess; an empty host would quietly mean this machine.
+      def url(model = nil)
+        uri = URI.parse(base_url)
+        unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+          raise ConfigurationError, "system_one base_url needs http:// or https:// and a host, got #{base_url.inspect}"
+        end
+
+        super
+      rescue URI::InvalidURIError
+        raise ConfigurationError, "system_one base_url is not a URL: #{base_url.inspect}"
+      end
+
+      def request_body(model:, state:, questions:, images: nil)
+        body = {}
+        body["model"] = model unless model.nil?
+        body["state"] = state
+        body["questions"] = questions
+        body["images"] = images if images
+        JSON.generate(body)
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/typesafe.rb

@@ -7,6 +7,7 @@ module RubyDecisionModel
     class Typesafe < Base
       ALIASES = {
         "typesafe/jev-1.13" => "jev-latest",
+        "~typesafe/jev-latest" => "jev-latest",
         "jev" => "jev-latest"
       }.freeze
 

data/lib/ruby_decision_model/providers.rb

@@ -3,42 +3,76 @@
 require_relative "providers/base"
 require_relative "providers/open_router"
 require_relative "providers/typesafe"
+require_relative "providers/openai"
+require_relative "providers/cloudflare"
+require_relative "providers/perplexity"
+require_relative "providers/databricks"
+require_relative "providers/system_one"
 
 module RubyDecisionModel
   module Providers
     REGISTRY = {
       open_router: OpenRouter,
-      typesafe: Typesafe
+      typesafe: Typesafe,
+      openai: OpenAI,
+      cloudflare: Cloudflare,
+      perplexity: Perplexity,
+      databricks: Databricks,
+      system_one: SystemOne
     }.freeze
 
+    # Names a provider from the environment, ahead of any key sniffing.
+    PROVIDER_ENV_VAR = "RUBY_DECISION_MODEL_PROVIDER"
+
     module_function
 
     def names
       REGISTRY.keys
     end
 
+    # Names are matched without regard to case, and `-` reads as `_`, so
+    # "OpenAI" and "open-router" from an env file both resolve.
     def build(name, api_key: nil, base_url: nil)
-      klass = REGISTRY[name.to_s.to_sym]
+      klass = REGISTRY[name.to_s.strip.downcase.tr("-", "_").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
+    # api_key is given. Typesafe wins when several are set. Only settings
+    # that exist for decision models take part; general-purpose credentials
+    # such as OPENAI_API_KEY or CLOUDFLARE_API_TOKEN never pick a provider
+    # on their own. Name those with RUBY_DECISION_MODEL_PROVIDER.
+    ENV_PRIORITY = [Typesafe, OpenRouter, SystemOne].freeze
+
+    # The provider name RUBY_DECISION_MODEL_PROVIDER holds, or nil.
+    def named_in_env
+      named = ENV.fetch(PROVIDER_ENV_VAR, nil).to_s.strip
+      named.empty? ? nil : named
+    end
 
-    # Picks a provider from the environment, or nil when no key is set.
+    # Picks a provider from the environment, or nil when nothing is set.
+    # RUBY_DECISION_MODEL_PROVIDER wins when present, even if that provider
+    # turns out to be missing its key, so the error names the right thing.
     def from_env
+      named = named_in_env
+      return build(named) if named
+
       ENV_PRIORITY.each do |klass|
         provider = klass.new
-        return provider if provider.api_key?
+        return provider if provider.configured?
       end
       nil
     end
 
     def env_vars
-      ENV_PRIORITY.map { |klass| klass.new.env_var }
+      [PROVIDER_ENV_VAR] + ENV_PRIORITY.map { |klass| env_var_for(klass) }
+    end
+
+    def env_var_for(klass)
+      klass == SystemOne ? SystemOne::BASE_URL_ENV_VAR : klass.new.env_var
     end
+    private_class_method :env_var_for
   end
 end

data/lib/ruby_decision_model/retry_policy.rb

@@ -21,7 +21,7 @@ module RubyDecisionModel
   )
     DEFAULT_STATUSES = ([408, 429] + (500..599).to_a).freeze
 
-    TIMEOUT_EXCEPTIONS = [Net::OpenTimeout, Net::ReadTimeout].freeze
+    TIMEOUT_EXCEPTIONS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout].freeze
     CONNECTION_EXCEPTIONS = [
       Errno::ECONNRESET,
       Errno::ECONNREFUSED,

data/lib/ruby_decision_model/version.rb

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

data/lib/ruby_decision_model.rb

@@ -6,6 +6,7 @@ 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/images"
 require_relative "ruby_decision_model/answers"
 require_relative "ruby_decision_model/response"
 require_relative "ruby_decision_model/providers"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_decision_model
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Obie Fernandez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -40,9 +40,11 @@ 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 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.
+  posts them with a state and optional images to a decision-model provider (OpenRouter,
+  Typesafe, OpenAI, Cloudflare, Perplexity, Databricks, or any System One server such
+  as Ollama), and returns the same normalized answers with probabilities, confidence,
+  legends, and usage whichever vendor served them. Retries follow the official Typesafe
+  SDKs.
 email:
 - obiefernandez@gmail.com
 executables: []
@@ -56,9 +58,15 @@ files:
 - lib/ruby_decision_model/answers.rb
 - lib/ruby_decision_model/client.rb
 - lib/ruby_decision_model/errors.rb
+- lib/ruby_decision_model/images.rb
 - lib/ruby_decision_model/providers.rb
 - lib/ruby_decision_model/providers/base.rb
+- lib/ruby_decision_model/providers/cloudflare.rb
+- lib/ruby_decision_model/providers/databricks.rb
 - lib/ruby_decision_model/providers/open_router.rb
+- lib/ruby_decision_model/providers/openai.rb
+- lib/ruby_decision_model/providers/perplexity.rb
+- lib/ruby_decision_model/providers/system_one.rb
 - lib/ruby_decision_model/providers/typesafe.rb
 - lib/ruby_decision_model/questions.rb
 - lib/ruby_decision_model/response.rb
@@ -88,6 +96,6 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: 'The decision-model interface for Ruby: OpenRouter and Typesafe behind one
-  client'
+summary: 'The decision-model interface for Ruby: one client for Jev, gpt-6-luna, Clef,
+  pplx-decider, and more'
 test_files: []