squishling 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fb55da97a0a032802afcd90b8e56d497a42194206ad90f07d71bc46c70a9e49
-  data.tar.gz: 79430c869cda0726357c42c1ad1fdc7cbf9108a00ebcd56814df4e45acf99db6
+  metadata.gz: 2c50560e08f93a644589fb8ab529a41eca9ae201b81b9dd9233ecc9ea86873c5
+  data.tar.gz: f8e2e5bca400137917567449ce299b59a05b40af787631154144f6b986ba8dbb
 SHA512:
-  metadata.gz: 95f83f1f99d86b5b2fddcc0d5e7d845aff73dbb7cc85620eafb93f999edd69181e8a72c726409cdb6ec11fa1286264947c48ac5f3467c1fb368755ef8ad95b62
-  data.tar.gz: 4ad6fbec6185bb9e4369c972b9f561bce840db75a96ba02c619fe82d1726e15230330b8f457c740017b08e412b3da2c364fd40f657db3128b28cab9c01ba993b
+  metadata.gz: fa16bccb992c1a7b040254e6c909bb1a36588c4e9fa068ce8eb7d6b5bcf4f2e0394429c15b5d4ab7e90ac39f2cf286367eb44475b7abfce9b9a2f177e1388b3f
+  data.tar.gz: 97998785808aae5c1182fa6e0780990f512e2ea653856b853e89fbb330e09621f653355aabc6be2e294d2a13c031df5f94143e3bad85fa3f2315609d445bda0d

data/CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 ```
@@ -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) 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,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" }) }
+```

data/docs/configuration.md

@@ -1,7 +1,9 @@
 # Configuration
 
-Squishling sends requests through [RubyLLM](https://rubyllm.com), so configure provider API keys there first
-(OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, OpenRouter, and any other provider RubyLLM supports):
+Squishling sends requests through an [adapter](adapters.md): [RubyLLM](https://rubyllm.com) (OpenAI, Anthropic
+Claude, Google Gemini, AWS Bedrock, OpenRouter, and any other provider RubyLLM supports), any OpenAI-compatible
+endpoint, or your own. With none configured it uses RubyLLM when the `ruby_llm` gem is in your bundle. For RubyLLM,
+configure provider API keys there first (`require "ruby_llm"` first if your app doesn't use `Bundler.require`):
 
 ```ruby
 RubyLLM.configure do |config|
@@ -14,6 +16,7 @@ Then configure Squishling:
 
 ```ruby
 Squishling.configure do |config|
+  config.adapter = :ruby_llm                   # or :openai_compatible, or your own: see Adapters
   config.default_model = "claude-sonnet-5-5"   # or default_escalation, below
   config.default_provider = nil
   config.default_params = { temperature: 0 }
@@ -24,17 +27,20 @@ end
 
 | Option | Default | Description |
 |---|---|---|
-| `default_model` | `nil` | The universal model (a single attempt) for every squishling class that doesn't declare one. `nil` uses RubyLLM's `default_model`. |
+| `adapter` | `nil` (RubyLLM, when its gem is available) | How requests reach a model: `:ruby_llm`, `:openai_compatible`, a [registered](adapters.md#writing-your-own) name, a Hash with `type:` and that adapter's options, or an adapter instance. See [Adapters](adapters.md). |
+| `default_model` | `nil` | The universal model (a single attempt) for every squishling class that doesn't declare one. `nil` uses the adapter's own default (RubyLLM's `default_model`; the OpenAI-compatible adapter's `default_model:` option). |
 | `default_escalation` | `nil` | The universal [escalation](#models-and-escalation): models tried in order. Assigning it clears `default_model`, and vice versa. |
-| `default_provider` | `nil` | The provider for `default_model`/`default_escalation` steps that don't name one. Only needed for models missing from RubyLLM's registry (see below). |
+| `default_provider` | `nil` | The provider for `default_model`/`default_escalation` steps that don't name one. What it means depends on the adapter: RubyLLM needs it only for models missing from its registry (see below); the OpenAI-compatible adapter ignores it. |
 | `default_params` | `{}` | Generation params for every call (temperature, reasoning effort, top_p, …), overridable per class, per method, and per escalation step. See [Generation params](#generation-params). |
-| `squawk` | `nil` | A callable run after every LLM attempt with the raw output, for sending it to an error tracker or tracing tool. Also settable per class and per method. See [Observing every attempt](failures.md#observing-every-attempt-squawk). |
+| `default_max_total_output_tokens`, `default_max_total_input_tokens` | `nil` (no limit) | The most output (or input) tokens one call may use across all its requests; once reached, the call raises `BudgetExhaustedError` instead of making another attempt. Overridable per class (`squishling max_total_output_tokens: ...`), per method, and per `squish!` call. See [Capping a call's cost](failures.md#capping-a-calls-cost-token-budgets). |
+| `squawk` | `nil` | A callable run after every LLM attempt (see `squawk_on`) with the raw output, for sending it to an error tracker or tracing tool. Also settable per class and per method. See [Observing every attempt](failures.md#observing-every-attempt-squawk). |
+| `squawk_on` | `:all` | Which attempts reach the `squawk` hook: `:all`, `:rejections` (errors only), `:retries` (errors plus any accepted attempt after the first), `:final` (the last attempt the escalation allows), or a list of them (any one holding runs the hook). Also settable per class and per method. |
 | `observer` | `nil` | An around-style hook for every provider request: `:coolhand`, any object responding to `around(call)`, or `false` for none. `nil` uses the [Coolhand observer](coolhand.md) when the `coolhand` gem is configured. See [Observers](observers.md). |
 | `default_harness` | `nil` (`:escalation`) | How every squishling class that doesn't declare its own uses its escalation: `:escalation`, `:squishsum`, `:judged_squishsum`, a [registered custom harness](harnesses.md#custom-harnesses), or a Hash with `type:` and options. See [Harnesses](harnesses.md). |
 | `logger` | `nil` | Any `Logger`. Debug lines when a call routes to the LLM, warnings on each escalation and when a fallback is used. Never includes the raw model response; see [what ends up in errors and logs](failures.md#what-ends-up-in-errors-and-logs). |
 
-Transport-level retries (rate limits, 5xx, timeouts) are configured on RubyLLM itself
-(`RubyLLM.config.max_retries`, `request_timeout`).
+Transport-level retries (rate limits, 5xx, timeouts) belong to the adapter: RubyLLM's own
+(`RubyLLM.config.max_retries`, `request_timeout`), or the OpenAI-compatible adapter's `max_retries:` option.
 
 > **`max_retries` was removed.** The escalation now decides how many attempts run, and setting
 > `config.max_retries` raises `ConfigurationError`. The old default (`max_retries = 1`, two attempts on one model) is
@@ -65,7 +71,9 @@ Each step is a model name, or a Hash with:
 | `attempts:` | `1` | How many attempts this step gets before escalating to the next one. |
 | `priority:` | position | An Integer; steps run lowest first. Give every step a `priority:` or none. Steps with the same priority are one tier (see [Rotating models](#rotating-models-within-a-priority)). Gaps are fine. `order:` is the deprecated name for it. |
 | `rotate:` | `true` | Set `false` on a step to keep its tier in the order written instead of rotating it. |
+| `include_when:` | always | A Proc that leaves this step out of any call where it returns falsy (see [Excluding a model per call](#excluding-a-model-per-call)). |
 | `provider:` | the level's `provider:` | See [Providers](#providers-and-newly-released-models). |
+| `retry_temperature:` | none | A Numeric `temperature` for this step's retries in the same chat (not its first attempt), to nudge a model that keeps sending the same rejected reply. Don't use it on a step that sets `thinking`, since reasoning models reject `temperature`. |
 | `forward_rejected:` | `true` | Set `false` to start this step from the original input alone, without the previous step's rejected output and its errors (see below). |
 | `params:` | `{}` | [Generation params](#generation-params) for this step, merged over the class and method params key by key. |
 
@@ -107,6 +115,25 @@ squishling escalation: [
   whole tier in the order written, whatever its other steps say.
 - Rotation also moves which stages the [`:squishsum` and `:judged_squishsum`](harnesses.md) harnesses sample first.
 
+### Excluding a model per call
+
+`include_when:` takes a Proc, called like a `squish_when` predicate: against the instance, with the method's inputs as
+keywords. A step whose Proc returns falsy is left out of that call's escalation, for example a model without a BAA:
+
+```ruby
+squishling escalation: [
+  { model: "gpt-5", include_when: ->(client:, **) { !client.needs_a_baa_model? } },
+  "claude-sonnet-5-5"
+]
+```
+
+- Steps are filtered before rotation, so a tier rotates only between the models still eligible for the call. A step
+  that is excluded takes no part in its tier, so an excluded `rotate: false` step no longer pins it.
+- A call whose steps are all excluded raises `ConfigurationError`. It is never retried or passed to `squish_fallback`.
+- It applies wherever an escalation is declared (class, method, `default_escalation`, or `squish!`), but not to a judge
+  or harness step, which are single steps.
+- The Proc runs on the calling thread. An exception it raises propagates unwrapped.
+
 `params:` on a step let one step switch to a reasoning model that rejects sampling params:
 
 ```ruby
@@ -123,7 +150,7 @@ The first level that declares a `model:` or an `escalation:` supplies the whole
 2. per method: `squish :name, model: ...` or `escalation: ...`
 3. per class: `squishling model: ...` or `escalation: ...` (inherited by subclasses)
 4. universal: `Squishling.config.default_model` or `default_escalation`
-5. RubyLLM's `default_model` (a single attempt)
+5. the adapter's default model (RubyLLM's `default_model`, or the OpenAI-compatible adapter's `default_model:`; a single attempt)
 
 ```ruby
 class InvoiceParser
@@ -139,16 +166,20 @@ end
 Passing both `model:` and `escalation:` in one declaration raises `ConfigurationError`, and so does a list passed as
 `model:`. Across separate declarations (a reopened class, or two config assignments), the latest one wins.
 
-Consecutive attempts of the same step (same model, provider, params, and `forward_rejected:`, e.g. `attempts: 2`)
+Consecutive attempts of the same step (same model, provider, params, `forward_rejected:`, and `retry_temperature:`, e.g. `attempts: 2`)
 continue one conversation. Moving to a different step starts a fresh chat with the original input plus the previous
 output and why it was rejected, so no provider-specific history crosses providers. That rejected output is
 model-generated and is sent to the next step's provider, even when it is a different one, truncated to 4,000
 characters. If you don't want a step to see it (say, because the next step is a different provider), set
 `forward_rejected: false` on that step and it starts from the original input only. Configuration errors (bad
-credentials, an unknown model, a request the provider rejects) never move to the next attempt. See [Failure handling](failures.md).
+credentials, an unknown model, a request the provider rejects) never move to the next attempt. A retry that returns
+exactly the reply the step was just told was invalid skips the step's remaining attempts and moves to the next step. See [Failure handling](failures.md).
 
 ## Providers and newly released models
 
+This section is about the RubyLLM adapter; the OpenAI-compatible adapter takes model names as given and ignores
+`provider:`.
+
 RubyLLM looks models up in its bundled registry. To use a model that isn't there yet, such as a newly released
 OpenAI or Anthropic model, name its provider next to it. Squishling then tells RubyLLM to assume the model exists:
 
@@ -189,14 +220,17 @@ end
 
 | Key | Sent as |
 |---|---|
-| `temperature` | RubyLLM's `with_temperature` |
-| `max_output_tokens` | RubyLLM's `with_max_output_tokens` (translated to each provider's own field) |
-| `thinking` | RubyLLM's `with_thinking`: `true` (the model's default), `false` (off), or options such as `{ effort: :low }`, `{ budget: 1024 }`, `{ display: :omitted }` |
-| anything else (`top_p`, `seed`, `service_tier`, Gemini's `generationConfig`, …) | merged into the provider request as-is via `with_provider_options`, in that provider's own field names |
+| `temperature` | RubyLLM's `with_temperature`; `temperature` in the request body for OpenAI-compatible endpoints |
+| `max_output_tokens` | RubyLLM's `with_max_output_tokens` (translated to each provider's own field); `max_completion_tokens` (or `max_tokens`) for OpenAI-compatible endpoints |
+| `thinking` | RubyLLM's `with_thinking`: `true` (the model's default), `false` (off), or options such as `{ effort: :low }`, `{ budget: 1024 }`, `{ display: :omitted }`. OpenAI-compatible endpoints take only `{ effort: }`, as `reasoning_effort`. |
+| anything else (`top_p`, `seed`, `service_tier`, Gemini's `generationConfig`, …) | merged into the provider request as-is (via `with_provider_options` in RubyLLM), in that provider's own field names |
 
 - **No params means provider defaults.** Squishling sends nothing unless you set it. For structured
   extraction on non-reasoning models (e.g. Anthropic Claude Haiku), a low temperature reduces run-to-run
   variance.
+- **Thinking counts against `max_output_tokens`** on providers that bill it as output: leave room for the thinking
+  budget plus the answer. With `thinking: { budget: 8192 }` and `max_output_tokens: 8192`, a reply that uses its full
+  budget is cut off before any JSON, which shows as [`InvalidOutputError#truncated?`](failures.md#a-cutoff-or-a-wrong-answer).
 - **Reasoning models** (e.g. OpenAI GPT-6 Luna) usually reject sampling params like `temperature` and `top_p`;
   tune `thinking: { effort: }` instead. Anthropic requires `temperature` to be 1 (or unset) when `thinking` is on.
 - **Unsetting an inherited key:** set it to `nil` to send nothing for that key, so the provider default applies.
@@ -206,8 +240,8 @@ end
   squish :triage, model: "gpt-6-luna", provider: :openai, params: { temperature: nil, thinking: { effort: :low } }
   ```
 
-- Keys that Squishling or RubyLLM control (`model`, `messages`, `input`, `instructions`, `system`, `stream`,
-  `response_format`, `text`, `output_config`, `tools`, `tool_choice`, `schema`, and the camelCase and plural
+- Keys that Squishling or the adapter control (`model`, `messages`, `input`, `instructions`, `system`, `stream`,
+  `response_format`, `text`, `output_config`, `tools`, `tool_choice`, `functions`, `function_call`, `schema`, and the camelCase and plural
   spellings other providers use, such as `systemInstruction`, `toolConfig`/`tool_config`, `outputConfig`, `inputs`, …)
   raise `ConfigurationError`, because they would override the model, the conversation, or the strict output format.
 - **Nested containers** such as Gemini's `generationConfig` (and `generation_config` for Gemini Interactions) and
@@ -225,7 +259,7 @@ end
 
 ## Inheritance
 
-Subclasses inherit the model or escalation and its provider (as a pair), harness, generation params (merged key by key), purpose, output schema,
+Subclasses inherit the model or escalation and its provider (as a pair), harness, generation params (merged key by key), token budgets (limit by limit), purpose, output schema,
 `squish_when` predicate, `squish_context` names, `squish_validate`, `squish_fallback`, and every `squish` declaration. Overrides in a subclass, including
 overridden methods, are routed the same way.
 
@@ -235,5 +269,6 @@ overridden methods, are routed the same way.
 ## Per-call overrides
 
 Inside a squished method, `squish!` sends the call to the LLM with its own `purpose:`,
-`append_to_purpose:`, `context:`, `model:` or `escalation:` (with `provider:`), `params:`, and `harness:`. Each layers over the method and class
+`append_to_purpose:`, `context:`, `model:` or `escalation:` (with `provider:`), `params:`, `harness:`, and
+`max_total_output_tokens:`/`max_total_input_tokens:`. Each layers over the method and class
 settings the same way they layer over each other. See [Handing off to the LLM](routing.md#handing-off-to-the-llm-with-squish).