vangrail 0.1.0 → 0.2.0

data/lib/vangrail/engine.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative 'assessor'
 require_relative 'errors'
 require_relative 'rail'
 require_relative 'result'
 require_relative 'result_cache'
+require_relative 'screening'
 
 module Vangrail
   # Runs ordered rails over text and reports one Result.
@@ -21,6 +23,9 @@ module Vangrail
   # about: a redaction rail that runs before a policy rail should have the
   # policy rail judge the redacted text, not the original.
   class Engine
+    Screening = Vangrail::Screening
+    Triage = Vangrail::Triage
+
     attr_reader :input_rails, :context_rails, :output_rails, :on_error, :cache
 
     def initialize(input: [], context: [], output: [], on_error: :allow, cache: true)
@@ -46,57 +51,18 @@ module Vangrail
       run(:context, context_rails, text, context)
     end
 
-    # Screens a set of retrieved documents and reports what survived.
-    #
-    # A document that fails is dropped rather than failing the whole turn. One
-    # poisoned wiki page should cost a reader that page, not their answer, and
-    # an application that refuses outright teaches its readers that the
-    # guardrail is the problem.
-    def screen(documents, **context)
-      kept = []
-      rejected = []
-      uncertain = nil
+    def screen(...) = Screening.run(self, ...)
 
-      Array(documents).each_with_index do |document, index|
-        result = check_context(text_of(document), **context, document: document, index: index)
-        uncertain ||= result unless result.certain?
-        if result.blocked?
-          rejected << { document: document, result: result }
-        else
-          kept << (result.modified? ? replace_text(document, result.content) : document)
-        end
-      end
-
-      Screening.new(kept: kept, rejected: rejected, certain: uncertain.nil?, reason: uncertain&.reason)
-    end
+    def assess(...) = Assessor.new(self).assess(...)
 
-    # What screen returns. `certain` means what it means on a Result: false says
-    # a rail did not reach a decision about some document, so "nothing was
-    # rejected" is not evidence that nothing was wrong.
-    Screening = Struct.new(:kept, :rejected, :certain, :reason, keyword_init: true) do
-      def certain?
-        certain
-      end
-
-      def rejected?
-        !rejected.empty?
-      end
-
-      def to_h
-        {
-          'kept' => kept.size,
-          'rejected' => rejected.map { |r| r[:result].to_h },
-          'certain' => certain?,
-          'reason' => reason
-        }.compact
-      end
-    end
+    def triage(...) = Assessor.new(self).triage(...)
 
     def rails(side)
       case side.to_sym
       when :input then input_rails
       when :context then context_rails
-      else output_rails
+      when :output then output_rails
+      else raise ArgumentError, "unknown side: #{side}"
       end
     end
 
@@ -122,7 +88,7 @@ module Vangrail
         'output' => rail_names(:output),
         'on_error' => on_error.to_s,
         'offline' => offline?,
-        'cache' => cache&.to_h
+        'cache' => cache&.to_h,
       }.compact
     end
 
@@ -138,28 +104,18 @@ module Vangrail
       parts.join(' ')
     end
 
-    private
-
-    def text_of(document)
-      return document.to_s unless document.is_a?(Hash)
-
-      (document['text'] || document[:text]).to_s
+    # Public so Assessor can run one rail without going through #run.
+    def invoke(rail, text, ctx)
+      memoized(rail, text, ctx) { call_rail(rail, text, ctx) }
     end
 
-    # A context rail may rewrite a document rather than reject it, so the
-    # replacement has to go back into the shape the caller passed in.
-    def replace_text(document, content)
-      return content.to_s unless document.is_a?(Hash)
-
-      key = document.key?('text') ? 'text' : :text
-      document.merge(key => content.to_s)
-    end
+    private
 
     def run(side, rails, text, context)
       return Result.unchecked(rail: side, reason: "no #{side} rails configured") if rails.empty?
 
       ctx = context.merge(side: side)
-      current = text.to_s
+      current = text
       modified_by = nil
       uncertain = nil
       unbuilt = nil
@@ -176,7 +132,7 @@ module Vangrail
         end
         next if result.certain?
 
-        # A rail that ran and could not decide says more than one that was
+        # A rail that ran and could not decide says more than a rail that was
         # never built, so its reason is the one the caller sees. Without this,
         # a placeholder earlier in the list reports "no endpoint was resolved"
         # over the rail that actually tried and had the connection refused.
@@ -200,10 +156,6 @@ module Vangrail
       Result.passed(rail: side)
     end
 
-    def invoke(rail, text, ctx)
-      memoized(rail, text, ctx) { call_rail(rail, text, ctx) }
-    end
-
     def call_rail(rail, text, ctx)
       result = rail.call(text, ctx)
       return result if result.is_a?(Result)
@@ -211,6 +163,11 @@ module Vangrail
       raise ProtocolError, "#{rail.name} returned #{result.class}, expected Vangrail::Result"
     rescue Error => e
       failed(rail, e)
+    rescue ArgumentError, EncodingError => e
+      # A rail that could not read the bytes is a rail that did not answer.
+      # Rail#call scrubs first; a rail doing its own decoding can still get
+      # here, and it must not take the turn with it.
+      failed(rail, e)
     end
 
     # A rail that raised did not answer. Which way that falls is the operator's
@@ -228,13 +185,15 @@ module Vangrail
     # Cache keys carry everything the decision depends on. A rail says what that
     # is through `cache_key`; nil means the rail is not memoizable, which is the
     # right answer for anything reading passages or history.
-    def memoized(rail, text, ctx, &block)
-      return block.call unless cache
+    def memoized(rail, text, ctx, &)
+      return yield unless cache
 
-      key = rail.respond_to?(:cache_key) ? rail.cache_key(text, ctx) : nil
-      return block.call if key.nil?
+      # Key the readable form. Raw bytes can carry a NUL or a wrong tag
+      # and would store the same decision under two keys.
+      key = rail.cache_key(Rail.usable(text), ctx)
+      return yield if key.nil?
 
-      cache.fetch(ctx[:side], rail.name, key, &block)
+      cache.fetch(ctx[:side], rail.name, key, &)
     end
   end
 end

data/lib/vangrail/errors.rb

@@ -40,9 +40,14 @@ module Vangrail
   # report checks it is not performing.
   class ColangError < Error; end
 
-  # A flow referred to an action or a bot message that nothing defines.
+  # A flow called an action that is not in the registry. Raised at execute.
   class UnknownAction < ColangError; end
 
   # The configuration folder is missing something the rails it declares need.
   class ConfigError < Error; end
+
+  # A span was offered to a slot its origin cannot occupy: data in the
+  # instruction, or a privileged cell in a passage fence. The cut is
+  # the type system; this is what raising looks like when it is crossed.
+  class PrivilegeError < Error; end
 end

data/lib/vangrail/evidence.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require_relative 'beta'
+
+module Vangrail
+  # One rail's measured operating point, read as evidence rather than as a
+  # verdict.
+  #
+  # Every rail in this gem answers a yes-or-no question, and the engine combines
+  # those answers by taking the first "yes". That is what the published defences
+  # do too, and it throws away almost everything the rails know. It cannot say
+  # how much a hit is worth, cannot add up three near misses, and cannot tell an
+  # operator what a block actually means about the text.
+  #
+  # What a hit is worth is a ratio, and it is measurable: how much likelier this
+  # rail is to fire on an attack than on ordinary documentation. That number,
+  # the likelihood ratio, is all a rail needs to contribute to a shared
+  # judgement, and it is exactly what the corpora in this repository already
+  # measure. Every entry here comes from running a rail over the same attack and
+  # benign sets as every other rail, which is what makes the numbers comparable
+  # in the first place: a detection rate measured on one paper's corpus and a
+  # false-positive rate measured on another's cannot be combined at all.
+  #
+  # Rates are smoothed with the Jeffreys prior, (hits + 1/2) / (n + 1), for a
+  # reason that is not decoration. A rail that caught 60 of 60 has an unsmoothed
+  # detection rate of exactly 1, an unsmoothed likelihood ratio of infinity, and
+  # would single-handedly decide every judgement it appears in on the strength
+  # of a sixty-item corpus. Smoothing keeps the evidence finite and proportional
+  # to how much was actually measured.
+  Evidence = Struct.new(:rail, :attacks_caught, :attacks, :benign_flagged, :benign, :group,
+                        keyword_init: true) do
+    # Probability the rail fires given the text is an attack.
+    def detection
+      (attacks_caught + 0.5) / (attacks + 1.0)
+    end
+
+    # Probability it fires given the text is ordinary.
+    def false_alarm
+      (benign_flagged + 0.5) / (benign + 1.0)
+    end
+
+    # How much likelier a hit is on an attack than on ordinary text.
+    def ratio_fired
+      detection / false_alarm
+    end
+
+    # And how much likelier silence is on ordinary text than on an attack. This
+    # is the half that OR-combination cannot express at all: a sensitive rail
+    # staying quiet is evidence too, and it points the other way.
+    def ratio_silent
+      (1 - detection) / (1 - false_alarm)
+    end
+
+    # The rates a corpus this size can actually defend, rather than the ones it
+    # happens to have produced.
+    #
+    # A rail that fired on none of 48 benign texts has a point estimate of one
+    # in a hundred and a 95% upper bound of one in twenty-six. The difference is
+    # two bits of evidence that nobody measured, and reporting the point
+    # estimate spends them.
+    #
+    # Pessimistic on both sides at once: detection at the low end of its
+    # posterior and false alarms at the high end. That single operating point is
+    # conservative for a hit and for silence alike, because both ratios move the
+    # same way under it.
+    # Memoised, because the bound is a function of counts that never change and
+    # the inverse of an incomplete beta is sixty bisections of a continued
+    # fraction. Computed once per entry per confidence level; the rails call it
+    # on every check.
+    def detection_bound(confidence)
+      bounds[[:detection, confidence]] ||=
+        Beta.quantile(1 - confidence, attacks_caught + 0.5, attacks - attacks_caught + 0.5)
+    end
+
+    def false_alarm_bound(confidence)
+      bounds[[:false_alarm, confidence]] ||=
+        Beta.quantile(confidence, benign_flagged + 0.5, benign - benign_flagged + 0.5)
+    end
+
+    def bounds
+      @bounds ||= {}
+    end
+
+    # Evidence in bits, positive towards attack. Bits rather than nats because
+    # an operator has to read these: one bit is a doubling of the odds, and
+    # "this rail is worth four bits" is a sentence somebody can act on.
+    #
+    # With a confidence, the bits are what the corpus can defend at that level
+    # rather than what it measured. A table built from a few hundred texts
+    # should be read this way; the point estimate is what it would say if the
+    # corpus were the world.
+    def bits(fired, confidence: nil)
+      return Math.log2(fired ? ratio_fired : ratio_silent) if confidence.nil?
+
+      detection = detection_bound(confidence)
+      false_alarm = false_alarm_bound(confidence)
+      Math.log2(fired ? detection / false_alarm : (1 - detection) / (1 - false_alarm))
+    end
+
+    # How much of the question this rail actually answers, at a given base rate.
+    #
+    # Detection and false-alarm rates describe a rail; they do not describe what
+    # it is worth in a deployment, because they say nothing about how often the
+    # thing being detected happens. The intrusion-detection literature settled
+    # this with an information-theoretic measure: the fraction of the
+    # uncertainty about "is this an attack" that the rail's verdict removes.
+    #
+    # Measured on the shipped table, the base rate costs every rail roughly two
+    # fifths of its capability between a balanced corpus and one attack in ten
+    # thousand: paraphrase falls from 0.52 to 0.28, and every other rail sits
+    # under 0.1 at both. many_shot manages 0.001, which is the honest reading of
+    # a rail that caught six of 270 because the corpus is mostly not its attack.
+    #
+    # Ranking rails by this rather than by detection rate is the point. It is
+    # the only number here that changes when the deployment does.
+    def capability(prior:)
+      return 0.0 unless measured?
+
+      mutual_information(prior) / entropy(prior)
+    end
+
+    def to_bits_h(prior:, confidence: nil)
+      {
+        'rail' => rail,
+        'bits_if_fired' => bits(true, confidence: confidence).round(2),
+        'bits_if_silent' => bits(false, confidence: confidence).round(2),
+        'capability' => capability(prior: prior).round(4),
+      }
+    end
+
+    # A rail that never fired on either corpus has measured nothing, whatever
+    # its detection rate looks like after smoothing.
+    def measured?
+      attacks.positive? && benign.positive?
+    end
+
+    def to_h
+      {
+        'rail' => rail, 'group' => group,
+        'attacks_caught' => attacks_caught, 'attacks' => attacks,
+        'benign_flagged' => benign_flagged, 'benign' => benign,
+        'detection' => detection.round(4), 'false_alarm' => false_alarm.round(4),
+        'bits_if_fired' => bits(true).round(2), 'bits_if_silent' => bits(false).round(2)
+      }
+    end
+
+    private
+
+    def entropy(prior)
+      -((prior * Math.log2(prior)) + ((1 - prior) * Math.log2(1 - prior)))
+    end
+
+    # I(X;Y) over the two-by-two table of truth against verdict.
+    def mutual_information(prior)
+      joint = [[prior * detection, prior * (1 - detection)],
+               [(1 - prior) * false_alarm, (1 - prior) * (1 - false_alarm)]]
+      fires = joint[0][0] + joint[1][0]
+      quiet = joint[0][1] + joint[1][1]
+      marginals = [[prior * fires, prior * quiet], [(1 - prior) * fires, (1 - prior) * quiet]]
+
+      joint.flatten.zip(marginals.flatten).sum do |cell, marginal|
+        next 0.0 if cell <= 0 || marginal <= 0
+
+        cell * Math.log2(cell / marginal)
+      end
+    end
+  end
+
+  # Combines rail evidence into a posterior probability that the text is an
+  # attack.
+  #
+  # The arithmetic is one line: odds after = odds before times every likelihood
+  # ratio. In bits it is addition, which is why the contributions of individual
+  # rails can be printed and read.
+  #
+  # Three things make this more than a formality, and all three are things the
+  # published defences leave on the floor.
+  #
+  # The prior is the deployment's, and it dominates. Detector papers evaluate on
+  # balanced corpora, where half the traffic is an attack; a documentation desk
+  # sees maybe one poisoned page in ten thousand. At that base rate a rail with
+  # a one percent false-alarm rate is wrong far more often than it is right when
+  # it fires, and no amount of detection rate fixes it. That is not a criticism
+  # of the rails: it is the arithmetic every operator inherits and almost none
+  # is shown.
+  #
+  # Abstention is evidence of nothing, which is different from evidence against.
+  # A rail that was off, unreachable, or undecided contributes no term at all,
+  # and this gem is unusual in knowing which rails those were: `certain?` is
+  # exactly that fact, and here it finally has arithmetic to feed.
+  #
+  # Correlated rails do not each get a vote. Three rails that fire on the same
+  # sentence for the same reason are one observation reported three times, and
+  # summing them is how naive Bayes talks itself into certainty. Rails measured
+  # to agree are grouped, and a group contributes once.
+  module Posterior
+    module_function
+
+    # Combines and returns [posterior, contributions].
+    #
+    # `observations` maps a rail name to true (fired), false (ran and did not
+    # fire), or nil (did not run). The nils are the point.
+    # `direct` carries rails that computed their own log-likelihood ratio rather
+    # than answering yes or no. A rail that can say how sure it is should not be
+    # flattened to one bit on the way in, and nothing about the arithmetic
+    # changes: bits are bits, whoever produced them.
+    # Defensible by default. The point estimate is what a corpus happened to
+    # produce and it is unreadable at the edges: a rail that caught none of the
+    # published attacks and fired on none of eighteen thousand documents scores
+    # +7 bits on the point estimate, from two smoothing constants dividing each
+    # other, and -2.7 on the bound. The bound is the number that survives being
+    # measured against somebody else's corpus, so it is the one that runs.
+    DEFAULT_CONFIDENCE = 0.95
+
+    def combine(prior:, observations:, evidence: EvidenceData::TABLE, confidence: DEFAULT_CONFIDENCE,
+                direct: {})
+      raise ArgumentError, 'prior must be strictly between 0 and 1' unless prior.positive? && prior < 1
+
+      contributions = weigh(observations, evidence, confidence) + quantified(direct)
+      total = contributions.sum { |c| c[:bits] }
+      [from_odds(to_odds(prior) * (2**total)), contributions]
+    end
+
+    # One term per group rather than one per rail.
+    #
+    # Within a group, the firing rail with the most evidence speaks for the
+    # group; if none fired, the most sensitive member's silence speaks for it.
+    # Both rules pick the single most informative member, which is the
+    # conservative reading of a set of observations that are not independent.
+    def weigh(observations, evidence, confidence = nil)
+      seen = observations.filter_map do |rail, fired|
+        next if fired.nil?
+
+        entry = evidence[rail.to_s]
+        next unless entry&.measured?
+
+        { rail: rail.to_s, group: entry.group || rail.to_s, fired: fired, entry: entry }
+      end
+
+      seen.group_by { |o| o[:group] }.map { |group, members| speak_for(group, members, confidence) }
+    end
+
+    def speak_for(group, members, confidence = nil)
+      fired = members.select { |m| m[:fired] }
+      chosen = if fired.empty?
+                 members.max_by { |m| m[:entry].detection }
+               else
+                 fired.max_by { |m| m[:entry].bits(true, confidence: confidence) }
+               end
+
+      {
+        group: group,
+        rail: chosen[:rail],
+        fired: chosen[:fired],
+        bits: chosen[:entry].bits(chosen[:fired], confidence: confidence),
+        spoke_for: members.map { |m| m[:rail] },
+      }
+    end
+
+    # How many bits it takes to get from a base rate to a target confidence.
+    #
+    # This is the number the whole design turns on, and it is worth being able
+    # to compute rather than assert. Reaching an even-money posterior from one
+    # attack in ten thousand takes about 13.3 bits, and no rail in this gem is
+    # worth half that, which is a statement about what a single detector can
+    # honestly justify rather than about these particular rails.
+    def required_bits(prior:, target: 0.5)
+      Math.log2(to_odds(target) / to_odds(prior))
+    end
+
+    # The false-alarm rate a single rail would need to carry a block on its own.
+    #
+    # Rearranged from the same identity: at base rate `prior`, one rail with
+    # detection `detection` reaches `target` only if it almost never fires on
+    # ordinary text. The answers come out in the region of one in ten thousand,
+    # which is below what any hand-built benign corpus can demonstrate: showing
+    # a rate that low needs tens of thousands of clean documents on which the
+    # rail stayed silent.
+    #
+    # That is the practical case for combining rails rather than trusting one,
+    # and it is an argument about evidence rather than about taste.
+    def false_alarm_needed(prior:, detection: 0.75, target: 0.5)
+      detection / (to_odds(target) / to_odds(prior))
+    end
+
+    def quantified(direct)
+      direct.map do |rail, bits|
+        { group: rail.to_s, rail: rail.to_s, fired: bits.positive?, bits: bits.to_f,
+          spoke_for: [rail.to_s], quantified: true }
+      end
+    end
+
+    def to_odds(probability)
+      probability / (1 - probability)
+    end
+
+    def from_odds(odds)
+      return 1.0 if odds.infinite?
+
+      odds / (1 + odds)
+    end
+  end
+end

data/lib/vangrail/evidence_data.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'evidence'
+
+module Vangrail
+  # What each rail is worth as evidence, measured on corpora written by other
+  # people.
+  #
+  # GENERATED FILE. Do not edit by hand; rerun script/measure_evidence_external.rb.
+  # The arithmetic that reads this table lives in evidence.rb, which is
+  # hand-written and survives regeneration.
+  #
+  # One benign source per side; the attack population is stated.
+  #
+  # Context: 125 published BIPIA injections spliced into installed
+  # documentation, plus 120 attacks from this repository's own corpus, against
+  # 18258 real documents from the same machine. Two attack families on
+  # purpose: BIPIA's off-task instructions, which no deterministic rail here
+  # catches, and the override-and-disclosure family the rails were built for,
+  # which the shipped corpus covers and which nobody else's benchmark does.
+  # The ratio is 125:120 and a deployment whose traffic is not that mix
+  # should reweight it and rerun the script.
+  #
+  # Input: 1405 in-the-wild jailbreak prompts against the
+  # 13735 ordinary prompts collected beside them.
+  #
+  # Read the context numbers before trusting anything built on them. Every
+  # deterministic rail catches none of the published injections, because BIPIA's
+  # attacks are off-task instructions carrying no override, no disclosure, and
+  # no concealment, and those three are all these rails know how to find. A
+  # rail that fires on a document under this measurement is reporting a false
+  # alarm more often than an attack, and the sign of its evidence says so.
+  #
+  # That is a statement about a threat model, not a verdict on the rails: the
+  # corpus this repository wrote scores them at 60 of 60, because it was
+  # written out of the same idea of an attack. Both numbers are real and
+  # neither is the answer on its own.
+  module EvidenceData
+    CONTEXT = [
+        Evidence.new(rail: "injected_instructions", group: "injected_instructions",
+                     attacks_caught: 58, attacks: 245,
+                     benign_flagged: 48, benign: 18258),
+        Evidence.new(rail: "jailbreak", group: "jailbreak",
+                     attacks_caught: 10, attacks: 245,
+                     benign_flagged: 20, benign: 18258),
+        Evidence.new(rail: "paraphrase", group: "paraphrase",
+                     attacks_caught: 61, attacks: 245,
+                     benign_flagged: 236, benign: 18258),
+        Evidence.new(rail: "alignment", group: "alignment",
+                     attacks_caught: 12, attacks: 245,
+                     benign_flagged: 24, benign: 18258),
+        Evidence.new(rail: "similarity", group: "similarity",
+                     attacks_caught: 12, attacks: 245,
+                     benign_flagged: 0, benign: 18258),
+        Evidence.new(rail: "many_shot", group: "many_shot",
+                     attacks_caught: 0, attacks: 245,
+                     benign_flagged: 2, benign: 18258),
+        Evidence.new(rail: "obfuscation", group: "obfuscation",
+                     attacks_caught: 60, attacks: 245,
+                     benign_flagged: 59, benign: 18258),
+        Evidence.new(rail: "hidden", group: "hidden",
+                     attacks_caught: 5, attacks: 245,
+                     benign_flagged: 0, benign: 18258),
+        Evidence.new(rail: "bayes", group: "bayes",
+                     attacks_caught: 100, attacks: 245,
+                     benign_flagged: 1617, benign: 18258)
+    ].freeze
+
+    INPUT = [
+        Evidence.new(rail: "injection_patterns", group: "injection_patterns",
+                     attacks_caught: 35, attacks: 1405,
+                     benign_flagged: 730, benign: 13735),
+        Evidence.new(rail: "jailbreak", group: "jailbreak",
+                     attacks_caught: 190, attacks: 1405,
+                     benign_flagged: 134, benign: 13735),
+        Evidence.new(rail: "paraphrase", group: "paraphrase",
+                     attacks_caught: 486, attacks: 1405,
+                     benign_flagged: 1666, benign: 13735),
+        Evidence.new(rail: "alignment", group: "alignment",
+                     attacks_caught: 160, attacks: 1405,
+                     benign_flagged: 998, benign: 13735),
+        Evidence.new(rail: "similarity", group: "similarity",
+                     attacks_caught: 127, attacks: 1405,
+                     benign_flagged: 857, benign: 13735),
+        Evidence.new(rail: "many_shot", group: "many_shot",
+                     attacks_caught: 10, attacks: 1405,
+                     benign_flagged: 34, benign: 13735),
+        Evidence.new(rail: "obfuscation", group: "obfuscation",
+                     attacks_caught: 248, attacks: 1405,
+                     benign_flagged: 440, benign: 13735),
+        Evidence.new(rail: "bayes", group: "bayes",
+                     attacks_caught: 340, attacks: 1405,
+                     benign_flagged: 1715, benign: 13735)
+    ].freeze
+
+    ENTRIES = (CONTEXT + INPUT).freeze
+
+    BY_SIDE = {
+      context: CONTEXT.to_h { |entry| [entry.rail, entry] }.freeze,
+      input: INPUT.to_h { |entry| [entry.rail, entry] }.freeze
+    }.freeze
+
+    # A rail's operating point depends on which side it runs on, by a lot: the
+    # same rail is worth different evidence reading a retrieved document and
+    # reading a question. The default is the input table because that is the
+    # side with a detection measurement worth having.
+    TABLE = BY_SIDE[:input]
+
+    def self.for_side(side)
+      BY_SIDE[side.to_sym] || TABLE
+    end
+  end
+end

data/lib/vangrail/http.rb

@@ -12,8 +12,22 @@ module Vangrail
     DEFAULT_OPEN_TIMEOUT = 5
     DEFAULT_READ_TIMEOUT = 30
 
+    # retries is a switch, not a count: 0 means no retry, any positive value
+    # retries TransportError once. HTTPError (including 429) is never retried
+    # and never slept on; a rail that waits is a rail that hangs the request.
     attr_reader :base_url, :open_timeout, :read_timeout, :retries
 
+    # Chat, Embeddings, Completion, and Client all take an HTTP or the
+    # arguments that build one. One helper so those constructors stay thin.
+    def self.build(http: nil, base_url: nil, api_key: nil,
+                   open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+                   missing: 'a client needs a base_url or an http client')
+      return http if http
+      raise ArgumentError, missing if base_url.to_s.strip.empty?
+
+      new(base_url: base_url, api_key: api_key, open_timeout: open_timeout, read_timeout: read_timeout)
+    end
+
     def initialize(base_url:, api_key: nil, open_timeout: DEFAULT_OPEN_TIMEOUT,
                    read_timeout: DEFAULT_READ_TIMEOUT, retries: 1, headers: {})
       @base_url = base_url.to_s.sub(/\/+\z/, '')
@@ -49,20 +63,11 @@ module Vangrail
 
     def request(klass, path, payload)
       uri = URI.join("#{base_url}/", path.to_s.sub(/\A\/+/, ''))
-      attempt = 0
-      begin
-        attempt += 1
-        perform(klass, uri, payload)
-      rescue TransportError, HTTPError => e
-        raise unless attempt <= retries && retryable?(e)
-
-        sleep(0.25 * attempt)
-        retry
-      end
-    end
+      perform(klass, uri, payload)
+    rescue TransportError
+      raise if retries < 1
 
-    def retryable?(error)
-      error.is_a?(TransportError) || error.retryable?
+      perform(klass, uri, payload)
     end
 
     def perform(klass, uri, payload)