samagotchi 0.63.0 → 0.65.0

data/lib/samagotchi/llm/api_key.rb

@@ -5,14 +5,23 @@ require_relative "errors"
 module Samagotchi
   module LLM
     # A host's API key: the environment variable its api_key_env: names,
-    # sent as `Authorization: Bearer <key>` on every request LLM::HTTP makes
-    # for the host (llama.cpp started with --api-key, or a provider). The
-    # key itself never goes into a message.
-    ApiKey = Data.define(:env_name, :host, :env) do
+    # sent on every request LLM::HTTP makes for the host (llama.cpp started
+    # with --api-key, or a provider) in the header its +scheme+ names:
+    # :bearer `Authorization: Bearer <key>`, :x_api_key `x-api-key: <key>`
+    # (Anthropic's Messages API, which refuses a request carrying both).
+    # The key itself never goes into a message.
+    ApiKey = Data.define(:env_name, :host, :env, :scheme) do
       # nil for a host without api_key_env: its requests carry no header.
-      def self.for(env_name, host:, env: ENV)
+      # @param scheme [Symbol, nil] one of ApiKey::SCHEMES; nil is :bearer
+      def self.for(env_name, host:, env: ENV, scheme: nil)
         name = env_name.to_s.strip
-        name.empty? ? nil : new(env_name: name, host: host.to_s, env: env)
+        name.empty? ? nil : new(env_name: name, host: host.to_s, env: env, scheme: scheme || :bearer)
+      end
+
+      def initialize(env_name:, host:, env:, scheme: :bearer)
+        raise ArgumentError, "unknown auth scheme #{scheme.inspect}" unless self.class::SCHEMES.include?(scheme)
+
+        super
       end
 
       # What to try after a 401/403 from a host that has no api_key_env.
@@ -20,22 +29,30 @@ module Samagotchi
         "the server may want an API key: put it in an environment variable and name it with api_key_env: on host #{host}"
       end
 
-      # Sets the header, or raises AuthError when the variable is not set.
+      # Sets the scheme's header (exactly one of the two), or raises
+      # AuthError when the variable is not set.
       def authorize(request)
         key = env[env_name].to_s
         raise AuthError.new("#{host}: set #{env_name} (the API key for host #{host})", host: host) if key.strip.empty?
 
-        request["Authorization"] = "Bearer #{key}"
+        if scheme == :x_api_key
+          request.delete("Authorization")
+          request["x-api-key"] = key
+        else
+          request.delete("x-api-key")
+          request["Authorization"] = "Bearer #{key}"
+        end
       end
 
       # What to try after a 401/403 with the key sent.
       def hint = "check #{env_name} (the API key for host #{host})"
 
       # Without the environment: it holds this key and every other secret.
-      def inspect = "#<#{self.class.name} #{env_name} host=#{host}>"
+      def inspect = "#<#{self.class.name} #{env_name} host=#{host}#{" scheme=#{scheme}" unless scheme == :bearer}>"
       alias_method :to_s, :inspect
 
       def pretty_print(printer) = printer.text(inspect)
     end
+    ApiKey::SCHEMES = %i[bearer x_api_key].freeze
   end
 end

data/lib/samagotchi/llm/chat_loop.rb

@@ -49,6 +49,10 @@ module Samagotchi
     class ChatLoop < ModelBackend
       include LLM::StreamDrops
 
+      # The line after an answer an OpenAI-compatible host's content filter
+      # cut (finish_reason content_filter with text): kept, not asked again.
+      FILTERED_MARK = "[cut off by the provider's content filter]"
+
       attr_accessor :adapter
       # The session every request is for; Engine sets it with the adapter.
       # Goes out as a Session-Id header (OpenAIChat#chat).
@@ -147,6 +151,11 @@ module Samagotchi
         conversation = llm_context_view.messages(conversation)
         paired = paired_call_ids(conversation)
         boundary = reasoning_boundary(conversation, since: since, level: reasoning)
+        # The last reply with tool calls keeps its thinking blocks past the
+        # boundary: a run stopped between steps (Stop, the step limit) left
+        # its tool_use last, and Messages wants the thinking before it.
+        last_calls = conversation.rindex { |entry| entry[:role].to_s == "model" }
+        last_calls = nil unless last_calls && !Array(conversation[last_calls][:tool_calls]).empty?
         plan = ImagePlan.new(conversation, vision)
         tool_images = []
         wire = []
@@ -162,6 +171,8 @@ module Samagotchi
           when "model"
             message = assistant_message(entry, paired)
             message[:reasoning_content] = entry[:thinking] if boundary && index >= boundary && thought?(entry)
+            blocks = replay_blocks(entry, paired, keep_thinking: (boundary && index >= boundary) || index == last_calls)
+            message[:anthropic_content] = blocks if blocks
             wire << message
           when "tool_response"
             id = entry[:tool_call_id]
@@ -226,13 +237,20 @@ module Samagotchi
 
       # The turn's ReasoningHistory level (the kernel's turn_settings); drop
       # without settings, and for a +model+ whose host refused it
-      # (#reasoning_history_refused!).
+      # (#reasoning_history_refused!). An adapter that sends its blocks back
+      # (#replays_content?) is floored at turn: the running run's thinking
+      # blocks always go back (a tool loop with thinking needs the last
+      # assistant turn's), whatever the level says.
       def reasoning_history(model = nil)
-        return :drop if model && @reasoning_history_refused&.include?(model)
-
-        @kernel.turn_settings&.reasoning_history || :drop
+        level = model && @reasoning_history_refused&.include?(model) ? :drop : @kernel.turn_settings&.reasoning_history
+        level ||= :drop
+        level == :drop && replays_content? ? :turn : level
       end
 
+      # Whether the adapter sends a model entry's saved blocks back verbatim
+      # (AnthropicMessages); the OpenAI wire doesn't.
+      def replays_content? = @adapter.respond_to?(:replays_content?) && @adapter.replays_content?
+
       # The host refused +model+'s reasoning sent back: send none from now on
       # (this worker's lifetime, as #thinking_refused!).
       def reasoning_history_refused!(model)
@@ -252,12 +270,13 @@ module Samagotchi
       # The turn's thinking level (the kernel's turn_settings).
       def thinking = @kernel.turn_settings.thinking || Thinking::DEFAULT
 
-      # The request fields the thinking level adds (Thinking.chat_fields);
-      # none for a model whose host refused them (#thinking_refused!).
+      # The request fields the thinking level adds, as the adapter's wire
+      # takes them (OpenAIChat#thinking_fields: Thinking.chat_fields); none
+      # for a model whose host refused them (#thinking_refused!).
       def thinking_fields(model = nil)
         return {} if model && (@thinking_refused ||= Set.new).include?(model)
 
-        Thinking.chat_fields(thinking)
+        adapter.thinking_fields(thinking)
       end
 
       # The host refused +model+'s thinking fields: leave them out from now on.
@@ -270,14 +289,26 @@ module Samagotchi
       # under the sampling (a sampling key wins, chat_template_kwargs merges
       # per sub-key), the empty-answer retry's temperature on top, then every
       # null dropped at any depth (a sampling null means "don't send it").
+      # A +model+ whose host refused a sampling field (#sampling_refused!)
+      # gets none of SAMPLING_KEYS.
       def request_options(retry_generation: false, model: nil)
         max_tokens = Samagotchi::Config.max_tokens
         options = deep_merge(thinking_fields(model), sampling)
         options = { max_tokens: max_tokens }.merge(options) if max_tokens
         options = EmptyAnswerRetry.sampling(options) if retry_generation
+        options = options.except(*SAMPLING_KEYS) if model && @sampling_refused&.include?(model)
         deep_compact(options)
       end
 
+      # The fields a sampling refusal (BadRequest#sampling_refused?) drops.
+      SAMPLING_KEYS = %i[temperature top_p top_k].freeze
+
+      # The host refused a sampling field for +model+: send none of
+      # SAMPLING_KEYS from now on (this worker's lifetime, as #thinking_refused!).
+      def sampling_refused!(model)
+        (@sampling_refused ||= Set.new) << model
+      end
+
       def strip_model_thought(text) = @kernel.strip_model_thought(text)
 
       def tool_runner
@@ -323,6 +354,7 @@ module Samagotchi
           message[:turn_id] = entry[:turn_id] if entry[:turn_id]
           message[:turn_start] = true if entry[:turn_start] == true
           message[:thinking] = entry[:thinking] if entry[:thinking].is_a?(String) && !entry[:thinking].empty?
+          message[:anthropic_content] = entry[:anthropic_content] if entry[:anthropic_content].is_a?(Array)
           ToolResponse::SAVED_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[TurnNote::RETRY_NUDGE] = true if TurnNote.retry_nudge?(entry)
           marker = TurnNote.empty_answer(entry)
@@ -408,6 +440,24 @@ module Samagotchi
 
       def thought?(entry) = entry[:thinking].is_a?(String) && !entry[:thinking].strip.empty?
 
+      THINKING_BLOCKS = %w[thinking redacted_thinking].freeze
+
+      # A model entry's saved blocks (anthropic_content) to send back
+      # verbatim, for an adapter that replays them: nil when there are none,
+      # for an interrupted entry (its partial blocks have no signature), and
+      # for one with unpaired calls (it goes as flattened text: a tool_use
+      # without its tool_result would fail every later request). Before the
+      # reasoning boundary (+keep_thinking+ false) the thinking blocks are
+      # left out, which removes them only from the front of the history.
+      def replay_blocks(entry, paired, keep_thinking:)
+        blocks = entry[:anthropic_content]
+        return nil unless replays_content? && blocks.is_a?(Array) && !blocks.empty? && !entry[:interrupted]
+        return nil unless Array(entry[:tool_calls]).all? { |call| paired.include?(call[:id]) }
+
+        blocks = blocks.reject { |block| block.is_a?(Hash) && THINKING_BLOCKS.include?((block["type"] || block[:type]).to_s) } unless keep_thinking
+        blocks.empty? ? nil : blocks
+      end
+
       def scrub(text)
         text.encoding == Encoding::UTF_8 && !text.valid_encoding? ? text.scrub("?") : text
       end
@@ -415,6 +465,11 @@ module Samagotchi
       # One turn's state: the conversation, the stream sink and tool
       # activity.
       class Run
+        # Messages' refusal; OpenAI's content filter, a refusal only when
+        # it left no text (else the text stays, marked FILTERED_MARK).
+        REFUSAL = "refusal"
+        FILTERED = "content_filter"
+
         # +start+: where the run a step-limit Continue resumes started (nil:
         # this run starts at the conversation's end).
         def initialize(loop, conversation, on_stream_event, cancel_controller, model_name, pending_input, start: nil)
@@ -457,13 +512,22 @@ module Samagotchi
             end
 
             last_text = @loop.strip_model_thought(response.text)
-            if response.tool_calls.empty?
+            # A provider's refusal (or its content filter) ends the turn here:
+            # tool calls that came with it are not run.
+            @refusal = refusal_of(response, last_text)
+            stopped = @refusal || response.finish_reason.to_s == FILTERED
+            if response.tool_calls.empty? || stopped
+              # A refusal is no answer, never asked again; text it streamed
+              # before is not kept as one. A filtered answer's text stays,
+              # marked as cut by the filter.
+              last_text = "" if @refusal
+              last_text = "#{last_text}\n#{FILTERED_MARK}" if !@refusal && response.finish_reason.to_s == FILTERED
               # Only whitespace is no answer either (as in the native loop).
               empty = last_text.strip.empty?
               # Kept before a merge too: the model answers the merged line
               # knowing what it just said.
               @conversation << with_thinking({ role: "model", content: last_text }, response) unless empty
-              retry_empty = empty &&
+              retry_empty = empty && !stopped &&
                             @empty_retry.retry_empty?(iteration: iteration, cancelled: @cancel_controller&.cancelled?,
                                                       finish_reason: response.finish_reason,
                                                       used_tokens: response.usage&.total_tokens, window_tokens: @window&.tokens)
@@ -495,6 +559,18 @@ module Samagotchi
 
         private
 
+        # A provider's refusal as ModelResult#refusal ({category:} when its
+        # stop_details name one): finish reason refusal, or content_filter
+        # with no visible +text+.
+        def refusal_of(response, text)
+          reason = response.finish_reason.to_s
+          return nil unless reason == REFUSAL || (reason == FILTERED && text.strip.empty?)
+
+          details = response.stop_details
+          category = details["category"] || details[:category] if details.is_a?(Hash)
+          category.to_s.strip.empty? ? {} : { category: category.to_s }
+        end
+
         # The hidden nudge before the next generation (EmptyAnswerRetry),
         # which runs at the retry temperature. Returns true.
         def nudge_empty_answer(iteration, response)
@@ -521,10 +597,14 @@ module Samagotchi
         # The host's reasoning, kept on the model message as +thinking+ for
         # the web turn view's reload (the whole of it, as the live view
         # shows), and sent back to the model as ChatLoop#wire_messages says
-        # (reasoning_history).
+        # (reasoning_history). A wire that sends its blocks back keeps them
+        # as +anthropic_content+ (ChatResponse#provider_content: string
+        # keys, as received, so a resumed session sends the same bytes).
         def with_thinking(message, response)
           reasoning = response.reasoning.to_s
-          reasoning.strip.empty? ? message : message.merge(thinking: reasoning)
+          message = message.merge(thinking: reasoning) unless reasoning.strip.empty?
+          blocks = response.provider_content
+          blocks.is_a?(Array) && !blocks.empty? ? message.merge(anthropic_content: blocks) : message
         end
 
         # One streamed request. Returns [response, nil], or [reason, partial
@@ -551,7 +631,11 @@ module Samagotchi
             begin
               ask.call
             rescue BadRequest => e
-              if refused?(e) && reasoning_sent? then without_reasoning(iteration, e, ask)
+              # A wire that replays its blocks sends them under the turn
+              # floor anyway: asking again without reasoning would resend
+              # the same body.
+              if e.sampling_refused? && sampling_sent?(retry_generation) then without_sampling(iteration, e, ask)
+              elsif refused?(e) && reasoning_sent? && !@loop.replays_content? then without_reasoning(iteration, e, ask)
               elsif thinking_refused?(e) then without_thinking(iteration, e, ask)
               else raise
               end
@@ -613,7 +697,7 @@ module Samagotchi
               event = { type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
                         thinking: reasoning, payload: payload }
               # A tool call streaming: a steer doesn't cut it (Engine#cut_for_steer).
-              tool_call = OpenAIChat.tool_call_delta?(payload)
+              tool_call = @loop.adapter.tool_call_delta?(payload)
               event[:tool_call] = true if tool_call
               streamed_any&.call if !content.to_s.empty? || !reasoning.to_s.empty? || tool_call
               emit(event)
@@ -708,6 +792,21 @@ module Samagotchi
           @without_reasoning = false
         end
 
+        # Whether this step's request sends a sampling field.
+        def sampling_sent?(retry_generation)
+          options = @loop.request_options(retry_generation: retry_generation, model: @model_name)
+          SAMPLING_KEYS.any? { |key| options.key?(key) }
+        end
+
+        # Once per model: asked again without the sampling fields (the
+        # thinking fields stay: an effort level with the empty-answer
+        # retry's temperature keeps thinking on).
+        def without_sampling(iteration, error, ask)
+          @loop.sampling_refused!(@model_name)
+          emit(type: :sampling_refused, iteration: iteration, model: @model_name, detail: error.detail)
+          ask.call
+        end
+
         # Once per model: asked again without the thinking fields.
         def without_thinking(iteration, error, ask)
           @loop.thinking_refused!(@model_name)
@@ -814,7 +913,7 @@ module Samagotchi
           @loop.apply_llm_context!(@conversation, moment: :turn_end, emit: method(:emit)) unless exhausted
           ModelResult.new(text: text, conversation: @loop.plain(@conversation), exhausted: exhausted,
                           tool_activity: @tool_activity, empty_steps: @empty_steps, empty_retries: @empty_retry.attempts,
-                          context_status: @context.display)
+                          context_status: @context.display, refusal: (@refusal unless exhausted))
         end
 
         def emit(event)

data/lib/samagotchi/llm/dialect.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # How a provider's Messages API (`api: anthropic`) departs from
+    # Anthropic's own: a small set of overrides on the standard wire, picked
+    # per host with `dialect:` (HostConfig#dialect, HostEntry#dialect_profile).
+    # A host without one is STANDARD (Anthropic, Splash, a gateway passing
+    # Claude through).
+    #
+    # name: the config value ("standard" for none);
+    # auth: the header the key goes in when the host sets no auth:
+    #   (LLM::ApiKey::SCHEMES);
+    # thinking_display: the `display` sent with adaptive or budget thinking,
+    #   nil for none;
+    # cache_breakpoints: whether chat requests carry cache_control;
+    # session_header: a header that carries the session id (beside
+    #   Session-Id), nil for none.
+    Dialect = Data.define(:name, :auth, :thinking_display, :cache_breakpoints, :session_header) do
+      # The dialect for a `dialect:` name (HostConfig#dialect); STANDARD for
+      # nil or an unknown one.
+      def self.for(name) = self::BY_NAME.fetch(name.to_s, self::STANDARD)
+
+      # A hosts entry's `dialect:` as written: the name, or nil when unset.
+      # An unknown name, or one on a host whose api isn't anthropic, warns
+      # once (naming +where+) and is ignored.
+      # @param api [Symbol, nil] the entry's api
+      # @return [String, nil]
+      def self.parse(value, where, api:)
+        text = value.to_s.strip.downcase
+        return nil if text.empty?
+
+        require_relative "../config"
+
+        unless self::BY_NAME.key?(text)
+          ConfigFile.warn_once "Warning: #{where}: dialect must be one of #{self::BY_NAME.keys.join(", ")}; ignored"
+          return nil
+        end
+        return text if api&.to_sym == :anthropic
+
+        ConfigFile.warn_once "Warning: #{where}: dialect has no effect on api: #{api || "(none)"}; ignored"
+        nil
+      end
+    end
+
+    Dialect::STANDARD = Dialect.new(name: "standard", auth: :x_api_key, thinking_display: "summarized",
+                                    cache_breakpoints: true, session_header: nil)
+    # Fireworks' /v1/messages (docs.fireworks.ai, anthropic-compatibility):
+    # Bearer auth, no `display` in its thinking schema (every object refuses
+    # extra fields; thinking comes back by default), an automatic prefix
+    # cache (no breakpoints), and x-session-affinity to keep a session on
+    # one replica, where its cache is.
+    Dialect::FIREWORKS = Dialect.new(name: "fireworks", auth: :bearer, thinking_display: nil,
+                                     cache_breakpoints: false, session_header: "x-session-affinity")
+    Dialect::BY_NAME = { "standard" => Dialect::STANDARD, "fireworks" => Dialect::FIREWORKS }.freeze
+  end
+end

data/lib/samagotchi/llm/errors.rb

@@ -28,7 +28,8 @@ module Samagotchi
     #   OverBudget       402 metadata.reason weight_exceeds_budget: the
     #                    request alone exceeds the key's budget; an
     #                    OutOfCredits, never retried
-    #   ServerError      5xx or a server's error event mid-stream
+    #   ServerError      5xx, or a mid-stream error event with no status or
+    #                    Anthropic error.type
     #   AuthError        401/403, or an API key variable that is not set
     #   BadRequest       other 4xx (a context overflow is one, whatever status;
     #                    so is a model that can't take tools)
@@ -136,11 +137,14 @@ module Samagotchi
       TOOLS_HINT = "this model can't use tools, and chi needs them: pick another model (/model) or host"
 
       # @param hint [String, nil] what to try, added to the summary
-      def initialize(message = nil, context_overflow: false, tools_unsupported: false, reasoning_refused: false, hint: nil,
-                     **)
+      def initialize(message = nil, context_overflow: false, tools_unsupported: false, reasoning_refused: false,
+                     thinking_signature: false, thinking_binding_unsupported: false, sampling_refused: false, hint: nil, **)
+        @sampling_refused = sampling_refused
         @context_overflow = context_overflow
         @tools_unsupported = tools_unsupported
         @reasoning_refused = reasoning_refused
+        @thinking_signature = thinking_signature
+        @thinking_binding_unsupported = thinking_binding_unsupported
         @hint = hint
         super(message, **)
       end
@@ -158,6 +162,24 @@ module Samagotchi
       # be what the host refuses (gpt-oss: "Reasoning is mandatory").
       def reasoning_refused? = @reasoning_refused
 
+      # A 400 about a replayed thinking block's signature (Anthropic: "Invalid
+      # `signature` in `thinking` block", bound to a different conversation
+      # or unreadable). The block is what's wrong, not the thinking fields:
+      # never #reasoning_refused?.
+      def thinking_signature? = @thinking_signature
+
+      # A 400 refusing the thinking binding controls: the
+      # thinking.block_binding field ("Extra inputs are not permitted") or
+      # the thinking-binding-controls beta header. Never #reasoning_refused?.
+      def thinking_binding_unsupported? = @thinking_binding_unsupported
+
+      # A 400 that refuses a sampling field (temperature, top_p, top_k):
+      # Claude's "temperature may only be set to 1 when thinking is
+      # enabled" for the empty-answer retry's temperature. Not
+      # reasoning_refused? although it says "thinking": ChatLoop asks again
+      # without those fields instead.
+      def sampling_refused? = @sampling_refused
+
       def kind = :bad_request
 
       def summary
@@ -277,15 +299,35 @@ module Samagotchi
     # Builds the ProviderError for an HTTP error response or a server's error
     # event.
     module ProviderErrors
-      CONTEXT_OVERFLOW_RE = /exceeds? (the )?(available )?context (size|length|window)|context[_ ]length[_ ]exceeded|exceed_context_size|maximum context length/i
+      # A prompt larger than the model's window; Anthropic: "prompt is too
+      # long: 208310 tokens > 200000 maximum", or "input length and
+      # `max_tokens` exceed context limit: 188240 + 21333 > 200000".
+      CONTEXT_OVERFLOW_RE = Regexp.union(
+        /exceeds? (the )?(available )?context (size|length|window)|context[_ ]length[_ ]exceeded|exceed_context_size/i,
+        /maximum context length|prompt is too long: \d+ tokens/i,
+        /input length and `?max_tokens`? exceed context limit: \d+ \+ \d+ > \d+/i
+      )
       # A model that takes no tools: OpenRouter when no endpoint of the model
       # does ("No endpoints found that support tool use", 404), Ollama ("…
       # does not support tools"), vLLM started without a tool parser.
       TOOLS_UNSUPPORTED_RE = /support tool use|(does not|doesn't) support tools|tool choice requires --enable-auto-tool-choice/i
       # A model or server that can't take images (see VisionUnsupported).
       VISION_UNSUPPORTED_RE = /support image input|image input is not supported|mmproj/i
-      # A 400 about the thinking fields chi sent (Thinking.chat_fields).
+      # A 400 about the thinking fields chi sent (Thinking.chat_fields). Broad;
+      # a signature or binding-control 400 (below) is not one.
       REASONING_REFUSED_RE = /reasoning|thinking/i
+      # Messages' 400 for an assistant turn sent back without its thinking
+      # block before tool_use: about the history sent, not a refusal of
+      # reasoning (it would turn thinking off for the model).
+      THINKING_BLOCK_MISSING_RE = /expected `?thinking`? or `?redacted_thinking`?|must start with a thinking block/i
+      # A 400 about a sampling field (BadRequest#sampling_refused?).
+      SAMPLING_REFUSED_RE = /\b(temperature|top_p|top_k)\b/i
+      # A 400 about a thinking block's signature (BadRequest#thinking_signature?).
+      THINKING_SIGNATURE_RE = /invalid `?signature`? in `?thinking`? block|bound to a different conversation/i
+      # A 400 refusing the binding controls (BadRequest#thinking_binding_unsupported?):
+      # the field without the beta header, or the beta header itself.
+      THINKING_BINDING_UNSUPPORTED_RE = Regexp.union(/block_binding:? extra inputs are not permitted/i,
+                                                     /unexpected value\(s\) `?thinking-binding-controls/i)
       # A 402 about credit held by in-flight requests (see CreditsHeld).
       CREDITS_HELD_RE = /in-flight requests/i
       # A 402's error.metadata.reason when the request can never fit the
@@ -294,6 +336,20 @@ module Samagotchi
       # Seconds to wait before retrying a CreditsHeld without a Retry-After.
       CREDITS_SETTLE_DELAY = 20.0
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
+      # The HTTP status an Anthropic error.type stands for, for an error
+      # object that carries no numeric code (a Messages stream's error event,
+      # an OpenAI error whose code is null or a name).
+      ERROR_TYPE_STATUS = {
+        "invalid_request_error" => 400, "authentication_error" => 401, "billing_error" => 402,
+        "permission_error" => 403, "not_found_error" => 404, "request_too_large" => 413,
+        "rate_limit_error" => 429, "api_error" => 500, "overloaded_error" => 529, "timeout_error" => 504
+      }.freeze
+      # The HTTP status a Google-style error.code stands for (Fireworks'
+      # errors before a request reaches a model: {"error":{"code":"NOT_FOUND"}}).
+      ERROR_CODE_STATUS = {
+        "INVALID_ARGUMENT" => 400, "UNAUTHENTICATED" => 401, "PERMISSION_DENIED" => 403, "NOT_FOUND" => 404,
+        "RESOURCE_EXHAUSTED" => 429
+      }.freeze
 
       module_function
 
@@ -322,10 +378,7 @@ module Samagotchi
           else
             OutOfCredits.new(text, **options)
           end
-        when 400..499
-          tools = TOOLS_UNSUPPORTED_RE.match?(message)
-          BadRequest.new(text, tools_unsupported: tools,
-                               reasoning_refused: status == 400 && !tools && REASONING_REFUSED_RE.match?(message), **options)
+        when 400..499 then bad_request(text, status, message, options)
         when 500..599
           ServerError.new(text, retryable: RETRYABLE_SERVER_STATUSES.include?(status),
                                 retry_after: parse_retry_after(retry_after), **options)
@@ -359,15 +412,31 @@ module Samagotchi
         from_error_json(body.to_s, host: host)
       end
 
+      # A BadRequest for a 4xx, with its predicates from +message+.
+      def bad_request(text, status, message, options)
+        tools = TOOLS_UNSUPPORTED_RE.match?(message)
+        signature = THINKING_SIGNATURE_RE.match?(message)
+        binding = !signature && THINKING_BINDING_UNSUPPORTED_RE.match?(message)
+        sampling = status == 400 && !tools && !signature && !binding && SAMPLING_REFUSED_RE.match?(message)
+        missing = THINKING_BLOCK_MISSING_RE.match?(message)
+        refused = status == 400 && !tools && !signature && !binding && !sampling && !missing &&
+                  REASONING_REFUSED_RE.match?(message)
+        BadRequest.new(text, tools_unsupported: tools, thinking_signature: signature, thinking_binding_unsupported: binding,
+                             sampling_refused: sampling, reasoning_refused: refused, **options)
+      end
+
       # The ProviderError for a JSON error object, by its error.code (an HTTP
-      # status); 500 when it has none.
+      # status, or a name in ERROR_CODE_STATUS), else by its error.type
+      # (ERROR_TYPE_STATUS); 500 when it has neither.
       def from_error_json(raw, host:)
         parsed = parse_json(raw)
         error = parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : parsed
         code = error.is_a?(Hash) ? error["code"] : nil
         code = code.to_i if code.is_a?(String) && code.match?(/\A\d{3}\z/)
-        status = code.is_a?(Integer) && code.between?(400, 599) ? code : 500
-        from_response(status: status, body: raw, host: host)
+        status = code if code.is_a?(Integer) && code.between?(400, 599)
+        status ||= ERROR_CODE_STATUS[code] if code.is_a?(String)
+        status ||= ERROR_TYPE_STATUS[error["type"]] if error.is_a?(Hash)
+        from_response(status: status || 500, body: raw, host: host)
       end
 
       # The human part of an error body: error.message, message, error (a

data/lib/samagotchi/llm/model_listing.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # A model a host lists. Unknown fields are nil.
+    ModelInfo = Data.define(:id, :context_window, :supports_tools, :raw) do
+      # true when the list says the model takes images, false when it says
+      # it doesn't, else nil: OpenRouter's architecture.input_modalities,
+      # Anthropic's capabilities.image_input.supported, Splash's top-level
+      # input_modalities or vision, Fireworks' supports_image_input,
+      # llama.cpp's "multimodal" capability.
+      def image_input
+        return nil unless raw.is_a?(Hash)
+
+        modalities = raw.dig("architecture", "input_modalities")
+        return modalities.include?("image") if modalities.is_a?(Array)
+
+        capabilities = raw["capabilities"]
+        supported = capabilities.dig("image_input", "supported") if capabilities.is_a?(Hash)
+        return supported if [true, false].include?(supported)
+        return raw["input_modalities"].include?("image") if raw["input_modalities"].is_a?(Array)
+        return raw["vision"] if [true, false].include?(raw["vision"])
+        return raw["supports_image_input"] if [true, false].include?(raw["supports_image_input"])
+        return true if capabilities.is_a?(Array) && capabilities.include?("multimodal")
+
+        nil
+      end
+    end
+
+    # A chat adapter's model list, kept per models_ttl: what #context_window
+    # and #image_input read. The adapter defines #list_models (its wire's
+    # GET) and calls #init_model_listing from its initializer.
+    module ModelListing
+      # The window (tokens) the host lists for +model+, or nil. The list is
+      # read once per models_ttl; a failed listing answers nil.
+      def context_window(model:)
+        listed_model(model)&.context_window
+      rescue StandardError
+        nil
+      end
+
+      # Whether the host's list says +model+ takes images (ModelInfo#image_input),
+      # or nil when it doesn't say or the listing fails.
+      def image_input(model:)
+        listed_model(model)&.image_input
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def init_model_listing(models_ttl)
+        @models_ttl = models_ttl
+        @models_mutex = Mutex.new
+      end
+
+      # +model+'s entry in the cached list: its exact id, else any case.
+      def listed_model(model)
+        cached_models.find { |m| m.id == model.to_s } || cached_models.find { |m| m.id.casecmp?(model.to_s) }
+      end
+
+      def model_entries(body)
+        return [] unless body.is_a?(Hash)
+
+        entries = body["data"].is_a?(Array) ? body["data"] : body["models"]
+        Array(entries).select { |entry| entry.is_a?(Hash) }
+      end
+
+      def model_info(raw)
+        id = (raw["id"] || raw["model"] || raw["name"]).to_s
+        ModelInfo.new(id: id, context_window: window_of(raw), supports_tools: tools_support(raw), raw: raw)
+      end
+
+      # The running window when the list says: context_length, context_window,
+      # max_model_len, or llama.cpp's meta.n_ctx (not n_ctx_train).
+      def window_of(raw)
+        [raw["context_length"], raw["context_window"], raw["max_model_len"], raw.dig("meta", "n_ctx")].each do |value|
+          return value if value.is_a?(Integer) && value.positive?
+        end
+        nil
+      end
+
+      # Whether the list says the model takes tools: OpenRouter's
+      # supported_parameters or llama.cpp's capabilities naming "tools"
+      # (true, else nil), or Fireworks' supports_tools (true or false).
+      def tools_support(raw)
+        return raw["supports_tools"] if [true, false].include?(raw["supports_tools"])
+
+        listed = raw["supported_parameters"] || raw["capabilities"]
+        return nil unless listed.is_a?(Array)
+
+        listed.include?("tools") || nil
+      end
+
+      def cached_models
+        @models_mutex.synchronize do
+          fresh = @models_at && (monotonic - @models_at) < @models_ttl
+          return @models if fresh
+        end
+        models = list_models
+        @models_mutex.synchronize do
+          @models = models
+          @models_at = monotonic
+        end
+        models
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end