inquirex-llm 0.10.0 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa6e28413bea905a4f70e49fa7a93465bbf0444dbc8594689a7c1adf92cfadd5
-  data.tar.gz: 86a367575aacb7639364196d17189073b0aa621b666b28c90aeec08e5ee6ae33
+  metadata.gz: 1261cf90cb18c935731001fc135e896e271d63e64f84aba6fc5b45105bfcaa8c
+  data.tar.gz: 74ddcc8813674ae65e5979a3becc1c9ecbd7bdf4b0e64e71161a6ddc15c86a01
 SHA512:
-  metadata.gz: f9eb6d18836ee810231421e172b4a36c7b4cae7a4f01681dc7c80577a031b50cf75a7ae8c96deeaea00c2aa08223534222654bd774dcfdd6affc3fa73972ce28
-  data.tar.gz: 57440f09e0446239c3f5f0b1fbb4535127b5c7d5e09c707dd1824d82101a9fd244e4d3447e933cf960cf852f2fbccd80c5a3459dc6faf0df84cbcecc422df209
+  metadata.gz: 1eda2a5ae132b1027700dc058f90ff47fe3a29e5e8804669b5ad4c9c1771f76b8c01484963e8f3d63d5e3fc9f3311e568d67d73b0f35f7e3cff9c1723a4d723c
+  data.tar.gz: 7af624fbd2546c4cf1404f3ac51aecc72c670e013888fb7fdb654be5f2f3ee455023e08737dfea510295bdfa9fd783c4ffe801f2e383004f8491ed463ad02955

data/CHANGELOG.md

@@ -1,12 +1,47 @@
 # Changelog
 
+## 0.12.2 (unreleased)
+
+- **The eval suite now runs on llm-evals.** `inquirex/llm/evals` requires `llm/evals` and subclasses `::LLM::Evals`, because `agent-evals` was renamed and is no longer on RubyGems. The config file is `evals/.llm-evals.config.yml` and the executable is `evals`. Inside `Inquirex::LLM`, a bare `LLM` means this gem, so the leading `::` is required.
+
+## 0.12.0 (unreleased)
+
+Hand-written until `github_changelog_generator` regenerates this file at release. The family-wide notes are in inquirex's `INQUIREX_VERSION_LOG.md`.
+
+- **Current Claude model ids.** `AnthropicAdapter::MODELS` lists `claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5-5` and `claude-haiku-5-5`; the default (`claude-sonnet-5-5`) and the `:claude_sonnet`, `:claude_haiku`, `:claude_opus` and new `:claude_fable` aliases are looked up in it. 0.10.0 defaulted to `claude-sonnet-4-20250514`.
+- **`Inquirex::LLM.configuration`.** Provider, API keys, default models, token limits, temperatures and debug are set in one place, from ENV first (`INQUIREX_LLM_ADAPTER`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, new `INQUIREX_LLM_ANTHROPIC_MODEL`, `INQUIREX_LLM_OPENAI_MODEL`, `INQUIREX_LLM_MAX_TOKENS`, `INQUIREX_LLM_TEMPERATURE`, `INQUIREX_LLM_SUMMARY_MAX_TOKENS`, `INQUIREX_LLM_SUMMARY_TEMPERATURE`, `INQUIREX_DEBUG`), then today's defaults; `Inquirex::LLM.configure` overrides them and `reset_configuration!` re-reads ENV. Invalid values raise `Errors::ConfigurationError` naming the variable. Model ids moved to `Inquirex::LLM::Models`; the adapter constants still answer. `Inquirex::LLM.adapter` builds the adapter with the selection rules inquirex-tty used to carry.
+- **`OpenRouterAdapter`.** Any OpenRouter model through the OpenAI adapter's prompts and parsing, with an optional reasoning `effort:`. New `OPENROUTER_API_KEY` and `INQUIREX_LLM_OPENROUTER_MODEL` (default `anthropic/claude-sonnet-5.5`).
+- **Extraction result object.** An `extract` call returns an `Inquirex::LLM::Extraction`: the schema-shaped Hash it always returned (it is a `Hash`, so `prefill!`, `==` and JSON are unchanged) with `raw`, the JSON exactly as the model sent it before enum values were canonicalized, and `usage`, the tokens and cost the provider reported. One LLM call per extraction, as before.
+- **`JevAdapter`.** TypeSafe's Jev through its native typed-question API: `enum`, `boolean`, `multi_enum` and `integer` fields only, one request per step, `min_confidence:` to leave unsure fields unset, and per-field confidence in the `Extraction#raw`. Reads `TYPESAFE_API_KEY` and `INQUIREX_LLM_JEV_MODEL`, whose default is now `jev-latest` (was the unverified `jev-1.13.0`). Neither new adapter is auto-detected; `INQUIREX_LLM_ADAPTER` accepts `openrouter` and `jev`.
+- **The extraction eval suite now runs on agent-evals.** `evals/` holds `.agent-eval.config.yml` and `datasets/<NN-slug>/` (dsl.rb, schema.rb, `cases/{complete,vague}/`); the adapter and the five-outcome scorer are `Inquirex::LLM::Evals`, in the gem but loaded only by `require "inquirex/llm/evals"`. The standalone `extract-eval` runner is gone; its results are in `docs/evals-history.md`.
+- **Fix:** an `OpenAIAdapter` subclass's `MODEL_MAP` was ignored; model symbols always resolved through OpenAI's map.
+- **No `temperature` for current models.** They answer any sampling parameter with HTTP 400, so the adapter omits it for ids in `MODELS` and still sends it to a model named by an older id.
+- **Requires `inquirex ~> 0.12`**, which declares `prism` as a runtime dependency and so loads on Ruby 4.1.
+- `spec/inquirex/llm/gemspec_spec.rb` fails when `lib/` requires a library that neither ships with the running Ruby nor is a declared runtime dependency.
+- CircleCI config copied from inquirex core; `.ruby-version` pins 4.1.0-preview1.
+
+## [v0.10.0](https://github.com/inquirex/inquirex-llm/tree/v0.10.0) (2026-08-17)
+
+[Full Changelog](https://github.com/inquirex/inquirex-llm/compare/v0.8.0...v0.10.0)
+
+**Merged pull requests:**
+
+- Set the lockstep version to 0.10.0 [#7](https://github.com/inquirex/inquirex-llm/pull/7) ([kigster](https://github.com/kigster))
+- Bump to 0.9.6 [#6](https://github.com/inquirex/inquirex-llm/pull/6) ([kigster](https://github.com/kigster))
+- Add the summarize verb [#5](https://github.com/inquirex/inquirex-llm/pull/5) ([kigster](https://github.com/kigster))
+- Canonicalize LLM output against schema values [#3](https://github.com/inquirex/inquirex-llm/pull/3) ([kigster](https://github.com/kigster))
+
+## [v0.8.0](https://github.com/inquirex/inquirex-llm/tree/v0.8.0) (2026-08-01)
+
+[Full Changelog](https://github.com/inquirex/inquirex-llm/compare/v0.6.0...v0.8.0)
+
 ## [v0.6.0](https://github.com/inquirex/inquirex-llm/tree/v0.6.0) (2026-07-20)
 
 [Full Changelog](https://github.com/inquirex/inquirex-llm/compare/v0.5.0...v0.6.0)
 
 **Merged pull requests:**
 
-- Resolve extract schemas from question references [\#2](https://github.com/inquirex/inquirex-llm/pull/2) ([kigster](https://github.com/kigster))
+- Resolve extract schemas from question references [#2](https://github.com/inquirex/inquirex-llm/pull/2) ([kigster](https://github.com/kigster))
 
 ## [v0.5.0](https://github.com/inquirex/inquirex-llm/tree/v0.5.0) (2026-07-16)
 
@@ -14,7 +49,7 @@
 
 **Merged pull requests:**
 
-- Reduce LLM verbs to `extract` and release v0.5.0 [\#1](https://github.com/inquirex/inquirex-llm/pull/1) ([kigster](https://github.com/kigster))
+- Reduce LLM verbs to `extract` and release v0.5.0 [#1](https://github.com/inquirex/inquirex-llm/pull/1) ([kigster](https://github.com/kigster))
 
 ## [v0.4.1](https://github.com/inquirex/inquirex-llm/tree/v0.4.1) (2026-07-13)
 
@@ -28,6 +63,4 @@
 
 [Full Changelog](https://github.com/inquirex/inquirex-llm/compare/809890f89aa8230b34674820debf7a68ced283e5...v0.1.0)
 
-
-
 \* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/README.md

@@ -228,6 +228,8 @@ engine.answer(result)
 # engine.current_step_id => :summary
 ```
 
+The built-in adapters return an `Inquirex::LLM::Extraction` for an `extract` step. It is the Hash above (a `Hash` subclass, so `prefill!`, `==` and JSON serialization see only the values) carrying two more things from the one LLM call that produced it: `raw`, the JSON exactly as the model sent it before enum values were canonicalized (`raw[:entity_type] # => "LLC"` where `result[:entity_type] # => "llc"`), and `usage`, the tokens and, when the provider reports it, the cost.
+
 For testing, use `NullAdapter` which returns schema-conformant placeholder values without any API calls:
 
 ```ruby
@@ -236,39 +238,116 @@ result = adapter.call(engine.current_step)
 # => { industry: "", employee_count: 0, revenue: 0.0 }
 ```
 
+## Configuration
+
+Model ids, the provider and its credentials are set in one place, `Inquirex::LLM.configuration`. Each setting is read from its environment variable when that variable is set and not blank, and otherwise takes the default below. The adapters fall back on it whenever no `api_key:` or `model:` is passed and a node sets no `max_tokens` or `temperature` of its own.
+
+| Variable                           | Setting               | Default                                                                |
+| ---------------------------------- | --------------------- | ---------------------------------------------------------------------- |
+| `INQUIREX_LLM_ADAPTER`             | `provider`            | auto-detect; else `anthropic`, `openai`, `openrouter`, `jev` or `null` |
+| `ANTHROPIC_API_KEY`                | `anthropic_api_key`   | none                                                                   |
+| `OPENAI_API_KEY`                   | `openai_api_key`      | none                                                                   |
+| `OPENROUTER_API_KEY`               | `openrouter_api_key`  | none                                                                   |
+| `TYPESAFE_API_KEY`                 | `typesafe_api_key`    | none                                                                   |
+| `INQUIREX_LLM_ANTHROPIC_MODEL`     | `anthropic_model`     | `Models::ANTHROPIC_DEFAULT` (`claude-sonnet-5-5`)                      |
+| `INQUIREX_LLM_OPENAI_MODEL`        | `openai_model`        | `Models::OPENAI_DEFAULT` (`gpt-4o-mini`)                               |
+| `INQUIREX_LLM_OPENROUTER_MODEL`    | `openrouter_model`    | `Models::OPENROUTER_DEFAULT` (`anthropic/claude-sonnet-5.5`)           |
+| `INQUIREX_LLM_JEV_MODEL`           | `jev_model`           | `Models::JEV_DEFAULT` (`jev-latest`)                                   |
+| `INQUIREX_LLM_MAX_TOKENS`          | `max_tokens`          | `2048`                                                                 |
+| `INQUIREX_LLM_TEMPERATURE`         | `temperature`         | `0.2`                                                                  |
+| `INQUIREX_LLM_SUMMARY_MAX_TOKENS`  | `summary_max_tokens`  | `4096`                                                                 |
+| `INQUIREX_LLM_SUMMARY_TEMPERATURE` | `summary_temperature` | `0.4`                                                                  |
+| `INQUIREX_DEBUG`                   | `debug`               | off; any non-blank value turns it on                                   |
+
+An invalid value (an unknown provider, a token count that is not a positive integer, a temperature outside 0 to 2) raises `Inquirex::LLM::Errors::ConfigurationError` naming the variable. `to_h` and `inspect` print every `*_api_key` as `[REDACTED]`.
+
+ENV is read once, on first use. Code can override any setting afterwards; `nil` restores the default:
+
+```ruby
+Inquirex::LLM.configure do |c|
+  c.provider        = :anthropic
+  c.anthropic_model = "claude-opus-5-5"
+  c.max_tokens      = 4096
+end
+
+adapter = Inquirex::LLM.adapter            # built from the configuration
+Inquirex::LLM.reset_configuration!         # discard overrides and read ENV again
+```
+
+`Inquirex::LLM.adapter` picks the adapter, first match wins:
+
+| Condition                   | Adapter                                  |
+| --------------------------- | ---------------------------------------- |
+| `provider` is `:null`       | `NullAdapter`                            |
+| `provider` is `:anthropic`  | `AnthropicAdapter` (needs key)           |
+| `provider` is `:openai`     | `OpenAIAdapter` (needs key)              |
+| `provider` is `:openrouter` | `OpenRouterAdapter` (needs key)          |
+| `provider` is `:jev`        | `JevAdapter` (needs key; `extract` only) |
+| `anthropic_api_key` is set  | `AnthropicAdapter`                       |
+| `openai_api_key` is set     | `OpenAIAdapter`                          |
+| otherwise                   | `NullAdapter`                            |
+
+`OPENROUTER_API_KEY` and `TYPESAFE_API_KEY` never select an adapter on their own: a host that has one of those keys for something else keeps the adapter it had, and Jev cannot summarize, so both must be asked for by name.
+
 ## Built-in Adapters
 
-| Class                                   | Provider  | API                                | Auth                      | Key env var         |
-| --------------------------------------- | --------- | ---------------------------------- | ------------------------- | ------------------- |
-| `Inquirex::LLM::NullAdapter`            | —         | none (placeholders)                | none                      | —                   |
-| `Inquirex::LLM::AnthropicAdapter`       | Anthropic | `/v1/messages`                     | `x-api-key` header        | `ANTHROPIC_API_KEY` |
-| `Inquirex::LLM::OpenAIAdapter`          | OpenAI    | `/v1/chat/completions` (JSON mode) | `Authorization: Bearer …` | `OPENAI_API_KEY`    |
-| `Inquirex::LLM::LittleLLMAdapter` (TBD) | Any       | OpenAI Compatible API              | OpenAI Compatible Auth    | Provider Specific   |
+| Class                              | Provider   | API                                    | Auth                      | Key env var          |
+| ---------------------------------- | ---------- | -------------------------------------- | ------------------------- | -------------------- |
+| `Inquirex::LLM::NullAdapter`       | —          | none (placeholders)                    | none                      | —                    |
+| `Inquirex::LLM::AnthropicAdapter`  | Anthropic  | `/v1/messages`                         | `x-api-key` header        | `ANTHROPIC_API_KEY`  |
+| `Inquirex::LLM::OpenAIAdapter`     | OpenAI     | `/v1/chat/completions` (JSON mode)     | `Authorization: Bearer …` | `OPENAI_API_KEY`     |
+| `Inquirex::LLM::OpenRouterAdapter` | OpenRouter | `/api/v1/chat/completions` (JSON mode) | `Authorization: Bearer …` | `OPENROUTER_API_KEY` |
+| `Inquirex::LLM::JevAdapter`        | TypeSafe   | `/v1/systemone` (typed questions)      | `Authorization: Bearer …` | `TYPESAFE_API_KEY`   |
+
+OpenRouter and Jev are never auto-detected; select them with `INQUIREX_LLM_ADAPTER` or build them directly.
 
-The Anthropic and OpenAI adapters use `net/http` (stdlib, no extra dependency), inject the declared `schema` into the system prompt as a strict JSON contract, and raise `Inquirex::LLM::Errors::AdapterError` on HTTP / parse failures and `SchemaViolationError` when the model's output is missing declared fields.
+All adapters use `net/http` (stdlib, no extra dependency), inject the declared `schema` into the system prompt as a strict JSON contract, and raise `Inquirex::LLM::Errors::AdapterError` on HTTP / parse failures and `SchemaViolationError` when the model's output is missing declared fields.
 
 ### AnthropicAdapter
 
 ```ruby
-adapter = Inquirex::LLM::AnthropicAdapter.new(
-  api_key: ENV["ANTHROPIC_API_KEY"],
-  model:   "claude-sonnet-4-20250514"   # or pass the short symbol in the DSL
+adapter = Inquirex::LLM::AnthropicAdapter.new   # key and model from the configuration
+adapter = Inquirex::LLM::AnthropicAdapter.new(  # or name them; arguments win
+  api_key: "sk-ant-...",
+  model:   "claude-opus-5-5"                    # or pass the short symbol in the DSL
 )
 ```
 
-Recognized `model :symbol` values in the DSL: `:claude_sonnet`, `:claude_haiku`, `:claude_opus` (mapped to the current concrete model ids).
+The current model ids live in one constant, `Inquirex::LLM::Models::ANTHROPIC` (also reachable as `AnthropicAdapter::MODELS`): `claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5-5` and `claude-haiku-5-5`. The default is `Models::ANTHROPIC_DEFAULT`, `claude-sonnet-5-5`, unless `INQUIREX_LLM_ANTHROPIC_MODEL` names another. Recognized `model :symbol` values in the DSL: `:claude_sonnet`, `:claude_haiku`, `:claude_opus` and `:claude_fable`, each mapped to its family's id in `MODELS`. `:claude_fable` is Anthropic-only; the OpenAI adapter does not map it.
+
+These models reject sampling parameters, so the adapter does not send `temperature` to them. A `temperature` in the DSL still reaches a model you name by an older id, such as `model: "claude-sonnet-4-6"`.
 
 ### OpenAIAdapter
 
 ```ruby
-adapter = Inquirex::LLM::OpenAIAdapter.new(
-  api_key: ENV["OPENAI_API_KEY"],
-  model:   "gpt-4o-mini"
-)
+adapter = Inquirex::LLM::OpenAIAdapter.new     # key and model from the configuration
+adapter = Inquirex::LLM::OpenAIAdapter.new(api_key: "sk-...", model: "gpt-4.1")
 ```
 
 Uses Chat Completions with `response_format: { type: "json_object" }` so the model is constrained to return valid JSON. Recognized DSL symbols: `:gpt_4o`, `:gpt_4o_mini`, `:gpt_4_1`, `:gpt_4_1_mini`. For cross-provider portability, the adapter also accepts the Claude symbols (`:claude_sonnet` → `gpt-4o` etc.) so a flow file that says `model :claude_sonnet` runs unchanged against either provider.
 
+### OpenRouterAdapter
+
+```ruby
+adapter = Inquirex::LLM::OpenRouterAdapter.new   # key and model from the configuration
+adapter = Inquirex::LLM::OpenRouterAdapter.new(model: "google/gemini-2.5-flash", effort: "low")
+```
+
+Any model OpenRouter hosts, with the OpenAI adapter's prompts and parsing. The Claude and GPT symbols map to OpenRouter ids (`:claude_haiku` → `anthropic/claude-haiku-5.5`); any other model is sent as written. `effort:` (`none` … `max`) becomes OpenRouter's `reasoning.effort`; without it the model decides.
+
+### JevAdapter
+
+```ruby
+adapter = Inquirex::LLM::JevAdapter.new                       # key and model from the configuration
+adapter = Inquirex::LLM::JevAdapter.new(min_confidence: 0.6)  # less sure than 0.6 → nil
+extraction = adapter.call(node, answers)                      # the values, as every adapter returns them
+extraction.raw.dig("filing_status", "confidence")             # how sure Jev was, from TypeSafe's answer
+```
+
+Jev, TypeSafe's System One model, answers typed questions with calibrated probabilities instead of writing JSON. The adapter turns each schema field into questions and sends them all in one request: a Choice per `enum` (plus "not stated"), a yes / no / not-stated Choice per `boolean`, a presence Choice plus a Noul per value for `multi_enum`, and for `integer` a Choice among the numbers the text states (digits or words, `Inquirex::LLM::Numbers`) and the counts 0 to 12. It retries 429 and 529 twice with backoff.
+
+Jev chooses; it cannot write. A schema with a `string`, `text`, `date`, `email`, `phone` or other free-form field raises `AdapterError` before anything is sent (`JevAdapter.unsupported_fields(schema)` checks a flow up front), and `summarize` always raises. Route those to a text model.
+
 ## LLM-assisted Pre-fill Pattern
 
 A common use case: ask *one* open-ended question, let the LLM extract answers for *many* downstream questions, and only prompt the user for what the LLM couldn't determine. This is what the core engine's `Engine#prefill!` is for:
@@ -406,6 +485,30 @@ detour :followup do
 end
 ```
 
+## Evals
+
+Which model extracts best, measured with this gem's own prompts: ten flows, a complete and a vague text each, run on [llm-evals](https://github.com/kigster/llm-evals). The lineup and the data live in [`evals/`](evals/README.md); the adapter and the scorer are `Inquirex::LLM::Evals`, loaded only by `require "inquirex/llm/evals"`.
+
+How a run works:
+
+1. **Verify** (offline): each dataset's `schema.rb` must match the `extract` step in its `dsl.rb`, and every `expected.json` must fit that schema.
+1. **Expand the lineup**: every model under `vendors:` in `evals/.llm-evals.config.yml`, times each `effort`/`temperature` it lists, becomes one contender. Each contender runs every case.
+1. **Call the model**: one OpenRouter chat completion per case, built from this gem's production prompt and the step's schema.
+1. **Score the raw reply** field by field: `correct` 1.0, `missed` 0.2, `hallucinated` 0.15, `incorrect` 0.1, `invalid` 0. A case's score is the mean over its fields. The rules are in [`evals/README.md`](evals/README.md#scoring).
+1. **Report**: a leaderboard on screen and a JSON log under `log/llm-evals/`. If `BRAINTRUST_API_KEY` or `LOGFIRE_TOKEN` is set, each case is also sent to that one tracker; `--local` turns that off.
+
+```bash
+just evals -n                       # the whole matrix, calling nothing
+just evals                          # every configured model on every dataset
+just evals --local -d 05-managed-it-services   # one dataset, no remote tracker
+just evals-verify                   # step 1 only
+
+bundle exec evals cases       # the 20 cases
+bundle exec evals run -m openai/gpt-4o-mini   # one model, per-case breakdown
+```
+
+`just evals` needs `OPENROUTER_API_KEY` and the `:evals` bundle group. It is a paid run: 14 contenders × 20 cases = 280 calls.
+
 ## Development
 
 ```bash

data/lib/inquirex/llm/adapter.rb

@@ -128,6 +128,22 @@ module Inquirex
 
       protected
 
+      # The tokens a response reports, in one shape whatever the provider's:
+      # Anthropic counts input_tokens/output_tokens, OpenAI and OpenRouter
+      # prompt_tokens/completion_tokens, and OpenRouter adds the cost it
+      # billed. Empty when the response carries no usage at all.
+      #
+      # @param usage [Hash, nil] the response's "usage" object
+      # @return [Hash{Symbol => Numeric}] input_tokens, output_tokens, and cost_usd when reported
+      def usage_from(usage)
+        return {} unless usage.is_a?(Hash)
+
+        counts = usage.transform_keys(&:to_s)
+        { input_tokens:  (counts["input_tokens"] || counts["prompt_tokens"]).to_i,
+          output_tokens: (counts["output_tokens"] || counts["completion_tokens"]).to_i,
+          cost_usd:      counts["cost"]&.to_f }.compact
+      end
+
       # The canonical form value for a raw LLM answer, or nil when the answer
       # is outside the allowed list (after trimming and case-folding).
       #
@@ -166,6 +182,18 @@ module Inquirex
           "\"multi_enum\" fields. Never invent a value outside the list."
       end
 
+      # Prompt instruction for fields the source text does not answer. They
+      # must come back null: 0, "", false and [] are real answers (no
+      # dependents, not self-employed), and the engine prefills them and
+      # skips the question as though the user had said so.
+      #
+      # @return [String]
+      def missing_values_instruction
+        "Every key in the schema must be present in your output. When the source text does not " \
+          "provide a value, use null. Never use 0, \"\", false, or [] for a value that is missing: " \
+          "those are answers, and they would be recorded as what the user said."
+      end
+
       # One human-readable line per schema field, used in user prompts:
       #   income_types (multi_enum: W2 | business | crypto)
       #   dependents (integer)

data/lib/inquirex/llm/anthropic_adapter.rb

@@ -4,16 +4,16 @@ require "net/http"
 require "uri"
 require "json"
 require "inquirex/llm/adapter"
+require "inquirex/llm/extraction"
+require "inquirex/llm/configuration"
 
 module Inquirex
   module LLM
     # Real Anthropic Claude adapter for inquirex-llm.
     #
     # Usage:
-    #   adapter = Inquirex::LLM::AnthropicAdapter.new(
-    #     api_key: ENV["ANTHROPIC_API_KEY"],
-    #     model:   "claude-sonnet-4-20250514"
-    #   )
+    #   adapter = Inquirex::LLM::AnthropicAdapter.new  # key and model from Inquirex::LLM.configuration
+    #   adapter = Inquirex::LLM::AnthropicAdapter.new(api_key: "sk-...", model: "claude-opus-5-5")
     #   result = adapter.call(engine.current_step, engine.answers)
     #
     # The adapter:
@@ -26,42 +26,38 @@ module Inquirex
     class AnthropicAdapter < Adapter
       API_URL = "https://api.anthropic.com/v1/messages"
       API_VERSION = "2023-06-01"
-      DEFAULT_MODEL = "claude-sonnet-4-20250514"
-      DEFAULT_MAX_TOKENS = 2048
-
-      # Summaries want a little more room than an extraction (prose, not a
-      # handful of fields) and a little more warmth than one (0.2 produces
-      # summaries that read like a database dump).
-      DEFAULT_SUMMARY_MAX_TOKENS = 4096
-      DEFAULT_SUMMARY_TEMPERATURE = 0.4
-
-      # Maps Inquirex short model symbols to concrete Anthropic model ids.
-      MODEL_MAP = {
-        claude_sonnet: "claude-sonnet-4-20250514",
-        claude_haiku:  "claude-haiku-4-5-20251001",
-        claude_opus:   "claude-opus-4-20250514"
-      }.freeze
-
-      # @param api_key [String, nil] defaults to ENV["ANTHROPIC_API_KEY"]
-      # @param model   [String, nil] default model id when a node does not specify one
+      # The current Claude model ids. Kept as aliases of {Models} so callers
+      # that read them here keep working; {Models} is where they are written.
+      MODELS = Models::ANTHROPIC
+      MODEL_MAP = Models::ANTHROPIC_ALIASES
+      DEFAULT_MODEL = Models::ANTHROPIC_DEFAULT
+
+      DEFAULT_MAX_TOKENS = Configuration::DEFAULT_MAX_TOKENS
+      DEFAULT_SUMMARY_MAX_TOKENS = Configuration::DEFAULT_SUMMARY_MAX_TOKENS
+      DEFAULT_SUMMARY_TEMPERATURE = Configuration::DEFAULT_SUMMARY_TEMPERATURE
+
+      # @param api_key [String, nil] defaults to the configuration's anthropic_api_key (ANTHROPIC_API_KEY)
+      # @param model   [String, nil] default model id when a node does not specify one;
+      #   defaults to the configuration's anthropic_model (INQUIREX_LLM_ANTHROPIC_MODEL)
+      # @raise [ArgumentError] when no key is passed or configured
       def initialize(api_key: nil, model: nil)
         super()
-        @api_key = api_key || ENV.fetch("ANTHROPIC_API_KEY") {
-          raise ArgumentError, "ANTHROPIC_API_KEY is required (pass api_key: or set the env var)"
-        }
-        @default_model = model || DEFAULT_MODEL
+        @api_key = api_key || LLM.configuration.anthropic_api_key
+        raise ArgumentError, "ANTHROPIC_API_KEY is required (pass api_key: or set the env var)" unless @api_key
+
+        @default_model = model || LLM.configuration.anthropic_model
       end
 
       # @param node [Inquirex::LLM::Node] the current LLM step
       # @param answers [Hash] all collected answers so far
-      # @return [Hash] structured data matching the node's schema
+      # @return [Extraction] the schema-shaped values, with the model's raw JSON and the usage
       # @raise [Errors::AdapterError] on API / parse failures
       # @raise [Errors::SchemaViolationError] when the LLM output misses schema fields
       def call(node, answers = {})
         source      = source_answers(node, answers)
         model       = resolve_model(node)
-        temperature = node.respond_to?(:temperature) ? (node.temperature || 0.2) : 0.2
-        max_tokens  = node.respond_to?(:max_tokens)  ? (node.max_tokens  || DEFAULT_MAX_TOKENS) : DEFAULT_MAX_TOKENS
+        temperature = node.respond_to?(:temperature) ? (node.temperature || config.temperature) : config.temperature
+        max_tokens  = node.respond_to?(:max_tokens)  ? (node.max_tokens  || config.max_tokens) : config.max_tokens
 
         response = call_api(
           model:       model,
@@ -71,7 +67,8 @@ module Inquirex
           max_tokens:  max_tokens
         )
 
-        result = normalize_output(node, parse_response(response))
+        raw = parse_response(response)
+        result = Extraction.new(output: normalize_output(node, raw), raw: raw, usage: usage_from(response["usage"]))
         validate_output!(node, result)
         result
       end
@@ -93,20 +90,38 @@ module Inquirex
           model:       resolve_model(node),
           system:      Prompts::SUMMARIZE,
           user:        summary_input(transcript),
-          temperature: node.respond_to?(:temperature) ? (node.temperature || DEFAULT_SUMMARY_TEMPERATURE) : DEFAULT_SUMMARY_TEMPERATURE,
-          max_tokens:  node.respond_to?(:max_tokens) ? (node.max_tokens || DEFAULT_SUMMARY_MAX_TOKENS) : DEFAULT_SUMMARY_MAX_TOKENS
+          temperature: node.respond_to?(:temperature) ? (node.temperature || config.summary_temperature) : config.summary_temperature,
+          max_tokens:  node.respond_to?(:max_tokens) ? (node.max_tokens || config.summary_max_tokens) : config.summary_max_tokens
         )
         parse_text_response(response)
       end
 
       private
 
+      # Read on every call rather than kept from #initialize, so limits set
+      # through Inquirex::LLM.configure after the adapter was built still apply.
+      #
+      # @return [Configuration]
+      def config = LLM.configuration
+
       def resolve_model(node)
         return @default_model unless node.respond_to?(:model) && node.model
 
         MODEL_MAP[node.model.to_sym] || node.model.to_s
       end
 
+      # The models in {MODELS} reject sampling parameters: a request carrying
+      # `temperature` is answered with HTTP 400, whatever its value. The DSL's
+      # `temperature` is therefore sent only to an explicitly named older
+      # model that still accepts it.
+      #
+      # @param model [String] resolved model id
+      # @param temperature [Float]
+      # @return [Hash] `{}` or `{ temperature: }`
+      def sampling(model, temperature)
+        MODELS.include?(model) ? {} : { temperature: temperature }
+      end
+
       def build_system_prompt(node)
         "You are a data extraction assistant for a questionnaire engine. " \
         "Your job is to analyze user input and extract structured data." +
@@ -118,6 +133,7 @@ module Inquirex
           "\n\nYou MUST respond with ONLY a valid JSON object matching this schema:\n" \
             "#{schema_contract_json(node.schema)}\n" \
             "#{values_instruction(node.schema)}\n\n" \
+            "#{missing_values_instruction}\n" \
             "Do not include any text before or after the JSON. No markdown fences. Just the raw JSON object."
         else
           "\n\nRespond with a valid JSON object containing your analysis. " \
@@ -159,14 +175,14 @@ module Inquirex
         request["x-api-key"]         = @api_key
         request["anthropic-version"] = API_VERSION
         request.body = JSON.generate(
-          model:       model,
-          max_tokens:  max_tokens,
-          temperature: temperature,
-          system:      system,
-          messages:    [{ role: "user", content: user }]
+          model:      model,
+          max_tokens: max_tokens,
+          **sampling(model, temperature),
+          system:     system,
+          messages:   [{ role: "user", content: user }]
         )
 
-        warn "[inquirex-llm] Calling #{model}..." if ENV["INQUIREX_DEBUG"]
+        warn "[inquirex-llm] Calling #{model}..." if config.debug?
 
         response = http.request(request)
         unless response.is_a?(Net::HTTPSuccess)

data/lib/inquirex/llm/configuration.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "inquirex/llm/errors"
+require "inquirex/llm/models"
+
+module Inquirex
+  module LLM
+    # Gem-wide settings: which provider to use, its credentials, its default
+    # model, and the generation limits the adapters fall back on when a node
+    # does not set its own.
+    #
+    # Each setting is read from its environment variable when that variable
+    # is set and not blank, and otherwise takes the default below. ENV is read
+    # once, when the configuration is built; {LLM.reset_configuration!} builds
+    # it again. Writers override either, and a nil written restores the
+    # default.
+    #
+    # Invalid values raise {Errors::ConfigurationError} naming the variable
+    # (or the writer) that carried them, at the moment they are read, so a
+    # typo in INQUIREX_LLM_ADAPTER fails loudly instead of silently falling
+    # through to auto-detection.
+    #
+    # @example
+    #   Inquirex::LLM.configure do |c|
+    #     c.provider        = :anthropic
+    #     c.anthropic_model = "claude-opus-5-5"
+    #     c.max_tokens      = 4096
+    #   end
+    class Configuration
+      # The providers {LLM.adapter} can build. nil means auto-detect.
+      PROVIDERS = %i[anthropic openai openrouter jev null].freeze
+
+      DEFAULT_MAX_TOKENS = 2048
+      DEFAULT_TEMPERATURE = 0.2
+
+      # Summaries want more room than an extraction (prose, not a handful of
+      # fields) and more warmth than one (0.2 produces summaries that read
+      # like a database dump).
+      DEFAULT_SUMMARY_MAX_TOKENS = 4096
+      DEFAULT_SUMMARY_TEMPERATURE = 0.4
+
+      # The range both providers accept; OpenAI's is the wider of the two.
+      TEMPERATURES = (0.0..2.0)
+
+      # What {#to_h} and {#inspect} show instead of a credential.
+      REDACTED = "[REDACTED]"
+
+      # One setting: the variable it is read from, its default, and the
+      # coercion its value goes through.
+      Setting = Data.define(:env, :default, :type)
+
+      # Every setting, in the order {#to_h} lists them. Readers, writers,
+      # the ENV table in the README and the specs all follow this table.
+      SETTINGS = {
+        provider:            Setting.new("INQUIREX_LLM_ADAPTER", nil, :provider),
+        anthropic_api_key:   Setting.new("ANTHROPIC_API_KEY", nil, :string),
+        openai_api_key:      Setting.new("OPENAI_API_KEY", nil, :string),
+        openrouter_api_key:  Setting.new("OPENROUTER_API_KEY", nil, :string),
+        typesafe_api_key:    Setting.new("TYPESAFE_API_KEY", nil, :string),
+        anthropic_model:     Setting.new("INQUIREX_LLM_ANTHROPIC_MODEL", Models::ANTHROPIC_DEFAULT, :string),
+        openai_model:        Setting.new("INQUIREX_LLM_OPENAI_MODEL", Models::OPENAI_DEFAULT, :string),
+        openrouter_model:    Setting.new("INQUIREX_LLM_OPENROUTER_MODEL", Models::OPENROUTER_DEFAULT, :string),
+        jev_model:           Setting.new("INQUIREX_LLM_JEV_MODEL", Models::JEV_DEFAULT, :string),
+        max_tokens:          Setting.new("INQUIREX_LLM_MAX_TOKENS", DEFAULT_MAX_TOKENS, :positive_integer),
+        temperature:         Setting.new("INQUIREX_LLM_TEMPERATURE", DEFAULT_TEMPERATURE, :temperature),
+        summary_max_tokens:  Setting.new("INQUIREX_LLM_SUMMARY_MAX_TOKENS", DEFAULT_SUMMARY_MAX_TOKENS, :positive_integer),
+        summary_temperature: Setting.new("INQUIREX_LLM_SUMMARY_TEMPERATURE", DEFAULT_SUMMARY_TEMPERATURE, :temperature),
+        debug:               Setting.new("INQUIREX_DEBUG", false, :flag)
+      }.freeze
+
+      SETTINGS.each_key do |name|
+        attr_reader name
+
+        # @param value [Object, nil] nil restores the default
+        # @raise [Errors::ConfigurationError] when the value is invalid
+        define_method(:"#{name}=") do |value|
+          instance_variable_set(:"@#{name}", resolve(name, value, "Inquirex::LLM.configuration.#{name}"))
+        end
+      end
+
+      # @param env [#[]] the environment to read; ENV unless a spec says otherwise
+      # @raise [Errors::ConfigurationError] when a variable holds an invalid value
+      def initialize(env = ENV)
+        SETTINGS.each do |name, setting|
+          instance_variable_set(:"@#{name}", resolve(name, env[setting.env], setting.env))
+        end
+      end
+
+      # @return [Boolean] whether debug logging is on
+      def debug? = debug
+
+      # Every setting, with credentials replaced by {REDACTED} when set.
+      #
+      # @return [Hash{Symbol => Object}]
+      def to_h
+        SETTINGS.keys.to_h do |name|
+          value = public_send(name)
+          [name, secret?(name) && value ? REDACTED : value]
+        end
+      end
+
+      # Never shows a credential: an exception report or a console session
+      # that prints the configuration must not leak a key.
+      #
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} #{to_h.map { |name, value| "#{name}=#{value.inspect}" }.join(", ")}>"
+      end
+      alias to_s inspect
+
+      private
+
+      def secret?(name) = name.end_with?("_api_key")
+
+      # @param name [Symbol] the setting
+      # @param value [Object, nil] raw value from ENV or a writer
+      # @param source [String] what to name in an error
+      # @return [Object] the coerced value, or the default when blank
+      def resolve(name, value, source)
+        setting = SETTINGS.fetch(name)
+        return setting.default if value.nil? || (value.is_a?(String) && value.strip.empty?)
+
+        send(:"coerce_#{setting.type}", value, source)
+      end
+
+      def coerce_string(value, _source) = value.to_s.strip
+
+      def coerce_provider(value, source)
+        provider = value.to_s.strip.downcase.to_sym
+        return provider if PROVIDERS.include?(provider)
+
+        invalid!(source, value, "one of #{PROVIDERS.join(", ")}")
+      end
+
+      def coerce_positive_integer(value, source)
+        integer = Integer(value.to_s.strip, 10)
+        integer.positive? ? integer : invalid!(source, value, "a positive integer")
+      rescue ArgumentError, TypeError
+        invalid!(source, value, "a positive integer")
+      end
+
+      def coerce_temperature(value, source)
+        float = Float(value.to_s.strip)
+        TEMPERATURES.cover?(float) ? float : invalid!(source, value, "a number from #{TEMPERATURES.min} to #{TEMPERATURES.max}")
+      rescue ArgumentError, TypeError
+        invalid!(source, value, "a number from #{TEMPERATURES.min} to #{TEMPERATURES.max}")
+      end
+
+      # Any non-blank value turns debugging on, as INQUIREX_DEBUG always has.
+      def coerce_flag(value, _source) = value.is_a?(String) || value == true
+
+      def invalid!(source, value, expected)
+        raise Errors::ConfigurationError, "#{source} must be #{expected} (got #{value.inspect})"
+      end
+    end
+
+    class << self
+      # The gem-wide configuration, built from ENV on first use.
+      #
+      # @return [Configuration]
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # @yieldparam config [Configuration]
+      # @return [Configuration]
+      def configure
+        yield configuration
+        configuration
+      end
+
+      # Discards every write and reads ENV again. Call it after changing ENV
+      # (a .env file loaded late, or a spec), since ENV is read only once.
+      #
+      # @return [Configuration]
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end