squishling 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76e867f7a93f81c06fb80016fcbeb1e1db39a064f1b8bb1e7cd98194bbf6ef6e
-  data.tar.gz: 2c2ea6a4994f4fb764337c9f194c26eb264cea7a7ecae3e881fa3a4d75303e83
+  metadata.gz: ad18b43555b041d5c0ef6eabda578fc6a2111ecfbf962b2003a7b502584f0c91
+  data.tar.gz: f4ce9bb54bd2c57abd73c5a2f0e50472c338e299f25fe7ed0dd2edb2f4854f06
 SHA512:
-  metadata.gz: ac0484e5a496beb3c3e27a51d13765c8b62c243d2253eacd12c1b532017e141780f723df5164bcaa7548e37b28f27fa901ff493fb343a34426ffafe120d96bde
-  data.tar.gz: 483a5344615d1bc0b1cbb9f3608e4f48df8891eb05dfcb7ad9ac31f22fb3574392f3621d5227037f0a28b48e5389f6e375ef336181ccfd9b3c8836969856cae6
+  metadata.gz: 726d27bcc6067039d3bba294a923c302f49fc756ce0882541461525d8421be48d5cbb9c02e1d201eb1c062c9519353f62b66f9cf43795fc46a15c9834d7e24fe
+  data.tar.gz: 9e4093ad080e9742b38e6bfe3d59f2b5be21f0bf3ddfd5a8288b552bbe9d0abdffe3d47f6fea8d5d0c54afdb0172c69769451249e65f69cfc2665b96682b1b52

data/CHANGELOG.md

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

@@ -71,7 +71,7 @@ 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).
 
 ## Installation
 
@@ -80,11 +80,12 @@ 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:
+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
 ```
 
@@ -108,18 +109,44 @@ Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM
 - **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,
+  and params. 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
+    ]
+    # instructions, output_schema, ...
+  end
+  ```
+- **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.
 - **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.
 
 ## Documentation
 
-- [Configuration](docs/configuration.md): options, model and provider resolution, generation params, inheritance
+- [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_instructions`, 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
 - [Live examples](examples/README.md): end-to-end tests against Anthropic Claude Haiku and OpenAI GPT-6 Luna
 
 ## Development

data/docs/configuration.md

@@ -14,46 +14,102 @@ 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.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). |
+| `logger` | `nil` | Any `Logger`. Debug lines when a call routes to the LLM, warnings on each escalation and when a fallback is used. |
 
 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). |
+| `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, and params, 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. 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
@@ -65,14 +121,14 @@ squish :triage, model: "claude-haiku-4-5", provider: :anthropic
 Squishling.configure { |c| c.default_model = "gpt-6-luna"; 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
+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 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.
 
 ## 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,15 +163,16 @@ 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`, `outputConfig`, `inputs`, …) raise
+  `ConfigurationError`, because they would override the model, the conversation, or the strict output format.
 - 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, provider, generation params (merged key by key), instructions, 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
@@ -124,5 +181,5 @@ overridden methods, are routed the same way.
 ## 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).
+`append_instructions:`, `context:`, `model:` or `escalation:` (with `provider:`), and `params:`. 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).

data/docs/failures.md

@@ -2,34 +2,71 @@
 
 ## When the LLM fails
 
+Every squished call works through its [escalation](configuration.md#models-and-escalation), one attempt at a time.
+A failed attempt moves on to the next one; once the last fails, the error is raised (or handed to the
+[fallback](#fallbacks)). A plain `model:` makes a single attempt.
+
 | Failure | What Squishling does |
 |---|---|
-| Rate limit, 5xx, overload, timeout, connection error | RubyLLM retries at the HTTP level (`RubyLLM.config.max_retries`, default 3). If it still fails, raises `Squishling::LLMError`; the original exception is its `cause`. |
-| Bad API key, unknown model, missing provider config | Raises `Squishling::ConfigurationError`. Never retried, never sent to the fallback. |
-| Provider rejects the request (400 Bad Request), e.g. an unsupported `temperature` or a schema it won't accept | Raises `ConfigurationError` with the provider's message and the params in use. Never retried, never sent to the fallback, so a setup mistake can't be silently covered up on every call. |
-| Empty or `nil` response (e.g. a refusal or a max-tokens cutoff) | Re-asks, then raises `Squishling::InvalidOutputError` |
-| Malformed or truncated JSON | Re-asks, then raises `InvalidOutputError`. JSON wrapped in a markdown code fence is accepted. |
-| JSON that doesn't match the schema (wrong types, missing or extra keys, root not an object) | Re-asks with the validation errors, then raises `InvalidOutputError` |
+| Rate limit, 5xx, overload, timeout, connection error | RubyLLM retries at the HTTP level first (`RubyLLM.config.max_retries`, default 3). If it still fails, moves to the next attempt in a fresh chat; on the last attempt, raises `Squishling::LLMError` with the original exception as its `cause`. |
+| Bad API key, unknown model, missing provider config | Raises `Squishling::ConfigurationError`. Never escalated, never sent to the fallback. |
+| Provider rejects the request (400 Bad Request), e.g. an unsupported `temperature` or a schema it won't accept | Raises `ConfigurationError` with the provider's message and the params in use. Never escalated, never sent to the fallback, so a setup mistake can't be silently covered up on every call. |
+| Empty or `nil` response (e.g. a refusal or a max-tokens cutoff) | Moves to the next attempt, then raises `Squishling::InvalidOutputError` |
+| Malformed or truncated JSON | Moves to the next attempt, then raises `InvalidOutputError`. JSON wrapped in a markdown code fence is accepted. |
+| JSON that doesn't match the schema (wrong types, missing or extra keys, `null` in a non-`optional` field, a broken [conditional rule](schemas.md#contracts-beyond-the-schema), root not an object) | Moves to the next attempt with the validation errors, then raises `InvalidOutputError` |
+| Schema-valid output that [`squish_validate`](#output-checks-squish_validate) rejects | Moves to the next attempt with your messages, then raises `InvalidOutputError` |
 
 Squishling validates output itself with [json_schemer](https://github.com/davishmcclurg/json_schemer), because
-RubyLLM doesn't, and some providers don't enforce strict mode. Re-asks happen in the same conversation, so the model
-sees what it got wrong. `Squishling.config.max_retries` (default 1) sets how many follow-ups are allowed.
-`InvalidOutputError` exposes `errors`, `raw` (the last response), and `attempts`.
+RubyLLM doesn't, and some providers don't enforce strict mode. When the next attempt is on the same step (same
+model, provider, and params), the re-ask happens in the same conversation, so the model sees what it got wrong. A
+different step gets a fresh chat with the original input plus the rejected output and its errors, so that output is
+sent to the next step's provider, which may not be the one that produced it. `InvalidOutputError` exposes `errors`,
+`raw` (the last response), `attempts`, and `models` (the model tried on each attempt). With a `logger` configured,
+every escalation is logged as a warning.
+
+## Output checks (`squish_validate`)
+
+The schema covers shape and types. For rules it can't express, such as cross-field arithmetic or a lookup against
+your data, add a Ruby check. It runs only on LLM output that already matches the schema, receives the typed result
+plus the method's inputs as keywords, and runs against the instance:
+
+```ruby
+class InvoiceParser
+  include Squishling
+  # ...
+  squish_validate do |result, **|
+    errors = []
+    errors << "total must equal the sum of line_items" unless result.total == result.line_items.sum(&:amount)
+    errors << "unknown currency" unless Currency.supported?(result.currency)
+    errors
+  end
+end
+```
+
+- Return `nil`, `true`, `""`, or `[]` to accept the output.
+- Return a message or an array of messages to reject it. The messages are sent to the next attempt and end up in
+  `InvalidOutputError#errors` if every attempt fails. `false` rejects with a generic message.
+- A [dry-validation](https://dry-rb.org/gems/dry-validation/) result works too, if your app already uses it:
+  `squish_validate { |result, **| InvoiceContract.new.call(result.to_h) }`. Squishling doesn't depend on dry-rb.
+- Per method: `squish :triage, validate: ->(result, **inputs) { ... }`. Subclasses inherit the class-level check.
+- It doesn't run on deterministic or fallback returns: those are your own code.
+- Exceptions raised inside it propagate unwrapped, like any of your own code.
 
 ## Errors
 
 | Error | Raised when |
 |---|---|
 | `Squishling::Error` | Base class for everything below. Raised directly for misuse at call time, e.g. `result` or `squish!` called outside a squished method |
-| `Squishling::ConfigurationError` | Missing instructions or schema, a non-strict schema, invalid or reserved params, an invalid `append_instructions` item or unavailable source, bad credentials, an unknown model, a request the provider rejects (400) |
-| `Squishling::InvalidOutputError` | LLM output still invalid after `max_retries`, or a deterministic/fallback return that doesn't match the schema |
-| `Squishling::LLMError` | The provider call failed after RubyLLM's own retries, including context-length errors (`cause` holds the original) |
+| `Squishling::ConfigurationError` | Missing instructions or schema, a non-strict schema, invalid or reserved params, an invalid `model:`/`escalation:` declaration, an invalid `append_instructions` item or unavailable source, bad credentials, an unknown model, a request the provider rejects (400) |
+| `Squishling::InvalidOutputError` | LLM output still invalid (schema or `squish_validate`) after every attempt in the escalation, or a deterministic/fallback return that doesn't match the schema |
+| `Squishling::LLMError` | The provider call failed on the last attempt in the escalation, after RubyLLM's own retries, including context-length errors (`cause` holds the original) |
 
 Errors raised by your own Ruby code are not wrapped.
 
 ## Fallbacks
 
-Use `squish_fallback` to decide what happens when the LLM path fails with `InvalidOutputError` or `LLMError`.
+Use `squish_fallback` to decide what happens when every attempt fails, with `InvalidOutputError` or
+`LLMError`.
 It receives the error plus the method's inputs as keywords, and runs against the instance:
 
 ```ruby
@@ -49,7 +86,7 @@ end
 - Per method: `squish :triage, fallback: ->(error, **inputs) { ... }`.
 - Subclasses inherit the class-level fallback.
 - Calls handed to the LLM with `squish!` use the fallback too. A fallback can't call `squish!` itself; that
-  raises `Squishling::Error` rather than looping. See [Escalating from Ruby](routing.md#escalating-from-ruby-with-squish).
+  raises `Squishling::Error` rather than looping. See [Handing off to the LLM](routing.md#handing-off-to-the-llm-with-squish).
 - Without a fallback, the error propagates.
 
 Routing to Ruby code isn't automatic on failure. The predicate already chose the LLM for this input, so the

data/docs/routing.md

@@ -18,7 +18,7 @@ A squished call runs its Ruby implementation unless one of these sends it to the
 |---|---|---|
 | `squish_when` (or `when:`) predicate is truthy | class, or per method | before Ruby runs |
 | The method has no implementation: it isn't defined, or it raises `NotImplementedError` | the method body | when Ruby gives up |
-| `squish!` | inside the method, e.g. in a `rescue` | after Ruby has partly run, see [Escalating from Ruby](#escalating-from-ruby-with-squish) |
+| `squish!` | inside the method, e.g. in a `rescue` | after Ruby has partly run, see [Handing off to the LLM](#handing-off-to-the-llm-with-squish) |
 
 With no predicate and a working implementation, every call runs Ruby.
 
@@ -86,13 +86,13 @@ end
 - `instructions:` (replaces the class's)
 - `append_instructions:` (added to the class's, see [Appending to the instructions](#appending-to-the-instructions))
 - `output_schema:` (or a schema block)
-- `model:`, `provider:`, and `params:` (generation params; see [Configuration](configuration.md))
+- `model:` or `escalation:`, `provider:`, and `params:` (generation params; see [Configuration](configuration.md))
 - `when:`, a predicate proc
-- `fallback:` (see [Failure handling](failures.md))
+- `validate:` and `fallback:` (see [Failure handling](failures.md))
 
 `squish` can come before or after the method's `def`.
 
-## Escalating from Ruby with `squish!`
+## Handing off to the LLM with `squish!`
 
 Call `squish!` inside a squished method to hand *this call* to the LLM: for example, when the Ruby parser
 fails on an input it wasn't written for. It sends the call's arguments, as any LLM call would, and returns the
@@ -128,7 +128,7 @@ end
 | `context:` | A Hash sent under `"context"` with any `squish_context` values (a same-named key wins). Exceptions are sent as `{ "class", "message" }`, never their backtrace. |
 | `append_instructions:` | Added to the declared sections; `false` (alone or first in an Array) drops them for this call |
 | `instructions:` | Replaces the instructions |
-| `model:`, `provider:`, `params:` | E.g. escalate to a stronger model when Ruby fails. A `provider:` needs a `model:`; `params:` merge key by key over the declared ones. |
+| `model:` or `escalation:`, `provider:`, `params:` | E.g. send this call to a stronger model, or a whole [escalation](configuration.md#models-and-escalation), when Ruby fails. A `provider:` needs a `model:` or `escalation:`; `params:` merge key by key over the declared ones. |
 
 - **The output schema can't be overridden.** The call still returns the method's result type.
 - **Failures** go through the normal LLM path: a declared `squish_fallback` is used, otherwise
@@ -205,6 +205,12 @@ Source is read with Ruby's own parser (Prism) the first time it's needed and cac
   "context":   { "customer_tier": "enterprise", "product": "API" } }
 ```
 
+- **Retries and escalation:** another attempt of the same step gets the validation errors in the same conversation. A
+  later [escalation](configuration.md#models-and-escalation) step, which may be a different provider (say, local
+  Ollama, then hosted Anthropic Claude), gets the same JSON plus the previous model's rejected output and the
+  errors, including any messages your [`squish_validate`](failures.md#output-checks-squish_validate) check
+  returned. Don't put data in those messages that you wouldn't send as an argument.
+
 `squish_context` names are read from a method of that name if there is one, otherwise from the instance
 variable. Only context you name is sent. Instance variables are never dumped wholesale, so API clients,
 database connections, and secrets stay out of the prompt.

data/docs/schemas.md

@@ -85,3 +85,32 @@ branch as usual: `vitals` is a `Data` object or `nil`, and a list of objects is
 JSON Schema, `type: ["array", "null"]` works too. A union with more than one non-null branch is ambiguous, so its
 values come back as plain hashes. If you need the model to tell "none" apart from "not mentioned", say so in your
 instructions.
+
+## Contracts beyond the schema
+
+Every response is validated against the full schema, so some contracts are already enforced:
+
+- **A non-`optional` field can't be `null`.** `string :reason` rejects `"reason": null`. Make a field `optional` only
+  when "not provided" is a real answer.
+- **Constraints** such as `enum`, `min_length`, `pattern`, `minimum`, and `min_items` are checked locally, even where
+  a provider's strict mode ignores them.
+
+For rules that depend on another field, use Schematist's conditionals. A field can be nullable in general but
+required when a condition holds:
+
+```ruby
+output_schema do
+  string :status, enum: %w[approved rejected]
+  optional(:reason) { string }                                  # nil is fine when approved...
+  given(status: "rejected") { string :reason, min_length: 1 }   # ...but not when rejected
+end
+```
+
+Providers' strict modes don't support conditional keywords (`if`/`then`/`else` from `given`, and `dependentRequired`/
+`dependentSchemas` from `dependent`), so Squishling keeps them out of the schema it sends and enforces them itself.
+Output that breaks a rule is rejected like any other invalid output: the call moves on to the next attempt in its
+[escalation](configuration.md#models-and-escalation) with the errors. The model doesn't see these rules
+up front, so state them in your instructions too.
+
+For anything a schema can't express (sums, lookups against your data), use
+[`squish_validate`](failures.md#output-checks-squish_validate).

data/lib/squishling/class_methods.rb

@@ -7,15 +7,18 @@ module Squishling
 
     # Set class-wide options in one call:
     #   squishling model: "claude-sonnet-5-5", instructions: "...", output_schema: MySchema
+    # model: is a single attempt; escalation: is a list of models tried in order (see ModelPath):
+    #   squishling escalation: [{ model: "claude-haiku-4-5", attempts: 2 }, "claude-sonnet-5-5", "claude-opus-5-5"]
     # Pass provider: alongside model: for models missing from RubyLLM's registry, e.g.
     #   squishling model: "gpt-6-luna", provider: :openai
     # params: are generation params merged over the configured defaults (see Configuration#default_params):
     #   squishling params: { temperature: 0.1, top_p: 0.9 }
     # append_instructions: adds sections after the instructions (see #append_instructions):
     #   squishling append_instructions: ["The Ruby that handles well-formed input:", self]
-    def squishling(model: nil, provider: nil, params: nil, instructions: nil, append_instructions: nil,
-      output_schema: nil)
-      @squishling_model = model if model
+    def squishling(model: nil, escalation: nil, provider: nil, params: nil, instructions: nil,
+      append_instructions: nil, output_schema: nil)
+      path = ModelPath.declare(model, escalation, to_s)
+      @squishling_model_path = path if path
       @squishling_provider = provider if provider
       @squishling_params = Params.normalize(params, "#{self} params") if params
       self.instructions(instructions) if instructions
@@ -24,8 +27,9 @@ module Squishling
       self
     end
 
-    def squishling_model
-      squishling_lookup(:@squishling_model)
+    # The class's (or nearest ancestor's) model or escalation, as normalized steps.
+    def squishling_model_path
+      squishling_lookup(:@squishling_model_path)
     end
 
     def squishling_provider
@@ -91,6 +95,19 @@ module Squishling
       squishling_lookup(:@squishling_fallback)
     end
 
+    # Extra checks on LLM output that already matches the schema, called with the typed result and the
+    # method's inputs (as keywords), evaluated against the instance. Return nil (or true, "", []) to accept,
+    # or error message(s) to reject the output and move on to the next attempt, with the messages fed back:
+    #   squish_validate { |result, **| "total must equal the line items" if result.total != result.line_items.sum }
+    # A dry-validation style result (responding to success? and errors) is accepted too.
+    def squish_validate(&block)
+      @squishling_validator = block
+    end
+
+    def squishling_validator
+      squishling_lookup(:@squishling_validator)
+    end
+
     # Instance state (attributes or instance variables) to send to the LLM alongside the arguments.
     def squish_context(*names)
       (@squishling_context_names ||= []).concat(names.map(&:to_sym))
@@ -101,19 +118,21 @@ module Squishling
     end
 
     # Make methods elastic. Each may override the class-level settings:
-    #   squish :triage, instructions: "...", model: "...", provider: :openai, when: ->(**) { true },
-    #                   fallback: ->(error, **) { { priority: "medium" } }, append_instructions: [...] do
+    #   squish :triage, instructions: "...", escalation: %w[claude-haiku-4-5 claude-sonnet-5-5], when: ->(**) { true },
+    #                   fallback: ->(error, **) { { priority: "medium" } }, append_instructions: [...],
+    #                   validate: ->(result, **) { "team is required" if result.team.empty? } do
     #     string :priority
     #   end
-    def squish(*names, instructions: nil, append_instructions: nil, output_schema: nil, model: nil, provider: nil,
-      params: nil, when: nil, fallback: nil, &schema_block)
+    def squish(*names, instructions: nil, append_instructions: nil, output_schema: nil, model: nil, escalation: nil,
+      provider: nil, params: nil, when: nil, fallback: nil, validate: nil, &schema_block)
       schema = schema_block ? Schematist::Schema.create(&schema_block) : output_schema
+      model = ModelPath.declare(model, escalation, "#{self} squish")
       params &&= Params.normalize(params, "#{self} squish params")
       unless append_instructions.nil?
         append_instructions = Appendices.normalize(append_instructions, "#{self} squish append_instructions")
       end
       options = { instructions:, append_instructions:, output_schema: schema, model:, provider:, params:,
-                  predicate: binding.local_variable_get(:when), fallback: }.compact
+                  predicate: binding.local_variable_get(:when), fallback:, validator: validate }.compact
 
       names.map(&:to_sym).each do |name|
         (@squishling_methods ||= {})[name] = options