squishling 0.4.0 → 0.5.1

data/lib/squishling/adapter.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module Squishling
+  # How Squishling reaches a model. An adapter is the only code that talks to a provider: Squishling builds a
+  # Request (the system prompt, the conversation so far, the strict output schema, the resolved params), the adapter
+  # makes one completion and returns a Response. Squishling owns the conversation, the validation, and the retries.
+  # Two adapters ship (Adapters::RubyLLM, Adapters::OpenAICompatible); write your own by subclassing Adapter::Base
+  # and registering it (Squishling.register_adapter) or assigning an instance to config.adapter. See docs/adapters.md.
+  module Adapter
+    # One completion to make. messages holds the conversation so far as { role: :user | :assistant, content: String }
+    # Hashes, ending with the user message to answer; instructions is the system prompt. schema is the strict
+    # structured-output payload ({ "name", "description", "schema", "strict" => true }). params is the resolved
+    # generation params: the portable :temperature, :max_output_tokens, and :thinking, plus any provider-specific keys
+    # (see Params). label ("Class#method") prefixes the adapter's error messages. model and provider are the step's
+    # (nil when it names none).
+    Request = Data.define(:label, :model, :provider, :instructions, :messages, :schema, :params)
+
+    # Stands in for an empty reply when the conversation is replayed: some servers reject an empty assistant message.
+    EMPTY_REPLY = "(no output)"
+
+    # What a completion returns. content is the model's output: the raw String, or a Hash the adapter already parsed.
+    # model is the model id the provider reports. tokens is a Hash of counts (:input_tokens, :output_tokens, and
+    # whatever else the provider reports, such as :cache_read_tokens and :thinking_tokens), empty when unknown.
+    # finish_reason is why the provider stopped, as a Symbol: :stop, :max_tokens (the output cap cut the reply off),
+    # :content_filter, :tool_calls, or the provider's own spelling; nil when it reported none.
+    Response = Data.define(:content, :model, :tokens, :finish_reason) do
+      # model, tokens, and finish_reason may be left out; nil tokens count as none, and a String or blank
+      # finish_reason is made a Symbol or nil. Raises ConfigurationError for tokens that aren't a Hash.
+      def initialize(content:, model: nil, tokens: {}, finish_reason: nil)
+        tokens ||= {}
+        unless tokens.is_a?(Hash)
+          raise ConfigurationError, "Adapter::Response tokens must be a Hash, got #{tokens.class}"
+        end
+
+        finish_reason = finish_reason.to_s.strip.empty? ? nil : finish_reason.to_sym
+        super
+      end
+
+      # Whether the provider cut the reply off at the output token cap.
+      def truncated?
+        finish_reason == :max_tokens
+      end
+
+      # The token counts, or nil when the adapter reported none (what squawk's usage: carries).
+      def usage
+        tokens unless tokens.empty?
+      end
+
+      # The output as the text the model will see again in a retry: a Hash an adapter already parsed goes back as
+      # JSON, and nothing (or a value JSON can't represent, which is rejected as invalid output anyway) as
+      # EMPTY_REPLY.
+      def text
+        text = content.is_a?(String) ? utf8(content) : generated
+        text.strip.empty? ? EMPTY_REPLY : text
+      end
+
+      private
+
+      def generated
+        content.nil? ? "" : JSON.generate(content)
+      rescue JSON::JSONError
+        ""
+      end
+
+      # Text that goes back out in a request must be valid UTF-8, or serializing the history fails. A reply that
+      # wasn't is already reported as invalid output; only its undecodable bytes are replaced here.
+      def utf8(text)
+        (text.encoding == Encoding::BINARY ? text.dup.force_encoding(Encoding::UTF_8) : text).scrub("?")
+      end
+    end
+
+    # What an adapter puts on a Squishling error's #cause in place of a provider's own exception (see
+    # Base#sanitized_cause): the original's class name and HTTP status in its message, and its backtrace, but none of
+    # its message, response, or other state. Not a Squishling::Error: it is never raised, only carried.
+    class ProviderFailure < StandardError; end
+
+    # The adapter contract. Subclass it, implement #complete, and raise Squishling's errors:
+    #
+    #   class MyAdapter < Squishling::Adapter::Base
+    #     def complete(request)
+    #       reply = MyClient.chat(request.model, request.instructions, request.messages)
+    #       Squishling::Adapter::Response.new(content: reply.text, model: reply.model, tokens: reply.usage)
+    #     rescue MyClient::Unauthorized
+    #       raise configuration_error(request, "MyClient rejected the credentials")
+    #     rescue MyClient::Error => e
+    #       raise llm_error(request, "MyClient failed (#{e.class})"), cause: sanitized_cause(e, status: e.status)
+    #     end
+    #   end
+    #
+    # ConfigurationError is for setup mistakes (bad credentials, an invalid request, an unknown model): it is never
+    # retried or escalated. LLMError is for failures worth another attempt (rate limits, 5xx, timeouts, connection
+    # errors, a prompt too long for the model): the next attempt, or the last one's caller, sees it. Keep the provider's
+    # own message out of both: it can echo request content or part of a key. The same goes for the exception it came
+    # from, which error trackers report as the error's #cause: pass `cause: sanitized_cause(e, status:)` rather than
+    # letting a raise inside a rescue set a provider exception that carries a response body. Any other exception
+    # propagates unwrapped.
+    # Which of the two a provider failure is, is the adapter's call (#http_failure maps HTTP statuses, and
+    # #context_length? is where an adapter recognizes an overlong prompt); what happens next is Squishling's.
+    # Adapters are called from worker threads when a harness takes samples, so they must not share unsynchronized state.
+    class Base
+      # One completion. Returns an Adapter::Response.
+      def complete(_request)
+        raise NotImplementedError, "#{self.class} must implement #complete(request)"
+      end
+
+      # Whether #judge is supported (judges with type: :judgment).
+      def judgments?
+        false
+      end
+
+      # A System One judgment: input (a Hash) and questions (a Hash of name => question), with the step's model and
+      # params. Returns an object answering [name] with an answer that responds to choice and probabilities. label
+      # ("Class#method") prefixes error messages. Called as judge(input, questions:, step:, label:).
+      def judge(_input, **_options)
+        raise ConfigurationError, "#{self.class} doesn't support judgments (type: :judgment judges)"
+      end
+
+      # Called on the caller's thread before a harness's sample requests fan out to worker threads. Returns whatever
+      # #with_context needs to re-establish the caller's request context (tracing, say) on a worker.
+      def capture_context
+        nil
+      end
+
+      # Runs the block on a worker thread inside the context #capture_context returned.
+      def with_context(_context)
+        yield
+      end
+
+      private
+
+      def configuration_error(request, message)
+        ConfigurationError.new("#{request.label}: #{message}")
+      end
+
+      def llm_error(request, message)
+        LLMError.new("#{request.label}: #{message}")
+      end
+
+      # What to pass as `cause:` when raising a Squishling error for a provider's exception: a ProviderFailure naming
+      # the original's class and the HTTP status (when given), with the original's backtrace. A provider exception's
+      # message and response usually hold the provider's response body, which can echo request content, and error
+      # trackers (Sentry, say) report the whole cause chain. Built fresh, never a copy of the original, so none of
+      # its state (a Faraday response, say) comes along. Transport errors that carry no body can be passed as they are.
+      def sanitized_cause(error, status: nil)
+        ProviderFailure.new([error.class, ("HTTP #{status}" if status)].compact.join(", "))
+          .tap { |failure| failure.set_backtrace(error.backtrace) }
+      end
+
+      # Classifies a provider's HTTP failure, so adapters sort the same status the same way: 408, 413, 429, and 5xx are
+      # LLMErrors; 401, 402, 403, 404, and a redirect are ConfigurationErrors (credentials, billing, model or endpoint:
+      # nothing a retry fixes); every other 4xx is a RequestRejectedError, unless #context_length? says the input
+      # outgrew the model, which is an LLMError too (a bigger model may take it). via names how it failed (the error
+      # class, the HTTP status) and is all of the failure that is repeated, with a rejection's status and code tokens.
+      # body is the provider's error body, as for #rejected_request_error. A nil status (no HTTP response) or a
+      # success status (a reply that was unusable) is an LLMError.
+      def http_failure(request, status:, body:, via:)
+        case status
+        when nil, 100..299, 408, 413, 429, 500.. then llm_error(request, via)
+        when 401, 403 then configuration_error(request, "the provider refused the credentials (#{via})")
+        when 402 then configuration_error(request, "#{via}: the provider reports a billing or quota problem")
+        when 404 then configuration_error(request, "#{via}: check the model name and the endpoint")
+        when 300..399 then configuration_error(request, "#{via}: redirects aren't followed; check the endpoint")
+        else rejected_or_overlong(request, status:, body:, via:)
+        end
+      end
+
+      # Whether a rejected request (a 400, or another 4xx not otherwise classified) means the input was too long for the
+      # model, which makes it an LLMError rather than a RequestRejectedError. The adapter decides: only it knows how its
+      # provider says so. The default recognizes a 400 whose structured error code or type is "context_length_exceeded",
+      # never reading the message. Override it to recognize more (and call super); when an adapter can't tell, the
+      # failure stays a rejection. status and body are those given to #http_failure.
+      def context_length?(status:, body:)
+        status == 400 && ErrorBody.context_length?(body)
+      end
+
+      def rejected_or_overlong(request, status:, body:, via:)
+        return llm_error(request, via) if context_length?(status:, body:)
+
+        rejected_request_error(request, via:, body:, http_status: status)
+      end
+
+      # A RequestRejectedError for a request the provider rejected (a 400, or another 4xx). via names how it failed
+      # (the error class, the HTTP status); body is the provider's error body (a JSON String, or a Hash with String
+      # keys), of which only the status and code tokens are repeated, never its message. http_status, when given, drops
+      # a code that only repeats it. The params are pointed at only when the provider named one of them.
+      def rejected_request_error(request, via:, body:, http_status: nil)
+        found = ErrorBody.read(body, http_status:)
+        tokens = found.values_at(:status, :code).compact
+        RequestRejectedError.new(
+          "#{request.label}: the provider rejected the request (#{[via, *tokens].join(', ')}). " \
+          "#{rejection_hint(request.params, found[:param])}",
+          provider_status: found[:status], provider_code: found[:code]
+        )
+      end
+
+      def rejection_hint(params, field)
+        named = params.keys.find { |key| names?(field, key.to_s) }
+        return "The #{suspects(params)} may be invalid." unless named
+
+        "The provider named the #{named.inspect} param; check its value."
+      end
+
+      def suspects(params)
+        params.empty? ? "output schema or input" : "params, output schema, or input"
+      end
+
+      # Whether the provider's field is the param or inside it (thinking.budget_tokens, stop[0]).
+      def names?(field, name)
+        !field.nil? && (field == name || field.start_with?("#{name}.", "#{name}["))
+      end
+    end
+
+    # The adapters by name: the built-ins, registered as they load, and your own (Squishling.register_adapter).
+    module Registry
+      STORE = NamedRegistry.new("adapter")
+      private_constant :STORE
+
+      class << self
+        def register_built_in(name, klass)
+          STORE.register_built_in(name, klass)
+        end
+
+        # Registers an adapter class under a name. It is built with the options given next to its type: (or none).
+        def register(name, klass)
+          name = STORE.checked_name(name)
+          unless implements_complete?(klass)
+            raise ConfigurationError, "register_adapter needs a class that implements #complete, got #{klass.inspect}"
+          end
+
+          STORE.add(name, klass)
+        end
+
+        def fetch(name)
+          STORE.fetch(name)
+        end
+
+        def names
+          STORE.names
+        end
+
+        # Forgets the registered adapters; the built-ins stay.
+        def reset!
+          STORE.reset!
+        end
+
+        private
+
+        # A class that defines #complete itself, not one that only inherits Base's placeholder.
+        def implements_complete?(klass)
+          klass.is_a?(Class) && klass.method_defined?(:complete) && klass.instance_method(:complete).owner != Base
+        end
+      end
+    end
+
+    KEYWORD_KINDS = %i[key keyreq].freeze
+    private_constant :KEYWORD_KINDS
+
+    module_function
+
+    # The adapter a config.adapter value names: an instance (anything that responds to complete), a registered name,
+    # or a Hash with type: and that adapter's options. Built now, so a mistake (a missing gem, a bad option) fails at
+    # setup rather than on the first request.
+    def build(value, where)
+      case value
+      when Symbol, String then instantiate(value, {}, where)
+      when Hash
+        options = value.transform_keys(&:to_sym)
+        raise ConfigurationError, "#{where} adapter: needs a type: (#{type_list})" unless options.key?(:type)
+
+        instantiate(options.delete(:type), options, where)
+      else
+        return value if value.respond_to?(:complete)
+
+        raise ConfigurationError, "#{where} adapter must be an adapter (responding to complete), one of " \
+                                  "#{type_list}, or a Hash with type:, got #{Appendices.describe(value)}"
+      end
+    end
+
+    # The adapter used when none is configured: RubyLLM's, if the ruby_llm gem is available.
+    def detect
+      Adapters::RubyLLM.new
+    rescue Adapters::RubyLLM::MissingGemError
+      raise ConfigurationError, "No adapter is configured and the ruby_llm gem isn't available. " \
+                                "Add `gem \"ruby_llm\"` to your Gemfile, or set config.adapter " \
+                                "(#{type_list}, or your own adapter)"
+    end
+
+    def type_list
+      Registry.names.map(&:inspect).join(", ")
+    end
+
+    def instantiate(type, options, where)
+      name = type.to_s.to_sym
+      klass = Registry.fetch(name)
+      unless klass
+        raise ConfigurationError, "#{where} adapter: unknown adapter #{type.inspect} (available: #{type_list})"
+      end
+
+      check_options!(klass, options, name, where)
+      options.empty? ? klass.new : klass.new(**options)
+    end
+
+    # The keywords the adapter's initialize takes, so a typo is a ConfigurationError rather than an ArgumentError.
+    def check_options!(klass, options, name, where)
+      known, required = keywords(klass)
+      return unless known
+
+      unknown = options.keys - known
+      missing = required - options.keys
+      return if unknown.empty? && missing.empty?
+
+      problem = unknown.empty? ? "needs #{missing.join(', ')}" : "doesn't take #{unknown.join(', ')}"
+      hint = known.empty? ? "" : " (options: #{known.join(', ')})"
+      raise ConfigurationError, "#{where} adapter #{name.inspect} #{problem}#{hint}"
+    end
+
+    # [all keywords, required keywords] of klass#initialize, or nil when it takes any (**options).
+    def keywords(klass)
+      parameters = klass.instance_method(:initialize).parameters
+      return if parameters.any? { |kind, _| kind == :keyrest }
+
+      [parameters.filter_map { |kind, key| key if KEYWORD_KINDS.include?(kind) },
+       parameters.filter_map { |kind, key| key if kind == :keyreq }]
+    end
+    private_class_method :check_options!, :keywords
+    private_class_method :instantiate
+  end
+end

data/lib/squishling/adapters/openai_compatible.rb

@@ -0,0 +1,311 @@
+# 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
+      Transport = OpenAITransport
+      private_constant :Options, :Transport
+
+      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
+      DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+      MAX_RETRY_DELAY = 30
+      # How servers without OpenAI's error code (vLLM, Ollama, llama.cpp, ...) say a prompt is too long. Deliberately
+      # narrow (no bare "maximum ... tokens", which a bad max_tokens value also says): a wording that isn't here is a
+      # rejected request, which is the safe side. The message is only matched against this, never repeated.
+      CONTEXT_LENGTH_MESSAGE = /context (length|window|size)|too many tokens|prompt is too long/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. allow_insecure_http: lets a credential (api_key, or a header such as Authorization or api-key) go
+      # over plain http to a host that isn't loopback; without it that is a ConfigurationError. max_response_bytes:
+      # the most a response (an error body too) may hold, 8 MiB by default. total_timeout: the most seconds one
+      # attempt may take (read_timeout restarts at every read); it defaults to open_timeout + 2 * read_timeout.
+      # Responses are requested and accepted uncompressed only. 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,
+        allow_insecure_http: false, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES, total_timeout: nil)
+        super()
+        @endpoint = Options.endpoint(base_url)
+        @api_key = (Secret.new(api_key) unless api_key.nil?)
+        @headers = Secret.new(Options.headers(headers))
+        @allow_insecure_http = Options.flag(:allow_insecure_http, allow_insecure_http)
+        @default_model = Options.default_model(default_model)
+        @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)
+        @transport = build_transport(open_timeout, read_timeout, total_timeout, max_response_bytes)
+        check_cleartext!(api_key.respond_to?(:call) ? nil : api_key)
+      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). The key and headers are held in a Secret, so to_yaml, as_json and Marshal can't expose them
+      # either.
+      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&.success?
+
+          failure = failure_for(request, response, error)
+          raise failure, cause: error unless retryable?(response, error) && attempt <= @max_retries
+
+          pause(retry_delay(response, attempt))
+        end
+      rescue Transport::Refused => e
+        # A size or time limit, or compression: the same request would hit it again, so it isn't retried.
+        raise llm_error(request, e.message), cause: e
+      end
+
+      def exchange(body, headers)
+        [@transport.post(body, headers), nil]
+      rescue *NETWORK_ERRORS => e
+        [nil, e]
+      end
+
+      def build_transport(open_timeout, read_timeout, total_timeout, max_response_bytes)
+        open_timeout = Options.number(:open_timeout, open_timeout)
+        read_timeout = Options.number(:read_timeout, read_timeout)
+        Transport.new(endpoint: @endpoint, open_timeout:, read_timeout:,
+          total_timeout: Options.total_timeout(total_timeout, open_timeout, read_timeout),
+          max_response_bytes: Options.number(:max_response_bytes, max_response_bytes, type: Integer))
+      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_value.to_s.strip
+        if Options.unsafe_header?(key)
+          raise configuration_error(request,
+            "the api_key can't contain line breaks or NUL")
+        end
+        check_cleartext!(key, request)
+
+        headers = { "Content-Type" => "application/json", "Accept" => "application/json",
+                    "User-Agent" => "squishling/#{VERSION}" }
+        headers["Authorization"] = "Bearer #{key}" unless key.empty?
+        # Accept-Encoding is Squishling's own: a compressed response would be inflated past the size cap.
+        headers.merge(@headers.reveal).reject { |name, _| name.casecmp?("accept-encoding") }
+          .merge("Accept-Encoding" => "identity")
+      end
+
+      def api_key_value
+        key = @api_key&.reveal
+        key.respond_to?(:call) ? key.call : (key || default_api_key)
+      end
+
+      # A credential doesn't go over plain http to another machine unless allow_insecure_http: says so. Checked when the
+      # adapter is built for a key given as a String, and again with each request's own key (a callable's). Reads the
+      # headers through their Secret; the message names neither the key nor a header value.
+      def check_cleartext!(key, request = nil)
+        return if @allow_insecure_http || !Options.cleartext_credential?(@endpoint, key, @headers.reveal)
+
+        raise configuration_error(request, Options::CLEARTEXT_CREDENTIAL) if request
+
+        raise ConfigurationError, Options::CLEARTEXT_CREDENTIAL
+      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
+        http_failure(request, status:, body: response.body.to_s, via: "HTTP #{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
+
+      # The structured code or type, as for any adapter, or the usual wording of a server that sends none (a 400).
+      def context_length?(status:, body:)
+        super || (status == 400 && Adapter::ErrorBody.error(body)&.[]("message").to_s.scrub.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