hunch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4fe18b2f4a16d13a14ca5ff3c9887404e1ebc0b455e66b9c151951efc27c5fae
+  data.tar.gz: 638b1ee2b57368e9acd352f2fe06bfb6beafc89e29f93b42de1026cc5160c8c7
+SHA512:
+  metadata.gz: 95b72749b648e44622a5e414fe3f9e6c6df1d8926072e324f20802f1223e86382b1130e647038b256ecd9290558491976a9d8c5da593882ca86d789580728e42
+  data.tar.gz: 36256933743330d1b84d04b2b296fa8d758a90a24ea89c4ba50c373190eadb806553a6587734bcdc0c0b6da69eadfcf4d81e04c1108a964466339d8202012eef

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Carl Dawson
+
+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,309 @@
+# Hunch
+
+Probabilistic control flow for Ruby.
+
+Ruby gives you `if`, `case`, and `<=>` for facts. Hunch gives you the same
+three moves for judgment calls. Every question is a conditional probability —
+_how likely is this, given that_ — and the API reads that way:
+
+```ruby
+if Hunch.almost_certain?("this order is fraudulent", given: order.attributes)
+  order.hold!
+end
+```
+
+The English is the configuration. No prompts, no parsing, no tuning DSL.
+Answers come from [TypeSafe's Jev](https://typesafe.ai), a System One model:
+a single fast parallel pass that returns typed, calibrated probabilities
+instead of text — fast and cheap enough to sit inside a request cycle.
+
+## Installation
+
+```ruby
+gem "hunch"
+```
+
+```ruby
+Hunch.configure do |config|
+  config.api_key = ENV["TYPESAFE_API_KEY"]
+end
+```
+
+## The three primitives
+
+**`chance`** answers _whether_, as a probability:
+
+```ruby
+Hunch.chance("written by a real human, not spam", given: bio)  # => 0.87
+```
+
+Named levels collapse it into predicates:
+
+```ruby
+Hunch.possible?("fraudulent", given: order)        # chance >= 0.25
+Hunch.likely?("fraudulent", given: order)          # chance >= 0.5
+Hunch.probable?("fraudulent", given: order)        # chance >= 0.75
+Hunch.almost_certain?("fraudulent", given: order)  # chance >= 0.93
+
+Hunch.configure { |c| c.levels[:paranoid] = 0.99 }
+Hunch.paranoid?("fraudulent", given: order)        # chance >= 0.99
+```
+
+**`pick`** answers _which_:
+
+```ruby
+Hunch.pick(:ham, :spam, given: email)                                  # => :spam
+Hunch.pick(urgent: "needs a reply today", routine: "can wait",
+           given: ticket)                                              # => :routine
+```
+
+**`rate`** answers _how much_, on an ordered scale:
+
+```ruby
+mood = Hunch.rate(:calm, :frustrated, :livid, given: email)
+mood.level      # => :frustrated
+mood.position   # => 1.4
+mood >= :livid  # => false
+```
+
+If shuffling the options wouldn't change their meaning, use `pick`; if they
+form a ladder, use `rate`. Options are bare symbols or `symbol: "description"`,
+mixed freely, plus an optional `question:` when the options alone don't carry
+it. The keywords `given` and `question` are reserved.
+
+## Batching
+
+Several questions about one piece of state cost one API call:
+
+```ruby
+result = Hunch.decide(given: mail.raw_source) do |q|
+  q.likely? :urgent, "does this convey urgency?", over: :probable
+  q.pick    :team, billing: "payments", technical: "bugs", sales: "pricing"
+  q.rate    :mood, :calm, :frustrated, :livid
+end
+
+result.urgent             # => 0.92
+result.urgent?            # => true, past :probable
+result.team               # => :technical
+result.team_probabilities # => { billing: 0.08, technical: 0.85, sales: 0.07 }
+result.mood.level         # => :livid
+```
+
+## In a Rails app
+
+Everything below is lifted from [`example/`](example), a Rails app in this
+repo — its test suite covers each snippet, and all of them have been run
+against the live model.
+
+### Validations
+
+A validation method is just an `if`:
+
+```ruby
+class Signup < ApplicationRecord
+  validates :email, presence: true
+  validate :display_name_is_a_name, :bio_reads_like_a_human
+
+  private
+
+  def display_name_is_a_name
+    return if display_name.blank?
+    return if Hunch.likely?("a plausible human or company name, not an advert or URL", given: display_name)
+
+    errors.add(:display_name, "doesn't look like a name")
+  rescue Hunch::APIError
+    nil
+  end
+
+  def bio_reads_like_a_human
+    return if bio.blank?
+    return if Hunch.probable?("a genuine human bio, not spam or keyword stuffing", given: bio)
+
+    errors.add(:bio, "reads like spam")
+  rescue Hunch::APIError
+    nil
+  end
+end
+```
+
+```ruby
+signup = Signup.new(display_name: "BEST-CRYPTO-DEALS dot example",
+                    bio: "BUY CHEAP GOLD CLICK HERE best prices!!!")
+signup.valid?          # => false
+signup.errors[:bio]    # => ["reads like spam"]
+```
+
+The `rescue nil` is a deliberate policy: if the API is unreachable at save
+time, the record saves anyway. Fail closed instead where it matters more,
+like a spam gate.
+
+### Inbound email
+
+ActionMailbox routing without the regex graveyard:
+
+```ruby
+class SortingMailbox < ApplicationMailbox
+  def process
+    team = Hunch.pick(
+      support: "questions about using or configuring the product",
+      billing: "invoices, payments, refunds",
+      spam:    "unsolicited bulk or scam email",
+      given: "Subject: #{mail.subject}\n\n#{body}"
+    )
+    return if team == :spam
+
+    Ticket.create!(team: team.to_s, subject: mail.subject, body: body)
+  end
+end
+```
+
+### Error triage
+
+Replace the hand-maintained ignore-list with one judgment:
+
+```ruby
+class ErrorTriage
+  def report(error, handled:, severity: nil, context: {}, source: nil)
+    verdict = Hunch.rate(
+      ignore: "known noise, expected in normal operation",
+      notify: "worth a look during working hours",
+      page:   "users are impacted right now",
+      given: { class: error.class.name, message: error.message, handled:, source: }
+    )
+
+    case verdict.level
+    when :page then Pagerduty.trigger(error)
+    when :notify then SlackNotifier.post(error)
+    end
+  end
+end
+
+# config/initializers/error_reporting.rb
+Rails.application.config.after_initialize do
+  Rails.error.subscribe(ErrorTriage.new)
+end
+```
+
+### Job retries
+
+Exception classes don't tell you whether a failure is transient. Ask:
+
+```ruby
+class WebhookDeliveryJob < ApplicationJob
+  rescue_from Delivery::Error do |error|
+    if Hunch.likely?("retrying this failed delivery will succeed",
+                     given: { error: error.message, attempts: executions })
+      retry_job wait: 30.seconds
+    else
+      Rails.logger.warn("giving up on webhook: #{error.message}")
+    end
+  end
+
+  def perform(url, payload)
+    Delivery.post(url, payload)
+  end
+end
+```
+
+A `503 upstream timeout` retries; a `404 endpoint not found` doesn't.
+
+### Enum coercion
+
+Messy import data, typed by construction — `pick` can only return one of
+your enum's values:
+
+```ruby
+class Order < ApplicationRecord
+  enum :status, { pending: 0, shipped: 1, delivered: 2, cancelled: 3 }
+
+  def self.import_status(raw)
+    Hunch.pick(*statuses.keys.map(&:to_sym), given: raw,
+      question: "which order status does this text describe?")
+  end
+end
+
+Order.import_status("sent it out tuesday??") # => :shipped
+```
+
+### Moderation
+
+```ruby
+class Comment < ApplicationRecord
+  enum :status, { pending: 0, published: 1, held: 2, rejected: 3 }, default: :pending
+
+  def moderate!
+    tone = Hunch.rate(:civil, :heated, :abusive, given: body,
+      question: "how abusive is this comment?")
+
+    case tone.level
+    when :civil then published!
+    when :heated then held!
+    when :abusive then rejected!
+    end
+  end
+end
+```
+
+## Testing
+
+The stub backend is just another backend:
+
+```ruby
+Hunch.backend = Hunch::Backends::Stub.new(fraud: 0.95, team: :billing, mood: :calm)
+```
+
+Stub values are keyed by question key (`:answer` for the single-shot
+methods) and follow the question type: a probability or boolean for chance
+and its predicates, a symbol or probabilities hash for `pick`, a level
+symbol or position for `rate`. Unstubbed questions raise unless you pass
+`default:`. The stub records `calls` for assertions:
+
+```ruby
+test "spam is dropped without a ticket" do
+  Hunch.backend = Hunch::Backends::Stub.new(answer: :spam)
+  assert_no_difference -> { Ticket.count } do
+    receive_inbound_email_from_mail(subject: "You have WON", body: "claim your prize")
+  end
+end
+```
+
+## Configuration
+
+```ruby
+Hunch.configure do |config|
+  config.api_key = "..."          # default: ENV["TYPESAFE_API_KEY"]
+  config.model = "jev-latest"
+  config.url = "https://api.typesafe.ai/v1/systemone"
+  config.timeout = 5
+  config.open_timeout = 2
+  config.max_retries = 2          # 429/5xx/timeouts, with backoff, honours Retry-After
+  config.levels[:paranoid] = 0.99
+end
+```
+
+### Via OpenRouter
+
+Jev speaks the same wire format through
+[OpenRouter's Decisions endpoint](https://openrouter.ai/typesafe), so an
+OpenRouter key works today without the TypeSafe waitlist:
+
+```ruby
+Hunch.configure do |config|
+  config.api_key = ENV["OPENROUTER_API_KEY"]
+  config.url = "https://openrouter.ai/api/alpha/decisions"
+  config.model = "typesafe/jev-1.13"
+end
+```
+
+## Honesty about backends
+
+The interface is uniform; the guarantees are not. Jev's probabilities are
+calibrated, its answers are typed by construction, and it responds in
+milliseconds. A future LLM backend can implement the same three primitives,
+but its confidences are estimates, not calibrated probabilities, and it is
+orders of magnitude slower and more expensive. Same interface, different
+guarantees — choose accordingly.
+
+## License
+
+MIT

data/lib/hunch/backends/jev.rb

@@ -0,0 +1,95 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Hunch
+  module Backends
+    class Jev
+      def initialize(config = Hunch.configuration, transport: nil, sleeper: nil)
+        @config = config
+        @transport = transport || method(:http_post)
+        @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      end
+
+      def decide(state:, questions:, model: nil)
+        payload = {
+          "state" => state,
+          "model" => model || @config.model,
+          "questions" => questions.to_h { |key, question| [key.to_s, question.payload] }
+        }
+        with_retries { handle(*@transport.call(payload)) }
+      end
+
+      private
+
+      def with_retries
+        attempts = 0
+        begin
+          attempts += 1
+          yield
+        rescue RateLimitError, OverloadedError, ServerError, TimeoutError, ConnectionError => e
+          raise if attempts > @config.max_retries
+
+          @sleeper.call(e.respond_to?(:retry_after) && e.retry_after || backoff(attempts))
+          retry
+        end
+      end
+
+      def backoff(attempt)
+        (0.5 * (2**(attempt - 1))) + rand * 0.25
+      end
+
+      def handle(status, headers, body)
+        case status
+        when 200..299 then JSON.parse(body)
+        when 401 then raise AuthenticationError, error_message(body, "missing or invalid API key")
+        when 422 then raise ValidationError, error_message(body, "invalid request")
+        when 429 then raise RateLimitError.new(error_message(body, "rate limited"), retry_after: retry_after(headers))
+        when 529 then raise OverloadedError, error_message(body, "service overloaded")
+        when 500..599 then raise ServerError, "server error (#{status})"
+        else raise APIError, error_message(body, "unexpected response (#{status})")
+        end
+      end
+
+      def error_message(body, fallback)
+        parsed = JSON.parse(body)
+        error = parsed["error"] || parsed["message"] || fallback
+        error.is_a?(Hash) ? error["message"] || fallback : error
+      rescue JSON::ParserError, TypeError
+        fallback
+      end
+
+      def retry_after(headers)
+        value = headers["retry-after"] || headers["Retry-After"]
+        value&.to_f&.nonzero?
+      end
+
+      def http_post(payload)
+        uri = URI(@config.url)
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{api_key!}"
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = "hunch-ruby/#{VERSION}"
+        request.body = JSON.generate(payload)
+
+        response = Net::HTTP.start(
+          uri.host, uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: @config.open_timeout,
+          read_timeout: @config.timeout
+        ) { |http| http.request(request) }
+
+        [response.code.to_i, response.each_header.to_h, response.body]
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise TimeoutError, e.message
+      rescue SocketError, SystemCallError, EOFError, OpenSSL::SSL::SSLError => e
+        raise ConnectionError, e.message
+      end
+
+      def api_key!
+        @config.api_key or raise ConfigurationError,
+          "no API key: set TYPESAFE_API_KEY or Hunch.configure { |c| c.api_key = ... }"
+      end
+    end
+  end
+end

data/lib/hunch/backends/stub.rb

@@ -0,0 +1,73 @@
+module Hunch
+  module Backends
+    class Stub
+      attr_reader :calls
+
+      def initialize(default: nil, **answers)
+        @answers = answers
+        @default = default
+        @calls = []
+      end
+
+      def decide(state:, questions:, model: nil)
+        @calls << { state:, questions: }
+        answers = questions.to_h do |key, question|
+          [key.to_s, answer_for(key, question)]
+        end
+        { "answers" => answers, "model" => "stub" }
+      end
+
+      private
+
+      def answer_for(key, question)
+        value = @answers.fetch(key, @default)
+        if value.nil?
+          raise MissingStubAnswer,
+            "no stubbed answer for #{key.inspect}: Stub.new(#{key}: ...) or pass default:"
+        end
+
+        case question.type
+        when :noul then noul(value)
+        when :choice then choice(value, question)
+        when :rate then rate(value, question)
+        end
+      end
+
+      def noul(value)
+        probability =
+          case value
+          when true then 1.0
+          when false then 0.0
+          when Numeric then value.to_f
+          else raise ArgumentError, "noul stub must be true, false, or a probability"
+          end
+        { "type" => "noul", "noul" => probability }
+      end
+
+      def choice(value, question)
+        probabilities =
+          case value
+          when Symbol then question.options.keys.to_h { |option| [option.to_s, option == value ? 1.0 : 0.0] }
+          when Hash then value.transform_keys(&:to_s).transform_values(&:to_f)
+          else raise ArgumentError, "choice stub must be a symbol or a probabilities hash"
+          end
+        winner = probabilities.max_by { |_, p| p }.first
+        { "type" => "choice", "choice" => winner, "probabilities" => probabilities, "confidence" => probabilities[winner] }
+      end
+
+      def rate(value, question)
+        levels = question.levels.keys
+        position =
+          case value
+          when Symbol
+            levels.index(value) or raise ArgumentError, "#{value.inspect} is not a level of #{question.key}"
+          when Numeric then value.to_f
+          else raise ArgumentError, "rate stub must be a level symbol or a position"
+          end
+        nearest = position.round.clamp(0, levels.size - 1)
+        probabilities = levels.each_index.to_h { |i| [i.to_s, i == nearest ? 1.0 : 0.0] }
+        { "type" => "score", "score" => position.to_f, "probabilities" => probabilities, "confidence" => 1.0 }
+      end
+    end
+  end
+end

data/lib/hunch/configuration.rb

@@ -0,0 +1,46 @@
+module Hunch
+  class Configuration
+    LEVELS = { possible: 0.25, likely: 0.5, probable: 0.75, almost_certain: 0.93 }.freeze
+
+    attr_accessor :api_key, :model, :url, :timeout, :open_timeout, :max_retries, :levels
+    attr_writer :backend
+
+    def initialize
+      @api_key = ENV["TYPESAFE_API_KEY"]
+      @model = "jev-latest"
+      @url = "https://api.typesafe.ai/v1/systemone"
+      @timeout = 5
+      @open_timeout = 2
+      @max_retries = 2
+      @levels = LEVELS.dup
+      @backend = nil
+    end
+
+    def resolve_level(value)
+      case value
+      when Numeric then value.to_f
+      when Symbol
+        levels.fetch(value) do
+          raise ConfigurationError, "unknown level #{value.inspect}; known levels: #{levels.keys.join(", ")}"
+        end
+      else
+        raise ArgumentError, "at_least must be a number or a level name"
+      end
+    end
+
+    def backend
+      @backend = resolve(@backend)
+    end
+
+    private
+
+    def resolve(backend)
+      case backend
+      when nil, :jev then Backends::Jev.new(self)
+      when :stub then Backends::Stub.new
+      when Symbol then raise ConfigurationError, "unknown backend #{backend.inspect}"
+      else backend
+      end
+    end
+  end
+end

data/lib/hunch/decision.rb

@@ -0,0 +1,41 @@
+module Hunch
+  class Decision
+    attr_reader :questions
+
+    def initialize
+      @questions = {}
+    end
+
+    def likely?(key, question, yes: nil, no: nil, over: 0.5)
+      threshold = Hunch.configuration.resolve_level(over)
+      add Questions::Noul.new(key: key.to_sym, question:, yes:, no:, threshold:)
+    end
+
+    def pick(key, *options, question: nil, **described)
+      all = describe(options, described)
+      raise ArgumentError, "pick needs at least two options" if all.size < 2
+
+      add Questions::Choice.new(key: key.to_sym, question:, options: all)
+    end
+
+    def rate(key, *levels, question: nil, **described)
+      all = describe(levels, described)
+      raise ArgumentError, "rate needs at least two levels" if all.size < 2
+
+      add Questions::Rate.new(key: key.to_sym, question:, levels: all)
+    end
+
+    private
+
+    def describe(bare, described)
+      bare.to_h { |name| [name.to_sym, name.to_s.tr("_", " ")] }.merge(described)
+    end
+
+    def add(question)
+      raise ArgumentError, "duplicate question key #{question.key}" if @questions.key?(question.key)
+
+      @questions[question.key] = question
+      self
+    end
+  end
+end

data/lib/hunch/errors.rb

@@ -0,0 +1,23 @@
+module Hunch
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class ValidationError < Error; end
+  class APIError < Error; end
+  class ServerError < APIError; end
+  class OverloadedError < APIError; end
+  class TimeoutError < APIError; end
+  class ConnectionError < APIError; end
+
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = "rate limited", retry_after: nil)
+      super(message)
+      @retry_after = retry_after
+    end
+  end
+
+  class MissingStubAnswer < Error; end
+end

data/lib/hunch/questions.rb

@@ -0,0 +1,37 @@
+module Hunch
+  module Questions
+    Noul = Data.define(:key, :question, :yes, :no, :threshold) do
+      def type = :noul
+
+      def payload
+        criteria = { "true" => yes, "false" => no }.compact
+        base = { "type" => "noul", "instructions" => question }
+        criteria.empty? ? base : base.merge("criteria" => criteria)
+      end
+    end
+
+    Choice = Data.define(:key, :question, :options) do
+      def type = :choice
+
+      def payload
+        {
+          "type" => "choice",
+          "instructions" => question || "Which of these best describes the state?",
+          "criteria" => options.transform_keys(&:to_s)
+        }
+      end
+    end
+
+    Rate = Data.define(:key, :question, :levels) do
+      def type = :rate
+
+      def payload
+        {
+          "type" => "score",
+          "instructions" => question || "Where does the state sit on this scale?",
+          "criteria" => levels.values
+        }
+      end
+    end
+  end
+end

data/lib/hunch/rating.rb

@@ -0,0 +1,39 @@
+module Hunch
+  class Rating
+    include Comparable
+
+    attr_reader :position, :levels, :probabilities, :confidence
+
+    def initialize(position:, levels:, probabilities:, confidence: nil)
+      @position = position.to_f
+      @levels = levels.freeze
+      @probabilities = probabilities.freeze
+      @confidence = confidence
+    end
+
+    def level
+      levels[position.round.clamp(0, levels.size - 1)]
+    end
+
+    def <=>(other)
+      case other
+      when Rating then position <=> other.position
+      when Numeric then position <=> other
+      when Symbol
+        index = levels.index(other)
+        index && position <=> index
+      end
+    end
+
+    def ==(other)
+      other.is_a?(Symbol) ? level == other : super
+    end
+
+    def to_sym = level
+    def to_f = position
+
+    def inspect
+      "#<Hunch::Rating #{level} (#{position.round(2)})>"
+    end
+  end
+end

data/lib/hunch/result.rb

@@ -0,0 +1,65 @@
+module Hunch
+  class Result
+    attr_reader :model, :usage
+
+    def initialize(questions:, answers:, model: nil, usage: nil)
+      @model = model
+      @usage = usage
+      @values = {}
+      questions.each do |key, question|
+        raw = answers[key.to_s] || answers[key]
+        raise Error, "backend returned no answer for #{key}" unless raw
+
+        build(key, question, raw)
+      end
+    end
+
+    def [](key)
+      @values.fetch(key.to_sym)
+    end
+
+    def to_h = @values.dup
+
+    private
+
+    def build(key, question, raw)
+      case question.type
+      when :noul then build_noul(key, question, raw)
+      when :choice then build_choice(key, raw)
+      when :rate then build_rate(key, question, raw)
+      end
+    end
+
+    def build_noul(key, question, raw)
+      probability = raw["noul"].to_f
+      set(key, probability)
+      define(:"#{key}?") { probability >= question.threshold }
+    end
+
+    def build_choice(key, raw)
+      probabilities = (raw["probabilities"] || {}).transform_keys(&:to_sym)
+      choice = raw["choice"]&.to_sym || probabilities.max_by { |_, p| p }&.first
+      set(key, choice)
+      define(:"#{key}_probabilities") { probabilities }
+      define(:"#{key}_confidence") { raw["confidence"] }
+    end
+
+    def build_rate(key, question, raw)
+      levels = question.levels.keys
+      by_index = raw["probabilities"] || {}
+      probabilities = levels.each_with_index.to_h do |level, i|
+        [level, (by_index[i.to_s] || by_index[i] || 0.0).to_f]
+      end
+      set(key, Rating.new(position: raw["score"], levels:, probabilities:, confidence: raw["confidence"]))
+    end
+
+    def set(key, value)
+      @values[key.to_sym] = value
+      define(key.to_sym) { value }
+    end
+
+    def define(name, &block)
+      define_singleton_method(name, &block)
+    end
+  end
+end

data/lib/hunch/version.rb

@@ -0,0 +1,3 @@
+module Hunch
+  VERSION = "0.1.0"
+end

data/lib/hunch.rb

@@ -0,0 +1,82 @@
+require_relative "hunch/version"
+require_relative "hunch/errors"
+require_relative "hunch/questions"
+require_relative "hunch/rating"
+require_relative "hunch/decision"
+require_relative "hunch/result"
+require_relative "hunch/configuration"
+require_relative "hunch/backends/jev"
+require_relative "hunch/backends/stub"
+
+module Hunch
+  class << self
+    def configure
+      yield configuration
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+
+    def backend=(backend)
+      configuration.backend = backend
+    end
+
+    def decide(given:)
+      decision = Decision.new
+      yield decision
+      raise ArgumentError, "decide needs at least one question" if decision.questions.empty?
+
+      raw = configuration.backend.decide(state: given, questions: decision.questions, model: configuration.model)
+      Result.new(
+        questions: decision.questions,
+        answers: raw["answers"] || {},
+        model: raw["model"],
+        usage: raw["usage"]
+      )
+    end
+
+    def chance(question, given:, yes: nil, no: nil)
+      decide(given:) { |q| q.likely?(:answer, question, yes:, no:) }.answer
+    end
+
+    Configuration::LEVELS.each_key do |level|
+      define_method(:"#{level}?") do |question, given:, yes: nil, no: nil|
+        chance(question, given:, yes:, no:) >= configuration.levels.fetch(level)
+      end
+    end
+
+    def pick(*options, given:, question: nil, **described)
+      decide(given:) { |q| q.pick(:answer, *options, question:, **described) }.answer
+    end
+
+    def rate(*levels, given:, question: nil, **described)
+      decide(given:) { |q| q.rate(:answer, *levels, question:, **described) }.answer
+    end
+
+    private
+
+    def custom_level(name)
+      return unless name.to_s.end_with?("?")
+
+      level = name.to_s.delete_suffix("?").to_sym
+      configuration.levels.key?(level) ? level : nil
+    end
+
+    def method_missing(name, *args, **options, &block)
+      level = custom_level(name)
+      return super unless level
+
+      chance(*args, **options) >= configuration.levels.fetch(level)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      !custom_level(name).nil? || super
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: hunch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carl Dawson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'likely?, pick, and score: three primitives that let Ruby branch on judgment
+  calls, answered by TypeSafe''s Jev System One model or any backend you plug in.'
+email:
+- carldawson@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/hunch.rb
+- lib/hunch/backends/jev.rb
+- lib/hunch/backends/stub.rb
+- lib/hunch/configuration.rb
+- lib/hunch/decision.rb
+- lib/hunch/errors.rb
+- lib/hunch/questions.rb
+- lib/hunch/rating.rb
+- lib/hunch/result.rb
+- lib/hunch/version.rb
+homepage: https://github.com/carldaws/hunch
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/carldaws/hunch
+  source_code_uri: https://github.com/carldaws/hunch
+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: 4.0.18
+specification_version: 4
+summary: Probabilistic control flow for Ruby
+test_files: []