squishling 0.4.0 → 0.5.0

data/lib/squishling/adapters/openai_compatible.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require "zlib"
+
+module Squishling
+  module Adapters
+    # Sends requests to any server that speaks OpenAI's Chat Completions API (POST {base_url}/chat/completions):
+    # OpenAI itself, Ollama, vLLM, LM Studio, llama.cpp, Together, Groq, and the like. Plain Net::HTTP, so it needs
+    # no gem beyond Squishling's own. Squishling asks for strict structured output (response_format: json_schema);
+    # servers that lack it can use structured_output: :json_object or :none, where the schema goes into the system
+    # prompt instead, and Squishling's own validation still decides what is accepted. See docs/adapters.md.
+    #
+    #   Squishling.configure do |config|
+    #     config.adapter = { type: :openai_compatible, base_url: "http://localhost:11434/v1", default_model: "llama3.2" }
+    #   end
+    class OpenAICompatible < Adapter::Base
+      Options = OpenAIOptions
+      private_constant :Options
+
+      DEFAULT_BASE_URL = "https://api.openai.com/v1"
+      STRUCTURED_OUTPUT = %i[json_schema json_object none].freeze
+      TOKEN_PARAMS = %i[max_completion_tokens max_tokens].freeze
+      # Params Squishling maps itself; the rest go into the request body as given.
+      PORTABLE_PARAMS = %i[temperature thinking max_output_tokens].freeze
+      # Failures worth another try inside the adapter: timeouts, connection and protocol trouble (below), HTTP 408,
+      # 429, and 5xx. A timeout is retried even though the server may have processed the request.
+      NETWORK_ERRORS = [Timeout::Error, SocketError, EOFError, IOError, SystemCallError, Net::ProtocolError,
+                        Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, OpenSSL::OpenSSLError, Zlib::Error].freeze
+      MAX_RETRY_DELAY = 30
+      # How servers without OpenAI's error code (vLLM, Ollama, llama.cpp, ...) say a prompt is too long. The message is
+      # only matched against this, never repeated.
+      CONTEXT_LENGTH_MESSAGE = /context (length|window|size)|too many tokens|prompt is too long|maximum .{0,20}tokens/i
+      private_constant :STRUCTURED_OUTPUT, :TOKEN_PARAMS, :PORTABLE_PARAMS, :NETWORK_ERRORS, :MAX_RETRY_DELAY,
+        :CONTEXT_LENGTH_MESSAGE
+
+      # base_url: the API root, ending where /chat/completions starts. api_key: a String, or a callable that returns
+      # one; for OpenAI's own endpoint it defaults to ENV["OPENAI_API_KEY"] (read when a request is made). Any other
+      # endpoint gets only the key you give it, so an OpenAI key can't reach another host. None is sent when the key
+      # is blank (local servers). headers: extra request headers. default_model: used for steps that name no model.
+      # max_retries: how often a timeout, connection failure, HTTP 408, 429, or 5xx is retried here (honoring
+      # Retry-After) before it surfaces as an LLMError. max_tokens_param: the body key for max_output_tokens
+      # (:max_completion_tokens, or :max_tokens for older servers). structured_output: :json_schema, :json_object,
+      # or :none. Raises ConfigurationError for a bad option.
+      def initialize(base_url: DEFAULT_BASE_URL, api_key: nil, headers: {}, default_model: nil, open_timeout: 10,
+        read_timeout: 120, max_retries: 2, max_tokens_param: :max_completion_tokens, structured_output: :json_schema)
+        super()
+        @endpoint = Options.endpoint(base_url)
+        @api_key = api_key
+        @headers = Options.headers(headers)
+        @default_model = Options.default_model(default_model)
+        @open_timeout = Options.number(:open_timeout, open_timeout)
+        @read_timeout = Options.number(:read_timeout, read_timeout)
+        @max_retries = Options.retries(max_retries)
+        @max_tokens_param = Options.choice(:max_tokens_param, max_tokens_param, TOKEN_PARAMS)
+        @structured_output = Options.choice(:structured_output, structured_output, STRUCTURED_OUTPUT)
+      end
+
+      # Shows where requests go, never the key or the header values (a console, a log line, or an error tracker may
+      # print the config).
+      def inspect
+        "#<#{self.class.name} #{@endpoint.scheme}://#{@endpoint.authority}#{@endpoint.path} " \
+          "default_model=#{@default_model.inspect} structured_output=#{@structured_output.inspect}>"
+      end
+
+      def complete(request)
+        model = request.model || @default_model
+        unless model
+          raise configuration_error(request,
+            "no model: name one with model: or give the adapter a default_model:")
+        end
+
+        data = post(request, JSON.generate(body(request, model)), request_headers(request))
+        Adapter::Response.new(content: content_of(data), model: data["model"] || model,
+          tokens: tokens_of(data["usage"]), finish_reason: finish_reason_of(data))
+      end
+
+      private
+
+      # Params first, then what Squishling owns, so a param can never replace the model, the conversation, or the
+      # strict output format. n and stream are fixed: one non-streamed completion.
+      def body(request, model)
+        params = request.params
+        body = params.except(*PORTABLE_PARAMS).transform_keys(&:to_s)
+        body["temperature"] = params[:temperature] if params.key?(:temperature)
+        body[@max_tokens_param.to_s] = params[:max_output_tokens] if params.key?(:max_output_tokens)
+        body.merge!(reasoning(request, params[:thinking]))
+        body.merge("model" => model, "messages" => messages(request), "n" => 1, "stream" => false)
+          .merge(response_format(request))
+      end
+
+      # Chat Completions only has reasoning_effort: true and false have no equivalent, so they leave the default.
+      def reasoning(request, thinking)
+        return {} unless thinking.is_a?(Hash)
+
+        unsupported = thinking.keys - [:effort]
+        unless unsupported.empty?
+          raise configuration_error(request, "thinking #{unsupported.join(', ')} isn't supported by this adapter " \
+                                             "(only thinking: { effort: })")
+        end
+
+        { "reasoning_effort" => thinking[:effort].to_s }
+      end
+
+      def messages(request)
+        system = system_prompt(request)
+        turns = request.messages.map { |message| { "role" => message[:role].to_s, "content" => message[:content] } }
+        system ? [{ "role" => "system", "content" => system }] + turns : turns
+      end
+
+      # Without response_format: json_schema the model has to be told the schema in words.
+      def system_prompt(request)
+        return request.instructions if @structured_output == :json_schema
+
+        schema = JSON.pretty_generate(request.schema["schema"])
+        [request.instructions,
+         "Respond only with JSON that validates against this JSON Schema:\n#{schema}"].compact.join("\n\n")
+      end
+
+      def response_format(request)
+        case @structured_output
+        when :json_schema then { "response_format" => { "type" => "json_schema",
+                                                        "json_schema" => json_schema(request) } }
+        when :json_object then { "response_format" => { "type" => "json_object" } }
+        else {}
+        end
+      end
+
+      def json_schema(request)
+        schema = request.schema
+        name = schema["name"].to_s.gsub(/[^A-Za-z0-9_-]/, "_")[0, 64]
+        { "name" => name.empty? ? "response" : name, "description" => schema["description"],
+          "schema" => schema["schema"], "strict" => true }.compact
+      end
+
+      # One request, retried here for failures worth retrying. A refusal or an empty answer is returned as empty
+      # content, which Squishling reports as invalid output.
+      def post(request, body, headers)
+        attempt = 0
+        loop do
+          attempt += 1
+          response, error = exchange(body, headers)
+          return parse_body(request, response) if response.is_a?(Net::HTTPSuccess)
+
+          failure = failure_for(request, response, error)
+          raise failure, cause: error unless retryable?(response, error) && attempt <= @max_retries
+
+          pause(retry_delay(response, attempt))
+        end
+      end
+
+      def exchange(body, headers)
+        [http_post(body, headers), nil]
+      rescue *NETWORK_ERRORS => e
+        [nil, e]
+      end
+
+      # Redirects aren't followed: the next hop could be another host, and the Authorization header would go with it.
+      def http_post(body, headers)
+        http = Net::HTTP.new(@endpoint.hostname, @endpoint.port)
+        http.use_ssl = @endpoint.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+        http.write_timeout = @read_timeout
+        post = Net::HTTP::Post.new(@endpoint.request_uri, headers)
+        post.body = body
+        http.request(post)
+      end
+
+      # Built once per call, before any request and outside the network-error rescue, so the developer's own api_key
+      # callable runs once and its exceptions propagate as they are.
+      def request_headers(request)
+        key = (@api_key.respond_to?(:call) ? @api_key.call : (@api_key || default_api_key)).to_s.strip
+        if Options.unsafe_header?(key)
+          raise configuration_error(request,
+            "the api_key can't contain line breaks or NUL")
+        end
+
+        headers = { "Content-Type" => "application/json", "Accept" => "application/json",
+                    "User-Agent" => "squishling/#{VERSION}" }
+        headers["Authorization"] = "Bearer #{key}" unless key.empty?
+        headers.merge(@headers)
+      end
+
+      def default_api_key
+        default = URI.parse(DEFAULT_BASE_URL)
+        return unless @endpoint.scheme == default.scheme && @endpoint.hostname.downcase == default.hostname
+
+        ENV.fetch("OPENAI_API_KEY", nil)
+      end
+
+      def parse_body(request, response)
+        data = JSON.parse(response.body.to_s.dup.force_encoding(Encoding::UTF_8))
+        return data if data.is_a?(Hash)
+
+        raise llm_error(request, "the response wasn't a JSON object (HTTP #{response.code})")
+      rescue JSON::ParserError
+        raise llm_error(request, "the response wasn't valid JSON (HTTP #{response.code})")
+      end
+
+      def retryable?(response, error)
+        return !certificate_failure?(error) if error
+
+        status = response.code.to_i
+        [408, 429].include?(status) || status >= 500
+      end
+
+      # The provider's own message is never repeated: only the class of failure or the HTTP status.
+      def failure_for(request, response, error)
+        return transport_failure(request, error) if error
+
+        status = response.code.to_i
+        return llm_error(request, "HTTP #{status}") if retryable?(response, nil) || too_large?(response, status)
+
+        rejection(request, response, status)
+      end
+
+      # A certificate that doesn't verify is a setup mistake (base_url, CA store) that a retry can't fix.
+      def transport_failure(request, error)
+        if certificate_failure?(error)
+          return configuration_error(request, "TLS certificate verification failed (#{error.class}); check base_url " \
+                                              "and the CA certificates")
+        end
+
+        llm_error(request, "the request failed (#{error.class})")
+      end
+
+      def certificate_failure?(error)
+        error.is_a?(OpenSSL::SSL::SSLError) && error.message.include?("certificate verify failed")
+      end
+
+      def rejection(request, response, status)
+        case status
+        when 401, 403 then configuration_error(request, "the provider refused the credentials (HTTP #{status})")
+        when 404 then configuration_error(request, "HTTP 404: check base_url and the model name")
+        when 300..399 then configuration_error(request, "HTTP #{status}: redirects aren't followed; check base_url")
+        else rejected_request_error(request, via: "HTTP #{status}", body: response.body.to_s,
+          http_status: status)
+        end
+      end
+
+      # A request too long for the model's context (or for the server: 413) depends on the input and is worth another
+      # attempt (a bigger model may take it), unlike other 4xx. Only the error's code is read from the body.
+      def too_large?(response, status)
+        status == 413 || context_length?(response)
+      end
+
+      def context_length?(response)
+        return false unless response.code.to_i == 400
+
+        error = Adapter::ErrorBody.error(response.body.to_s)
+        error.is_a?(Hash) && (error.values_at("code", "type").include?("context_length_exceeded") ||
+          error["message"].to_s.match?(CONTEXT_LENGTH_MESSAGE))
+      end
+
+      def retry_delay(response, attempt)
+        after = response&.[]("retry-after").to_s
+        seconds = after.match?(/\A\d+\z/) ? after.to_i : (0.5 * (2**(attempt - 1))) + (rand * 0.25)
+        [seconds, MAX_RETRY_DELAY].min
+      end
+
+      def pause(seconds)
+        sleep(seconds)
+      end
+
+      def content_of(data)
+        message = Array(data["choices"]).first
+        message = message["message"] if message.is_a?(Hash)
+        content = message.is_a?(Hash) ? message["content"] : nil
+        content.is_a?(Array) ? content.filter_map { |part| part["text"] if part.is_a?(Hash) }.join : content
+      end
+
+      # The first choice's finish_reason, in the vocabulary of Adapter::Response ("length" is the output cap).
+      def finish_reason_of(data)
+        choice = Array(data["choices"]).first
+        reason = choice["finish_reason"] if choice.is_a?(Hash)
+        return unless reason.is_a?(String)
+
+        reason == "length" ? :max_tokens : reason
+      end
+
+      def tokens_of(usage)
+        return {} unless usage.is_a?(Hash)
+
+        {
+          input_tokens: usage["prompt_tokens"],
+          output_tokens: usage["completion_tokens"],
+          cache_read_tokens: detail(usage, "prompt_tokens_details", "cached_tokens"),
+          thinking_tokens: detail(usage, "completion_tokens_details", "reasoning_tokens")
+        }.select { |_, count| count.is_a?(Integer) }
+      end
+
+      # A count inside a usage sub-object, which a server might send in any shape.
+      def detail(usage, group, key)
+        usage[group][key] if usage[group].is_a?(Hash)
+      end
+    end
+
+    Adapter::Registry.register_built_in(:openai_compatible, OpenAICompatible)
+  end
+end

data/lib/squishling/adapters/openai_options.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Squishling
+  module Adapters
+    # Checks the options of Adapters::OpenAICompatible, raising ConfigurationError (without echoing a value that may
+    # be a secret) for a bad one.
+    module OpenAIOptions
+      # The URL itself is never in the message: it may carry credentials.
+      INVALID_BASE_URL = "adapter :openai_compatible base_url must be an http(s) URL without credentials (use " \
+                         "api_key:), a query, or a fragment"
+      INVALID_HEADER = "adapter :openai_compatible headers (and the api_key) can't contain line breaks or NUL"
+
+      module_function
+
+      def endpoint(base_url)
+        uri = URI.parse(base_url.to_s.strip.sub(%r{/+\z}, ""))
+        unless uri.is_a?(URI::HTTP) && uri.host && uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+          raise ConfigurationError, INVALID_BASE_URL
+        end
+
+        URI.parse("#{uri}/chat/completions")
+      rescue URI::InvalidURIError
+        raise ConfigurationError, INVALID_BASE_URL
+      end
+
+      def headers(headers)
+        unless headers.is_a?(Hash) && headers.all? { |name, value| name.is_a?(String) && value.is_a?(String) }
+          raise ConfigurationError, "adapter :openai_compatible headers must be a Hash of String names to String values"
+        end
+        raise ConfigurationError, INVALID_HEADER if headers.flatten.any? { |text| unsafe_header?(text) }
+
+        # A copy, so the caller can't change a header after the check above.
+        headers.to_h { |name, value| [name.dup.freeze, value.dup.freeze] }.freeze
+      end
+
+      # Net::HTTP raises, with the value in the message, for a header that carries a line break.
+      def unsafe_header?(text)
+        text.match?(/[\r\n\0]/)
+      end
+
+      def default_model(model)
+        return nil if model.nil?
+        return model.to_s if (model.is_a?(String) || model.is_a?(Symbol)) && !model.to_s.strip.empty?
+
+        raise ConfigurationError, "adapter :openai_compatible default_model must be a model name, got #{model.inspect}"
+      end
+
+      def number(name, value)
+        return value if value.is_a?(Numeric) && value.positive?
+
+        raise ConfigurationError, "adapter :openai_compatible #{name} must be a positive number, got #{value.inspect}"
+      end
+
+      def retries(value)
+        return value if value.is_a?(Integer) && !value.negative?
+
+        raise ConfigurationError,
+          "adapter :openai_compatible max_retries must be an Integer of 0 or more, got #{value.inspect}"
+      end
+
+      def choice(name, value, choices)
+        symbol = value.is_a?(String) ? value.to_sym : value
+        return symbol if choices.include?(symbol)
+
+        raise ConfigurationError,
+          "adapter :openai_compatible #{name} must be one of #{choices.join(', ')}, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/squishling/adapters/ruby_llm.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Squishling
+  module Adapters
+    # Sends requests through RubyLLM (https://rubyllm.com): OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock,
+    # OpenRouter, and any other provider it supports. Configure provider API keys in RubyLLM as usual
+    # (RubyLLM.configure); transient HTTP failures are retried by RubyLLM itself (RubyLLM.config.max_retries).
+    # The ruby_llm gem is loaded when the adapter is built, so Squishling doesn't depend on it. See docs/adapters.md.
+    class RubyLLM < Adapter::Base
+      MINIMUM_VERSION = Gem::Version.new("2.1")
+
+      # The ruby_llm gem isn't installed (Adapter.detect tells that apart from a gem that is, but too old).
+      class MissingGemError < ConfigurationError; end
+
+      # Raises ConfigurationError when the ruby_llm gem is missing.
+      def initialize
+        super
+        require "ruby_llm"
+        check_version!
+        @lib = gem_lib_dir
+      rescue LoadError => e
+        raise unless e.path == "ruby_llm"
+
+        raise MissingGemError, "adapter :ruby_llm needs the ruby_llm gem; add `gem \"ruby_llm\"` to your Gemfile"
+      end
+
+      # One chat on the request's model: the system prompt, the strict output schema, and the params, then the
+      # conversation so far replayed, answering its last message. 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 complete(request)
+        chat = build_chat(request)
+        *history, last = request.messages
+        history.each { |message| chat.add_message(role: message[:role], content: message[:content]) }
+        response = guarded(request) { chat.ask(last[:content]) }
+        Adapter::Response.new(content: response.content, model: response.model, tokens: tokens_of(response),
+          finish_reason: response.finish_reason)
+      end
+
+      def judgments?
+        true
+      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.
+      def judge(input, questions:, step:, label:)
+        request = judgment_request(label, step)
+        guarded(request) do
+          ::RubyLLM.judge(input, questions:, provider_options: step.params, **model_options(step.model, step.provider))
+        rescue ::RubyLLM::ModelNotFoundError, ::RubyLLM::Error, ArgumentError => e
+          raise unless setup_failure?(e)
+
+          raise ConfigurationError, "#{label}: #{e.message}"
+        end
+      end
+
+      # RubyLLM's instrumentation context (the workflow and its captured context) is carried to the worker threads
+      # 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.
+      def capture_context
+        instrumentation = ::RubyLLM::Support::Instrumentation if defined?(::RubyLLM::Support::Instrumentation)
+        return unless instrumentation.respond_to?(:current_workflow) && instrumentation.respond_to?(:capture_context)
+
+        [instrumentation.current_workflow, instrumentation.capture_context]
+      end
+
+      def with_context(context, &)
+        return yield unless context
+
+        instrumentation = ::RubyLLM::Support::Instrumentation
+        instrumentation.with_workflow(context.first) { instrumentation.with_context(context.last, &) }
+      end
+
+      private
+
+      def tokens_of(response)
+        response.tokens ? response.tokens.to_h : {}
+      end
+
+      # Whether a failure from RubyLLM.judge is a judgment RubyLLM can't make, rather than a failed request or the
+      # developer's own error.
+      def setup_failure?(error)
+        case error
+        when ::RubyLLM::ModelNotFoundError then true
+        when ArgumentError then raised_by_ruby_llm?(error)
+        else error.instance_of?(::RubyLLM::Error) && error.response.nil?
+        end
+      end
+
+      def judgment_request(label, step)
+        Adapter::Request.new(label:, model: step.model, provider: step.provider, instructions: nil, messages: [],
+          schema: nil, params: step.params)
+      end
+
+      def build_chat(request)
+        chat = ::RubyLLM.chat(**model_options(request.model, request.provider))
+        chat.with_instructions(request.instructions)
+        chat.with_schema(request.schema)
+        apply_params(chat, request)
+        chat
+      rescue ::RubyLLM::ModelNotFoundError, ::RubyLLM::ConfigurationError => e
+        raise configuration_error(request, 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, request)
+        params = request.params
+        rest = params.except(:temperature, :thinking, :max_output_tokens)
+        chat.with_temperature(params[:temperature]) if params.key?(:temperature)
+        chat.with_max_output_tokens(params[:max_output_tokens]) if params.key?(:max_output_tokens)
+        apply_thinking(chat, params[:thinking]) if params.key?(:thinking)
+        chat.with_provider_options(rest) if rest.any?
+      rescue ArgumentError => e
+        raise configuration_error(request, "invalid params #{params.keys.inspect} (#{e.message})")
+      end
+
+      # true: the model's default thinking; false: off; a Hash: { effort:, budget:, display: }.
+      def apply_thinking(chat, thinking)
+        thinking.is_a?(Hash) ? chat.with_thinking(**thinking) : chat.with_thinking(thinking)
+      end
+
+      # Transient HTTP failures are already retried by RubyLLM; 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.
+      # 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 guarded(request)
+        yield
+      rescue ::RubyLLM::ConfigurationError => e
+        raise configuration_error(request, "#{e.class}: #{e.message}")
+      rescue ::RubyLLM::UnauthorizedError, ::RubyLLM::ForbiddenError => e
+        raise configuration_error(request, describe_failure(e))
+      rescue ::RubyLLM::BadRequestError => e
+        raise rejected_request_error(request, via: describe_failure(e), body: response_field(e.response, :body),
+          http_status: response_field(e.response, :status))
+      rescue ::RubyLLM::Error, Faraday::Error => e
+        raise llm_error(request, describe_failure(e))
+      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)
+        status = response_field(error.response, :status)
+        status ? "#{error.class}, HTTP #{status}" : error.class.to_s
+      end
+
+      # A field of an error's response, which is a Faraday::Response, or a Hash for a Faraday error.
+      def response_field(response, field)
+        response.is_a?(Hash) ? response[field] : (response.public_send(field) if response.respond_to?(field))
+      end
+
+      def model_options(model, provider)
+        options = { model:, provider: }.compact
+        options[:assume_model_exists] = true if model && provider && !known_model?(model, provider)
+        options
+      end
+
+      def known_model?(model, provider)
+        ::RubyLLM.models.find(model, provider:)
+        true
+      rescue ::RubyLLM::ModelNotFoundError
+        false
+      end
+
+      def raised_by_ruby_llm?(error)
+        error.backtrace&.first&.start_with?("#{@lib}/") || false
+      end
+
+      # The adapter uses RubyLLM 2.1 APIs (judgments, with_max_output_tokens, Tokens#to_h), and no gemspec pins it.
+      def check_version!
+        version = Gem.loaded_specs["ruby_llm"]&.version
+        return if version.nil? || version >= MINIMUM_VERSION
+
+        raise ConfigurationError, "adapter :ruby_llm needs ruby_llm #{MINIMUM_VERSION} or newer, got #{version}"
+      end
+
+      # Where RubyLLM's own code lives, to tell its ArgumentErrors from the developer's (see #judge).
+      # It is read from the file that was loaded, which is the path RubyLLM's backtrace frames carry.
+      def gem_lib_dir
+        entry = $LOADED_FEATURES.find { |feature| feature.end_with?("/lib/ruby_llm.rb") }
+        return File.dirname(entry) if entry
+
+        File.join(Gem.loaded_specs.fetch("ruby_llm").full_gem_path, "lib")
+      end
+    end
+
+    Adapter::Registry.register_built_in(:ruby_llm, RubyLLM)
+  end
+end

data/lib/squishling/budget.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Squishling
+  # A cap on what one squished call may spend across every request it makes: max_total_output_tokens: and
+  # max_total_input_tokens:, each a positive Integer. A budget is a Hash of the limits one level declares
+  # ({ output:, input: }), layered config -> class -> method -> squish! like generation params. `false` lifts a limit an
+  # outer level set. See docs/failures.md.
+  module Budget
+    # The limit, as declared, for each kind of token, and the counter in Tally#used it is checked against.
+    KEYS = { output: :max_total_output_tokens, input: :max_total_input_tokens }.freeze
+
+    module_function
+
+    # One level's limits, validated. A limit left nil is not set at this level.
+    def build(label, output: nil, input: nil)
+      { output:, input: }.compact.to_h { |kind, value| [kind, check(value, KEYS.fetch(kind), label)] }.freeze
+    end
+
+    # value as is when it is a positive Integer, or false (no limit). Raises ConfigurationError otherwise.
+    def check(value, name, label)
+      return value if value == false || (value.is_a?(Integer) && value.positive?)
+
+      raise ConfigurationError,
+        "#{label}: #{name} must be a positive Integer (or false for no limit), got #{value.inspect}"
+    end
+
+    # The limits that apply: later levels override earlier ones limit by limit, and false removes a limit.
+    def resolve(*layers)
+      layers.compact.reduce({}) { |merged, layer| merged.merge(layer) }.select { |_kind, max| max }
+    end
+
+    # What one call has spent so far, counted from every response it receives. Requests of one round run on worker
+    # threads, so the totals are taken under a lock. A response without token counts adds nothing, so a provider that
+    # reports no usage never exhausts a budget.
+    class Tally
+      def initialize(budget)
+        @budget = budget
+        @used = { input_tokens: 0, output_tokens: 0 }
+        @lock = Mutex.new
+      end
+
+      # Counts a response's tokens: an Adapter::Response, or a judgment (see Observer.usage).
+      def add(response)
+        usage = Observer.usage(response)
+        @lock.synchronize do
+          @used[:input_tokens] += count(usage.input_tokens)
+          @used[:output_tokens] += count(usage.output_tokens)
+        end
+        response
+      end
+
+      # The first limit that has been reached ({ limit:, max:, used: }, used being both totals), or nil.
+      def exhausted
+        @lock.synchronize do
+          @budget.each do |kind, max|
+            next if @used.fetch(:"#{kind}_tokens") < max
+
+            return { limit: KEYS.fetch(kind), max:, used: @used.dup }
+          end
+          nil
+        end
+      end
+
+      private
+
+      def count(tokens)
+        tokens.is_a?(Integer) && tokens.positive? ? tokens : 0
+      end
+    end
+  end
+end