squishling 0.4.0 → 0.5.1

data/docs/observers.md

@@ -60,7 +60,7 @@ Anything else raises `ConfigurationError` when you assign it.
 | Field | |
 |---|---|
 | `label` | `"Class#method"` |
-| `purpose` | The purpose text sent as the system prompt (after `purpose` procs and `append_to_purpose` sections are resolved) |
+| `purpose` | The purpose text sent as the system prompt (after `purpose` procs and `append_to_purpose` sections are resolved). It is the whole prompt, including any source you pass to `append_to_purpose` and whatever your `purpose` procs return, so treat it as sensitive: don't log it to a place the prompt itself shouldn't go |
 | `handed_off` | `true` when a `squish!` call sent the call to the LLM (typically from a `rescue`), `false` when `squish_when` or a missing implementation did |
 | `harness` | The harness type (`:escalation`, `:squishsum`, `:judged_squishsum`, or a [custom one](harnesses.md#custom-harnesses)) |
 | `role` | `nil` for an escalation attempt, `:sample` or `:judge`, as in `squawk`'s `metadata` |
@@ -69,8 +69,8 @@ Anything else raises `ConfigurationError` when you assign it.
 | `model`, `provider` | The step's model and provider (`provider` is `nil` unless declared) |
 | `request` | `:chat`, or `:judgment` for a System One judge |
 
-It carries metadata only. The method's inputs, its context, and the model's output never reach an observer: it gets
-the request's token [`Usage`](#what-yield-returns) back, and `squawk` is the route for output.
+It carries metadata, plus the rendered `purpose`. The method's inputs, its context, and the model's output never reach an
+observer: it gets the request's token [`Usage`](#what-yield-returns) back, and `squawk` is the route for output.
 
 ## Errors
 

data/docs/routing.md

@@ -17,7 +17,7 @@ A squished call runs its Ruby implementation unless one of these sends it to the
 | Trigger | Declared where | Decided |
 |---|---|---|
 | `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 |
+| The method has no implementation: it isn't defined, or its own body raises `NotImplementedError` | the method body | when Ruby gives up |
 | `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.
@@ -41,8 +41,14 @@ is validated against the schema and turned into the same typed result the LLM pa
 already has a `result` (see [Naming and collisions](naming.md)). Invalid deterministic output raises
 `Squishling::InvalidOutputError` too, so a hardened path can't silently drift from the contract.
 
-A `NotImplementedError` raised anywhere inside the method, including from code it calls, also routes to the
-LLM.
+Only the method's own stub routes: a `NotImplementedError` raised directly in the method body (`raise
+NotImplementedError` in a `def` or a `define_method` block, including one in a module prepended before
+`include Squishling`, or in a squished parent reached through `super`). One raised by code the method calls
+(a helper, another object, a block, or a `super` into a parent that isn't squished) is a bug in that code, not a
+missing implementation, so it propagates and nothing is sent to the provider. Keep the `raise` in the method body:
+a shared `not_implemented!` helper, or a decorator prepended before `include Squishling` that wraps the method with
+its own `super` frame, hides the stub and the error propagates (use `squish_when { true }` or `squish!` to
+send those calls to the LLM).
 
 Each call is routed on its own, including a squished method that calls itself on smaller inputs (those
 recursive calls must return schema-valid values too). A subclass
@@ -61,6 +67,9 @@ This is the workflow from [Elastic Software](https://everythingengineer.substack
 
 Callers never change, because both paths return the same result class.
 
+To keep a particular model off certain inputs (a client that needs a BAA, say), give its escalation step an
+`include_when:` Proc; see [Excluding a model per call](configuration.md#excluding-a-model-per-call).
+
 ## Entry points
 
 Squish methods other than `call` with `squish`, optionally overriding the class-level settings per method:
@@ -91,6 +100,7 @@ end
 - `output_schema:` (or a schema block)
 - `model:` or `escalation:`, `provider:`, and `params:` (generation params; see [Configuration](configuration.md))
 - `harness:` (see [Harnesses](harnesses.md), including your own)
+- `max_total_output_tokens:` and `max_total_input_tokens:` (see [Capping a call's cost](failures.md#capping-a-calls-cost-token-budgets))
 - `when:`, a predicate proc
 - `validate:` and `fallback:` (see [Failure handling](failures.md))
 
@@ -134,6 +144,7 @@ end
 | `purpose:` | Replaces the purpose |
 | `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. |
 | `harness:` | Replaces the declared [harness](harnesses.md), e.g. `harness: :judged_squishsum` to double-check a hand-off |
+| `max_total_output_tokens:`, `max_total_input_tokens:` | Cap what this call may spend, e.g. a tighter budget for a hand-off; `false` lifts a declared cap. See [Capping a call's cost](failures.md#capping-a-calls-cost-token-budgets). |
 
 - **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

data/docs/schemas.md

@@ -30,6 +30,11 @@ output_schema(
 )
 ```
 
+A raw schema's `$ref`s must point inside the schema (`"#/$defs/address"`). Squishling resolves them when it builds the
+schema, so one that points nowhere (a remote URI, which is never fetched, or a `$defs` entry that doesn't exist)
+raises `Squishling::ConfigurationError` then, and [`Squishling.verify`](verifying.md) reports it, instead of failing on
+the first response.
+
 ## Describing fields
 
 Every DSL type, and `optional`, takes a `description:`. It is sent to the provider as guidance for that field
@@ -49,8 +54,10 @@ end
 
 ## Strict schemas only
 
-Squishling only supports **strict** output schemas: it always asks RubyLLM for strict structured output, and a
-schema declaring `strict: false` raises `Squishling::ConfigurationError`. RubyLLM 2.0 on its own would send a
+Squishling only supports **strict** output schemas: it always asks the adapter for strict structured output (the
+OpenAI-compatible adapter's `structured_output: :json_object` and `:none` modes are the explicit exception, for servers
+that lack it, where the schema goes into the prompt instead), and a schema declaring `strict: false` raises
+`Squishling::ConfigurationError`. Squishling validates every answer against the schema either way. RubyLLM 2.0 on its own would send a
 schema with optional properties non-strict; Squishling always sets the flag explicitly, so it stays strict.
 
 With raw hashes, follow your provider's strict-mode rules (e.g. list every property in `required` and set
@@ -75,6 +82,21 @@ r.to_h                           # deep Hash with symbol keys
 r.squished?                      # => true when it came from the LLM
 ```
 
+A property can't share a name with a method the result depends on, because the `Data` member would replace it.
+Squishling raises `ConfigurationError` when the schema is built (before any request), naming the clashing
+fields; rename them (`class` to `ticket_class`). The reserved names are `class`, `is_a?`, `kind_of?`, `hash`, `inspect`, `to_s`,
+`to_h`, `members`, `with`, `dup`, `send`, `public_send`, `eql?`, `==`, `[]`, `squished?`, `object_id`,
+`deconstruct_keys`, and a few Ruby and Squishling internals (`initialize*`, `__send__`, `squishling_squished`).
+Other names, such as `method`, `format`, or `type`, work as usual. This applies to nested objects and array items too.
+
+With a hand-written Hash schema, every object schema that becomes a result (and so a nested result) must also say
+`type: "object"`; `allOf` parts and unions with several non-null branches aren't typed, so they are exempt. A schema with
+`properties` alone accepts a String or Array too (JSON Schema applies `properties` only to objects), which would end
+up in the typed result where a nested result belongs. Squishling raises `ConfigurationError` when the schema is built
+(and `Squishling.verify` reports it) for the root, a nested property, array `items`, the object branch of an
+`optional`, or a `$ref` target. A union that includes it, like `["object", "null"]`, is fine. The DSL always sets
+the type for you.
+
 On the deterministic path, return a `Hash` or build the result with `result(...)`. Either way it's validated
 against the schema, and so is anything else you return (`nil`, a string, another schema's result), which raises
 `Squishling::InvalidOutputError` unless it matches.

data/docs/testing.md

@@ -0,0 +1,187 @@
+# Testing
+
+`require "squishling/testing"` adds test support: a scripted [adapter](adapters.md) that answers in place of a
+provider and records what was sent to it, stand-ins for the callers of squished methods, replies derived from an output
+schema, and assertions. It is opt-in (`require "squishling"` doesn't load it), needs no test framework or mocking
+library, and works with RSpec (without rspec-mocks), Minitest, and Mocha alike. It makes no network request.
+
+```ruby
+# Minitest
+include Squishling::Testing::Minitest
+
+# RSpec
+RSpec.configure { |config| config.include Squishling::Testing::RSpec }
+```
+
+Both give your tests the helpers below and put back, after each test, whatever the helpers changed
+(`Squishling::Testing.reset!`). They touch only the adapter, observer, and stubs they installed (and only while they
+still hold what the helpers set), so the rest of your `Squishling.configure` survives.
+
+The helpers change global state (`Squishling.config` and the stubbed classes), so tests that use them must not run
+in parallel threads. That includes `no_llm_call` / `assert_no_llm_call`, which swap the process-wide `config.adapter`
+for the block: a request another thread makes meanwhile is forbidden too, and may be counted in the block's calls.
+
+## Scripting the model
+
+```ruby
+fake = fake_squishling do |llm|
+  llm.step("gemini-2.5-flash").reply({ regex: "[bad(" }, { regex: "Run.*" })  # in order; the last one repeats
+  llm.step("gemini-2.5-pro").fail(:rate_limit)
+  llm.step(:any).reply({ regex: "fallback.*" })                               # anything no rule above claims
+end
+
+result = RegexInferrer.call(sample_turns: turns)
+
+assert_equal "Run.*", result.regex
+assert_equal 2, fake.requests.size
+assert_sent_arguments fake, { sample_turns: turns }       # what left the process
+assert_includes fake.requests.last.errors, "regex is not a valid Ruby regex"   # the re-ask carried them
+```
+
+A reply is one of:
+
+| Reply | The model… |
+|---|---|
+| a `Hash` | answered with this object |
+| a `String` | returned this text (malformed or fenced JSON, truncated output) |
+| `nil` | returned nothing (a refusal or a cut-off) |
+| `Squishling::Testing::Reply.new(content, model: "m", usage: { input_tokens: 10, output_tokens: 3 })` | answered, and the provider reported this model and these token counts (`squawk`'s `metadata[:usage]`, the observer's `Usage`) |
+| an `Exception` | made the request raise it |
+| `.fail(intent)` | the provider failed: see below |
+
+`reply` takes several, `.fail` adds one, and `.once` makes running out of replies an error instead of repeating the last.
+
+**Provider failures by intent.** You don't need to know which SDK error maps to which Squishling error:
+
+| Intent | Raises |
+|---|---|
+| `:rate_limit`, `:server_error`, `:overloaded`, `:timeout`, `:context_length` | `LLMError` (the next attempt is tried) |
+| `:bad_request`, `:unauthorized`, `:forbidden` | `ConfigurationError` (never retried, never given to a fallback) |
+
+**Selecting what a rule answers.** `step(model)`, `step(provider: :vertexai)`, and `step(:any)` answer escalation
+attempts; `attempt: 2` narrows a step rule to one attempt of the escalation. Rules are matched most specific first
+(a sample or the judge, then the rule naming the most of model, provider and attempt, then `step(:any)`), and by
+declaration order within that.
+Scripts are keyed by model, so a rotated tier (`priority:`) gets the same answers whichever model goes first. Which
+model goes first still depends on how many calls the class has had, so don't assert the order of `fake.models` for a
+rotated tier unless the class is new to the test (or pin the tier with `rotate: false`).
+A request no rule covers raises `Squishling::Testing::UnscriptedRequestError` naming the squished method; it isn't
+a `Squishling::Error`, so `squish_fallback` can't hide it.
+
+### Harnesses
+
+```ruby
+fake_squishling do |llm|
+  llm.sample("a").reply(valid_reply_for(Triager))
+  llm.sample("b").reply(valid_reply_for(Triager, team: "billing"))
+  llm.judge.verdict(:a, reason: "a fits")                    # a chat judge
+  llm.judge.judgment(:b, confidence: 0.92)                   # a System One judge (type: :judgment, min_confidence:)
+  llm.judge.fail_judgment(:timeout)
+end
+```
+
+Each sample has its own script, so the order its worker thread happens to run in can't change what it gets. The
+scripts, the request log, and the conversation tracking are taken under one lock. `DisagreementError#candidates`
+and `#verdict` are the real ones; rescue them as you would in production.
+
+## Inspecting what was sent
+
+`fake.requests` is every provider request, in order, as `Squishling::Testing::Request`:
+
+| | |
+|---|---|
+| `arguments`, `context` | the method's arguments and the `squish_context` / `squish!` context the model was sent |
+| `system_prompt`, `output_schema` | the purpose (with `append_to_purpose` sections) and the strict schema |
+| `model`, `provider`, `params` | the step it went to |
+| `role`, `sample`, `attempt`, `attempts` | `nil`/`:sample`/`:judge`, `"a"`, and where it is in the escalation |
+| `conversation` | the chat it belongs to |
+| `errors` | the validation messages a retry or escalation carried back to the model |
+| `forwarded_rejected` | the rejected output forwarded to the next step (`nil` with `forward_rejected: false`) |
+| `candidates` | for a judge, the two samples |
+| `messages`, `reply`, `failed?` | the conversation as sent, and the `Adapter::Response` (or error) that came back |
+
+`fake.conversations` groups the requests by chat: a retry on the same step shares one, and an escalation to a new
+step starts a new one. `fake.requests_for(sample: "a")`, `fake.models`, and `fake.arguments` are shortcuts.
+
+## Asserting the LLM was not called
+
+```ruby
+assert_no_llm_call { RegexInferrer.call(sample_turns: easy_turns) }   # then: refute result.squished?
+assert_llm_calls fake, 2
+```
+
+`assert_no_llm_call` fails even if the code under test rescued the error that stopped the call.
+
+**A safety net for the whole suite.** In a suite-wide `before` hook, `forbid_provider_calls!` makes any request that
+reaches the provider raise `ProviderCallError` naming the squished method (`"RegexInferrer#call reached the provider…"`),
+so a missing script fails at the call, not far from it. Installing a fake replaces it.
+
+## Stubbing a squished class for its callers
+
+Callers of a squished class shouldn't run Squishling at all. These make `Klass.call` return a real, schema-validated
+typed result, or raise the real error class, without `allow(...).to receive`:
+
+```ruby
+stub_squishling_result(PatternGenerator, regex: "x")                          # squished? is true
+stub_squishling_result(PatternGenerator, { regex: "x" }, squished: false)     # as the Ruby path would return it
+stub_squishling_result(PatternGenerator, regex: "x") { ... }                  # for the block only
+
+stub_squishling_error(PatternGenerator, :invalid_output, errors: ["bad"], raw: "{}", attempts: 2, models: %w[a b])
+stub_squishling_error(PatternGenerator, :llm_error)           # also :configuration, :disagreement (candidates:, verdict:, reason:)
+```
+
+Attributes that don't satisfy the method's `output_schema` raise `Squishling::Testing::SetupError` when you stub, so a
+stand-in can't drift from the real result type. Pass `method: :triage` for another squished method. The stubs are
+removed after each test. A stub applies to that class only, not to its subclasses, which keep their own behavior. The
+hook that makes a stub possible stays on the class for the life of the process, even after `Testing.reset!` has
+removed the stub (it is inert, but keeps the class alive), so stub the classes of your suite, not one per test.
+
+## Running parts of a method without a model
+
+```ruby
+squishling_validate(Klass, { "regex" => "[bad(" }, text: "x")   # => ["regex is not a valid Ruby regex"]
+squishling_fallback_for(Klass, Squishling::LLMError.new("x"), text: "x")   # the typed fallback result
+squishling_preview(Klass, text: "x")
+# => { system_prompt:, user_message:, output_schema:, step: }   # for snapshot tests; makes no request
+```
+
+Arguments are keywords, or `args: [...]` for positional ones; `receiver:` supplies an instance for a class whose
+constructor takes arguments; `method:` names a squished method other than `call`. (A squished method with a parameter
+called `args`, `receiver`, or `method` can't be given it as a keyword here.) `squishling_preview` doesn't advance model rotation.
+
+## Replies derived from the schema
+
+```ruby
+valid_reply_for(Triager)                                  # => { "priority" => "example", "team" => "example" }
+valid_reply_for(Triager, team: "billing")                 # overrides
+invalid_reply_for(Triager, violating: :score)             # out of its range, enum, or type
+invalid_reply_for(Triager, violating: :score, how: :missing)   # :enum, :range, :type, :null, :missing
+```
+
+Both accept a squished class, a `Squishling::Schema`, or a schema Hash, and are checked against the schema before they
+are returned, so a test that doesn't care about the content stays valid when the schema changes. A schema it can't
+satisfy on its own (a `pattern`, an unsatisfiable conditional) raises `SetupError` and asks for overrides.
+
+## `squawk` and observers
+
+```ruby
+capture = with_squawk(capture_squawk) { Klass.call(text: "x") }
+capture.calls.map { |call| call.metadata[:attempt] }    # output:, error:, and metadata: of every attempt
+```
+
+`with_squawk` swaps `config.squawk` for the block and puts the previous hook back, so an app-wide hook that enqueues
+a job isn't run in tests. A `squawk:` set on a class or method still takes precedence over the configured one.
+
+The capture also records the [report of a stopped call](failures.md#a-call-that-is-stopped) (`metadata[:stopped]` is
+`:budget` or `:disagreement`). `stub_error` replaces the method without running Squishling, so it reports nothing.
+
+An observer you configured *before* `fake_squishling` keeps working while the fake is installed (it is chained behind
+the fake's own). Configure it first: one assigned afterwards replaces the fake's, and then sample and judge scripts
+can't tell which request is which.
+
+## How it works
+
+`fake_squishling` assigns a `Squishling::Testing::Adapter` (a `Squishling::Adapter::Base`) as `config.adapter`, and an
+observer that tells it which role, sample, and attempt each request is. Because it sits behind the same interface as
+the real adapters, it needs no knowledge of RubyLLM or any provider, and it is covered by Squishling's own specs.
+Call `Squishling::Testing.install` and `.reset!` yourself if you use a test framework other than the two above.

data/docs/verifying.md

@@ -0,0 +1,86 @@
+# Verifying squished classes
+
+Most mistakes in a squished class fail when the class loads (a bad `escalation:`, `params:`, `harness:` or `squawk:`
+raises `ConfigurationError` as the declaration runs). The output schema and its typed result are built on the first
+call, and the keywords your `include_when:` and `squish_when` procs take are only used when a call is routed. So
+Squishling keeps a list of the classes that include it and can check them all without making a request, for example
+in CI.
+
+## `Squishling.verify` and `verify!`
+
+```ruby
+report = Squishling.verify            # every squished class
+report.ok?                            # => false
+puts report
+# Squishling found 2 problems:
+#   Triage#route: escalation step "claude-haiku-4-5" include_when: requires tier:, which is not an input of the method
+#   Invoice#call: invalid data member: total=
+
+Squishling.verify!                    # raises Squishling::VerificationError (a ConfigurationError) naming every problem
+Squishling.verify(Triage, Invoice)    # just these classes
+```
+
+`verify` returns a `Squishling::Verification::Report` (`ok?`, `size`, `problems`, `to_s`). Each problem has a
+`label` and a `message`. `verify!` returns the report when it is clean and otherwise raises
+`Squishling::VerificationError`, which has `report` and `problems`. Every problem is listed, not just the first.
+
+For each squished method (inherited ones too, with the subclass's settings) it checks:
+
+- **The output schema:** that it builds (and is strict), is valid JSON Schema, and produces a typed result, so a
+  property name that can't be a result member (`total=`), an object with `properties` but no `type: "object"`, or a
+  `$ref` that doesn't resolve within the schema (a remote URI is never fetched; a missing `$defs` entry) is reported.
+  A method with no output schema or no purpose is reported, because its LLM path would raise. The default `call`
+  method is skipped when you don't implement or configure it.
+- **What the layers resolve to:** the escalation, generation params and `squawk` that the method, its class and
+  `Squishling.config` add up to.
+- **The harness:** that it is still registered (not removed or replaced since the class declared it), and that a
+  `type: :judgment` judge has an adapter that supports judgments.
+- **Keywords:** that each `include_when:` and the `squish_when` block can be called with the method's inputs as keywords
+  (`instance_exec(**inputs, &proc)`): no required keyword that isn't an input, and no input a lambda (or a proc that names
+  keywords) can't take. Add `**` to accept any. A method that takes `**` or has no implementation can receive any
+  keyword, so nothing is reported for it. `squish_fallback` and `squish_validate` are called with the inputs too, but
+  aren't checked.
+- **The adapter** (once): that `config.adapter`, or RubyLLM's, can be built.
+
+A problem in an inherited method is reported once for each subclass, since each is checked with its own settings.
+
+Nothing is sent to a provider, and your own code (the Ruby implementation, `squish_when`, the procs) is not run.
+
+## Only loaded classes are checked
+
+The list holds the classes that have been loaded. In Rails, load everything first:
+
+```ruby
+Rails.application.eager_load!
+Squishling.verify!
+```
+
+The list holds its classes weakly, so it doesn't keep classes alive across code reloads, and a named class whose
+constant now holds a different object (replaced by a reload but not yet collected) is left out. Anonymous classes are
+included. `Squishling.squished_classes` returns the list.
+
+## In CI
+
+**Rake.** In Rails the `squishling:verify` task is added for you and eager loads the app first. Elsewhere, load it in your
+`Rakefile`:
+
+```ruby
+load "squishling/tasks/squishling.rake"
+```
+
+`bundle exec rake squishling:verify` prints the report and exits non-zero when there are problems. Load your classes
+before the task runs (an `:environment` task, if you have one, is invoked first). The Railtie adds the task in Rails
+when Squishling is required after Rails (as Bundler does), so a Rails app needn't load the file itself.
+
+**RSpec.** `require "squishling/rspec"` adds a matcher whose failure message is the report:
+
+```ruby
+require "squishling/rspec"
+
+RSpec.describe "squished classes" do
+  before(:all) { Rails.application.eager_load! }
+
+  it { expect(Squishling).to be_squishling_valid }
+  it { expect(InvoiceParser).to be_squishling_valid }   # or just one class, or an Array of them
+end
+```

data/lib/squishling/adapter/error_body.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Squishling
+  module Adapter
+    # Reads the machine-readable fields of a provider's error body: the status (OpenAI-style `type`, Gemini's
+    # `status`), the code, and the name of the field it objected to. Only short plain tokens come out; the message
+    # and anything else a provider might echo from the request never do.
+    module ErrorBody
+      # A status or code is an enumeration-like word (no hyphens, so an API key like sk-... never passes); a param is
+      # a field path (messages[0].content), which is only compared with the developer's own param names and never
+      # repeated.
+      WORD = /\A[A-Za-z0-9][\w.]{0,39}\z/
+      PATH = /\A[\w.\-\[\]]{1,64}\z/
+      CONTEXT_LENGTH_EXCEEDED = "context_length_exceeded"
+      private_constant :WORD, :PATH, :CONTEXT_LENGTH_EXCEEDED
+
+      module_function
+
+      # body: a JSON String, a Hash with String keys, or an Array wrapping the Hash (Gemini does that). http_status
+      # drops a code that only repeats it. Returns { status:, code:, param: }, each a String or nil.
+      def read(body, http_status: nil)
+        detail = error(body)
+        return { status: nil, code: nil, param: nil } unless detail
+
+        code = token(detail["code"], WORD)
+        { status: token(detail["status"], WORD) || token(detail["type"], WORD),
+          code: (code unless code == http_status.to_s),
+          param: token(detail["param"], PATH) }
+      end
+
+      # The body's `error` Hash, or nil when it has none (or isn't JSON). For adapters that need more of it than
+      # #read returns, e.g. to recognize a wording; they must not repeat it.
+      def error(body)
+        data = body.is_a?(String) ? JSON.parse(body.dup.force_encoding(Encoding::UTF_8)) : body
+        data = data.first if data.is_a?(Array)
+        detail = data["error"] if data.is_a?(Hash)
+        detail if detail.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Whether the body's code or type is the structured "context_length_exceeded" (what OpenAI sends for a prompt too
+      # long for the model). Only that field is read, never the message.
+      def context_length?(body)
+        (error(body)&.values_at("code", "type") || []).include?(CONTEXT_LENGTH_EXCEEDED)
+      end
+
+      def token(value, pattern)
+        value = value.to_s if value.is_a?(Integer)
+        value if value.is_a?(String) && value.valid_encoding? && value.match?(pattern)
+      end
+    end
+  end
+end