squishling 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76e867f7a93f81c06fb80016fcbeb1e1db39a064f1b8bb1e7cd98194bbf6ef6e
-  data.tar.gz: 2c2ea6a4994f4fb764337c9f194c26eb264cea7a7ecae3e881fa3a4d75303e83
+  metadata.gz: '0748f552c985521890d365ebc0818ec59c4336f93fb183d1769f49ed8cd32349'
+  data.tar.gz: '05128ecf8d7156e0c8ca084bf8a1860b754596017df2cdfdcc35e2242138fa7b'
 SHA512:
-  metadata.gz: ac0484e5a496beb3c3e27a51d13765c8b62c243d2253eacd12c1b532017e141780f723df5164bcaa7548e37b28f27fa901ff493fb343a34426ffafe120d96bde
-  data.tar.gz: 483a5344615d1bc0b1cbb9f3608e4f48df8891eb05dfcb7ad9ac31f22fb3574392f3621d5227037f0a28b48e5389f6e375ef336181ccfd9b3c8836969856cae6
+  metadata.gz: 2be443b51d2dc1460a410fbf0850bed09e33fff5f7ad894d4bd92e3f47d428d22df7bfc0371036c090a6b806f466b1d930de3a9caf8d1b044185fd4000b765bf
+  data.tar.gz: 3a18d6e041f5807c966677fea5499de8af5d0f28146cb98bbe205141598ee6a01a2d598b1326df3b78227455dcc124c69cf95afacabf9a1689a1cc382a652414

data/CHANGELOG.md

@@ -7,6 +7,129 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-09
+
+### Added
+
+- Harnesses: a `harness:` option (on `squishling`, `squish`, `squish!`, and `default_harness` in
+  `Squishling.configure`) chooses how a call uses its escalation. `:escalation` is the existing behavior and stays
+  the default. `:squishsum` asks the first escalation step twice, concurrently, and accepts the result only when the
+  two samples agree (exact match, or a custom `compare:`). `:judged_squishsum` sends a disagreement to a judge: the
+  next escalation step or a dedicated `judge:` step, either a chat model or a Jev-style decision model through
+  `RubyLLM.judge`, with a default prompt you can override through `judge_instructions:`. Samples that still disagree
+  raise the new `Squishling::DisagreementError < InvalidOutputError`, which carries both typed results, and
+  `squish_fallback` remains the only fallback. See [Harnesses](docs/harnesses.md). (#16)
+- `:ensemble` and `:judged_ensemble` harnesses: like the squishsum ones, but the two concurrent samples come from the
+  escalation's first and second steps (a cross-model check) instead of the first step twice, each retrying within its
+  own step's `attempts:`. A judged ensemble's judge defaults to the third step, or `judge:`, and
+  `DisagreementError#models` names the model behind each sample. An ensemble needs at least two distinct steps (adjacent
+  identical steps count as one step's attempts) or it raises `ConfigurationError` before any request. (#20)
+- `squawk`, an opt-in hook for sending what the model returned to an error tracker or tracing tool. It is called after
+  every LLM attempt (every sample and judge attempt under a harness) with `output:`, `metadata:`, and `error:`, and
+  can be set on `Squishling.configure`, `squishling`, and `squish`. It does nothing by default, and exceptions it
+  raises propagate unchanged. (#15)
+- `forward_rejected:` on escalation steps. When an attempt is rejected and the next step starts, the previous
+  output is forwarded to that step's provider by default (unchanged behavior); set `forward_rejected: false` to start
+  that step from the original input alone. (#14)
+- `include Squishling` raises `ConfigurationError` when the class inherits a method Squishling would override (for
+  example `Sinatra::Base.call`) instead of silently shadowing it. See [Naming and collisions](docs/naming.md). (#17)
+
+### Documentation
+
+- A new guide, [Measuring token spend](docs/measuring-tokens.md), covers working out what each squished path costs
+  (with Coolhand Labs, the `squawk` hook, OpenTelemetry, LangSmith, or RubyLLM's instrumenter), and the README is
+  reworked around using Squishling to harden code paths as the economics justify it. (#21)
+
+### Changed
+
+- **Breaking:** the DSL method `instructions` is now `purpose`, and `append_instructions` is now `append_to_purpose`,
+  including the `instructions:`/`append_instructions:` keywords on `squishling`, `squish`, and `squish!`. There are no
+  aliases. Rename them in your classes: `instructions "..."` becomes `purpose "..."`, and
+  `append_instructions: [...]` becomes `append_to_purpose: [...]`. The error for a missing prompt now says
+  "has no purpose". (#17)
+- **Breaking:** `ruby_llm` must now be `~> 2.1` (was `~> 2.0`); run `bundle update ruby_llm`. (#16)
+- **Breaking:** every value a method with an `output_schema` returns is now validated and typed, not only Hashes. On
+  the Ruby path and in `squish_fallback`, a `nil`, String, Array, or other non-Hash return that used to pass through
+  now raises `InvalidOutputError`; return a Hash (or `result(...)`) that matches the schema. A result of the schema's
+  own class passes through, another schema's result is re-validated, and values JSON can't represent (`NaN`,
+  `Infinity`, cycles) raise `InvalidOutputError` instead of a raw JSON error. Inner calls (`super`, or the method
+  called from `squish_when` or a fallback) still only type Hashes, so overrides can reshape values. (#13)
+- **Behavior change:** a provider now travels with the model declared at the same level on a class too. A subclass
+  that declares its own `model:` or `escalation:` no longer inherits its parent's `provider:`, which could send the
+  whole payload to the parent's provider under another provider's model name. If you relied on that, set `provider:`
+  next to the subclass's model.
+- **Behavior change:** a `provider:` with no model beside it now raises `ConfigurationError` instead of being
+  silently ignored (the default provider was used). `squish ..., provider: ...` needs a `model:` or `escalation:` in
+  the same call, as `squish!` already did; `squishling provider: ...` needs one in the call or already declared on that
+  class. Move the `provider:` next to a model, or use `config.default_provider` with the default model.
+- The `result` alias for `squishling_result` is no longer added when the class already has a `result` (its own or
+  inherited); use `squishling_result` there. (#17)
+- `InvalidOutputError#message` and `config.logger` warnings no longer quote the model's response. For unparseable JSON
+  they report only the line and column; the raw output stays in `InvalidOutputError#raw`. (#15)
+
+### Fixed
+
+- A number a model writes outside the range JSON can represent (such as `1e400`, which parses to `Infinity`), or a
+  string with invalid UTF-8, was accepted as valid, while the same value from a Ruby method was rejected. It is now
+  invalid output on the LLM path too, and no longer raises a bare `JSON::GeneratorError` when `:squishsum` compares samples.
+
+### Security
+
+- Params can no longer replace the strict output format or tools through the containers that also hold ordinary
+  settings: `generationConfig`/`generation_config` (Google Gemini) and `completion_args` (Mistral Conversations) now
+  reject their format and tool keys, with symbol or string keys, and a non-Hash value for them is rejected.
+  `tool_config` is reserved at the top level. Settings such as `topK` still work. (#12)
+- The previous model's rejected output forwarded to the next escalation step is capped at 4,000 characters
+  (`Invoker::MAX_FORWARDED_CHARS`), with a truncation marker. (#14)
+- Model output is kept out of error messages and logs (see the `InvalidOutputError#message` change above); `squawk`
+  is the one sanctioned way for it to leave the process. (#15) A chat judge's `reason` is model-written, so
+  `DisagreementError#message` and the logs no longer include it; read it from `DisagreementError#reason`. A
+  `:judgment` judge's message still carries the choice and probability, and a choice other than `a`, `b`, or `neither`
+  is no longer repeated.
+- Only the first 20 validation errors (plus a count of the rest) are fed back to the model, logged, and put in
+  `InvalidOutputError#message` for one invalid output, so a very large malformed response can no longer produce a
+  megabyte-sized retry message or log line.
+
+## [0.2.0] - 2026-10-09
+
+### Added
+
+- Model escalation: `escalation:` (and `default_escalation` in `Squishling.configure`) declares an ordered list of
+  steps, each a model name or a Hash with `model:`, `attempts:`, an optional explicit `order:`, `provider:`, and
+  `params:`. Invalid output or an `LLMError` moves on to the next attempt. Attempts on the same step continue one
+  conversation; a new step starts a fresh chat that is told about the rejected output and its errors.
+  `ConfigurationError` never escalates. Works per method, per class, in config, and per `squish!` call; the first
+  level that declares a model or escalation wins and levels are never merged. `InvalidOutputError#models` lists the
+  model tried on each attempt. (#6)
+- `squish_validate` (and `validate:` on `squish`): Ruby checks on schema-valid LLM output. Return `nil` or `true` to
+  accept, or `false`, a String, an Array of Strings, or a dry-validation style result to reject the output and
+  trigger the next attempt. Deterministic and fallback returns are not run through it. (#6)
+- Conditional schema rules: Schematist's `given` and `dependent` (JSON Schema `if`/`then`/`else`,
+  `dependentRequired`, and `dependentSchemas`) are kept out of the schema sent to the provider, whose strict mode
+  doesn't support them, and are still enforced locally on every result. (#6)
+
+### Changed
+
+- **Breaking:** `config.max_retries` is removed; reading or setting it raises `ConfigurationError` with a migration
+  hint. The escalation now decides how many attempts run, and a plain `model:` makes a single attempt. To keep the
+  old behavior (two attempts on one model), set
+  `config.default_escalation = [{ model: "your-model", attempts: 2 }]`. (#6)
+- `squish!`'s Ruby-to-LLM handoff is now described as "handing off", so "escalation" only means the model list.
+  `squish!` also accepts `escalation:` (instead of `model:`) for one call. (#6)
+
+### Fixed
+
+- A method with an unnamed positional parameter (a destructuring parameter such as `def call((a, b), second)`) sent
+  every later argument to the LLM under the wrong name. Each argument now keeps its own name, and unnamed ones are
+  sent as `arg0`, `arg1`, and so on.
+
+### Security
+
+- Params can no longer override the system prompt, tool config, or structured-output format through the camelCase
+  and plural request keys used by Google Gemini, Amazon Bedrock Converse, and Mistral Conversations
+  (`systemInstruction`, `cachedContent`, `toolConfig`, `outputConfig`, `inputs`); these now raise
+  `ConfigurationError` like the other reserved keys.
+
 ## [0.1.0] - 2026-10-08
 
 Initial release.

data/README.md

@@ -1,46 +1,54 @@
-# Squishling
+<h1 align="center">
+  <img src="assets/squishling-logo.png" alt="Squishling" width="420">
+</h1>
 
 [![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)
 
-Elastic Ruby classes. A squished method either runs its Ruby implementation or sends its inputs through an LLM
-(via [RubyLLM](https://rubyllm.com)), and either way returns the same strict-schema-validated, typed result.
-Callers can't tell the difference.
+**Don't just use AI to write code. Use AI to not need code.** Write code only where it's worth maintaining.
 
-Inspired by [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai):
-start flexible with AI, then harden high-volume paths into code as the economics justify it.
+A squished method either runs its Ruby implementation, with the LLM as a failover, or routes some callers
+through an LLM as a way of eliminating (or discovering) the cost of maintaining them as deterministic code.
+Either way it returns the same strict-schema-validated, typed result, so callers can't tell the difference.
+
+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).
 
 ## Use cases
 
-### Instant integration
+### Zero-code integrations
 
 Accept a new data source today, before anyone writes a parser. Declare what you want back and leave the
 method unimplemented: every call goes to the LLM, and its output is validated against your schema.
 
 ```ruby
-class PaymentWebhook
+class ShipmentUpdate
   include Squishling
 
-  instructions "Normalize this payment provider's webhook into our payment event."
+  purpose "Normalize this carrier's tracking webhook into our shipment update."
   output_schema do
-    string  :event, enum: %w[succeeded failed refunded disputed]
-    integer :amount_cents
-    string  :currency
-    string  :external_id
+    string :status, enum: %w[label_created in_transit out_for_delivery delivered exception]
+    string :tracking_number
+    string :location
   end
   # No `def call` yet, so every webhook goes to the LLM.
 end
 
-event = PaymentWebhook.call(provider: "adyen", payload: request.raw_post)
-event.event          # => "refunded"
-event.amount_cents   # => 4200
-event.squished?      # => true
+update = ShipmentUpdate.call(carrier: "acme-freight", payload: request.raw_post)
+update.status        # => "out_for_delivery"
+update.squished?     # => true
 ```
 
-When one provider carries the volume, write `def call` for it and add
-`squish_when { |provider:, **| provider != "stripe" }`. Stripe then runs in Ruby, everything else stays on the
+When one carrier carries the volume, write `def call` for it and add
+`squish_when { |carrier:, **| carrier != "ups" }`. UPS then runs in Ruby, everything else stays on the
 LLM, and callers don't change. See [Hardening a path](docs/routing.md#hardening-a-path).
 
-### Error recovery
+Validation guarantees the *shape* of the result, not that it's true. Where a wrong value is costly (money,
+identity), cross-check it against another source or keep that path in Ruby.
+
+### Rescue errors your code can't handle yet
 
 Keep the Ruby you have for the inputs it understands, and hand the rest to the LLM instead of failing. When the
 parser raises, `squish!` sends this call to the LLM with the error and the parser's own source as context.
@@ -49,8 +57,8 @@ parser raises, `squish!` sends this call to the LLM with the error and the parse
 class InvoiceParser
   include Squishling
 
-  instructions "Extract the invoice fields from the vendor's document."
-  append_instructions "The Ruby parser that handles well-formed invoices:", self   # this class's source
+  purpose "Extract the invoice fields from the vendor's document."
+  append_to_purpose "The Ruby parser that handles well-formed invoices:", self   # this class's source
   output_schema do
     string :invoice_number
     number :total
@@ -60,7 +68,7 @@ class InvoiceParser
     invoice = VendorFormats.fetch(vendor).parse(document)
     result(invoice_number: invoice.number, total: invoice.total)
   rescue VendorFormats::ParseError => e
-    squish!(append_instructions: "The parser failed on this document; the error is in the context.",
+    squish!(append_to_purpose: "The parser failed on this document; the error is in the context.",
             context: { parse_error: e })
   end
 end
@@ -71,7 +79,30 @@ InvoiceParser.call(vendor: "acme", document: scanned_text).squished? # => true
 
 Both calls return the same result class. If the LLM can't deliver either, `squish_fallback` decides what to
 return, or the error is raised with the original `ParseError` as its cause. See
-[Escalating from Ruby](docs/routing.md#escalating-from-ruby-with-squish).
+[Handing off to the LLM](docs/routing.md#handing-off-to-the-llm-with-squish).
+
+### 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
+meter, so "should we write a parser for this?" becomes arithmetic: what the path costs in tokens each month,
+against what it costs to write and maintain the code. Write it when the first number is bigger.
+
+Add and initialize the [`coolhand`](https://github.com/Coolhand-Labs/coolhand-ruby) gem, and it picks up your
+squishling calls automatically and measures their accuracy and cost:
+
+```ruby
+# Gemfile
+gem "coolhand"
+
+# config/initializers/coolhand.rb
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_API_KEY")
+end
+```
+
+`squished?` tells you which path served a call. Coolhand records your LLM requests and responses; see
+[what each tool sees](docs/measuring-tokens.md#privacy). Want to roll your own metrics? Check out
+[our guide](docs/measuring-tokens.md) for doing it with other tools.
 
 ## Installation
 
@@ -79,18 +110,19 @@ return, or the error is raised with the original `ParseError` as its cause. See
 gem "squishling"
 ```
 
-Requires Ruby 3.3+ and RubyLLM 2.x. Configure your provider API keys in RubyLLM as usual, then optionally set a
-universal model:
+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:
 
 ```ruby
 Squishling.configure do |config|
   config.default_model = "claude-sonnet-5-5" # falls back to RubyLLM's default when nil
+  # or: config.default_escalation = [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5", "claude-opus-5-5"]
 end
 ```
 
 ## How it works
 
-A squishling class needs **instructions** (the system prompt) and an **output schema** (the shape of the result,
+A squishling class needs a **purpose** (the system prompt) and an **output schema** (the shape of the result,
 validated on both paths). A squished call goes to the LLM when:
 
 - its `squish_when` predicate is truthy for these inputs,
@@ -103,23 +135,62 @@ Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM
 
 - **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_instructions` adds sections to the prompt, including a class's or method's
+- **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,
   reasoning effort, top_p, …).
-- **Defined failure behavior**: invalid output is re-asked with the validation errors, provider errors become
-  `Squishling::LLMError`, and `squish_fallback` decides what to return when the LLM can't deliver.
+- **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
+  cross providers, e.g. a local Qwen model on Ollama, then Anthropic Claude Haiku on AWS Bedrock, then Claude Opus:
+
+  ```ruby
+  RubyLLM.configure do |config|
+    config.ollama_api_base = "http://localhost:11434/v1"
+    config.bedrock_api_key = ENV["AWS_ACCESS_KEY_ID"]
+    config.bedrock_secret_key = ENV["AWS_SECRET_ACCESS_KEY"]
+    config.bedrock_region = "us-east-1"
+    config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  end
+
+  class TicketTriager
+    include Squishling
+
+    squishling escalation: [
+      { model: "qwen3:8b", provider: :ollama, attempts: 2 },   # local and free, tried twice
+      { model: "claude-haiku-4-5", provider: :bedrock },       # small hosted model
+      { model: "claude-opus-5-5", provider: :anthropic }       # last resort
+    ]
+    # purpose, output_schema, ...
+  end
+  ```
+- **[Harnesses](docs/harnesses.md)**: choose how a call uses its escalation with `harness:`
+  - [`: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
+- **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.
 - **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.
+  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
+  model's rejected output, unless the step sets `forward_rejected: false`.
 
 ## Documentation
 
-- [Configuration](docs/configuration.md): options, model and provider resolution, generation params, inheritance
-- [Routing](docs/routing.md): when a call goes to the LLM, `squish!`, `append_instructions`, hardening a path,
+- [Configuration](docs/configuration.md): options, models and escalation, providers, generation params, inheritance
+- [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
-- [Failure handling](docs/failures.md): retries, error classes, fallbacks
+- [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)
+- [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
 - [Live examples](examples/README.md): end-to-end tests against Anthropic Claude Haiku and OpenAI GPT-6 Luna
 
 ## Development
@@ -131,6 +202,17 @@ bundle exec rake        # RSpec (offline; RubyLLM is stubbed) + RuboCop
 
 See [AGENTS.md](AGENTS.md) for repo conventions, and [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
 
+## Credits
+
+Inspired by [Elastic Software](https://everythingengineer.substack.com/p/beginners-write-software-with-ai).
+
 ## License
 
 Apache-2.0
+
+---
+
+<p align="center">
+  This open source project is supported by <a href="https://coolhandlabs.com/">Coolhand Labs</a>.<br><br>
+  <a href="https://coolhandlabs.com/"><img src="assets/coolhand-labs.png" alt="Coolhand Labs" width="220"></a>
+</p>

data/docs/configuration.md

@@ -14,65 +14,135 @@ Then configure Squishling:
 
 ```ruby
 Squishling.configure do |config|
-  config.default_model = "claude-sonnet-5-5"
+  config.default_model = "claude-sonnet-5-5"   # or default_escalation, below
   config.default_provider = nil
   config.default_params = { temperature: 0 }
-  config.max_retries = 1
+  config.default_harness = :escalation
   config.logger = Rails.logger
 end
 ```
 
 | Option | Default | Description |
 |---|---|---|
-| `default_model` | `nil` | The universal model for every squishling class that doesn't declare one. `nil` uses RubyLLM's `default_model`. |
-| `default_provider` | `nil` | The provider for `default_model`. Only needed for models missing from RubyLLM's registry (see below). |
-| `default_params` | `{}` | Generation params for every call (temperature, reasoning effort, top_p, …), overridable per class and per method. See [Generation params](#generation-params). |
-| `max_retries` | `1` | How many times to re-ask the LLM after schema-invalid output before raising `InvalidOutputError`. `0` means a single attempt. See [Failure handling](failures.md). |
-| `logger` | `nil` | Any `Logger`. Debug lines when a call routes to the LLM, warnings when a fallback is used. |
+| `default_model` | `nil` | The universal model (a single attempt) for every squishling class that doesn't declare one. `nil` uses RubyLLM's `default_model`. |
+| `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_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_harness` | `nil` (`:escalation`) | How every squishling class that doesn't declare its own uses its escalation: `:escalation`, `:squishsum`, `:judged_squishsum`, `:ensemble`, `:judged_ensemble`, 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`).
 
-## Model resolution
+> **`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
+> `default_escalation = [{ model: "your-model", attempts: 2 }]`. A plain `model:` now makes one attempt.
 
-The model for a squished call comes from the first level that declares one:
+## Models and escalation
 
-1. per call: `squish!(model: "...")` (see [Per-call overrides](#per-call-overrides))
-2. per method: `squish :name, model: "..."`
-3. per class: `squishling model: "..."` (inherited by subclasses)
-4. universal: `Squishling.config.default_model`
-5. RubyLLM's `default_model`
+Declare **either** a `model:`, one model with a single attempt, **or** an `escalation:`, the models to try in
+order. When an attempt fails (invalid output, a [`squish_validate`](failures.md#output-checks-squish_validate)
+rejection, or a provider failure), the call moves on to the next attempt. It stops at the first valid output, or
+raises once the last attempt fails.
+
+```ruby
+Squishling.configure do |config|
+  config.default_escalation = [
+    { model: "claude-haiku-4-5", attempts: 2 },   # attempts 1-2: same conversation, told what was wrong
+    "claude-sonnet-5-5",                          # attempt 3: fresh chat, shown Haiku's last output and errors
+    "claude-opus-5-5"                             # attempt 4
+  ]
+end
+```
+
+Each step is a model name, or a Hash with:
+
+| Key | Default | Description |
+|---|---|---|
+| `model:` | required | The model id. |
+| `attempts:` | `1` | How many attempts this step gets before escalating to the next one. |
+| `order:` | position | An Integer; steps run lowest first. Give every step an `order:` or none (duplicates are rejected). Gaps are fine. |
+| `provider:` | the level's `provider:` | See [Providers](#providers-and-newly-released-models). |
+| `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. |
+
+Without `order:`, steps run in the order written. With it, the order is explicit and doesn't depend on position:
+
+```ruby
+squishling escalation: [
+  { model: "claude-opus-5-5",   order: 20, params: { thinking: { effort: :high } } },
+  { model: "claude-haiku-4-5",  order: 0, attempts: 2 },
+  { model: "claude-sonnet-5-5", order: 10 }
+]
+```
+
+`params:` on a step let one step switch to a reasoning model that rejects sampling params:
+
+```ruby
+squishling params: { temperature: 0 },
+           escalation: ["gpt-5-mini", { model: "gpt-6-luna", provider: :openai,
+                                        params: { temperature: nil, thinking: { effort: :high } } }]
+```
+
+### Which model or escalation applies
+
+The first level that declares a `model:` or an `escalation:` supplies the whole thing (levels aren't merged):
+
+1. per call: `squish!(model: ...)` or `squish!(escalation: ...)` (see [Per-call overrides](#per-call-overrides))
+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)
 
 ```ruby
 class InvoiceParser
   include Squishling
-  squishling model: "claude-sonnet-5-5"                 # class default
+  squishling escalation: %w[claude-sonnet-5-5 claude-opus-5-5]   # class escalation
 
-  squish :classify, model: "claude-haiku-4-5" do        # cheaper model for one method
+  squish :classify, model: "claude-haiku-4-5" do                 # one cheap attempt for this method
     string :category
   end
 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`)
+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).
+
 ## Providers and newly released models
 
 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:
 
 ```ruby
-squishling model: "gpt-6-luna", provider: :openai
+squishling model: "gpt-7-preview", provider: :openai
 squish :triage, model: "claude-haiku-4-5", provider: :anthropic
-Squishling.configure { |c| c.default_model = "gpt-6-luna"; c.default_provider = :openai }
+Squishling.configure { |c| c.default_model = "gpt-7-preview"; c.default_provider = :openai }
 ```
 
-A provider is paired with the model declared at the same level, so a per-method model never inherits a
-class-level provider meant for a different model. For models that are in the registry, a provider is optional
-and the normal registry lookup is kept.
+A provider is paired with the model or escalation declared at the same level, and applies to that escalation's steps
+that don't name their own. A model never inherits a provider meant for a different model: a per-method model doesn't
+take the class's provider, and a subclass that declares its own `model:` or `escalation:` doesn't take its parent's
+(a subclass that only changes params or the purpose keeps the parent's model and provider together). For models that
+are in the registry, a provider is optional and the normal registry lookup is kept.
+
+A `provider:` with no model beside it would apply to nothing, so it raises `ConfigurationError`:
+`squish ..., provider: ...` needs a `model:` or `escalation:` in the same call (as `squish!` always has), and
+`squishling provider: ...` needs one in the call or already declared on that same class (not inherited). Set the
+provider next to the model, or, for the configured default model, use `config.default_provider`.
 
 ## Generation params
 
-`params` holds generation settings. Set them at any of three levels; each level overrides the one above it
-**key by key**:
+`params` holds generation settings. Set them at any of three levels, plus per step in an
+[escalation](#models-and-escalation); each level overrides the one above it **key by key**:
 
 ```ruby
 Squishling.configure { |c| c.default_params = { temperature: 0 } }   # every call
@@ -107,22 +177,33 @@ end
   ```
 
 - Keys that Squishling or RubyLLM control (`model`, `messages`, `input`, `instructions`, `system`, `stream`,
-  `response_format`, `text`, `output_config`, `tools`, `tool_choice`, `schema`, …) raise `ConfigurationError`,
-  because they would override the model, the conversation, or the strict output format.
+  `response_format`, `text`, `output_config`, `tools`, `tool_choice`, `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
+  Mistral Conversations' `completion_args` accept ordinary settings, but reject the keys inside them that carry the
+  output format or tools (`responseMimeType`, `responseSchema`, `responseJsonSchema`, `response_format`, `tools`,
+  `tool_choice`, `toolConfig`, and their snake_case spellings). Use `output_schema` instead:
+
+  ```ruby
+  squishling params: { generationConfig: { topK: 5 } }                      # ok
+  squishling params: { generationConfig: { responseMimeType: "text/plain" } } # ConfigurationError
+  ```
+
 - If a provider rejects a param, the call raises `Squishling::ConfigurationError` naming the params. It isn't
   retried or sent to `squish_fallback`. See [Failure handling](failures.md).
 
 ## Inheritance
 
-Subclasses inherit the model, provider, generation params (merged key by key), instructions, output schema,
-`squish_when` predicate, `squish_context` names, `squish_fallback`, and every `squish` declaration. Overrides in a subclass, including
+Subclasses inherit the model or escalation and its provider (as a pair), harness, generation params (merged key by key), 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.
 
-`append_instructions` sections are added to, not replaced: a subclass's sections follow its parent's, and
-`append_instructions false` drops the inherited ones. See [Appending to the instructions](routing.md#appending-to-the-instructions).
+`append_to_purpose` sections are added to, not replaced: a subclass's sections follow its parent's, and
+`append_to_purpose false` drops the inherited ones. See [Appending to the purpose](routing.md#appending-to-the-purpose).
 
 ## Per-call overrides
 
-Inside a squished method, `squish!` sends the call to the LLM with its own `instructions:`,
-`append_instructions:`, `context:`, `model:`/`provider:`, and `params:`. Each layers over the method and class
-settings the same way they layer over each other. See [Escalating from Ruby](routing.md#escalating-from-ruby-with-squish).
+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
+settings the same way they layer over each other. See [Handing off to the LLM](routing.md#handing-off-to-the-llm-with-squish).