squishling 0.4.0 → 0.5.1

data/lib/squishling/invoker.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Squishling
-  # The elastic path: sends a squished method's inputs through RubyLLM with structured output.
+  # The elastic path: sends a squished method's inputs through the configured adapter with structured output.
   class Invoker
     INPUT_NOTE = <<~NOTE
       The input is a JSON object. "arguments" holds the values passed to this operation; "context", when
@@ -21,25 +21,45 @@ module Squishling
       @inputs = inputs
     end
 
+    # Everything a Run needs of the call: the prompt, the payload it was built from, and the purpose text.
+    Built = Data.define(:prompt, :payload, :purpose)
+
     # Runs the harness (Definition#harness) over a Run of the call: the harness decides how the escalation is
-    # used, and what it returns is checked against the output schema's type.
+    # used, and what it returns is checked against the output schema's type. A call that ends on the token budget
+    # or a disagreement is reported to squawk once here, as the stop no attempt of its own reported.
     def call
+      built = build
+      harness = @definition.harness
+      run = Run.new(definition: @definition, receiver: @receiver, inputs: @inputs, prompt: built.prompt,
+        payload: built.payload, purpose: built.purpose, harness:)
+      accepted(call_harness(harness, run), run, harness)
+    end
+
+    # The first request the call would make (system prompt, output schema, user message), without making it.
+    def prompt
+      build.prompt
+    end
+
+    private
+
+    def call_harness(harness, run)
+      harness.klass.new.call(run, **harness.options)
+    rescue BudgetExhaustedError, DisagreementError => e
+      run.report_stop(e)
+      raise
+    end
+
+    def build
       purpose = @definition.purpose(@receiver)
       schema = @definition.schema
       raise ConfigurationError, "#{@definition.label} has no purpose" if purpose.nil? || purpose.empty?
       raise ConfigurationError, "#{@definition.label} has no output_schema" unless schema
 
-      harness = @definition.harness
       body = payload
-      prompt = Prompt.new(instructions: "#{purpose}\n\n#{INPUT_NOTE}", schema:,
-        input: JSON.generate(body), role: nil)
-      run = Run.new(definition: @definition, receiver: @receiver, inputs: @inputs, prompt:, payload: body, purpose:,
-        harness:)
-      accepted(harness.klass.new.call(run, **harness.options), run, harness)
+      prompt = Prompt.new(instructions: "#{purpose}\n\n#{INPUT_NOTE}", schema:, input: JSON.generate(body), role: nil)
+      Built.new(prompt:, payload: body, purpose:)
     end
 
-    private
-
     # What a harness returns must be a result its run produced: validated output, typed like the deterministic
     # path's. One built by hand, or a hash, would skip the schema and squish_validate.
     def accepted(value, run, harness)
@@ -58,16 +78,26 @@ module Squishling
     end
 
     # Exceptions are sent as their class and message. Plain JSON would send only the message, and with
-    # json/add/exception loaded it would also send the backtrace, which exposes file paths.
-    def describe(value)
+    # json/add/exception loaded it would also send the backtrace, which exposes file paths. path is the Hashes and
+    # Arrays being walked: one that contains itself is a ConfigurationError rather than a SystemStackError.
+    def describe(value, path = [])
       case value
       when Exception then { class: exception_class_name(value.class), message: value.message }
-      when Hash then value.transform_values { |item| describe(item) }
-      when Array then value.map { |item| describe(item) }
+      when Hash then within(value, path) { |inner| value.transform_values { |item| describe(item, inner) } }
+      when Array then within(value, path) { |inner| value.map { |item| describe(item, inner) } }
       else value
       end
     end
 
+    def within(container, path)
+      if path.any? { |ancestor| ancestor.equal?(container) }
+        raise ConfigurationError, "#{@definition.label}: an argument or context value contains itself, " \
+                                  "so it can't be sent as JSON"
+      end
+
+      yield path + [container]
+    end
+
     # An anonymous error class (Class.new(StandardError)) is named after its closest named ancestor.
     def exception_class_name(klass)
       klass = klass.superclass until klass.name

data/lib/squishling/judge.rb

@@ -4,10 +4,12 @@ module Squishling
   # Picks between two disagreeing samples, or rejects both (see Run#judge). The judge is the given judge:
   # step, or else the escalation's next stage after the first. A chat judge answers with a strict verdict
   # schema; a :judgment judge (a System One decision model such as Jev) answers one choice question through
-  # RubyLLM.judge, and its pick counts only at or above min_confidence.
+  # the adapter's judgments (RubyLLM's, with the RubyLLM adapter), and its pick counts only at or above
+  # min_confidence.
   class Judge
     # The judge kinds: :chat (a chat model answering VERDICT_SCHEMA) and :judgment (a System One decision model
-    # through RubyLLM.judge). A judge is an escalation step (see ModelPath) plus these keys: type: (default :chat)
+    # through the adapter's judgments). A judge is an escalation step (see ModelPath) plus these keys:
+    # type: (default :chat)
     # and, for :judgment, min_confidence: (the probability the chosen candidate needs).
     TYPES = %i[chat judgment].freeze
     STEP_KEYS = %i[type min_confidence].freeze
@@ -42,14 +44,16 @@ module Squishling
     # judge: is a normalized judge step (see Harness::JudgedSquishsum) or nil for the escalation's next stage,
     # instructions: a String, a Proc evaluated against the receiver, or nil for the default prompt.
     def initialize(definition:, receiver:, client:, judge:, instructions:, path:, purpose:, payload:, escalate:,
-      log_failure:, guard:, harness_type:)
+      log_failure:, guard:, budget_check:, harness_type:)
       @definition = definition
       @receiver = receiver
       @client = client
       @judge = judge
       @instructions = instructions
       check!
+      check_judgments!
       @guard = guard
+      @budget_check = budget_check
       @harness_type = harness_type
       @purpose = purpose
       @payload = payload
@@ -95,6 +99,14 @@ module Squishling
       raise ConfigurationError, "#{label} instructions must be a non-blank String or a Proc"
     end
 
+    # Raised before any request, like the rest of the judge's checks.
+    def check_judgments!
+      return if !judgment? || @client.judgments?
+
+      raise ConfigurationError, "#{@definition.label}: judge type: :judgment needs an adapter that supports " \
+                                "judgments (the configured adapter doesn't); use type: :chat or the :ruby_llm adapter"
+    end
+
     def non_blank_string?(value)
       value.is_a?(String) && !value.strip.empty?
     end
@@ -163,6 +175,7 @@ module Squishling
     # A judgment always matches its questions, so only a failed request (LLMError) moves on to the next attempt.
     def judge_with_retries(input, questions)
       @steps.each.with_index(1) do |step, attempt|
+        @budget_check.call(attempts: attempt - 1)
         return @client.observed_judgment(input, questions:, step:, attempt:, attempts: @steps.size)
       rescue LLMError => e
         raise if attempt == @steps.size

data/lib/squishling/llm_client.rb

@@ -1,25 +1,41 @@
 # frozen_string_literal: true
 
 module Squishling
-  # RubyLLM requests for one squished method, with RubyLLM's errors mapped onto Squishling's taxonomy.
+  # The requests for one squished method, made through the configured adapter (see Adapter). Squishling owns the
+  # conversation: each Conversation holds the system prompt, the output schema, and the messages so far, and every
+  # request sends all of it to the adapter.
   class LLMClient
-    # Where RubyLLM's own code lives, to tell its ArgumentErrors from the developer's (see #judge).
-    RUBY_LLM_LIB = File.dirname(RubyLLM.method(:judge).source_location.first)
-    private_constant :RUBY_LLM_LIB
+    # One chat on one escalation step. messages are { role:, content: } Hashes, grown by #ask.
+    Conversation = Struct.new(:step, :instructions, :schema, :messages)
+
+    # purpose, harness (the harness type), and handed_off (squish! sent the call here) are only told to the observer.
+    # budget (see Budget) caps the tokens the requests of this client may use between them.
+    def initialize(label, purpose:, harness:, handed_off:, budget: {})
+      @label = label
+      @purpose = purpose
+      @harness = harness
+      @handed_off = handed_off
+      @adapter = Squishling.config.resolved_adapter
+      @tally = Budget::Tally.new(budget)
+    end
+
+    # The budget limit this client's requests have reached ({ limit:, max:, used: }), or nil. Checked before each
+    # request, so one already in flight is never cut short.
+    def exhausted_budget
+      @tally.exhausted
+    end
 
     # Runs each job on its own thread and returns, in order, each job's [value, exception]. Only provider
     # requests run here: parsing, validation, and the developer's callbacks stay on the caller's thread. Fiber
-    # storage (RubyLLM's usage owner) is inherited by the threads, and RubyLLM's instrumentation context is
-    # carried over the way RubyLLM's own concurrent tool calls do it. Unlike those, the threads don't enter the
-    # Rails executor: the caller already holds it, and a second share can deadlock against a pending code reload.
-    # If the caller is interrupted while waiting (a timeout, Thread#raise), the requests still running are
-    # stopped rather than left running unobserved.
-    def self.concurrently(jobs)
+    # storage is inherited by the threads, and the adapter carries over whatever request context it keeps (see
+    # Adapter::Base#capture_context). If the caller is interrupted while waiting (a timeout, Thread#raise), the
+    # requests still running are stopped rather than left running unobserved.
+    def concurrently(jobs)
       return jobs.map { |job| capture(job) } if jobs.size < 2
 
-      context = instrumentation_context
+      context = @adapter.capture_context if @adapter.respond_to?(:capture_context)
       threads = jobs.map do |job|
-        thread = Thread.new { with_instrumentation_context(context) { capture(job) } }
+        thread = Thread.new { with_context(context) { capture(job) } }
         thread.report_on_exception = false
         thread
       end
@@ -28,76 +44,32 @@ module Squishling
       threads&.each { |thread| thread.kill.join if thread.alive? }
     end
 
-    def self.capture(job)
-      [job.call, nil]
-    rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised on the caller's thread
-      [nil, e]
-    end
-
-    def self.instrumentation_context
-      instrumentation = defined?(RubyLLM::Support::Instrumentation) && RubyLLM::Support::Instrumentation
-      return unless instrumentation.respond_to?(:current_workflow) && instrumentation.respond_to?(:capture_context)
-
-      [instrumentation.current_workflow, instrumentation.capture_context]
-    end
-
-    def self.with_instrumentation_context(context, &)
-      return yield unless context
-
-      instrumentation = RubyLLM::Support::Instrumentation
-      instrumentation.with_workflow(context.first) { instrumentation.with_context(context.last, &) }
-    end
-
-    private_class_method :capture, :instrumentation_context, :with_instrumentation_context
-
-    # purpose, harness (the harness type), and handed_off (squish! sent the call here) are only told to the observer.
-    def initialize(label, purpose:, harness:, handed_off:)
-      @label = label
-      @purpose = purpose
-      @harness = harness
-      @handed_off = handed_off
-    end
-
-    # A fresh chat on one escalation step, with the system prompt, the strict output schema, and its params.
+    # A fresh conversation on one escalation step, with the system prompt and the strict output schema.
     def chat(step, instructions:, schema:)
-      chat = build_chat(step)
-      chat.with_instructions(instructions)
-      chat.with_schema(schema)
-      apply_params(chat, step.params)
-      chat
+      Conversation.new(step, instructions, schema, [])
     end
 
-    # Transient HTTP failures are already retried by RubyLLM (RubyLLM.config.max_retries); anything
-    # that still fails is surfaced as an LLMError, which moves on to the next attempt of the
-    # escalation (or propagates from the last one). A 400 means the request we built is invalid (an
-    # unsupported param, a schema the provider rejects), so it's a setup mistake: escalating or a
-    # fallback would otherwise hide it on every call.
+    # One request in the conversation: the message goes in, and the adapter's answer is kept in it so the next
+    # message continues from there. A request that fails leaves the conversation as it was.
+    # The adapter raises ConfigurationError for setup mistakes (never retried) and LLMError for failures worth another
+    # attempt, which moves on to the next attempt of the escalation (or propagates from the last one).
     # The request runs inside the configured observer (see Observer), on this thread: for samples, the worker's.
     # role is nil for an escalation attempt, :sample (with its name) or :judge; attempt counts in attempts.
-    def ask(chat, message, step, attempt:, attempts:, role: nil, sample: nil)
+    # reask is whether this message is a retry in the same chat (see ModelPath::Step#request_params).
+    def ask(chat, message, step, attempt:, attempts:, role: nil, sample: nil, reask: false)
       call = call_info(step, :chat, role:, sample:, attempt:, attempts:)
-      Observer.around(call) { request(step) { chat.ask(message) } }
+      Observer.around(call) { complete(chat, message, step, reask) }
     end
 
-    # A System One judgment (RubyLLM.judge) on one step. The step's params are sent as provider options.
-    # RubyLLM raises ArgumentError for a judgment it can't build (e.g. a model on a provider that takes none, or
-    # a provider option its protocol reserves), and a bare RubyLLM::Error without an HTTP response for a provider
-    # that doesn't support judgments at all. An ArgumentError from anywhere else (an instrumentation subscriber
-    # runs inside the call) is the developer's own and propagates as-is.
+    # Whether the adapter can make System One judgments (judges with type: :judgment).
+    def judgments?
+      @adapter.respond_to?(:judgments?) && @adapter.respond_to?(:judge) && @adapter.judgments?
+    end
+
+    # A System One judgment on one step, through the adapter.
+    # Judge#check_judgments! has already refused an adapter that can't.
     def judge(input, questions:, step:)
-      request(step) do
-        RubyLLM.judge(input, questions:, provider_options: step.params, **model_options(step))
-      rescue RubyLLM::ModelNotFoundError => e
-        raise ConfigurationError, "#{@label}: #{e.message}"
-      rescue ArgumentError => e
-        raise unless raised_by_ruby_llm?(e)
-
-        raise ConfigurationError, "#{@label}: #{e.message}"
-      rescue RubyLLM::Error => e
-        raise unless e.instance_of?(RubyLLM::Error) && e.response.nil?
-
-        raise ConfigurationError, "#{@label}: #{e.message}"
-      end
+      @tally.add(@adapter.judge(input, questions:, step:, label: @label))
     end
 
     # #judge inside the configured observer (see Observer), attempt counting in attempts.
@@ -108,73 +80,35 @@ module Squishling
 
     private
 
-    def call_info(step, request, attempt:, attempts:, role: nil, sample: nil)
-      Observer::Call.new(label: @label, purpose: @purpose, harness: @harness, handed_off: @handed_off, role:, sample:,
-        attempt:, attempts:, model: step.model, provider: step.provider, request:)
-    end
-
-    def raised_by_ruby_llm?(error)
-      error.backtrace&.first&.start_with?("#{RUBY_LLM_LIB}/") || false
-    end
-
-    def build_chat(step)
-      RubyLLM.chat(**model_options(step))
-    rescue RubyLLM::ModelNotFoundError, RubyLLM::ConfigurationError => e
-      raise ConfigurationError, "#{@label}: #{e.message}"
-    end
-
-    # RubyLLM validates some settings locally (e.g. an impossible thinking budget for the model)
-    # and raises ArgumentError before any request is sent.
-    def apply_params(chat, params)
-      Params.apply(chat, params)
-    rescue ArgumentError => e
-      raise ConfigurationError, "#{@label}: invalid params #{params.inspect} (#{e.message})"
+    def capture(job)
+      [job.call, nil]
+    rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised on the caller's thread
+      [nil, e]
     end
 
-    # A provider's or transport's own message never goes into ours: a provider can echo request content or part of
-    # an API key in it, and ours reach logs and error trackers. The original stays as #cause for whoever
-    # chooses to read it. RubyLLM's own ConfigurationError is local (it names a missing setting), so it is kept.
-    def request(step)
-      yield
-    rescue RubyLLM::ConfigurationError => e
-      raise ConfigurationError, "#{@label}: #{e.class}: #{e.message}"
-    rescue RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
-      raise ConfigurationError, "#{@label}: #{describe_failure(e)}"
-    rescue RubyLLM::BadRequestError => e
-      raise ConfigurationError,
-        "#{@label}: the provider rejected the request (#{describe_failure(e)})#{params_hint(step.params)}"
-    rescue RubyLLM::Error, Faraday::Error => e
-      raise LLMError, "#{@label}: #{describe_failure(e)}"
-    end
+    def complete(chat, message, step, reask)
+      messages = chat.messages + [{ role: :user, content: message }]
+      request = Adapter::Request.new(label: @label, model: step.model, provider: step.provider,
+        instructions: chat.instructions, messages:, schema: chat.schema, params: step.request_params(reask))
+      response = @adapter.complete(request)
+      unless response.is_a?(Adapter::Response)
+        raise ConfigurationError, "#{@label}: the #{@adapter.class} adapter must return a " \
+                                  "Squishling::Adapter::Response from #complete, got #{response.class}"
+      end
 
-    # The error's class and HTTP status, when it has one, which is all of it that is ours to repeat.
-    def describe_failure(error)
-      response = error.response
-      status = response.is_a?(Hash) ? response[:status] : (response.status if response.respond_to?(:status))
-      status ? "#{error.class}, HTTP #{status}" : error.class.to_s
+      chat.messages = messages + [{ role: :assistant, content: response.text }]
+      @tally.add(response)
     end
 
-    # Models missing from RubyLLM's registry (e.g. newly released ones) are only usable when a
-    # provider is named, so RubyLLM is told to assume they exist.
-    def model_options(step)
-      model = step.model
-      provider = step.provider
-      options = { model:, provider: }.compact
-      options[:assume_model_exists] = true if model && provider && !known_model?(model, provider)
-      options
-    end
+    def with_context(context, &)
+      return yield unless @adapter.respond_to?(:with_context)
 
-    def known_model?(model, provider)
-      RubyLLM.models.find(model, provider:)
-      true
-    rescue RubyLLM::ModelNotFoundError
-      false
+      @adapter.with_context(context, &)
     end
 
-    def params_hint(params)
-      return "" if params.empty?
-
-      ". Check params #{params.inspect}; reasoning models often reject sampling params such as temperature and top_p"
+    def call_info(step, request, attempt:, attempts:, role: nil, sample: nil)
+      Observer::Call.new(label: @label, purpose: @purpose, harness: @harness, handed_off: @handed_off, role:, sample:,
+        attempt:, attempts:, model: step.model, provider: step.provider, request:)
     end
   end
 end

data/lib/squishling/model_path.rb

@@ -12,18 +12,31 @@ module Squishling
   # instead of positional. Steps sharing a priority are one tier: each call rotates which of them goes first
   # (see Rotation), and the others follow before the next tier, unless a step in the tier sets rotate: false.
   # order: is the deprecated name of priority:. forward_rejected: false starts a step from the original input
-  # alone, without the previous step's rejected output.
+  # alone, without the previous step's rejected output. include_when: (a Proc, called like squish_when with the
+  # method's inputs as keywords, on the instance) drops the step from any call where it is falsy.
+  # retry_temperature: (a Numeric) is the temperature for the step's same-chat retries after the first attempt.
   module ModelPath
-    # One attempt: the model, its provider, the fully resolved generation params, and whether the previous
-    # step's rejected output is shown to it.
-    Step = Data.define(:model, :provider, :params, :forward_rejected) do
-      # The model for logs and messages (nil means RubyLLM's default model).
+    # One attempt: the model, its provider, the fully resolved generation params, whether the previous
+    # step's rejected output is shown to it, and the temperature its retries in the same chat use, if any.
+    Step = Data.define(:model, :provider, :params, :forward_rejected, :retry_temperature) do
+      def initialize(model:, provider:, params:, forward_rejected:, retry_temperature: nil)
+        super
+      end
+
+      # The params for a request: on a retry in the same chat (reask), the step's retry_temperature replaces the
+      # temperature, if it sets one.
+      def request_params(reask)
+        reask && retry_temperature ? Params.resolve(params, temperature: retry_temperature) : params
+      end
+
+      # The model for logs and messages (nil means the adapter's default model).
       def display_name
-        model || "RubyLLM default model"
+        model || "the adapter's default model"
       end
     end
 
-    STEP_KEYS = %i[model provider params attempts priority order rotate forward_rejected].freeze
+    STEP_KEYS = %i[model provider params attempts priority order rotate forward_rejected include_when
+                   retry_temperature].freeze
 
     module_function
 
@@ -64,11 +77,24 @@ module Squishling
     def steps(path, provider:, params:, turn: 0)
       rotated(path, turn).flat_map do |step|
         attempt = Step.new(model: step[:model], provider: step[:provider] || provider,
-          params: Params.resolve(params, step[:params]), forward_rejected: step[:forward_rejected])
+          params: Params.resolve(params, step[:params]), forward_rejected: step[:forward_rejected],
+          retry_temperature: step[:retry_temperature])
         [attempt] * step[:attempts]
       end
     end
 
+    # The steps this call may use: those without an include_when:, and those whose include_when: is truthy for the
+    # call's inputs (evaluated against the receiver, like squish_when). Priority order is kept.
+    def eligible(path, receiver, inputs, label)
+      kept = path.select do |step|
+        gate = step[:include_when]
+        gate.nil? || receiver.instance_exec(**inputs, &gate)
+      end
+      raise ConfigurationError, "#{label}: include_when: excluded every escalation step" if kept.empty?
+
+      kept
+    end
+
     # Whether any tier of the path has several models to rotate between.
     def rotating?(path)
       tiers(path).any? { |tier| rotates?(tier) }
@@ -134,6 +160,8 @@ module Squishling
         raise ConfigurationError, "#{label} (#{model}): rotate: must be true or false, got #{step[:rotate].inspect}"
       end
 
+      check_include_when!(step, label, model)
+      check_retry_temperature!(step, label, model)
       forward_rejected = step.fetch(:forward_rejected, true)
       unless [true, false].include?(forward_rejected)
         raise ConfigurationError,
@@ -142,15 +170,34 @@ module Squishling
 
       params = step[:params] && Params.normalize(step[:params], "#{label} (#{model}) params")
       normalized = { model:, provider: step[:provider], params:, attempts:, forward_rejected: }
-      normalized.merge(step.slice(:priority, :rotate, *extras))
+      normalized.merge(step.slice(:priority, :rotate, :include_when, :retry_temperature, *extras))
+    end
+
+    def check_include_when!(step, label, model)
+      return if !step.key?(:include_when) || step[:include_when].is_a?(Proc)
+
+      raise ConfigurationError,
+        "#{label} (#{model}): include_when: must be a Proc, got #{step[:include_when].inspect}"
+    end
+
+    def valid_temperature?(temperature)
+      temperature.is_a?(Numeric) && temperature.real? && temperature.finite? && !temperature.negative?
+    end
+
+    def check_retry_temperature!(step, label, model)
+      temperature = step[:retry_temperature]
+      return if !step.key?(:retry_temperature) || valid_temperature?(temperature)
+
+      raise ConfigurationError,
+        "#{label} (#{model}): retry_temperature: must be a finite Numeric of 0 or more, got #{temperature.inspect}"
     end
 
-    # A step used on its own (a judge, a harness's step) can't take part in a tier, so it takes no priority: or
-    # rotate:. who names it for the message.
+    # A step used on its own (a judge, a harness's step) can't take part in a tier or be left out of a call, so it
+    # takes no priority:, rotate:, or include_when:. who names it for the message.
     def single_step!(step, who)
-      return unless step.key?(:priority) || step.key?(:rotate)
+      return unless step.key?(:priority) || step.key?(:rotate) || step.key?(:include_when)
 
-      raise ConfigurationError, "#{who} takes no priority: or rotate:"
+      raise ConfigurationError, "#{who} takes no priority:, rotate:, or include_when:"
     end
 
     # order: is the deprecated name of priority:.

data/lib/squishling/named_registry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Classes by name, for the things that can be registered (harnesses, adapters): the built-ins, registered as they
+  # load, and the developer's own. Shared across threads, so every read and write is under the lock.
+  class NamedRegistry
+    NAME = /\A[a-z][a-z0-9_]*\z/
+
+    # kind names what is registered ("harness"), for messages.
+    def initialize(kind)
+      @kind = kind
+      @lock = Mutex.new
+      @built_in = {}
+      @custom = {}
+    end
+
+    def register_built_in(name, klass)
+      @lock.synchronize { @built_in[name] = klass }
+    end
+
+    # The name as a Symbol. Raises ConfigurationError when it isn't a Symbol or String of lowercase letters, digits
+    # and underscores, starting with a letter.
+    def checked_name(name)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        raise ConfigurationError, "#{@kind} name must be a Symbol or String, got #{name.inspect}"
+      end
+
+      name = name.to_sym
+      return name if NAME.match?(name)
+
+      raise ConfigurationError,
+        "#{@kind} name #{name.inspect} must be lowercase letters, digits, and underscores, starting with a letter"
+    end
+
+    # Registers klass under name (already checked), unless the name is taken.
+    def add(name, klass)
+      @lock.synchronize do
+        raise ConfigurationError, "#{@kind} #{name.inspect} is already registered" if taken?(name)
+
+        @custom[name] = klass
+      end
+      klass
+    end
+
+    def fetch(name)
+      @lock.synchronize { @built_in[name] || @custom[name] }
+    end
+
+    def names
+      @lock.synchronize { @built_in.keys + @custom.keys }
+    end
+
+    # Forgets the registered classes; the built-ins stay.
+    def reset!
+      @lock.synchronize { @custom.clear }
+    end
+
+    private
+
+    def taken?(name)
+      @built_in.key?(name) || @custom.key?(name)
+    end
+  end
+end

data/lib/squishling/observer.rb

@@ -33,12 +33,12 @@ module Squishling
         return observer if BUILT_IN.include?(observer)
 
         raise ConfigurationError, "#{where} observer must be one of #{BUILT_IN.map(&:inspect).join(', ')}, " \
-                                  "an object that responds to around, or false, got #{observer.inspect}"
+                                  "an object that responds to around, or false, got #{Appendices.describe(observer)}"
       end
       return observer if observer.respond_to?(:around)
 
       raise ConfigurationError, "#{where} observer must respond to around(call) { ... } (or be false), " \
-                                "got #{observer.inspect}"
+                                "got #{Appendices.describe(observer)}"
     end
 
     # The observer that wraps a request: the configured one, the Coolhand observer when nothing is configured and
@@ -89,12 +89,21 @@ module Squishling
       response
     end
 
+    # An Adapter::Response carries its token counts in a Hash; a judgment (see Adapter::Base#judge) may carry them in
+    # an object with input and output instead. Shared with Budget::Tally; not part of the public API.
     def usage(response)
       tokens = response.respond_to?(:tokens) ? response.tokens : nil
       model = response.respond_to?(:model) ? response.model : nil
-      Usage.new(input_tokens: tokens&.input, output_tokens: tokens&.output,
+      Usage.new(input_tokens: token_count(tokens, :input_tokens, :input),
+        output_tokens: token_count(tokens, :output_tokens, :output),
         model: model.respond_to?(:id) ? model.id : model)
     end
-    private_class_method :usage
+
+    def token_count(tokens, key, reader)
+      return tokens[key] if tokens.is_a?(Hash)
+
+      tokens.respond_to?(reader) ? tokens.public_send(reader) : nil
+    end
+    private_class_method :token_count
   end
 end