hunch 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 385258ecd737c836bd9b677e023cbc5ffc653770ee046aba43aeeac3225c8cc2
-  data.tar.gz: 335bd7011b904736715d5490ca56645ce9a012faf7aff0fd485929d8ec5e5cf3
+  metadata.gz: e7f094c2b401f7331d45ca78228ceec41c45aacd76104ca3af0a9bf7708362f4
+  data.tar.gz: 57450f766b733602126cf65e128aa98245926a7b73679c5684f9aacd6e824d47
 SHA512:
-  metadata.gz: 05473ca9fbca95957fecd251d2dc53ee239f5e12b4b579846dbccf20c92f78a36ee0d4697b5a410ef89ddf406829e85bcead5aa0361307e32a3eb97984f9fd98
-  data.tar.gz: 9e50657e98f6e290fe96f08e161416ead241aae674dad5a9862c38eaac60232fc3fb314f60ae0cbee342f3d51b71fa2e5d8a0ce7cfb2eaaafa9411cb3fb08ca0
+  metadata.gz: bbef66e803a4362cc7e72f52096d01f412060ddb2d68fb7fd8b79172de9acb335ddd724a0b0d566b8c3a497d36779ff9c1f5fb8e31c0d17680d6038b50f69293
+  data.tar.gz: 99ccaed307b8501dd8ea9ecc1aab28dcaf6d86accb24e79a2107caf0e3971dfd354c17ea5a157211a738b1fae74665a8cc98cb95f6fa0049b2068ba3e7f793c3

data/README.md

@@ -2,9 +2,8 @@
 
 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:
+Hunch lets you ask questions about text or application data and use the
+answers in your Ruby code.
 
 ```ruby
 if Hunch.almost_certainly?("this order is fraudulent", given: order.attributes)
@@ -12,10 +11,11 @@ if Hunch.almost_certainly?("this order is fraudulent", given: order.attributes)
 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.
+You can get a probability, choose between options, or rate something on a
+scale. Questions are written in plain English; answers come back as Ruby values.
+
+Hunch asks a System One model, such as [TypeSafe's Jev](https://typesafe.ai),
+which answers with calibrated probabilities rather than text.
 
 ## Installation
 
@@ -23,21 +23,29 @@ instead of text — fast and cheap enough to sit inside a request cycle.
 gem "hunch"
 ```
 
+Point Hunch at a System One endpoint. Jev is available through
+[OpenRouter](https://openrouter.ai/typesafe):
+
 ```ruby
+# config/initializers/hunch.rb
 Hunch.configure do |config|
-  config.api_key = ENV["TYPESAFE_API_KEY"]
+  config.backend = Hunch::Backends::SystemOne.new(
+    url: "https://openrouter.ai/api/alpha/decisions",
+    api_key: ENV["OPENROUTER_API_KEY"],
+    model: "typesafe/jev-1.13"
+  )
 end
 ```
 
-## The three primitives
+## Usage
 
-**`chance`** answers _whether_, as a probability:
+**`chance`** returns a probability between 0 and 1:
 
 ```ruby
 Hunch.chance("written by a real human, not spam", given: bio)  # => 0.87
 ```
 
-Named levels collapse it into predicates:
+Use a named threshold when you want a boolean:
 
 ```ruby
 Hunch.possibly?("fraudulent", given: order)         # chance >= 0.25
@@ -45,14 +53,14 @@ Hunch.likely?("fraudulent", given: order)           # chance >= 0.5
 Hunch.probably?("fraudulent", given: order)         # chance >= 0.75
 Hunch.almost_certainly?("fraudulent", given: order) # chance >= 0.93
 
-Hunch.configure { |c| c.levels[:paranoid] = 0.99 }
-Hunch.paranoid?("fraudulent", given: order)        # chance >= 0.99
+Hunch.configure { |c| c.levels[:definitely] = 0.99 }
+Hunch.definitely?("fraudulent", given: order)        # chance >= 0.99
 ```
 
 Configure built-in thresholds with the matching level names, for example
 `Hunch.configure { |c| c.levels[:probably] = 0.8 }`.
 
-**`pick`** answers _which_:
+**`pick`** chooses one of the options you provide:
 
 ```ruby
 Hunch.pick(:ham, :spam, given: email)                                  # => :spam
@@ -60,7 +68,7 @@ Hunch.pick(urgent: "needs a reply today", routine: "can wait",
            given: ticket)                                              # => :routine
 ```
 
-**`rate`** answers _how much_, on an ordered scale:
+**`rate`** returns a rating with a position on an ordered scale:
 
 ```ruby
 mood = Hunch.rate(:calm, :frustrated, :livid, given: email)
@@ -69,14 +77,16 @@ 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.
+Use `pick` for categories such as billing, support, and sales. Use `rate`
+for ordered levels such as low, medium, and high.
+
+Both accept symbols or `symbol: "description"` pairs, or a mix of the two.
+Add `question:` if the options need more context. `given:` supplies the data
+to evaluate. These two keywords are reserved and can't be used as option names.
 
 ## Batching
 
-Several questions about one piece of state cost one API call:
+Use `Hunch.decide` to ask several questions about the same data in one API call:
 
 ```ruby
 result = Hunch.decide(given: mail.raw_source) do |q|
@@ -94,13 +104,11 @@ 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.
+The [`example/`](example) Rails app contains these examples and their tests.
 
 ### Validations
 
-A validation method is just an `if`:
+Check a display name and bio during validation:
 
 ```ruby
 class Signup < ApplicationRecord
@@ -136,13 +144,13 @@ 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.
+These validations rescue `Hunch::APIError`, so an API failure adds no
+validation error. Other validations, including the email presence check,
+still apply.
 
 ### Inbound email
 
-ActionMailbox routing without the regex graveyard:
+Route incoming email by its contents:
 
 ```ruby
 class SortingMailbox < ApplicationMailbox
@@ -162,7 +170,7 @@ end
 
 ### Error triage
 
-Replace the hand-maintained ignore-list with one judgment:
+Choose whether to ignore an error, send a notification, or page someone:
 
 ```ruby
 class ErrorTriage
@@ -189,7 +197,7 @@ end
 
 ### Job retries
 
-Exception classes don't tell you whether a failure is transient. Ask:
+Use the error message and attempt count to decide whether to retry:
 
 ```ruby
 class WebhookDeliveryJob < ApplicationJob
@@ -208,12 +216,9 @@ class WebhookDeliveryJob < ApplicationJob
 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:
+Map imported text to an existing enum value:
 
 ```ruby
 class Order < ApplicationRecord
@@ -249,21 +254,26 @@ end
 
 ## Testing
 
-The stub backend is just another backend:
+Use the stub backend to supply answers without making API calls:
 
 ```ruby
-Hunch.backend = Hunch::Backends::Stub.new(fraud: 0.95, team: :billing, mood: :calm)
+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:
+Use the question's key to supply its answer, or `:answer` for calls outside
+a `Hunch.decide` block. Stub values depend on the method:
+
+- `chance` and its predicates: a probability or boolean.
+- `pick`: a symbol or a hash of probabilities.
+- `rate`: a level symbol or numeric position.
+
+Missing answers raise unless you pass a fallback, as in
+`Hunch::Backends::Stub.new({}, fallback: 0.5)`. The stub records each call
+in `calls` for assertions.
 
 ```ruby
 test "spam is dropped without a ticket" do
-  Hunch.backend = Hunch::Backends::Stub.new(answer: :spam)
+  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
@@ -274,38 +284,32 @@ end
 
 ```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
+  config.backend = Hunch::Backends::SystemOne.new(
+    url: "https://openrouter.ai/api/alpha/decisions",
+    api_key: ENV["OPENROUTER_API_KEY"], # a missing key raises when you ask
+    model: "typesafe/jev-1.13",
+    timeout: 5,                         # seconds to read the response
+    open_timeout: 2,                    # seconds to connect
+    max_retries: 2                      # 429/5xx/timeouts, with backoff, honours Retry-After
+  )
+  config.levels[:definitely] = 0.99
 end
 ```
 
-### Via OpenRouter
+## Errors
 
-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
-```
+`Hunch::APIError` covers failures worth working around: timeouts, lost
+connections, rate limits, server errors, and answers the backend got wrong
+(`Hunch::InvalidAnswerError`). `AuthenticationError`, `ValidationError`, and
+`ConfigurationError` mean your setup needs fixing, so they are not
+`APIError`s.
 
-## Honesty about backends
+## 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.
+`Hunch::Backends::SystemOne` talks to any endpoint that speaks the System One
+decisions protocol of noul, choice, and score questions. `Hunch::Backends::Stub`
+is for [testing](#testing). A backend is any object with a
+`decide(state:, questions:)` method that returns `{ "answers" => ... }`.
 
 ## License
 

data/lib/hunch/backends/stub.rb

@@ -3,13 +3,13 @@ module Hunch
     class Stub
       attr_reader :calls
 
-      def initialize(default: nil, **answers)
+      def initialize(answers = {}, fallback: nil)
         @answers = answers
-        @default = default
+        @fallback = fallback
         @calls = []
       end
 
-      def decide(state:, questions:, model: nil)
+      def decide(state:, questions:)
         @calls << { state:, questions: }
         answers = questions.to_h do |key, question|
           [key.to_s, answer_for(key, question)]
@@ -20,10 +20,10 @@ module Hunch
       private
 
       def answer_for(key, question)
-        value = @answers.fetch(key, @default)
+        value = @answers.fetch(key, @fallback)
         if value.nil?
           raise MissingStubAnswer,
-            "no stubbed answer for #{key.inspect}: Stub.new(#{key}: ...) or pass default:"
+            "no stubbed answer for #{key.inspect}: Stub.new({ #{key}: ... }) or pass fallback:"
         end
 
         case question.type

data/lib/hunch/backends/{jev.rb → system_one.rb}

@@ -4,17 +4,24 @@ require "uri"
 
 module Hunch
   module Backends
-    class Jev
-      def initialize(config = Hunch.configuration, transport: nil, sleeper: nil)
-        @config = config
+    class SystemOne
+      def initialize(url:, api_key:, model:, timeout: 5, open_timeout: 2, max_retries: 2, transport: nil, sleeper: nil)
+        @url = url
+        @api_key = api_key
+        @model = model
+        @timeout = timeout
+        @open_timeout = open_timeout
+        @max_retries = max_retries
         @transport = transport || method(:http_post)
         @sleeper = sleeper || ->(seconds) { sleep(seconds) }
       end
 
-      def decide(state:, questions:, model: nil)
+      def decide(state:, questions:)
+        raise ConfigurationError, "no API key for #{@url}" if @api_key.nil? || @api_key.empty?
+
         payload = {
           "state" => state,
-          "model" => model || @config.model,
+          "model" => @model,
           "questions" => questions.to_h { |key, question| [key.to_s, question.payload] }
         }
         with_retries { handle(*@transport.call(payload)) }
@@ -28,7 +35,7 @@ module Hunch
           attempts += 1
           yield
         rescue RateLimitError, OverloadedError, ServerError, TimeoutError, ConnectionError => e
-          raise if attempts > @config.max_retries
+          raise if attempts > @max_retries
 
           @sleeper.call(e.respond_to?(:retry_after) && e.retry_after || backoff(attempts))
           retry
@@ -41,7 +48,7 @@ module Hunch
 
       def handle(status, headers, body)
         case status
-        when 200..299 then JSON.parse(body)
+        when 200..299 then 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))
@@ -51,6 +58,12 @@ module Hunch
         end
       end
 
+      def parse(body)
+        JSON.parse(body)
+      rescue JSON::ParserError, TypeError
+        raise APIError, "response was not valid JSON"
+      end
+
       def error_message(body, fallback)
         parsed = JSON.parse(body)
         error = parsed["error"] || parsed["message"] || fallback
@@ -65,9 +78,9 @@ module Hunch
       end
 
       def http_post(payload)
-        uri = URI(@config.url)
+        uri = URI(@url)
         request = Net::HTTP::Post.new(uri)
-        request["Authorization"] = "Bearer #{api_key!}"
+        request["Authorization"] = "Bearer #{@api_key}"
         request["Content-Type"] = "application/json"
         request["User-Agent"] = "hunch-ruby/#{VERSION}"
         request.body = JSON.generate(payload)
@@ -75,8 +88,8 @@ module Hunch
         response = Net::HTTP.start(
           uri.host, uri.port,
           use_ssl: uri.scheme == "https",
-          open_timeout: @config.open_timeout,
-          read_timeout: @config.timeout
+          open_timeout: @open_timeout,
+          read_timeout: @timeout
         ) { |http| http.request(request) }
 
         [response.code.to_i, response.each_header.to_h, response.body]
@@ -85,11 +98,6 @@ module Hunch
       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/configuration.rb

@@ -2,16 +2,10 @@ module Hunch
   class Configuration
     LEVELS = { possibly: 0.25, likely: 0.5, probably: 0.75, almost_certainly: 0.93 }.freeze
 
-    attr_accessor :api_key, :model, :url, :timeout, :open_timeout, :max_retries, :levels
+    attr_accessor :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
@@ -29,18 +23,8 @@ module Hunch
     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
+      @backend or raise ConfigurationError,
+        "no backend: Hunch.configure { |c| c.backend = Hunch::Backends::SystemOne.new(url:, api_key:, model:) }"
     end
   end
 end

data/lib/hunch/decision.rb

@@ -56,6 +56,9 @@ module Hunch
     end
 
     def add(question)
+      if Result::RESERVED_KEYS.include?(question.key)
+        raise ArgumentError, "#{question.key} is reserved on results; choose another key"
+      end
       raise ArgumentError, "duplicate question key #{question.key}" if @questions.key?(question.key)
 
       @questions[question.key] = question

data/lib/hunch/errors.rb

@@ -5,6 +5,7 @@ module Hunch
   class AuthenticationError < Error; end
   class ValidationError < Error; end
   class APIError < Error; end
+  class InvalidAnswerError < APIError; end
   class ServerError < APIError; end
   class OverloadedError < APIError; end
   class TimeoutError < APIError; end

data/lib/hunch/result.rb

@@ -1,5 +1,7 @@
 module Hunch
   class Result
+    RESERVED_KEYS = %i[model usage to_h].freeze
+
     attr_reader :model, :usage
 
     def initialize(questions:, answers:, model: nil, usage: nil)
@@ -8,7 +10,7 @@ module Hunch
       @values = {}
       questions.each do |key, question|
         raw = answers[key.to_s] || answers[key]
-        raise Error, "backend returned no answer for #{key}" unless raw
+        raise InvalidAnswerError, "backend returned no answer for #{key}" unless raw
 
         build(key, question, raw)
       end
@@ -25,26 +27,38 @@ module Hunch
     def build(key, question, raw)
       case question.type
       when :noul then build_noul(key, question, raw)
-      when :choice then build_choice(key, raw)
+      when :choice then build_choice(key, question, 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 }
+      probability = raw["noul"]
+      unless probability.is_a?(Numeric) && probability.between?(0, 1)
+        raise InvalidAnswerError, "#{key} needs a probability, got #{probability.inspect}"
+      end
+
+      set(key, probability.to_f)
+      define(:"#{key}?") { probability >= question.threshold } if question.threshold
     end
 
-    def build_choice(key, raw)
+    def build_choice(key, question, raw)
       probabilities = (raw["probabilities"] || {}).transform_keys(&:to_sym)
       choice = raw["choice"]&.to_sym || probabilities.max_by { |_, p| p }&.first
+      unless question.options.key?(choice)
+        raise InvalidAnswerError, "#{key} needs one of #{question.options.keys.join(", ")}, got #{choice.inspect}"
+      end
+
       set(key, choice)
       define(:"#{key}_probabilities") { probabilities }
       define(:"#{key}_confidence") { raw["confidence"] }
     end
 
     def build_rate(key, question, raw)
+      unless raw["score"].is_a?(Numeric) && raw["score"].finite?
+        raise InvalidAnswerError, "#{key} needs a position, got #{raw["score"].inspect}"
+      end
+
       levels = question.levels.keys
       by_index = raw["probabilities"] || {}
       probabilities = levels.each_with_index.to_h do |level, i|

data/lib/hunch/version.rb

@@ -1,3 +1,3 @@
 module Hunch
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/hunch.rb

@@ -5,7 +5,7 @@ require_relative "hunch/rating"
 require_relative "hunch/configuration"
 require_relative "hunch/decision"
 require_relative "hunch/result"
-require_relative "hunch/backends/jev"
+require_relative "hunch/backends/system_one"
 require_relative "hunch/backends/stub"
 
 module Hunch
@@ -32,17 +32,11 @@ module Hunch
       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"]
-      )
+      ask(decision.questions, given)
     end
 
     def chance(question, given:, yes: nil, no: nil)
-      decide(given:) { |q| q.likely?(:answer, question, yes:, no:) }.answer
+      ask({ answer: Questions::Noul.new(key: :answer, question:, yes:, no:, threshold: nil) }, given).answer
     end
 
     Configuration::LEVELS.each_key do |level|
@@ -61,6 +55,11 @@ module Hunch
 
     private
 
+    def ask(questions, state)
+      raw = configuration.backend.decide(state:, questions:)
+      Result.new(questions:, answers: raw["answers"] || {}, model: raw["model"], usage: raw["usage"])
+    end
+
     def custom_level(name)
       return unless name.to_s.end_with?("?")
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hunch
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Carl Dawson
@@ -20,8 +20,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/hunch.rb
-- lib/hunch/backends/jev.rb
 - lib/hunch/backends/stub.rb
+- lib/hunch/backends/system_one.rb
 - lib/hunch/configuration.rb
 - lib/hunch/decision.rb
 - lib/hunch/errors.rb