ruby_decision_model 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40caeb94a3a1a8365e7719753591173b6a8b89f8b0431579ac1df3f6b731caeb
+  data.tar.gz: 3fd04d44ed5083947c79921aa2fe2c05e9616294104e351ffbea3a47448e7dd7
+SHA512:
+  metadata.gz: dc8ba08eaf6fa210ef58809c7b3e8e585e835dc4bbaa09b7d65956b39d2168cd47d4812dabe7a6c72420fa93ebc0d9f2716e9d33a17d076f0a709ab5a573bd0c
+  data.tar.gz: 47260e6b68ae8bf8dafec39aae852460281d4423285116f33f8a097da0556e2f0a52327503964310018561e69a3f3cd66fc9b9cb5d51f2dbca6c1bd8c5f9a7c1

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.0.1 - 2026-09-18
+
+Initial release. Client and question builders for OpenRouter's `/decisions`
+endpoint with Typesafe Jev as the first backend. Supports noul, choice, and
+score questions, normalized answers, retry on transient errors, and a typed
+error hierarchy.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obie Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+# 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.
+
+## Install
+
+```ruby
+gem "ruby_decision_model"
+```
+
+## Usage
+
+```ruby
+require "ruby_decision_model"
+
+client = RubyDecisionModel::Client.new(api_key: ENV["OPENROUTER_API_KEY"])
+
+response = client.ask(
+  state: { title: "Server returns 500 on checkout", reporter: "support" },
+  questions: {
+    "urgent" => RubyDecisionModel::Questions.noul("Is this urgent?"),
+    "severity" => RubyDecisionModel::Questions.score(
+      "How severe is this issue?",
+      criteria: ["cosmetic", "minor", "major", "critical"]
+    )
+  }
+)
+
+response["urgent"].noul       # => 0.87
+response["severity"].score    # => 2.4
+response.usage.cost           # => 0.0012
+```
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `ConfigurationError` | Missing api_key, model, or base_url |
+| `RequestError` | Questions hash was empty |
+| `TransportError` (`TimeoutError`) | Network or timeout failure |
+| `ApiError` (`Unauthorized`, `PayloadTooLarge`, `RateLimited`) | Non-2xx response, carries `#status` and `#body` |
+| `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.
+
+The companion gem `ruby_dm` builds decisions and verdicts on top of this client.

data/lib/ruby_decision_model/answers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyDecisionModel
+  module Answers
+    Noul = Data.define(:noul, :probabilities) do
+      def type
+        "noul"
+      end
+
+      def probability
+        noul
+      end
+    end
+
+    Choice = Data.define(:choice, :confidence, :probabilities) do
+      def type
+        "choice"
+      end
+    end
+
+    Score = Data.define(:score, :confidence, :probabilities, :legend) do
+      def type
+        "score"
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/client.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+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("/")
+      @timeout = timeout
+      @transport = transport || default_transport
+      @sleeper = sleeper
+    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)
+    end
+
+    private
+
+    def default_transport
+      lambda do |url:, headers:, body:|
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = body
+
+        response = http.request(request)
+        [response.code.to_i, response.body]
+      end
+    end
+
+    def perform_with_retry(url:, headers:, body:)
+      attempts = 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
+        rescue Error
+          raise
+        rescue StandardError => e
+          raise_transport_error(e)
+        end
+
+        return [status, response_body] unless RETRYABLE_STATUSES.include?(status) && attempts < MAX_ATTEMPTS
+
+        @sleeper.call(backoff_seconds)
+      end
+    end
+
+    def backoff_seconds
+      0.5 + (rand * 0.25)
+    end
+
+    def raise_transport_error(exception)
+      if exception.is_a?(Net::OpenTimeout) || exception.is_a?(Net::ReadTimeout)
+        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)
+      case status
+      when 200..299
+        parse_success(response_body, questions)
+      when 401
+        raise Unauthorized.new("unauthorized", status: status, body: response_body)
+      when 413
+        raise PayloadTooLarge.new("payload too large", status: status, body: response_body)
+      when 429
+        raise RateLimited.new("rate limited", status: status, body: response_body)
+      else
+        raise ApiError.new("api error (status #{status})", status: status, body: response_body)
+      end
+    end
+
+    def parse_success(response_body, questions)
+      parsed = begin
+        JSON.parse(response_body)
+      rescue JSON::ParserError => e
+        raise InvalidResponse, "response body was not valid JSON: #{e.message}"
+      end
+
+      raise InvalidResponse, "response body was not a JSON object" unless parsed.is_a?(Hash)
+
+      raw_answers = parsed["answers"]
+      raw_answers = {} unless raw_answers.is_a?(Hash)
+
+      normalized = {}
+      malformed = []
+      missing = []
+
+      questions.each do |raw_id, question|
+        id = raw_id.to_s
+        answer_hash = raw_answers[id]
+        expected_type = question_type(question)
+
+        if answer_hash.is_a?(Hash) && answer_hash["type"] == expected_type
+          begin
+            normalized[id] = normalize_answer(expected_type, answer_hash)
+          rescue MalformedAnswer
+            malformed << id
+          end
+        else
+          missing << id
+        end
+      end
+
+      if malformed.any?
+        raise InvalidResponse.new(
+          "malformed answer fields for: #{malformed.join(', ')}",
+          answers: normalized
+        )
+      end
+
+      if missing.any?
+        raise MissingAnswers.new(
+          "missing or wrong-type answers for: #{missing.join(', ')}",
+          answers: normalized,
+          missing: missing
+        )
+      end
+
+      Response.new(
+        answers: normalized,
+        usage: normalize_usage(parsed["usage"]),
+        model: parsed["model"],
+        id: parsed["id"],
+        raw: parsed
+      )
+    end
+
+    class MalformedAnswer < StandardError; end
+
+    def normalize_answer(type, hash)
+      case type
+      when "noul"
+        noul = hash["noul"]
+        raise MalformedAnswer unless noul.is_a?(Numeric)
+
+        Answers::Noul.new(noul: noul.to_f, probabilities: hash_or_empty(hash["probabilities"]))
+      when "choice"
+        choice = hash["choice"]
+        confidence = hash["confidence"]
+        raise MalformedAnswer unless choice.is_a?(String) && confidence.is_a?(Numeric)
+
+        Answers::Choice.new(
+          choice: choice,
+          confidence: confidence.to_f,
+          probabilities: hash_or_empty(hash["probabilities"])
+        )
+      when "score"
+        score = hash["score"]
+        confidence = hash["confidence"]
+        raise MalformedAnswer unless score.is_a?(Numeric) && confidence.is_a?(Numeric)
+
+        Answers::Score.new(
+          score: score.to_f,
+          confidence: confidence.to_f,
+          probabilities: hash_or_empty(hash["probabilities"]),
+          legend: hash_or_empty(hash["legend"])
+        )
+      else
+        raise MalformedAnswer
+      end
+    end
+
+    def question_type(question)
+      return nil unless question.is_a?(Hash)
+
+      question["type"] || question[:type]
+    end
+
+    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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RubyDecisionModel
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class RequestError < Error; end
+
+  class TransportError < Error
+    attr_reader :cause_error
+
+    def initialize(message, cause_error: nil)
+      super(message)
+      @cause_error = cause_error
+    end
+  end
+
+  class TimeoutError < TransportError; end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status:, body:)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class Unauthorized < ApiError; end
+
+  class PayloadTooLarge < ApiError; end
+
+  class RateLimited < ApiError; end
+
+  class InvalidResponse < Error
+    attr_reader :answers
+
+    def initialize(message, answers: {})
+      super(message)
+      @answers = answers
+    end
+  end
+
+  class MissingAnswers < InvalidResponse
+    attr_reader :missing
+
+    def initialize(message, answers: {}, missing: [])
+      super(message, answers: answers)
+      @missing = missing
+    end
+  end
+end

data/lib/ruby_decision_model/questions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyDecisionModel
+  # Pure builders for question hashes. No I/O.
+  module Questions
+    module_function
+
+    def noul(instructions, criteria: nil)
+      validate_instructions!(instructions)
+
+      question = { "type" => "noul", "instructions" => instructions }
+      question["criteria"] = criteria unless criteria.nil?
+      question
+    end
+
+    def choice(instructions, criteria:)
+      validate_instructions!(instructions)
+      unless criteria.is_a?(Hash) && criteria.size.between?(1, 255)
+        raise ArgumentError, "criteria must be a Hash with 1..255 entries"
+      end
+
+      stringified = {}
+      criteria.each { |k, v| stringified[k.to_s] = v }
+
+      { "type" => "choice", "instructions" => instructions, "criteria" => stringified }
+    end
+
+    def score(instructions, criteria:)
+      validate_instructions!(instructions)
+      unless criteria.is_a?(Array) && criteria.size.between?(2, 10)
+        raise ArgumentError, "criteria must be an Array with 2..10 entries"
+      end
+
+      { "type" => "score", "instructions" => instructions, "criteria" => criteria }
+    end
+
+    def validate_instructions!(instructions)
+      case instructions
+      when String
+        raise ArgumentError, "instructions must not be empty" if instructions.empty?
+      when Hash, Array
+        raise ArgumentError, "instructions must not be empty" if instructions.empty?
+      else
+        raise ArgumentError, "instructions must be a String, Hash, or Array"
+      end
+    end
+    private_class_method :validate_instructions!
+  end
+end

data/lib/ruby_decision_model/response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubyDecisionModel
+  class Response
+    Usage = Data.define(:input_tokens, :output_tokens, :cost)
+
+    attr_reader :answers, :usage, :model, :id, :raw
+
+    def initialize(answers:, usage:, model:, id:, raw:)
+      @answers = answers
+      @usage = usage
+      @model = model
+      @id = id
+      @raw = raw
+    end
+
+    def [](id)
+      answers[id]
+    end
+  end
+end

data/lib/ruby_decision_model/version.rb

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

data/lib/ruby_decision_model.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+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/client"
+
+module RubyDecisionModel
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: ruby_decision_model
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Obie Fernandez
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        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.
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ruby_decision_model.rb
+- lib/ruby_decision_model/answers.rb
+- lib/ruby_decision_model/client.rb
+- lib/ruby_decision_model/errors.rb
+- lib/ruby_decision_model/questions.rb
+- lib/ruby_decision_model/response.rb
+- lib/ruby_decision_model/version.rb
+homepage: https://github.com/obie/ruby_decision_model
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/obie/ruby_decision_model
+  changelog_uri: https://github.com/obie/ruby_decision_model/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Ruby client for decision models such as Typesafe Jev
+test_files: []