squishling 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fb55da97a0a032802afcd90b8e56d497a42194206ad90f07d71bc46c70a9e49
-  data.tar.gz: 79430c869cda0726357c42c1ad1fdc7cbf9108a00ebcd56814df4e45acf99db6
+  metadata.gz: 14b40817f3f49682f1ed311aa5c05007dfc7f55957c9cf89683fd26fea962aa7
+  data.tar.gz: 32b93a239eaa8f5994675a24fca6598e5e0a9edeb8d77efa97ebcf9783db6aa4
 SHA512:
-  metadata.gz: 95f83f1f99d86b5b2fddcc0d5e7d845aff73dbb7cc85620eafb93f999edd69181e8a72c726409cdb6ec11fa1286264947c48ac5f3467c1fb368755ef8ad95b62
-  data.tar.gz: 4ad6fbec6185bb9e4369c972b9f561bce840db75a96ba02c619fe82d1726e15230330b8f457c740017b08e412b3da2c364fd40f657db3128b28cab9c01ba993b
+  metadata.gz: 184955d83ece437fbf86d7f93c2103a1c61302d8df9b70f7430b49b2896c7aab42e04d1f7503203979ff1087ed8e05b67baeb767c9283c43f4bafa82c720abd8
+  data.tar.gz: 351cdbe7b06b587e2c236ff75012fae0bf2fa526613a2d79e6b6c37aac643547bc22cfc74f73cb2e965dc31dd5f0234a7addf034fce8b1de5ea8dd74dab529d3

data/CHANGELOG.md

@@ -7,6 +7,155 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-10-31
+
+The v0.5.0 red-team follow-ups (#70): data-egress, secret-leakage, and misclassification fixes. Several of them change
+behavior that used to work, so read **Changed** before upgrading.
+
+### Added
+
+- The OpenAI-compatible adapter takes `allow_insecure_http:` (default `false`), `max_response_bytes:` (default 8 MiB), and
+  `total_timeout:` (default `open_timeout + 2 * read_timeout`, per attempt). See **Changed** for what they guard.
+  (#74, #86)
+- `keep_cause: true` on the RubyLLM adapter keeps the provider's original exception as `cause`. (#76, #84)
+- `Adapter::Base#http_failure(request, status:, body:, via:)`, an overridable `context_length?(status:, body:)` hook, and
+  `sanitized_cause(error, status:)` for custom adapters: one shared mapping from an HTTP status to `LLMError`,
+  `ConfigurationError`, or `RequestRejectedError`, and a body-free `cause`. See [Adapters](docs/adapters.md). (#72, #76,
+  #84, #88)
+- `squawk` metadata gains `stopped:` (`:budget`, `:disagreement`, or `nil` for an ordinary attempt). (#73, #87)
+
+### Changed
+
+- **Behavior change:** a `NotImplementedError` raised by code a squished method calls (an abstract method on another
+  object, a helper, a block) now propagates instead of sending the method's arguments to the provider. Only the
+  method's own stub routes to the LLM: `def x = raise NotImplementedError`, `define_method`, a prepended module, and an
+  undefined method. To use the LLM from a rescue deeper in the stack, call `squish!` in the method. (#71, #83)
+- **Behavior change:** `error.cause` from the RubyLLM adapter is now an `Adapter::ProviderFailure` that names only the
+  original's class and HTTP status (`RubyLLM::RateLimitError, HTTP 429`) and keeps its backtrace, because the original's
+  message is the provider's response body, which can echo request content and which error trackers such as Sentry report
+  from the cause chain. This reverses 0.4.0's choice to keep the original: code that read `e.cause.message` or
+  `e.cause.is_a?(RubyLLM::...)` needs `keep_cause: true`. The OpenAI-compatible adapter's transport causes carry no body
+  and are unchanged. (#76, #84)
+- **Behavior change:** a provider failure is classified by the adapter from its HTTP status and structured error
+  `code`/`type`, no longer from the provider's message text. Both adapters now agree: 408, 413, 429, and 5xx are
+  `LLMError`; 401, 402, 403, 404, and 3xx are `ConfigurationError`; every other 4xx is a `RequestRejectedError`. On
+  RubyLLM, 402, 404, and 422 were retryable `LLMError`s. A context overflow is an `LLMError` (so it retries and
+  escalates) only when the body's `code`/`type` is `context_length_exceeded`, the adapter recognizes it (the
+  OpenAI-compatible adapter still matches the usual wordings, no longer a bare "maximum ... tokens"), or RubyLLM raised
+  its `ContextLengthExceededError`; one that is only in the message text now raises `RequestRejectedError`. (#72, #88)
+- **Behavior change:** the OpenAI-compatible adapter refuses to send an `api_key` or `Authorization` header over
+  `http://` to a host that isn't loopback (`localhost`, `*.localhost`, `127.0.0.0/8`, `::1`), raising
+  `ConfigurationError`. A LAN or Docker setup such as `http://ollama:11434/v1` needs `allow_insecure_http: true`.
+  Successful responses over `max_response_bytes` raise `LLMError`, requests send `Accept-Encoding: identity` and a
+  compressed successful reply is refused, and `total_timeout:` bounds a whole attempt, not each read. None of those is
+  retried by the adapter. A failure status (4xx, 5xx, redirect) is classified by its status even when its body is
+  compressed or over the cap. (#74, #86)
+- **Behavior change:** a hand-written Hash `output_schema` with `properties` but no `type: "object"`, at the root or
+  nested (a property, array `items`, an `optional` branch, a `$ref` target), now raises `ConfigurationError` when the
+  schema is built, and `Squishling.verify` reports it. Add `type: "object"` (or a union that includes it). Schematist
+  schemas are unaffected. (#77, #81)
+- **Behavior change:** a schema with a remote or unresolvable `$ref` now raises `ConfigurationError` when it is built
+  (and in `verify`), not a raw `JSONSchemer::UnknownRef` on the first reply. A Hash or Array argument that contains
+  itself raises `ConfigurationError`, not `SystemStackError`. `cached_content` joins the reserved `params` keys. (#78,
+  #85)
+- **Behavior change:** the `squawk` hook now also runs once when a call ends on `BudgetExhaustedError` or
+  `DisagreementError`, with `output: nil`, `final: true`, and `stopped:` set, so `squawk_on: :final` and `:rejections`
+  see those endings. A hook that assumes every call has output or usage should skip calls where `metadata[:stopped]` is
+  set. (#73, #87)
+- `Marshal.dump` of an `OpenAICompatible` adapter (or a config holding one) now raises `TypeError`, and its API key and
+  header values show as `[REDACTED]` in `to_yaml` and `as_json`, as they already did in `inspect`. Rebuild the adapter
+  from its options instead of caching a dump. (#75, #82)
+
+### Fixed
+
+- A provider 400 whose error `message`, `code`, or `type` is not valid UTF-8 (for example an echo cut mid-character) now
+  raises `RequestRejectedError` like any other 400, instead of a bare `ArgumentError` that is not a Squishling error.
+- A `ConfigurationError` for a rejected `config.adapter`, `observer`, or `squawk` now names the object's class instead of
+  its `inspect` output, which could print an instance variable such as an access token.
+- `Schema::CACHE` holds its keys weakly, so schema classes replaced by a Rails code reload can be collected. Two equal
+  Hash schemas now share one cached `Schema`. (#78, #85)
+
+### Documented
+
+- `Observer::Call#purpose` is the fully rendered system prompt, including `append_to_purpose` source and procs: treat it
+  as sensitive. `Testing::Stubs` hooks persist after `Testing.reset!`; `Testing.no_llm_call` swaps the process-wide
+  adapter, so it is not safe under parallel test threads; `Run#produced?` compares by identity. (#78, #85)
+
+## [0.5.0] - 2026-10-28
+
+### Added
+
+- Pluggable adapters: provider requests go through an adapter (`Squishling::Adapter::Base`, a stateless
+  `complete(request)`), set with `config.adapter` or registered with `Squishling.register_adapter`. Two ship:
+  `:ruby_llm` (the previous behavior) and `:openai_compatible`, plain `Net::HTTP` against any `/chat/completions`
+  endpoint with retries and strict `json_schema` output, which keeps keys and provider text out of errors, logs, and
+  `inspect`. See [Adapters](docs/adapters.md). (#47)
+- `include_when:` on an escalation step: a Proc called like `squish_when` (the method's inputs as keywords, on the
+  instance) that leaves the step out of a call when falsy, for example a model without a BAA. Steps are filtered before
+  rotation, and a call left with no steps raises `ConfigurationError`. (#46)
+- `squishling/testing` (opt-in, `require "squishling/testing"`): a scripted adapter that records requests and
+  conversations, `assert_no_llm_call`/`forbid_provider_calls!`, schema-validated `stub_result`/`stub_error`,
+  `validate`/`fallback_for`/`preview`, schema-driven `valid_reply_for`/`invalid_reply_for`, squawk capture, and
+  Minitest and RSpec mixins. See [Testing](docs/testing.md). (#44, #50)
+- `Squishling.verify`/`verify!` check every squished class without a request (output schema and typed result, resolved
+  escalation, params and squawk, harness and judge, the keywords `include_when:`/`squish_when` take, and the adapter),
+  reporting every problem; `verify!` raises `VerificationError`. Squished classes are tracked in a weak registry
+  (`Squishling.squished_classes`). A `squishling:verify` rake task (with a Rails Railtie) and a `be_squishling_valid`
+  RSpec matcher (`require "squishling/rspec"`) wrap it. See [Verifying squished classes](docs/verifying.md). (#48, #67)
+- Per-call token budgets: `max_total_output_tokens:` and `max_total_input_tokens:` (on `squishling`, `squish`,
+  `squish!`, and `default_max_total_*` in `Squishling.configure`; layered limit by limit, `false` lifts one) cap what one
+  call spends across its escalation attempts, squishsum sample rounds, and judge. A request in flight is never cut short,
+  so a call can end above the limit by one request. Once a limit is reached the call raises `BudgetExhaustedError`, an
+  `InvalidOutputError`, so `squish_fallback` still receives it. (#55, #68)
+- `squawk_on:` (`:all`, `:rejections`, `:retries`, `:final`, or a list) filters which attempts reach the `squawk` hook,
+  settable with `config.squawk_on`, `squishling squawk_on:`, and `squish :method, squawk_on:`. The default `:all` keeps
+  the old behavior. (#58, #69)
+- `Adapter::Response#finish_reason` (a Symbol such as `:stop` or `:max_tokens`), filled by both built-in adapters.
+  `InvalidOutputError` gains `finish_reason` and `truncated?`, with a fixed note in its message and log line when the
+  reply was cut off, and `squawk` metadata gains `finish_reason`. (#54, #60)
+- `InvalidOutputError#error_details`: `InvalidOutputError::Detail` entries (`message`, `source` of `:schema`,
+  `:validator`, `:parse` or `:squishling`) with a `model_derived?` predicate that is true only for schema errors, which
+  can name a key the model chose. Escape just those when forwarding messages to a chat webhook, HTML, or markdown.
+  `#errors` is still an Array of Strings (now frozen). (#57, #62)
+- `RequestRejectedError` (a `ConfigurationError`) for a provider's 400, with `provider_status` and `provider_code` read
+  as plain tokens from the error body (`INVALID_ARGUMENT`, `invalid_request_error`). The provider's message is still
+  never repeated. (#52, #53)
+- `retry_temperature:` on an escalation step sets the temperature for same-chat retries only. (#56, #61)
+
+### Changed
+
+- **Breaking change:** `ruby_llm` is no longer a runtime dependency of the gem. Apps that use the RubyLLM adapter (the
+  default when no adapter is configured and `ruby_llm` is loadable) must now list `gem "ruby_llm"` in their own
+  Gemfile, and `require "ruby_llm"` before `RubyLLM.configure` if they don't use `Bundler.require`; or switch to
+  `config.adapter = :openai_compatible`. (#47)
+- **Behavior change:** a schema property named like a method the typed result needs (`class`, `hash`, `to_h`,
+  `members`, `inspect`, `is_a?`, ...) now raises `ConfigurationError` when the schema is built, before any request,
+  instead of replacing that method on the result class and failing late. Rename such fields (`class` to
+  `ticket_class`); the reserved names are listed in [Output schemas](docs/schemas.md). (#43, #49)
+- **Behavior change:** when a same-chat retry returns the exact reply it was just rejected for, Squishling skips the
+  step's remaining attempts and moves to the next step (or raises `InvalidOutputError` right away on the last step);
+  samples end early the same way. `InvalidOutputError#attempts` counts requests actually made, `squawk` metadata gains
+  `repeated:`, and `final:` now means no attempt follows a rejection. Size a step's `attempts:` for replies that can
+  differ. (#56, #61)
+- A provider 400's "Check params" hint now names a param only when the provider's error body names one you configured,
+  and otherwise says the params, output schema, or input may be invalid. An array-wrapped overlong-context 400 from the
+  OpenAI-compatible adapter is now an `LLMError`. (#53)
+
+### Fixed
+
+- A raw Hash `output_schema` that omits `type: "object"` no longer lets a non-object reply (a String, Array, or number)
+  reach the typed result as a `NoMethodError`; it is now invalid output, retried, escalated, and sent to
+  `squish_fallback` like any other. Schemas built with Schematist always had `type: "object"`.
+- `RequestRejectedError`'s `provider_status` and `provider_code` no longer accept a hyphenated token, so a key-shaped
+  string a gateway echoes into an error body is never repeated in our message. The RubyLLM adapter's "invalid params"
+  `ConfigurationError` now names the param keys, not their values.
+
+### Internal
+
+- Development dependencies: `ruby_llm` 2.1.1, `coolhand` 0.10.0, and `rubocop` 1.92.1; CI pins `ruby/setup-ruby` v1.335.0
+  so the matrix resolves Ruby 3.3.13, 3.4.12, and 4.0.9. A `finish-release` skill now tags and publishes a reviewed
+  release-prep PR. (#45, #51, #59, #63, #64, #65)
+
 ## [0.4.0] - 2026-10-18
 
 ### Added

data/README.md

@@ -130,12 +130,17 @@ end
 gem "squishling"
 ```
 
-Requires Ruby 3.3+ and RubyLLM 2.1+. Configure your provider API keys in RubyLLM as usual, then optionally set a
-universal model, or an escalation of models to try in order:
+Requires Ruby 3.3+ and an [adapter](docs/adapters.md) to reach a model: the `ruby_llm` gem (2.1+; Squishling uses it
+automatically when it is in your bundle), or any OpenAI-compatible endpoint, which needs no extra gem. Squishling no
+longer installs or requires `ruby_llm` for you, so add `gem "ruby_llm"` next to it if you use RubyLLM (and
+`require "ruby_llm"` before `RubyLLM.configure` if your app doesn't load its Gemfile with `Bundler.require`). With RubyLLM,
+configure your provider API keys there as usual. Then choose an adapter, and optionally set a universal model, or an
+escalation of models to try in order:
 
 ```ruby
 Squishling.configure do |config|
-  config.default_model = "claude-sonnet-5-5" # falls back to RubyLLM's default when nil
+  config.adapter = :ruby_llm                 # or { type: :openai_compatible, base_url: "http://localhost:11434/v1" }
+  config.default_model = "claude-sonnet-5-5" # falls back to the adapter's default when nil
   # or: config.default_escalation = [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5", "claude-opus-5-5"]
 end
 ```
@@ -146,7 +151,7 @@ A squishling class needs a **purpose** (the system prompt) and an **output schem
 validated on both paths). A squished call goes to the LLM when:
 
 - its `squish_when` predicate is truthy for these inputs,
-- the method has no implementation (it isn't defined, or raises `NotImplementedError`), or
+- the method has no implementation (it isn't defined, or its own body raises `NotImplementedError`), or
 - the Ruby implementation calls `squish!`.
 
 Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM output.
@@ -162,11 +167,14 @@ sees it right where the value goes, and the purpose stays short and about the go
   returned as the same typed `Data` objects. `squished?` tells you which path served a call.
 - **Your code as context**: `append_to_purpose` adds sections to the prompt, including a class's or method's
   own Ruby source.
-- **Any RubyLLM provider and model**: OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, OpenRouter, and more.
-  Set a universal, per-class, per-method, or per-call model, plus layered generation params (temperature,
+- **[Bring your own adapter](docs/adapters.md)**: Squishling doesn't depend on any one LLM client. Use the
+  [RubyLLM](https://rubyllm.com) adapter (OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, OpenRouter, and more),
+  the OpenAI-compatible adapter (OpenAI, Ollama, vLLM, LM Studio, Together, Groq, … over plain HTTP), or write your
+  own in one method.
+- **Any provider and model**: set a universal, per-class, per-method, or per-call model, plus layered generation params (temperature,
   reasoning effort, top_p, …).
 - **Model escalation**: declare an `escalation:` instead of a `model:`, with per-step `attempts:`, `priority:` (models tied on priority take turns going first), provider,
-  params, and `forward_rejected:`. Invalid output (with its errors fed back) or a provider failure moves on to the next attempt. Steps can
+  params, `forward_rejected:`, `retry_temperature:`, and `include_when:` (leave a model out of calls where a Proc is falsy). Invalid output (with its errors fed back) or a provider failure moves on to the next attempt. Steps can
   cross providers, e.g. a local Qwen model on Ollama, then Anthropic Claude Haiku on AWS Bedrock, then Claude Opus:
 
   ```ruby
@@ -195,12 +203,15 @@ sees it right where the value goes, and the purpose stays short and about the go
   - [`:judged_squishsum`](docs/harnesses.md#the-judge): a chat or Jev judge picks between disagreeing samples
   - [Your own](docs/harnesses.md#custom-harnesses): `Squishling.register_harness` plugs a custom harness into the same
     machinery (samples, judges, `squawk`, `squish_fallback`)
+- **Cost caps**: `max_total_output_tokens:` and `max_total_input_tokens:` stop a call that keeps failing from
+  spending without limit (see [Capping a call's cost](docs/failures.md#capping-a-calls-cost-token-budgets)).
 - **Output contracts**: beyond the strict schema, conditional rules (`given`) and Ruby checks (`squish_validate`)
   reject bad output and trigger the next attempt.
 - **Defined failure behavior**: provider errors become `Squishling::LLMError`, and `squish_fallback` lets you decide
   what to return when every attempt fails.
-- **Observability**: the opt-in [`squawk`](docs/failures.md#observing-every-attempt-squawk) hook sends every attempt's
-  raw output to your error tracker. Model output stays out of error messages and logs otherwise.
+- **Observability**: the opt-in [`squawk`](docs/failures.md#observing-every-attempt-squawk) hook sends each attempt's
+  raw output (or only the rejected and retried ones), and the end of a call that a token budget or a disagreement
+  stopped, to your error tracker. Model output stays out of error messages and logs otherwise.
 - **Opt-in context**: only method arguments, the instance state you name with `squish_context`, the `context:` you
   pass to `squish!`, and the source you choose to append are sent to the provider. The one addition: when
   [escalation](docs/configuration.md#models-and-escalation) moves to the next step, that step also sees the previous
@@ -211,23 +222,28 @@ sees it right where the value goes, and the purpose stays short and about the go
 - [Explainer site](https://coolhand-labs.github.io/squishling/): interactive walkthrough, spectrum slider, and
   token-cost calculator
 - [Configuration](docs/configuration.md): options, models and escalation, providers, generation params, inheritance
+- [Adapters](docs/adapters.md): the RubyLLM and OpenAI-compatible adapters, and writing your own
 - [Routing](docs/routing.md): when a call goes to the LLM, `squish!`, `append_to_purpose`, hardening a path,
   what the LLM sees
 - [Output schemas](docs/schemas.md): schema forms, strict mode, typed results, optional vs. empty, contracts
 - [Failure handling](docs/failures.md): escalation, `squish_validate`, error classes, fallbacks
 - [Harnesses](docs/harnesses.md): escalation, squishsum, judges (chat or Jev), and custom harnesses
+- [Verifying squished classes](docs/verifying.md): `Squishling.verify!`, a rake task, and an RSpec matcher that check
+  every class ahead of runtime, without a request
 - [Naming and collisions](docs/naming.md): the methods `include Squishling` adds and what happens when a name is taken
 - [Measuring token spend](docs/measuring-tokens.md): see what each squished path costs, with Coolhand Labs,
   the `squawk` hook, your own observer, or OpenTelemetry
 - [Observers](docs/observers.md): wrap every provider request, and the built-in [Coolhand Labs](docs/coolhand.md) observer
   that files each call under its workload and template
+- [Testing](docs/testing.md): `require "squishling/testing"`: a scripted adapter, call assertions, result and error
+  stubs, and schema-driven fixtures, for Minitest and RSpec
 - [Live examples](examples/README.md): end-to-end tests against Anthropic Claude Haiku and OpenAI GPT-6 Luna
 
 ## Development
 
 ```sh
 bin/setup
-bundle exec rake        # RSpec (offline; RubyLLM is stubbed) + RuboCop
+bundle exec rake        # RSpec (offline; adapters are faked or stubbed) + RuboCop
 ```
 
 See [AGENTS.md](AGENTS.md) for repo conventions, and [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

data/docs/adapters.md

@@ -0,0 +1,257 @@
+# Adapters
+
+An **adapter** is how Squishling reaches a model. Squishling builds the request (system prompt, conversation so far,
+strict output schema, generation params), the adapter makes one completion and returns the model's output, and
+Squishling does the rest: validation, `squish_validate`, retries and escalation, harnesses, `squawk`, and fallbacks.
+Two adapters ship, and you can write your own.
+
+| Adapter | Reaches | Needs |
+|---|---|---|
+| [`:ruby_llm`](#ruby_llm) | OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, OpenRouter, and every provider [RubyLLM](https://rubyllm.com) supports | `gem "ruby_llm"` |
+| [`:openai_compatible`](#openai-compatible-endpoints) | Any server that speaks OpenAI's Chat Completions API: OpenAI, Ollama, vLLM, LM Studio, llama.cpp, Together, Groq, … | nothing (Ruby's `Net::HTTP`) |
+| [Your own](#writing-your-own) | Anything | a class with one method |
+
+Squishling itself depends on neither RubyLLM nor any provider SDK.
+
+## Choosing one
+
+```ruby
+Squishling.configure do |config|
+  config.adapter = :ruby_llm                    # a built-in or registered adapter, by name
+  # config.adapter = { type: :openai_compatible, base_url: "http://localhost:11434/v1", default_model: "llama3.2" }
+  # config.adapter = MyAdapter.new              # or any adapter instance
+end
+```
+
+An adapter is built when you assign it, so a missing gem or a bad option fails at boot, not on the first request.
+There is one adapter per process; every squishling class, method, and escalation step goes through it.
+
+**When you set none**, Squishling uses the RubyLLM adapter if the `ruby_llm` gem is in your bundle, so apps that
+configured RubyLLM before adapters existed keep working. Squishling no longer requires `ruby_llm` when it loads, so an
+app that doesn't load its Gemfile with `Bundler.require` should `require "ruby_llm"` before `RubyLLM.configure`. Without the gem, the first squished call
+raises `Squishling::ConfigurationError` saying what to add.
+
+## `:ruby_llm`
+
+Everything works as it did before adapters: configure provider API keys with `RubyLLM.configure`, name models, and
+use `provider:` for models missing from RubyLLM's registry. See [Configuration](configuration.md). Transport-level
+retries are RubyLLM's (`RubyLLM.config.max_retries`, `request_timeout`).
+
+| Option | Default | Description |
+|---|---|---|
+| `keep_cause` | `false` | RubyLLM's exception holds the provider's response body, which can echo your request, and error trackers report the whole `cause` chain. By default the errors the adapter raises carry a sanitized `cause` (the class and HTTP status only). `true` keeps RubyLLM's original exception there. See [the cause of a provider failure](failures.md#the-cause-of-a-provider-failure). |
+
+**Failures** are sorted by the HTTP status of the error's response, the same way as for the OpenAI-compatible adapter
+below (an error with no response, such as a timeout, is sorted by its class). RubyLLM's own error classes are not what
+decides: on a 400 its middleware picks a class from the provider's message text, so a bad parameter whose message says
+"per day" would otherwise look like a rate limit. The one RubyLLM class that is honored over the status is
+`RubyLLM::ContextLengthExceededError`, an `LLMError`, since RubyLLM is where each provider's wording for an overlong
+prompt is known. RubyLLM picks that class from the message on a 400, with wording broader than the OpenAI-compatible
+adapter's, so a bad parameter whose message happens to match is retried as an overflow rather than rejected. Each of
+these errors carries a sanitized `cause` (see `keep_cause` above).
+
+This is the only built-in adapter that supports `type: :judgment` judges ([System One decision models](harnesses.md#the-judge)).
+
+## OpenAI-compatible endpoints
+
+```ruby
+Squishling.configure do |config|
+  config.adapter = {
+    type: :openai_compatible,
+    base_url: "http://localhost:11434/v1",   # where /chat/completions lives
+    api_key: ENV["LLM_API_KEY"],             # optional for local servers
+    default_model: "llama3.2"                # for steps that name no model
+  }
+  config.default_model = "llama3.2"
+end
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `base_url` | `https://api.openai.com/v1` | The API root. Requests go to `{base_url}/chat/completions`. Must be `http(s)` and carry no credentials, query, or fragment. |
+| `api_key` | `ENV["OPENAI_API_KEY"]` for OpenAI's own endpoint, else none | A String, or a callable returning one (called once per completion, outside the adapter's retry handling, so rotating keys work and its exceptions reach you unchanged). Sent as a bearer token; omitted when blank. The key is sent as-is, and not over plain `http://` to another machine unless `allow_insecure_http: true` (below). `OPENAI_API_KEY` is read only for OpenAI's own `https://api.openai.com`, so it can never go to another host: pass `api_key:` for any other endpoint that needs one. |
+| `headers` | `{}` | Extra request headers, e.g. `{ "OpenAI-Organization" => "org-…" }` or a gateway's own. |
+| `default_model` | `nil` | The model for steps that don't name one. Without it, a step with no model raises `ConfigurationError`. |
+| `allow_insecure_http` | `false` | A credential (the `api_key`, or a header named `Authorization`, `Proxy-Authorization`, `api-key`, or `X-Api-Key`; other headers aren't inspected) is never sent over plain `http://` to a host that isn't this machine: building the adapter (or, for a callable key, making the request) raises `ConfigurationError`. Loopback hosts (`localhost`, `*.localhost`, `127.0.0.0/8`, `::1`) are exempt, judged by the name as written and never resolved, so a `*.localhost` name counts even on a resolver that doesn't map it to loopback (use the bare `localhost`, or an IP, if you can't rely on that). Set `true` to send it anyway, for a trusted LAN or container network. With no credential, `http://` to any host is fine. |
+| `open_timeout` / `read_timeout` | `10` / `120` | Seconds. `read_timeout` restarts at every read, so it alone doesn't bound a request. |
+| `total_timeout` | `open_timeout + 2 * read_timeout` | Seconds one attempt (each retry gets its own) may take from connecting to the last byte of the response. Past it the call fails with an `LLMError` that isn't retried by the adapter. |
+| `max_response_bytes` | `8388608` (8 MiB) | The most a response body may hold, an error body included, checked against `Content-Length` and the bytes actually read. Over it, a successful response fails with an `LLMError` that isn't retried by the adapter; a failure status drops the body and is classified by its status. Raise it only if you expect very large completions. |
+| `max_retries` | `2` | Timeouts, connection and protocol failures, HTTP 408, 429, and 5xx are retried this many times with exponential backoff (honoring `Retry-After`, up to 30 seconds) before they surface as an `LLMError`. A timed-out request may still have been processed by the server, so a retry can be billed twice; set `max_retries: 0` if that matters more than resilience. |
+| `max_tokens_param` | `:max_completion_tokens` | The body key for `max_output_tokens`. Use `:max_tokens` for servers that don't know the newer name. |
+| `structured_output` | `:json_schema` | `:json_schema` asks for strict structured output. For servers without it use `:json_object`, or `:none`: the schema then goes into the system prompt in words. Squishling validates every answer itself either way. |
+
+**Credentials stay out of serializers.** The adapter holds the `api_key` and the `headers` (which may carry an
+`api-key` or `Authorization` value) in an opaque wrapper, not in plain instance variables, so logging or caching the
+adapter or `Squishling.config` can't write them out: `inspect`, `to_s`, `pp`, `to_yaml`, `as_json` (including
+ActiveSupport's `instance_values` walk) and `to_json` show `[REDACTED]`, and `Marshal.dump` raises a `TypeError`
+instead of dumping the key. This guards against accidental serialization (a logged config, an error tracker, a cache
+dump), not against code running in your process, which can still reach the value. If you write your own adapter,
+keep credentials out of plain instance variables the same way, or define `encode_with`, `as_json`, and
+`marshal_dump` to omit them.
+
+**How params map.** `temperature` → `temperature`; `max_output_tokens` → `max_tokens_param`; `thinking: { effort: }` →
+`reasoning_effort` (`true`/`false` leave the model's default, and a `budget:` or `display:` raises
+`ConfigurationError`, since Chat Completions has no field for them). Any other param (`top_p`, `seed`, …) goes into
+the request body as given. Squishling's own keys (`model`, `messages`, `response_format`, `n`, `stream`) always win.
+`provider:` has no meaning here and is ignored.
+
+**Failures.** The HTTP status decides (see [the status mapping](#the-error-contract)): 408, 413, 429, 5xx, timeouts, and
+connection errors raise `LLMError` once the adapter's own retries are used up; 401, 402, 403, 404, and a redirect raise
+`ConfigurationError`; any other 4xx (400, 409, 422, …) raises `RequestRejectedError`, never retried or escalated. The
+one exception is a 400 that reports an overlong context, which is an `LLMError` too, since it depends on the input (a
+bigger model may take it). This adapter recognizes one when the error's `code` or `type` is `context_length_exceeded`, or,
+for servers that send neither (vLLM, Ollama, llama.cpp), when its message uses the usual wording ("context length",
+"context window", "context size", "too many tokens", "prompt is too long"). The message is only matched against that
+wording, never repeated; the match is deliberately narrow, so a wording it doesn't know is a rejected request, not a
+retry. Messages carry the status or error class only; a rejected request also carries the server's error status and code
+when they are plain tokens (as `provider_status` and `provider_code`). The server's message, the response body, and the
+API key never appear in an error or log. Redirects aren't followed, so the key can't be sent to another host.
+
+**Response limits.** The adapter sends `Accept-Encoding: identity` (it replaces any `Accept-Encoding` header you set)
+and reads the body in chunks. A successful (2xx) response that is compressed anyway, one over `max_response_bytes`,
+and any response that takes longer than `total_timeout` each raise an `LLMError` naming the limit (never the URL or
+any of the response) and are not retried by the adapter, since the same request would meet the same limit;
+escalation and `squish_fallback` handle it like any other `LLMError`. A failure status (4xx, 5xx, or a redirect) is
+classified by its status alone even when its body is compressed or over the cap: the body is dropped unread, so a
+gateway's gzipped 401 is still a `ConfigurationError`, not a transport failure that `squish_fallback` would absorb,
+and a 503 is still retried.
+
+## Writing your own
+
+Subclass `Squishling::Adapter::Base`, implement `complete`, and return a `Squishling::Adapter::Response`:
+
+```ruby
+class AcmeAdapter < Squishling::Adapter::Base
+  def initialize(client: Acme::Client.new)
+    super()
+    @client = client
+  end
+
+  def complete(request)
+    reply = @client.chat(
+      model: request.model,
+      system: request.instructions,
+      messages: request.messages,                 # [{ role: :user | :assistant, content: "…" }, …]
+      json_schema: request.schema["schema"],      # strict; Squishling validates the answer regardless
+      **request.params
+    )
+    Squishling::Adapter::Response.new(
+      content: reply.text,                        # the raw String (or a Hash you already parsed)
+      model: reply.model,
+      tokens: { input_tokens: reply.usage.in, output_tokens: reply.usage.out }
+    )
+  rescue Acme::AuthError
+    raise configuration_error(request, "Acme rejected the credentials")
+  rescue Acme::HTTPError => e
+    # sorted by status like the built-in adapters; only the status and a rejection's status/code tokens are repeated
+    raise http_failure(request, status: e.status, body: e.response_body, via: "Acme, HTTP #{e.status}")
+  rescue Acme::Error => e
+    raise llm_error(request, "Acme failed (#{e.class})")
+  end
+
+  private
+
+  # Optional: what an overlong prompt looks like for Acme. The default (super) already recognizes a 400 whose error
+  # code or type is "context_length_exceeded"; add whatever else Acme's errors tell you, without reading its message.
+  # body is the provider's error body, a JSON String or a Hash (or nil); ErrorBody.error reads either safely.
+  def context_length?(status:, body:)
+    super || (status == 400 && Squishling::Adapter::ErrorBody.error(body)&.[]("code") == "prompt_too_long")
+  end
+end
+
+Squishling.configure { |config| config.adapter = AcmeAdapter.new }
+# or register it by name, to use config.adapter = :acme (or { type: :acme, client: … }):
+Squishling.register_adapter(:acme, AcmeAdapter)
+```
+
+### The request
+
+`Squishling::Adapter::Request` carries everything for one completion:
+
+| Field | |
+|---|---|
+| `label` | `"Class#method"`, to prefix your error messages (the `configuration_error` / `llm_error` helpers do; `http_failure(request, status:, body:, via:)` sorts an HTTP failure; `rejected_request_error(request, via:, body:, http_status:)` builds the error for a rejected request, from a JSON String or String-keyed Hash body). |
+| `model`, `provider` | The escalation step's, or `nil` when it names none (use your own default). What `provider:` means is up to you. |
+| `instructions` | The system prompt. |
+| `messages` | The conversation so far, ending with the user message to answer. After invalid output, Squishling appends your previous answer and a retry message; you never keep history. |
+| `schema` | `{ "name", "description", "schema", "strict" => true }`: the strict structured-output payload, without the conditional keywords providers can't take. |
+| `params` | The resolved [generation params](configuration.md#generation-params): the portable `:temperature`, `:max_output_tokens`, `:thinking`, plus provider-specific keys. Squishling has already rejected the keys it owns. Translate the portable ones for your provider; pass the rest through if it takes them. |
+
+### The response
+
+`Squishling::Adapter::Response.new(content:, model:, tokens:, finish_reason:)`. `content` is the model's output as a
+String, or a Hash if you parsed it; `nil` or empty counts as invalid output and is retried. `model` is the id the
+provider reports. `tokens` is a Hash (`:input_tokens`, `:output_tokens`, and anything else you have); `{}` when
+unknown. These feed [`squawk`'s `usage`](failures.md#observing-every-attempt-squawk), the [observer](observers.md)'s `Usage`, and the
+[token budget](failures.md#capping-a-calls-cost-token-budgets), which counts `:input_tokens` and `:output_tokens`
+(a response with none never exhausts a budget).
+`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; leave it out (`nil`) when unknown. Map your
+provider's "length" reason to `:max_tokens`, so Squishling can [tell a cutoff from a wrong
+answer](failures.md#a-cutoff-or-a-wrong-answer).
+
+### The error contract
+
+Classifying a provider failure is the adapter's job; what happens next is Squishling's.
+
+**An adapter defines** which error a failure is. Only the adapter knows its provider's status codes, error bodies, and
+how it says a prompt is too long:
+
+| Raise | When | What Squishling does |
+|---|---|---|
+| `Squishling::ConfigurationError` | Bad credentials, billing, an unknown model or endpoint: anything a retry can't fix | Raised at once. Never retried, escalated, or sent to `squish_fallback`. |
+| `Squishling::RequestRejectedError` (a `ConfigurationError`) | The provider refused the request itself: a 400 or another 4xx for a bad param or schema | Same as `ConfigurationError`, so a setup mistake can't be hidden by a fallback on every call. |
+| `Squishling::LLMError` | Rate limit, 5xx, timeout, connection failure, an overlong context: anything worth another go | Moves to the next attempt; raised from the last one (and goes to `squish_fallback`). |
+
+**Squishling manages** everything that follows from the class: retries, escalation, the fallback, the token budget, and
+`squawk`. It never looks at a provider's status, code, or message; it sees only the error class your adapter raised.
+
+For an HTTP provider, `http_failure(request, status:, body:, via:)` does the sorting, so every adapter treats a status
+the same way: 408, 413, 429, 5xx, no status at all (a timeout), and a success status (a reply that was unusable) are
+`LLMError`s; 401, 402, 403, 404, and a redirect are `ConfigurationError`s;
+every other 4xx is a `RequestRejectedError`. `via` ("Acme, HTTP 400") is the only text repeated, plus the status and
+code tokens of a rejection. Between those, one case depends on the provider: a rejected request whose input was too
+long for the model should be an `LLMError`, since a bigger model may take it. `http_failure` asks the
+`context_length?(status:, body:)` hook. Its default recognizes a 400 whose error `code` or `type` is
+`context_length_exceeded` and never reads the message; override it (calling `super`) to recognize what your provider
+sends. Where the adapter can't tell, leave it: the failure stays a `RequestRejectedError`, which is never absorbed.
+
+Keep the provider's own message out of every error you raise: it can echo request content or part of a key, and ours
+reach logs and error trackers, and so do trackers that walk the `cause` chain. If the provider's exception carries a
+response body (an HTTP client error), don't leave it as the `cause` that raising inside a `rescue` sets: pass
+`cause: sanitized_cause(error, status: …)`, which builds a stand-in with only the class, the status, and the
+backtrace. An exception that carries no body (a timeout, a refused connection) can stay as the `cause`. Any other
+exception propagates unwrapped and is never retried, so map your transport's errors. Return anything but an
+`Adapter::Response` and Squishling raises `ConfigurationError`.
+
+### Optional hooks
+
+- **`judgments?` and `judge(input, questions:, step:, label:)`**: System One decision models for `type: :judgment` judges.
+  `judge` returns an object answering `[:winner]` with something that responds to `choice` and `probabilities`.
+  Without `judgments?`, such a judge raises `ConfigurationError` before any request. If the object has `tokens` (with
+  `input` and `output` readers), they count toward the call's token budget.
+- **`capture_context` and `with_context(context) { … }`**: samples (the `:squishsum` harnesses) send their requests from
+  worker threads. `capture_context` runs on the caller's thread and returns whatever your tracing needs; `with_context`
+  re-establishes it around each worker's request. The RubyLLM adapter uses this for its instrumentation workflow.
+
+### Thread safety
+
+Adapters are called concurrently from worker threads when a harness takes samples. Keep no unsynchronized mutable
+state (a per-request HTTP connection, as the OpenAI-compatible adapter does, is the simple way).
+
+### Testing against your adapter
+
+To test your *application* (not an adapter), use [`squishling/testing`](testing.md): a scripted adapter with request
+inspection, call assertions, and stubs. To unit-test an adapter you wrote, a canned one is enough:
+
+```ruby
+class CannedAdapter < Squishling::Adapter::Base
+  def initialize(*replies) = (@replies = replies)
+
+  def complete(request)
+    Squishling::Adapter::Response.new(content: @replies.shift, model: request.model, tokens: {})
+  end
+end
+
+Squishling.configure { |config| config.adapter = CannedAdapter.new({ "label" => "bug" }) }
+```