squishling 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76e867f7a93f81c06fb80016fcbeb1e1db39a064f1b8bb1e7cd98194bbf6ef6e
+  data.tar.gz: 2c2ea6a4994f4fb764337c9f194c26eb264cea7a7ecae3e881fa3a4d75303e83
+SHA512:
+  metadata.gz: ac0484e5a496beb3c3e27a51d13765c8b62c243d2253eacd12c1b532017e141780f723df5164bcaa7548e37b28f27fa901ff493fb343a34426ffafe120d96bde
+  data.tar.gz: 483a5344615d1bc0b1cbb9f3608e4f48df8891eb05dfcb7ad9ac31f22fb3574392f3621d5227037f0a28b48e5389f6e375ef336181ccfd9b3c8836969856cae6

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-08
+
+Initial release.
+
+### Added
+
+- `include Squishling` DSL that makes a class's methods *elastic*: each call either runs the method's Ruby
+  implementation or sends its inputs through an LLM via [RubyLLM](https://rubyllm.com) 2.x, and both paths return
+  the same strict-schema-validated, typed result. `squishling`, `instructions`, `output_schema`, `squish_when`,
+  `squish_context`, `squish`, `squish_fallback`, and `result` (alias `squishling_result`). (#1)
+- Per-input routing: a `squish_when` predicate chooses Ruby or the LLM per call, and a method that is missing or
+  raises `NotImplementedError` goes to the LLM automatically. `squish :name, ...` squishes methods other than
+  `call`, with per-method `instructions`, `output_schema`, `model`, `provider`, `params`, `when`, and
+  `fallback`. (#1)
+- Strict output schemas only, from a Schematist DSL block, a `Schematist::Schema` subclass, or a raw JSON Schema
+  Hash. Object schemas become `Data` result classes with `squished?`, `to_h`, and `[]`; `optional` expresses "not
+  provided" while keeping every key required. `strict: false` raises `ConfigurationError`. (#1)
+- Validation of everything that comes back, using `json_schemer`: LLM output, deterministic returns, and fallback
+  returns. Invalid LLM output is re-asked with the validation errors, up to `max_retries` (default 1). (#1)
+- Failure handling through the `Squishling::Error` taxonomy: `ConfigurationError` (never retried or passed to a
+  fallback), `InvalidOutputError` (with `errors`, `raw`, and `attempts`), and `LLMError` (original exception as
+  `cause`). `squish_fallback` decides what to return when the LLM can't deliver. Exceptions raised by your own
+  Ruby code are never wrapped. (#1)
+- `Squishling.configure` with `default_model`, `default_provider`, `default_params`, `max_retries`, and `logger`.
+  The model resolves per call, per method, per class, then universally, then RubyLLM's default. Naming a
+  `provider:` next to a model lets you use models missing from RubyLLM's registry. (#1)
+- Layered generation params (`temperature`, `max_output_tokens`, `thinking`, and any provider-specific key) that
+  merge key by key across universal, class, and method levels. Keys that Squishling owns (model, messages,
+  structured-output format, tools, streaming) are rejected. (#1)
+- Opt-in context: the LLM sees only method arguments and the `squish_context` values you name, never instance
+  variables wholesale. Fiber-local routing state and mutex-guarded caches keep it thread- and fiber-safe. (#1)
+- `squish!`, which hands the current call to the LLM from inside the Ruby implementation, typically from a
+  `rescue`. Optional per-call `context:`, `append_instructions:`, `instructions:`, `model:`, `provider:`, and
+  `params:`; the output schema can't be overridden, and a declared `squish_fallback` still applies. Exceptions
+  passed in `context:` are sent as their class and message only. (#3)
+- `append_instructions`, which adds sections to the system prompt at the class, subclass, `squish` method, or
+  per-call level. A section can be a String, a Proc, or a class, module, or method rendered as its Ruby source
+  (read with Prism, a Ruby default gem, so there is no new runtime dependency). `false` drops the sections
+  declared above it. Appended source is sent to your provider. (#3)
+- Live end-to-end examples in `examples/` for Anthropic Claude and OpenAI, including `squish!` scenarios. They need
+  real API keys and are not part of the packaged gem. (#1, #3)
+- Documentation: configuration, routing, output schemas, and failure handling guides under `docs/`. (#1, #3)

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,136 @@
+# Squishling
+
+[![CI](https://github.com/Coolhand-Labs/squishling/actions/workflows/ci.yml/badge.svg)](https://github.com/Coolhand-Labs/squishling/actions/workflows/ci.yml)
+
+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.
+
+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.
+
+## Use cases
+
+### Instant integration
+
+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
+  include Squishling
+
+  instructions "Normalize this payment provider's webhook into our payment event."
+  output_schema do
+    string  :event, enum: %w[succeeded failed refunded disputed]
+    integer :amount_cents
+    string  :currency
+    string  :external_id
+  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
+```
+
+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
+LLM, and callers don't change. See [Hardening a path](docs/routing.md#hardening-a-path).
+
+### Error recovery
+
+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.
+
+```ruby
+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
+  output_schema do
+    string :invoice_number
+    number :total
+  end
+
+  def call(vendor:, document:)
+    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.",
+            context: { parse_error: e })
+  end
+end
+
+InvoiceParser.call(vendor: "acme", document: pdf_text).squished?    # => false (Ruby parsed it)
+InvoiceParser.call(vendor: "acme", document: scanned_text).squished? # => true  (recovered by the LLM)
+```
+
+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).
+
+## Installation
+
+```ruby
+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:
+
+```ruby
+Squishling.configure do |config|
+  config.default_model = "claude-sonnet-5-5" # falls back to RubyLLM's default when nil
+end
+```
+
+## How it works
+
+A squishling class needs **instructions** (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,
+- the method has no implementation (it isn't defined, or raises `NotImplementedError`), or
+- the Ruby implementation calls `squish!`.
+
+Otherwise the Ruby runs, and whatever it returns is validated and typed like LLM output.
+
+## Features
+
+- **One contract, two paths**: Ruby returns and LLM output are validated against the same strict schema and
+  returned as the same typed `Data` objects. `squished?` tells you which path served a call.
+- **Your code as context**: `append_instructions` 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.
+- **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
+- [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
+- [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
+```
+
+See [AGENTS.md](AGENTS.md) for repo conventions, and [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
+
+## License
+
+Apache-2.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest published version of `squishling` on RubyGems is supported with security fixes.
+Please upgrade to the latest version before reporting an issue.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Instead, report vulnerabilities privately using one of the following:
+
+- [GitHub Security Advisories](https://github.com/Coolhand-Labs/squishling/security/advisories/new)
+  for this repository (preferred)
+- Email team@coolhandlabs.com
+
+Please include a description of the vulnerability, steps to reproduce, and the impact you believe
+it has. We aim to acknowledge reports within 3 business days and to provide a fix or mitigation
+plan within 30 days, depending on severity.

data/docs/configuration.md

@@ -0,0 +1,128 @@
+# 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):
+
+```ruby
+RubyLLM.configure do |config|
+  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
+end
+```
+
+Then configure Squishling:
+
+```ruby
+Squishling.configure do |config|
+  config.default_model = "claude-sonnet-5-5"
+  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. |
+
+Transport-level retries (rate limits, 5xx, timeouts) are configured on RubyLLM itself
+(`RubyLLM.config.max_retries`, `request_timeout`).
+
+## Model resolution
+
+The model for a squished call comes from the first level that declares one:
+
+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`
+
+```ruby
+class InvoiceParser
+  include Squishling
+  squishling model: "claude-sonnet-5-5"                 # class default
+
+  squish :classify, model: "claude-haiku-4-5" do        # cheaper model for one method
+    string :category
+  end
+end
+```
+
+## 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
+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
+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**:
+
+```ruby
+Squishling.configure { |c| c.default_params = { temperature: 0 } }   # every call
+
+class VisitSummarizer
+  include Squishling
+  squishling params: { temperature: 0.1, top_p: 0.9 }               # this class (and subclasses)
+
+  squish :brainstorm, params: { temperature: 0.9 } do               # one method: temperature 0.9, top_p 0.9
+    array :ideas, of: :string
+  end
+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 |
+
+- **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.
+- **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.
+  This is useful when one method switches to a model that rejects a class-level temperature:
+
+  ```ruby
+  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`, …) 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
+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).
+
+## 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).

data/docs/failures.md

@@ -0,0 +1,57 @@
+# Failure handling
+
+## When the LLM fails
+
+| 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` |
+
+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`.
+
+## 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) |
+
+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`.
+It receives the error plus the method's inputs as keywords, and runs against the instance:
+
+```ruby
+class TicketTriager
+  include Squishling
+  # ...
+  squish_fallback do |error, ticket_text:, **|
+    Rails.logger.warn("triage fell back: #{error.message}")
+    { priority: "medium", team: "support" }   # validated and typed, like a deterministic return
+  end
+end
+```
+
+- The fallback's return value is validated against the schema, like any deterministic return, and its
+  `squished?` is `false`. You can also build it with `result(...)`.
+- To propagate the error instead, re-raise it with `raise error`.
+- 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).
+- 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
+fallback is where you decide whether Ruby code can handle it after all. Calling the method from its fallback
+(`call(**inputs)`) runs its Ruby implementation directly, without routing it back to the LLM.