ruby_decision_model 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bea0fe1efb5046f07952098626ed15f1dcd28fc80f56fe1810b3a7cd1050bab
-  data.tar.gz: ebd51acc65df870cce1cd567033116d262424a2e38f3a86c41403c329a0dea31
+  metadata.gz: f1c6972a68e2a0545795663a4c792603a692eb65b609d630ce2754e9f032d6b2
+  data.tar.gz: 4252b768aa5f7ab6e16eee20ef09ca16923fdf2b192eb21a0fb79f06f51f8b42
 SHA512:
-  metadata.gz: 5f883f0e2cc526cdbf75b12632359670a70795caa030770c69b9c7af77ebc3cbe2054416f4900e3a5ed3773a507dc53246d1389e04714bc9e45d093b8b7184f8
-  data.tar.gz: b4fbb04f181c347fc28ae0c040da2f074d9ada571581cdb2c8d96097e43391d8955ab370dd3f09451ae1fe08a666b68881503ddadddca5979abf633f1b89faef
+  metadata.gz: 69abd24fe4a39391791c183b0880a8c909e8521a5155c7d1ac92be380780572a5d23423ed32cb9b1267f2f110fbe9a9958982dca5edd2486f4b43a9e3e0cb1d6
+  data.tar.gz: 40d47a12bf922d452ad350180d2d1fbac189a16f2a732f3885784a7f71438e30a7e8dd7b75b875e5eeb8882ffc36a22c214177c287d13622a329322edc1b6030

data/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.2.0 - 2026-10-06
+
+The decision models that shipped after Jev, behind the same `Client`.
+
+- Added providers `:openai` (OpenAI Decisions API, `gpt-6-luna`),
+  `:cloudflare` (Clef and Clef-flash on Workers AI), `:perplexity`
+  (`pplx-decider-v1.1-27b` and `pplx-decider-v1-27b`), `:databricks`
+  (`ai_decide` over REST), and `:system_one` (any server speaking
+  `/v1/systemone`: Ollama, the autojev server, strands-decider, and others).
+- The OpenAI provider translates both ways between System One and OpenAI's
+  wire format. Questions, answers, and `Answers::*` types are unchanged for
+  callers. A noul with true/false criteria goes out as a boolean choice and
+  comes back as a noul.
+- `Client#ask` takes `images:`, an array of base64 data URLs. Each provider
+  places them where its API expects. Providers that don't read images raise
+  `RequestError` before sending. Added `RubyDecisionModel::Images.data_url`
+  and `.from_file`.
+- Refused questions (OpenAI) raise `MissingAnswers` as before, with the new
+  `#refused` listing the ids the provider declined.
+- Noul `probabilities` are always `{"true" => p, "false" => 1 - p}`. Jev,
+  Clef, pplx-decider, and most System One servers send only the probability,
+  so the client fills in the split. A noul with junk `probabilities` now gets
+  the split instead of `{}`, and a noul outside 0..1 raises
+  `InvalidResponse`.
+- State or questions that cannot be encoded as JSON (invalid UTF-8, `NaN`,
+  nesting deeper than 100 levels) raise `RequestError`, with the original
+  error on `#cause`.
+- `RUBY_DECISION_MODEL_PROVIDER` names a provider from the environment ahead
+  of key detection (any case; `-` reads as `_`), and
+  `Client.new(api_key: ...)` sends that key to the named provider rather
+  than OpenRouter. `SYSTEM_ONE_BASE_URL` joins detection after
+  `TYPESAFE_API_KEY` and `OPENROUTER_API_KEY`. Keys like `OPENAI_API_KEY` do
+  not select a provider by themselves.
+- New aliases. On OpenRouter: `luna` and `gpt-6-luna` resolve to
+  `openai/gpt-6-luna-decisions`, `clef` and `clef-flash` to the
+  `cloudflare/` slugs, and `pplx-decider` to
+  `perplexity/pplx-decider-v1-27b`. Native providers accept the OpenRouter
+  slugs for their own models. Typesafe accepts `~typesafe/jev-latest`.
+- Each provider names its own request id header: `x-request-id` on OpenAI
+  and Perplexity, `cf-ray` on Cloudflare, and `x-typesafe-request-id`
+  everywhere else, as in 0.1.0.
+- `timeout:` now defaults to `nil`, meaning the provider's read timeout: 5
+  seconds for Typesafe, OpenRouter, and Cloudflare, 30 for OpenAI,
+  Perplexity, Databricks, and System One servers, with a 5 second open
+  timeout. Passing a number sets both, as before. The write timeout, which
+  bounds image uploads, follows the read timeout, and a write timeout is
+  retried and raised as `TimeoutError` like the other two. In 0.1.0 an
+  explicit `timeout: nil` meant no limit at all; it now means these
+  defaults. Added `Client#open_timeout`.
+- `ApiError` messages end with the vendor's reason when the error body has
+  one, for example `api error (status 400): Invalid model 'x'.` The client
+  reads OpenAI, Perplexity, and OpenRouter `error.message`, Cloudflare
+  `errors[].message`, FastAPI `detail[].msg` (Typesafe), and Databricks
+  `message`. The API key is masked if a vendor echoes it, and the text is
+  capped at 500 characters. `#body` is unchanged.
+- API keys are stripped before they go into the `Authorization` header, so
+  a key read from a file with its trailing newline works.
+- Added `rake smoke`, an opt-in live check against every provider whose keys
+  are set. CI never runs it.
+- Provider hooks for authors: `normalize_response`, `supports_images?`,
+  `request_id_header`, `requires_api_key?`, `default_timeout`,
+  `error_message`, `validate!`, `configured?`, and `url(model)`. Base sends
+  `Authorization` only when a key is present. Providers written against
+  0.1.0 keep working: a `url` override without the model argument is still
+  called without it.
+
 ## 0.1.0 - 2026-09-18
 
 Provider-neutral release. One `Client`, two providers behind it.

data/README.md

@@ -2,9 +2,13 @@
 
 The decision-model interface for Ruby. Decision models answer typed questions
 about a state with calibrated probabilities instead of generating text. This gem
-talks to them through one `Client` with a provider behind it: OpenRouter by
-default, Typesafe's native API as a second door, more providers as labs ship
-them. No runtime dependencies beyond the standard library.
+talks to them through one `Client` with a provider behind it. OpenRouter is the
+default. Typesafe (Jev), OpenAI (gpt-6-luna), Cloudflare (Clef), Perplexity
+(pplx-decider), and Databricks (`ai_decide`) each have a native provider, and
+any server that speaks the System One API (Ollama, strands-decider, the
+autojev server) works through `:system_one`. Your questions and answers keep
+one shape whichever provider serves them. No runtime dependencies beyond the
+standard library.
 
 ## Install
 
@@ -35,10 +39,25 @@ response["severity"].score    # => 2.4
 response.usage.input_tokens   # => 120
 ```
 
-`Client.new` with no arguments reads the environment: `TYPESAFE_API_KEY` selects
-Typesafe, otherwise `OPENROUTER_API_KEY` selects OpenRouter. With neither set it
-raises `ConfigurationError` naming both. `RubyDecisionModel.client` memoizes one
-such default client; assign `nil` to reset it.
+`Client.new` with no arguments reads the environment.
+`RUBY_DECISION_MODEL_PROVIDER` names a provider outright (`openai`,
+`cloudflare`, and so on, in any case, with `-` or `_`), and an `api_key:` passed without `provider:` goes
+to that provider. Without it, `TYPESAFE_API_KEY` selects Typesafe,
+then `OPENROUTER_API_KEY` selects OpenRouter, then `SYSTEM_ONE_BASE_URL`
+selects a System One server. General-purpose credentials such as
+`OPENAI_API_KEY` or `CLOUDFLARE_API_TOKEN` never pick a provider on their own,
+since plenty of apps hold them for other reasons. With nothing usable set,
+`Client.new` raises `ConfigurationError` naming the variables it checked.
+`RubyDecisionModel.client` memoizes one such default client; assign `nil` to
+reset it.
+
+Switching vendors is a configuration change:
+
+```ruby
+RubyDecisionModel::Client.new(provider: :openai)       # gpt-6-luna
+RubyDecisionModel::Client.new(provider: :perplexity)   # pplx-decider-v1.1-27b
+RubyDecisionModel::Client.new(provider: :open_router, model: "clef")
+```
 
 ## Providers
 
@@ -48,7 +67,8 @@ such default client; assign `nil` to reset it.
 # ENV["OPENROUTER_API_KEY"]
 client = RubyDecisionModel::Client.new(provider: :open_router)
 
-# or pass the key directly; api_key: alone still means OpenRouter
+# or pass the key directly; api_key: alone means OpenRouter
+# unless RUBY_DECISION_MODEL_PROVIDER names another provider
 client = RubyDecisionModel::Client.new(api_key: "sk-or-...")
 ```
 
@@ -65,18 +85,111 @@ client = RubyDecisionModel::Client.new(provider: :typesafe)
 Requests go to `https://api.typesafe.ai/v1/systemone`. The default model is
 `jev-latest`. Usage reports `input_tokens` and `output_tokens`; `cost` is `nil`.
 Typesafe returns an `x-typesafe-request-id` header, exposed as
-`response.request_id` (nil on OpenRouter). Quote it when reporting a problem
-to Typesafe.
+`response.request_id`. Quote it when reporting a problem to Typesafe.
+
+### OpenAI Decisions API
+
+```ruby
+# ENV["OPENAI_API_KEY"]
+client = RubyDecisionModel::Client.new(provider: :openai)
+```
+
+Requests go to `https://api.openai.com/v1/decisions`. The API is in public beta
+as of October 2026, so its wire format may still change. The default model is
+`gpt-6-luna`. OpenAI's wire format differs from System One, so the
+provider translates both ways and your questions stay the same:
+
+- `state` becomes `input`. A String passes through as is. Anything else is
+  sent as JSON text, because the API takes no structured input.
+- `noul` becomes a `predicate`. A noul with `true`/`false` criteria becomes a
+  boolean `choice` so the descriptions reach the model, and the answer comes
+  back as a noul.
+- Choice criteria become `choices` and score criteria become `levels`.
+- Answers arrive as an array and are rebuilt keyed by question id, with
+  probability Hashes and a score `legend` built from your criteria.
+
+When the model declines a question the client raises `MissingAnswers` with
+that id in `#refused`; the other answers are on `#answers`. Usage reports
+tokens with no cost. OpenAI's response carries no id today, so `response.id`
+is nil unless OpenAI starts sending one. `response.request_id` reads
+`x-request-id`.
+
+### Cloudflare Workers AI (Clef)
+
+```ruby
+# ENV["CLOUDFLARE_API_TOKEN"] (or CLOUDFLARE_AUTH_TOKEN) and ENV["CLOUDFLARE_ACCOUNT_ID"]
+client = RubyDecisionModel::Client.new(provider: :cloudflare, model: "clef-flash")
+
+# or configure the provider directly
+provider = RubyDecisionModel::Providers::Cloudflare.new(api_key: "...", account_id: "...")
+client = RubyDecisionModel::Client.new(provider: provider)
+```
+
+Requests go to
+`https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/run/@cf/cloudflare/<model>`.
+The default model is `clef`; `clef-flash` is the smaller, faster one. The body
+is System One. The provider unwraps Cloudflare's `{"result": ...}` envelope,
+and a body with `"success": false` raises `InvalidResponse` carrying
+Cloudflare's error text. The account id and model end up in the URL path, so
+both are checked when the client is built. The account id may hold letters,
+digits, `-`, and `_`; surrounding whitespace is stripped. The model must start
+with a letter or digit and may also hold `.`, `-`, and `_`. Anything else
+raises `ConfigurationError`.
+Usage reports tokens with no cost, and `response.request_id` is the `cf-ray`
+header.
+
+### Perplexity (pplx-decider)
+
+```ruby
+# ENV["PERPLEXITY_API_KEY"]
+client = RubyDecisionModel::Client.new(provider: :perplexity)
+```
+
+Requests go to `https://api.perplexity.ai/v1/decisions`. The default model is
+`pplx-decider-v1.1-27b`; `pplx-decider-v1-27b` also works. The body is System
+One. `response.request_id` reads `x-request-id`.
+
+### Databricks `ai_decide`
+
+```ruby
+# ENV["DATABRICKS_HOST"] and ENV["DATABRICKS_TOKEN"]
+client = RubyDecisionModel::Client.new(provider: :databricks)
+```
+
+Requests go to `<host>/api/2.0/ai-functions/ai-decide`. `ai_decide` is a
+Databricks beta: a workspace admin has to enable it, and its REST shape may
+still change. The workspace serves one managed model, so
+`client.model` is nil and passing `model:` raises `ConfigurationError`. The
+provider reads answers from the `response` wrapper. Databricks reports no
+usage, so every usage field is nil.
+
+### System One servers (Ollama, local models)
+
+```ruby
+# ENV["SYSTEM_ONE_BASE_URL"], and ENV["SYSTEM_ONE_API_KEY"] if the server wants one
+client = RubyDecisionModel::Client.new(provider: :system_one, base_url: "http://localhost:11434", model: "nimble")
+```
+
+Anything that serves Typesafe's API at `/v1/systemone` works here: the autojev
+server shipped with pplx-decider's weights, strands-decider's local server,
+and hosted lookalikes. Pydantic AI's docs say Ollama 0.35 and later serves it
+too, with models such as `nimble` and `tev1`. The base URL has no
+`/v1` suffix and needs its `http://` or `https://` and a host. It is checked
+when the first request is built rather than in `Client.new`, so a `base_url:`
+passed to the client can replace an unusable `SYSTEM_ONE_BASE_URL`; a bad one
+raises `ConfigurationError` from `ask`. The API key and model are optional; without a key no
+`Authorization` header is sent, and without a model the body has no `model`
+field. The environment variable names match Pydantic AI's.
 
 ### Options
 
 ```ruby
 RubyDecisionModel::Client.new(
-  provider: :typesafe,        # :open_router, :typesafe, or a Providers::Base instance
+  provider: :typesafe,        # a name from Providers.names, or a Providers::Base instance
   api_key: nil,               # overrides the provider's env var
   model: nil,                 # nil means the provider default; see aliases below
   base_url: nil,              # overrides the provider base URL
-  timeout: 5,                 # open and read timeout in seconds
+  timeout: nil,               # seconds; nil means the provider's read default and a 5s open timeout
   retry: { max_retries: 2 },  # RetryPolicy or a Hash of overrides
   transport: nil              # see Transport
 )
@@ -85,28 +198,53 @@ client.provider   # => #<RubyDecisionModel::Providers::Typesafe ...>
 client.model      # => "jev-latest" (resolved after aliasing)
 ```
 
-Both providers send `User-Agent: ruby_decision_model/<version>`.
+Every provider sends `User-Agent: ruby_decision_model/<version>`.
+
+The default read timeout is 5 seconds for Typesafe, OpenRouter, and
+Cloudflare, whose models answer in well under a second. OpenAI, Perplexity,
+Databricks, and System One servers default to 30, since Perplexity documents
+responses of up to 23 seconds on large inputs and a local server may load the
+model on the first request. Connecting gets 5 seconds either way. A number
+passed as `timeout:` sets both, as in 0.1.0. Through OpenRouter, pass a
+longer `timeout:` yourself for large inputs to slower models.
 
 ### Model aliases
 
-Each provider resolves a few friendly names to its own canonical model name.
-Anything not listed passes through untouched. The `model` field on a response
-is whatever the provider returned.
+Each provider resolves a few friendly names to its own canonical model name,
+so one short name follows a model from OpenRouter to its vendor's API and
+back. OpenRouter slugs also resolve on the vendor's own provider. Anything
+not listed passes through untouched, which is how you reach models without an
+alias, such as `liquid/d1` on OpenRouter. The `model` field on a response is
+whatever the provider returned.
 
-| You pass | OpenRouter sends | Typesafe sends |
+| You pass | OpenRouter sends | Native provider sends |
 | --- | --- | --- |
-| `nil` | `typesafe/jev-1.13` | `jev-latest` |
-| `"jev"` | `typesafe/jev-1.13` | `jev-latest` |
-| `"jev-latest"` | `typesafe/jev-1.13` | `jev-latest` |
-| `"typesafe/jev-1.13"` | `typesafe/jev-1.13` | `jev-latest` |
+| `nil` | `typesafe/jev-1.13` | that provider's default |
+| `"jev"`, `"jev-latest"` | `typesafe/jev-1.13` | `jev-latest` (Typesafe) |
+| `"typesafe/jev-1.13"`, `"~typesafe/jev-latest"` | as given | `jev-latest` (Typesafe) |
+| `"luna"`, `"gpt-6-luna"` | `openai/gpt-6-luna-decisions` | `gpt-6-luna` (OpenAI) |
+| `"openai/gpt-6-luna-decisions"`, `"openai/gpt-6-luna"`, `"gpt-6-luna-decisions"` | as given | `gpt-6-luna` (OpenAI) |
+| `"clef"`, `"clef-flash"` | `cloudflare/clef`, `cloudflare/clef-flash` | as given (Cloudflare) |
+| `"cloudflare/clef"`, `"cloudflare/clef-flash"` | as given | `clef`, `clef-flash` (Cloudflare) |
+| `"@cf/cloudflare/clef"`, `"@cf/cloudflare/clef-flash"` | as given | `clef`, `clef-flash` (Cloudflare) |
+| `"pplx-decider"` | `perplexity/pplx-decider-v1-27b` | `pplx-decider-v1.1-27b` (Perplexity) |
+| `"pplx-decider-v1-27b"` | `perplexity/pplx-decider-v1-27b` | as given (Perplexity) |
+| `"perplexity/pplx-decider-v1-27b"` | as given | `pplx-decider-v1-27b` (Perplexity) |
 | anything else | as given | as given |
 
+OpenRouter carries pplx-decider v1 only, so `"pplx-decider"` means v1 there
+and v1.1 on Perplexity's own API.
+
 ### Writing a provider
 
 Subclass `RubyDecisionModel::Providers::Base` and define `name`, `env_var`,
-`default_base_url`, `endpoint_path`, `default_model`, and optionally `aliases`
-and `reports_cost?`. Override `headers`, `request_body`, or `usage` when the
-wire format differs. Pass an instance as `provider:`.
+`default_base_url`, `endpoint_path`, and `default_model`. Optional hooks:
+`aliases`, `reports_cost?`, `supports_images?`, `request_id_header`,
+`requires_api_key?`, `default_timeout`, `error_message`, and `validate!`. When the wire format differs from
+System One, override `request_body` to encode and `normalize_response` to turn
+the parsed body back into System One answers keyed by question id; the
+OpenAI provider shows both directions. Override `url(model)` when the model
+belongs in the path. Pass an instance as `provider:`.
 
 ## Questions and answers
 
@@ -126,7 +264,31 @@ of one type keyed the same way as `response.answers`.
 
 Score `probabilities` and `legend` are keyed by the wire's string level keys
 (`"0"`, `"1"`, ...), not by the criteria labels. Choice `probabilities` sum to
-approximately 1; treat them as calibrated, not normalized.
+approximately 1; treat them as calibrated, not normalized. Noul
+`probabilities` are always `{"true" => p, "false" => 1 - p}`. Most providers
+send only the probability, and the client fills in the split.
+
+## Images
+
+OpenAI, Cloudflare, Perplexity, and System One servers read images. Pass them
+as base64 data URLs; no provider fetches a remote URL.
+
+```ruby
+photo = RubyDecisionModel::Images.from_file("damage.jpg")
+# or RubyDecisionModel::Images.data_url(bytes, content_type: "image/png")
+
+client.ask(
+  state: "Customer says the screen arrived cracked.",
+  questions: { "damaged" => RubyDecisionModel::Questions.noul("Is there visible damage?") },
+  images: [photo]
+)
+```
+
+Each provider puts them where its API expects: `input_image` parts for
+OpenAI, the `images` field for Cloudflare and System One servers, and
+`image_url` parts inside `state` for Perplexity. Typesafe, OpenRouter, and
+Databricks don't take images, so the client raises `RequestError` before
+sending. Size and count limits vary by vendor and are enforced server side.
 
 ## Retries
 
@@ -144,12 +306,16 @@ Retry behaviour follows the official Typesafe SDKs and lives in
 | `respect_retry_after` | `true` | Honor `Retry-After` and `retry-after-ms` |
 | `max_retry_after` | `60.0` | Ceiling for a server-supplied delay |
 | `retry_connection_errors` | `true` | Retry socket and connection failures |
-| `retry_timeouts` | `true` | Retry open and read timeouts |
+| `retry_timeouts` | `true` | Retry open, read, and write timeouts |
 | `total_timeout` | `30.0` | Budget in seconds across attempts and delays; `nil` disables |
 
 When the next delay would push past `total_timeout`, the client stops and
 raises the last error instead of sleeping. The budget governs whether another
 attempt starts; an attempt already in flight still runs to its own `timeout`.
+With the 30 second read timeout that OpenAI, Perplexity, Databricks, and
+System One servers default to, an attempt that times out uses the whole
+default budget, so it is not retried. Pass `retry: { total_timeout: 90.0 }`
+if you would rather wait for a retry.
 
 Invalid settings (a negative duration, a non-integer `max_retries`, a jitter
 outside 0..1, a NaN budget) raise `ConfigurationError` when the client is built.
@@ -171,18 +337,37 @@ return is still accepted and treated as having no headers, which means no
 
 | Error | Meaning |
 | --- | --- |
-| `ConfigurationError` | No provider could be resolved, missing api_key, unknown provider, or bad `retry:` value |
-| `RequestError` | Questions hash was empty |
+| `ConfigurationError` | No provider could be resolved, a missing key or setting (api_key, account_id, base_url), unknown provider, a `model:` Databricks can't take, or bad `retry:` value |
+| `RequestError` | Questions hash was empty, images were not data URLs or went to a provider that doesn't read them, or state or questions could not be encoded as JSON (original error on `#cause`) |
 | `TransportError` (`TimeoutError`) | Network or timeout failure after retries, carries `#cause_error` |
-| `ApiError` | Non-2xx response, carries `#status`, `#body`, and `#headers` |
+| `ApiError` | Non-2xx response, carries `#status`, `#body`, and `#headers`. The message ends with the vendor's own reason when the body has one |
 | `Unauthorized` | 401 |
 | `PayloadTooLarge` | 413 |
 | `UnprocessableEntity` | 422 (never retried) |
 | `RateLimited` | 429 (retried) |
 | `Overloaded` | 529 (retried) |
-| `InvalidResponse` | Body wasn't JSON, wasn't a Hash, or an answer was malformed |
-| `MissingAnswers` | One or more question ids came back missing or wrong-typed, carries `#missing` |
+| `InvalidResponse` | Body wasn't JSON, wasn't a Hash, or an answer was malformed (including a noul outside 0..1 or an id answered twice) |
+| `MissingAnswers` | One or more question ids came back missing, wrong-typed, or refused. Carries `#missing`, `#refused` (the subset the provider declined), and `#answers` |
 
-Status: 0.1.0, API may change.
+Status: 0.2.0, API may change.
 
 The companion gem `decide` builds decisions and verdicts on top of this client.
+
+## Releasing
+
+Publishing runs through RubyGems trusted publishing, so no API key is stored
+anywhere. To ship a version:
+
+1. Bump `lib/ruby_decision_model/version.rb`.
+2. Add the version to `CHANGELOG.md`.
+3. Run `rake smoke` with whatever provider keys you have. It makes one live
+   request per configured provider and prints the answers. CI never runs it.
+   `TARGETS=open_router:clef,open_router:luna` picks provider and model
+   pairs, and `SMOKE_IMAGE=photo.png` adds an image where supported.
+4. Merge to `main`. The Release workflow runs the suite, builds the gem with
+   `gem build --strict`, checks the built gem carries every file under
+   `lib/`, and pushes it. A version already on RubyGems is skipped, so the
+   workflow is safe to re-run.
+
+The same workflow can be started by hand from the Actions tab or with
+`gh workflow run release.yml`.

data/lib/ruby_decision_model/client.rb

@@ -7,41 +7,48 @@ require "uri"
 
 module RubyDecisionModel
   class Client
-    REQUEST_ID_HEADER = "x-typesafe-request-id"
-
     # Kept from 0.0.1 for callers that referenced them. They describe the
-    # OpenRouter provider and the default RetryPolicy; prefer those directly.
+    # Typesafe and OpenRouter providers and the default RetryPolicy; prefer
+    # those directly. Each provider now names its own request id header.
+    REQUEST_ID_HEADER = "x-typesafe-request-id"
     DEFAULT_BASE_URL = Providers::OpenRouter.new.default_base_url
     DEFAULT_MODEL = Providers::OpenRouter.new.default_model
     MAX_ATTEMPTS = RetryPolicy.new.max_retries + 1
     RETRYABLE_STATUSES = RetryPolicy::DEFAULT_STATUSES
     RETRYABLE_EXCEPTIONS = (RetryPolicy::TIMEOUT_EXCEPTIONS + RetryPolicy::CONNECTION_EXCEPTIONS).freeze
 
-    attr_reader :provider, :model, :retry_policy, :timeout
+    # Connecting is quick wherever the answer is slow, so the open timeout
+    # stays short unless the caller sets timeout: explicitly.
+    DEFAULT_OPEN_TIMEOUT = 5
 
-    # provider:  :open_router, :typesafe, or a Providers::Base instance. When
-    #            nil, api_key: alone selects OpenRouter; otherwise the
-    #            environment decides (TYPESAFE_API_KEY, then OPENROUTER_API_KEY).
+    attr_reader :provider, :model, :retry_policy, :timeout, :open_timeout
+
+    # provider:  a name from Providers.names or a Providers::Base instance.
+    #            When nil, RUBY_DECISION_MODEL_PROVIDER names one if set;
+    #            otherwise api_key: alone selects OpenRouter, and with no
+    #            api_key: the environment decides (see Providers.from_env).
     # api_key:   overrides the provider's env var.
     # model:     nil means the provider default; aliases resolve per provider.
     # base_url:  overrides the provider base URL.
+    # timeout:   read timeout in seconds, and open timeout too when given;
+    #            nil means the provider's read default (5 for Jev-speed APIs,
+    #            30 where the vendor documents multi-second responses) with a
+    #            5 second open timeout.
     # transport: callable(url:, headers:, body:) returning
     #            [status, body_string, headers_hash] (a 2-element return is
     #            still accepted and treated as having no headers).
     # retry:     a RetryPolicy or a Hash of overrides.
     # random:    callable returning a Float in 0...1, used for backoff jitter.
     # clock:     callable returning monotonic seconds, used for total_timeout.
-    def initialize(provider: nil, api_key: nil, model: nil, base_url: nil, timeout: 5,
+    def initialize(provider: nil, api_key: nil, model: nil, base_url: nil, timeout: nil,
                    transport: nil, sleeper: ->(seconds) { sleep(seconds) }, retry: {},
                    random: -> { rand }, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       @provider = resolve_provider(provider, api_key: api_key, base_url: base_url)
-      unless @provider.api_key?
-        raise ConfigurationError,
-              "api_key is required for #{@provider.name}: pass api_key: or set #{@provider.env_var}"
-      end
+      @provider.validate!
 
       @model = @provider.resolve_model(model)
-      @timeout = timeout
+      @timeout = timeout || @provider.default_timeout
+      @open_timeout = timeout || DEFAULT_OPEN_TIMEOUT
       @transport = transport || default_transport
       @sleeper = sleeper
       @retry_policy = RetryPolicy.from(binding.local_variable_get(:retry))
@@ -53,18 +60,46 @@ module RubyDecisionModel
       @provider.base_url
     end
 
-    def ask(state:, questions:)
+    # images: data URLs (see Images) for providers that read images. Each
+    # provider places them where its API expects.
+    def ask(state:, questions:, images: nil)
       raise RequestError, "questions must not be empty" if questions.nil? || questions.empty?
 
-      body = @provider.request_body(model: @model, state: state, questions: questions)
+      body = build_body(state, questions, images)
       status, response_body, response_headers = perform_with_retry(
-        url: @provider.url, headers: @provider.headers, body: body
+        url: request_url, headers: @provider.headers, body: body
       )
       handle_response(status, response_body, response_headers, questions)
     end
 
     private
 
+    # Providers written against 0.1.0 may override url without the model
+    # argument added in 0.2.0.
+    def request_url
+      takes_model = @provider.method(:url).parameters.any? { |type, _| %i[req opt rest].include?(type) }
+      takes_model ? @provider.url(@model) : @provider.url
+    end
+
+    def build_body(state, questions, images)
+      images = Array(images)
+      return @provider.request_body(model: @model, state: state, questions: questions) if images.empty?
+
+      raise RequestError, "#{@provider.name} does not accept images" unless @provider.supports_images?
+
+      images.each do |image|
+        next if image.is_a?(String) && image.start_with?("data:image/")
+
+        raise RequestError, "images must be data URLs (data:image/...); see RubyDecisionModel::Images"
+      end
+
+      @provider.request_body(model: @model, state: state, questions: questions, images: images)
+    rescue JSON::GeneratorError, JSON::NestingError => e
+      # The generator's message can quote the offending value, so it stays
+      # on #cause rather than in a message that may be logged.
+      raise RequestError, "state or questions could not be encoded as JSON (#{e.class})"
+    end
+
     def resolve_provider(provider, api_key:, base_url:)
       case provider
       when Providers::Base
@@ -81,7 +116,7 @@ module RubyDecisionModel
             "no provider configured: pass provider: or api_key:, or set one of #{Providers.env_vars.join(', ')}"
           )
         else
-          Providers.build(:open_router, api_key: api_key, base_url: base_url)
+          Providers.build(Providers.named_in_env || :open_router, api_key: api_key, base_url: base_url)
         end
       else
         raise ConfigurationError, "provider must be a Symbol or a Providers::Base, got #{provider.class}"
@@ -93,8 +128,9 @@ module RubyDecisionModel
         uri = URI.parse(url)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"
-        http.open_timeout = @timeout
+        http.open_timeout = @open_timeout
         http.read_timeout = @timeout
+        http.write_timeout = @timeout
 
         request = Net::HTTP::Post.new(uri.request_uri)
         headers.each { |k, v| request[k] = v }
@@ -162,25 +198,23 @@ module RubyDecisionModel
       raise TransportError.new("transport error: #{exception.message}", cause_error: exception)
     end
 
+    ERROR_CLASSES = {
+      401 => [Unauthorized, "unauthorized"],
+      413 => [PayloadTooLarge, "payload too large"],
+      422 => [UnprocessableEntity, "unprocessable entity"],
+      429 => [RateLimited, "rate limited"],
+      529 => [Overloaded, "overloaded"]
+    }.freeze
+    private_constant :ERROR_CLASSES
+
     def handle_response(status, response_body, response_headers, questions)
-      case status
-      when 200..299
-        parse_success(response_body, response_headers, questions)
-      when 401
-        raise Unauthorized.new("unauthorized", status: status, body: response_body, headers: response_headers)
-      when 413
-        raise PayloadTooLarge.new("payload too large", status: status, body: response_body, headers: response_headers)
-      when 422
-        raise UnprocessableEntity.new("unprocessable entity", status: status, body: response_body,
-                                                              headers: response_headers)
-      when 429
-        raise RateLimited.new("rate limited", status: status, body: response_body, headers: response_headers)
-      when 529
-        raise Overloaded.new("overloaded", status: status, body: response_body, headers: response_headers)
-      else
-        raise ApiError.new("api error (status #{status})", status: status, body: response_body,
-                                                            headers: response_headers)
-      end
+      return parse_success(response_body, response_headers, questions) if (200..299).cover?(status)
+
+      klass, message = ERROR_CLASSES.fetch(status) { [ApiError, "api error (status #{status})"] }
+      detail = @provider.error_message(response_body)
+      message = "#{message}: #{detail}" if detail
+
+      raise klass.new(message, status: status, body: response_body, headers: response_headers)
     end
 
     def parse_success(response_body, response_headers, questions)
@@ -194,12 +228,16 @@ module RubyDecisionModel
 
       raise InvalidResponse, "response body was not a JSON object" unless parsed.is_a?(Hash)
 
-      raw_answers = parsed["answers"]
+      canonical = @provider.normalize_response(parsed, questions: questions)
+      raise InvalidResponse, "response body was not a JSON object" unless canonical.is_a?(Hash)
+
+      raw_answers = canonical["answers"]
       raw_answers = {} unless raw_answers.is_a?(Hash)
 
       normalized = {}
       malformed = []
       missing = []
+      refused = []
 
       questions.each do |raw_id, question|
         id = raw_id.to_s
@@ -213,6 +251,7 @@ module RubyDecisionModel
             malformed << id
           end
         else
+          refused << id if answer_hash.is_a?(Hash) && answer_hash["type"] == "refusal"
           missing << id
         end
       end
@@ -225,28 +264,27 @@ module RubyDecisionModel
       end
 
       if missing.any?
-        raise MissingAnswers.new(
-          "missing or wrong-type answers for: #{missing.join(', ')}",
-          answers: normalized,
-          missing: missing
-        )
+        message = "missing or wrong-type answers for: #{missing.join(', ')}"
+        message += " (refused: #{refused.join(', ')})" if refused.any?
+        raise MissingAnswers.new(message, answers: normalized, missing: missing, refused: refused)
       end
 
       Response.new(
         answers: normalized,
-        usage: @provider.usage(parsed),
-        model: parsed["model"],
-        id: parsed["id"],
+        usage: @provider.usage(canonical),
+        model: canonical["model"],
+        id: canonical["id"],
         raw: parsed,
         request_id: request_id_from(response_headers)
       )
     end
 
     def request_id_from(headers)
-      return nil unless headers.is_a?(Hash)
+      header = @provider.request_id_header
+      return nil unless header && headers.is_a?(Hash)
 
       headers.each do |key, value|
-        next unless key.to_s.casecmp?(REQUEST_ID_HEADER)
+        next unless key.to_s.casecmp?(header)
 
         return value.is_a?(Array) ? value.first : value
       end
@@ -259,7 +297,7 @@ module RubyDecisionModel
       case type
       when "noul"
         noul = hash["noul"]
-        raise MalformedAnswer unless noul.is_a?(Numeric)
+        raise MalformedAnswer unless noul.is_a?(Numeric) && noul.between?(0, 1)
 
         Answers::Noul.new(noul: noul.to_f, probabilities: hash_or_empty(hash["probabilities"]))
       when "choice"