squishling 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0748f552c985521890d365ebc0818ec59c4336f93fb183d1769f49ed8cd32349'
-  data.tar.gz: '05128ecf8d7156e0c8ca084bf8a1860b754596017df2cdfdcc35e2242138fa7b'
+  metadata.gz: 2c50560e08f93a644589fb8ab529a41eca9ae201b81b9dd9233ecc9ea86873c5
+  data.tar.gz: f8e2e5bca400137917567449ce299b59a05b40af787631154144f6b986ba8dbb
 SHA512:
-  metadata.gz: 2be443b51d2dc1460a410fbf0850bed09e33fff5f7ad894d4bd92e3f47d428d22df7bfc0371036c090a6b806f466b1d930de3a9caf8d1b044185fd4000b765bf
-  data.tar.gz: 3a18d6e041f5807c966677fea5499de8af5d0f28146cb98bbe205141598ee6a01a2d598b1326df3b78227455dcc124c69cf95afacabf9a1689a1cc382a652414
+  metadata.gz: fa16bccb992c1a7b040254e6c909bb1a36588c4e9fa068ce8eb7d6b5bcf4f2e0394429c15b5d4ab7e90ac39f2cf286367eb44475b7abfce9b9a2f177e1388b3f
+  data.tar.gz: 97998785808aae5c1182fa6e0780990f512e2ea653856b853e89fbb330e09621f653355aabc6be2e294d2a13c031df5f94143e3bad85fa3f2315609d445bda0d

data/CHANGELOG.md

@@ -7,7 +7,139 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.3.0] - 2026-10-09
+## [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
+
+- Custom harnesses: `Squishling.register_harness` (with `Squishling.harnesses` and `reset_harnesses!`) and
+  `Squishling::Harness::Base` let you write your own harness and use it anywhere a built-in works (`harness:`,
+  `squish!`, `default_harness`). A harness gets a `Squishling::Run` with `escalate`, `samples`, `judge`, `agree?`,
+  `stage`, and `log`, so it keeps model, provider, and params resolution, `squish_validate`, concurrent samples, and the
+  normal failure handling; it can only return typed results its `Run` produced, and its options are validated when it
+  is declared. The built-in `:escalation`, `:squishsum`, and `:judged_squishsum` now run on the same interface.
+  `squawk` metadata gains `role:` and `sample:`. See [Custom harnesses](docs/harnesses.md#custom-harnesses). (#31)
+- Round-robin models: escalation steps that share a `priority:` form a tier. Each call rotates which model in the tier
+  goes first (counted per class and method, shared across threads), and the tier's other models are tried before the
+  next priority. `rotate: false` on a step pins its tier to the order written. (#38)
+- `config.observer`: an around-style hook (`around(call) { ... }`) wrapped around every provider request, on the thread
+  that makes it, so a `:squishsum` sample's observer runs on its worker thread. It is told the request's `Observer::Call`
+  and gets back only an `Observer::Usage` (token counts and model), never the response. An observer that yields twice
+  or never raises `ConfigurationError`, and one that rescues the request's error has it raised again. See
+  [Observers](docs/observers.md). (#25, #40)
+- A bundled Coolhand observer (`observer = :coolhand`) that declares each call's workload (`Class#method`) and template
+  (`squish:L<n>`, `sample:a`, or `judge`) through `Coolhand.with_context`. The workload's description is
+  `Class#method`, or `Class#method (rescue)` when a `squish!` call handed the call to the LLM (`Observer::Call#handed_off`),
+  never the purpose text. It needs coolhand 0.9.0 or newer. See
+  [Coolhand Labs](docs/coolhand.md). (#40)
+- A docs page and landing-page section on the architecture, an explainer site in `site/` deployed to GitHub Pages, and
+  per-field `description:` documented as the best practice over `purpose` guidance. (#30, #33, #34, #36)
+
+### Changed
+
+- **Behavior change:** when the `coolhand` gem is loaded and configured (an API key, not disabled), Squishling now
+  declares each request's workload and template to it automatically. Nothing changes for apps without Coolhand. To
+  opt out, set `config.observer = false`.
+- **Behavior change:** two escalation steps may now share a `priority:` (they used to raise `duplicate order:`), and
+  they rotate per call as described above. If you relied on a fixed order between tied steps, give them distinct
+  priorities or set `rotate: false`.
+- `order:` on an escalation step is deprecated in favor of `priority:`. It still works, with a deprecation warning, and
+  giving both on one step raises `ConfigurationError`. Judge and harness steps take no `priority:` or `rotate:`. (#38)
+- **Behavior change:** `LLMError` and the `ConfigurationError` for a rejected request (400), bad credentials, or a
+  forbidden key no longer repeat the provider's own message, which can echo request content or part of an API key into
+  logs and error trackers. They carry the error class and HTTP status (`RubyLLM::RateLimitError, HTTP 429`); the
+  provider's message is still on `cause`. If you matched on provider text in `e.message`, read `e.cause.message`
+  instead.
+- `docs/measuring-tokens.md` now points to observers for bringing your own metrics instead of walking through a
+  hand-rolled one. (#40)
+
+### Removed
+
+- **Breaking change:** the `:ensemble` and `:judged_ensemble` harnesses added in 0.3.0 are gone. `harness: :ensemble`
+  or `:judged_ensemble` (and `default_harness`) now raise `ConfigurationError` (unknown harness). Use `:squishsum` or
+  `:judged_squishsum`, which sample the first escalation step twice with the judge defaulting to the next step, or
+  write a custom harness. (#22, #24)
+
+### Internal
+
+- CI gains an exhale duplication and complexity gate (`bin/exhale`), and dependabot bumps `rubocop` (1.92), `ruby/setup-ruby`,
+  and `actions/upload-artifact`. These are development-only changes. (#27, #28, #29, #41)
+
+## [0.3.0] - 2026-10-10
 
 ### Added
 

data/README.md

@@ -2,6 +2,10 @@
   <img src="assets/squishling-logo.png" alt="Squishling" width="420">
 </h1>
 
+<p align="center">
+  <strong><a href="https://coolhand-labs.github.io/squishling/">📖 Read the Squishling explainer →</a></strong>
+</p>
+
 [![CI](https://github.com/Coolhand-Labs/squishling/actions/workflows/ci.yml/badge.svg)](https://github.com/Coolhand-Labs/squishling/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/squishling.svg)](https://badge.fury.io/rb/squishling)
 
@@ -14,7 +18,17 @@ Either way it returns the same strict-schema-validated, typed result, so callers
 Think of code as a cache for AI judgment. Every line you write is something to maintain, so the LLM is the
 default and code has to earn its place: you build it for the inputs that carry the volume, and the LLM keeps
 handling the rest. New to the idea? Read
-[Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai).
+[Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai) or browse the
+[talk slides](https://michael.carroll.io/talks/2026/elastic-software/).
+
+Or try it on the [explainer site](https://coolhand-labs.github.io/squishling/):
+
+- [Spectrum slider](https://coolhand-labs.github.io/squishling/#spectrum): drag from traditional software to fully
+  LLM and see the tradeoff at each point
+- [Token-cost calculator](https://coolhand-labs.github.io/squishling/#number): price your tech debt in tokens
+  against code upkeep
+- [Walkthrough](https://coolhand-labs.github.io/squishling/#squishling): describe it, tune it, pay for accuracy,
+  harden the common shapes
 
 ## Use cases
 
@@ -81,6 +95,12 @@ Both calls return the same result class. If the LLM can't deliver either, `squis
 return, or the error is raised with the original `ParseError` as its cause. See
 [Handing off to the LLM](docs/routing.md#handing-off-to-the-llm-with-squish).
 
+### Retire code you no longer need
+
+Go the other way too. Find the parsers and handlers that serve a thin tail of your traffic and squish them. When a
+path's monthly token cost is lower than what its code costs to maintain, delete the code and relish the feeling of a
+slimmer code base (or let your AI coding agent relish it).
+
 ### Measure your tech debt in tokens
 
 Code you haven't written is debt you haven't taken on. A squished path has a running cost you can read off a
@@ -110,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
 ```
@@ -131,17 +156,25 @@ validated on both paths). A squished call goes to the LLM when:
 
 Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM output.
 
+**Best practice: describe fields in the schema, not the purpose.** Put per-field guidance in a `description:` on
+the field (`string :status, description: "..."`, or `optional(:eta, description: "...") { string }`). The model
+sees it right where the value goes, and the purpose stays short and about the goal. See
+[Describing fields](docs/schemas.md#describing-fields).
+
 ## Features
 
 - **One contract, two paths**: Ruby returns and LLM output are validated against the same strict schema and
   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:`, `order:`, provider,
-  params, and `forward_rejected:`. Invalid output (with its errors fed back) or a provider failure moves on to the next attempt. Steps can
+- **Model escalation**: declare an `escalation:` instead of a `model:`, with per-step `attempts:`, `priority:` (models tied on priority take turns going first), provider,
+  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
@@ -168,13 +201,17 @@ Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM
   - [`:escalation`](docs/configuration.md#models-and-escalation) (default): try each attempt until one passes
   - [`:squishsum`](docs/harnesses.md#samples): two concurrent samples, accepted only if they agree
   - [`:judged_squishsum`](docs/harnesses.md#the-judge): a chat or Jev judge picks between disagreeing samples
-  - [`:ensemble` and `:judged_ensemble`](docs/harnesses.md#ensembles): the same checks across two different models
+  - [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) 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
@@ -182,29 +219,40 @@ Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM
 
 ## Documentation
 
+- [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, ensemble, and judges (chat or Jev)
+- [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, OpenTelemetry, LangSmith, or RubyLLM's instrumenter
+  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.
+Have a suggestion to improve Squishling? [Open an issue](https://github.com/Coolhand-Labs/squishling/issues).
 
 ## Credits
 
-Inspired by [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai).
+Inspired by [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai); see also
+the [talk slides](https://michael.carroll.io/talks/2026/elastic-software/) from XO Ruby NYC 2026.
 
 ## License
 

data/docs/adapters.md

@@ -0,0 +1,189 @@
+# 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`).
+
+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, so use `https://` for anything off your machine or trusted network. `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`. |
+| `open_timeout` / `read_timeout` | `10` / `120` | Seconds. |
+| `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. |
+
+**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.** Every HTTP status of 300 or above except 408, 429, and 5xx (401, 403, 404, 400, 422, a redirect, …) raises `ConfigurationError`, a `RequestRejectedError` for a 400 or other rejected request (never retried or escalated; a 400 that
+reports an overlong context, and a 413, are `LLMError`s, since they depend on the input; a 400 counts as an overlong
+context when its error code is `context_length_exceeded` or its message uses the usual wording ("context length", "too many
+tokens", …), which the message is only matched against, never repeated). 408, 429, 5xx, timeouts, and
+connection errors raise `LLMError` once the adapter's own retries are used up. Messages carry the status or error
+class only; a rejected request (400) 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.
+
+## 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::BadRequest => e
+    # a 400: repeats only the body's status and code, and points at a param only if the provider named one
+    raise rejected_request_error(request, via: "Acme, HTTP 400", body: e.response_body, http_status: 400)
+  rescue Acme::Error => e
+    raise llm_error(request, "Acme failed (#{e.class})")
+  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; `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
+
+| Raise | When | What Squishling does |
+|---|---|---|
+| `Squishling::ConfigurationError` | Bad credentials, a request the provider rejects, an unknown model: anything a retry can't fix | Raised at once. Never retried, escalated, or sent to `squish_fallback`. |
+| `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`). |
+
+Keep the provider's own message out of both: it can echo request content or part of a key, and ours reach logs and
+error trackers. Put the original on `cause` (raising inside a `rescue` does that for you). 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" }) }
+```