samagotchi 0.51.0 → 0.52.0

data/lib/samagotchi/engine.rb

@@ -954,7 +954,7 @@ module Samagotchi
       served, served_for = served_model_for(snapshot, target: target)
       snapshot = snapshot.merge(served_model: served, served_model_for: served_for,
                                 served_expected_by: served_expected_by(served, target: target), llm_context: llm_context_summary,
-                                prompt_notes: prompt_notes.map(&:to_h), price_host: target.entry.name)
+                                thinking: thinking_explained&.summary, prompt_notes: prompt_notes.map(&:to_h), price_host: target.entry.name)
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(target)
         if window
@@ -1029,16 +1029,46 @@ module Samagotchi
       nil
     end
 
-    # "off (models: qwen)" for /model: the effective model's thinking level
-    # and where it came from, nil when none is set.
+    # "off (models: qwen)", "low (session)" for /model: the effective
+    # model's thinking level and where it came from, nil when none is set.
     def thinking_summary
+      explained = thinking_explained
+      explained&.source ? explained.label : nil
+    end
+
+    # The effective model's thinking level with where it came from and the
+    # session's own (Thinking::Explained), as the next turn resolves it;
+    # nil when it can't be resolved.
+    # @return [Thinking::Explained, nil]
+    def thinking_explained
       target = @host_registry.resolve(@effective_model_name)
-      level, source = Thinking.resolve(target, names: model_lookup_names(target))
-      source ? "#{level} (#{source})" : nil
+      Thinking.explain(target, names: model_lookup_names(target), session: thinking_override)
     rescue StandardError
       nil
     end
 
+    # The session's own thinking level, nil when it has none.
+    # @return [Symbol, nil]
+    def thinking_override = @session&.thinking
+
+    # What a thinking level change costs the effective model's prompt
+    # cache (Thinking.cache_cost): :full, :provider or :tail.
+    # @return [Symbol]
+    def thinking_cache_cost
+      target = @host_registry.resolve(@effective_model_name)
+      Thinking.cache_cost(target, profile: target.entry&.chat? ? nil : profile&.name)
+    end
+
+    # Set the session's own thinking level (nil unsets it); the next turn's
+    # start resolves it, never a running one (its TurnSettings are fixed).
+    # The caller saves the session.
+    # @raise [ArgumentError] with no session yet
+    def thinking_override=(level)
+      raise ArgumentError, "no session yet" unless @session
+
+      @session.thinking = level
+    end
+
     # The model the server serves for the current model, and the name asked
     # for: what the last generation of that name reported, else llama.cpp's
     # model_alias (/props, one short cached probe; not with probe: false),
@@ -1105,6 +1135,7 @@ module Samagotchi
         served_expected_by: served_expected_by(served_pair[0]),
         context_status: @last_context_status&.dup || saved_context_status(metrics[:context]),
         llm_context: llm_context_summary,
+        thinking: thinking_explained&.summary,
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
         recap_inactivity_seconds: @recap&.inactivity&.to_i
@@ -1242,22 +1273,22 @@ module Samagotchi
                elsif client_id == ClientId::REMINDER then "reminder"
                else "client"
                end
-      session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
-                            "seconds" => seconds.round(1), "origin" => source }
-      session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
-      session.last_turn.merge!(stop_facts(event))
+      session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
+                                       origin: source, exhausted: limit ? true : nil, limit: limit,
+                                       **stop_facts(event))
     end
 
-    # Why a turn stopped, from its end event, for a parent agent's wait
-    # (ReplyWait): a provider error's kind and whether a retry may help, a
-    # cancel's reason and the hook that stopped it. Only what is known.
+    # Why a turn stopped, from its end event (LastTurn::STOP_FACTS), for a
+    # parent agent's wait (ReplyWait): a provider error's kind and whether
+    # a retry may help, a cancel's reason and the hook that stopped it.
+    # Only what is known.
     def stop_facts(event)
       case event&.dig(:type)
       # kept_steps: the turn's work stayed (a parent must not send the task again).
       when :turn_failed
-        { "error_kind" => event[:error_kind]&.to_s, "retryable" => event[:retryable], "kept_steps" => event[:kept_steps] }.compact
+        { error_kind: event[:error_kind]&.to_s, retryable: event[:retryable], kept_steps: event[:kept_steps] }
       when :turn_canceled
-        { "cancel_reason" => event[:cancellation_reason]&.to_s, "stopped_by" => event[:cancelled_by]&.to_s }.compact
+        { cancel_reason: event[:cancellation_reason]&.to_s, stopped_by: event[:cancelled_by]&.to_s }
       else {}
       end
     end
@@ -2237,9 +2268,9 @@ module Samagotchi
       hook_notify(text, level, "thinking")
     end
 
-    # +target+'s thinking level (Thinking.resolve).
+    # +target+'s thinking level (Thinking.resolve), the session's own first.
     def thinking_level(target)
-      Thinking.resolve(target, names: model_lookup_names(target)).first
+      Thinking.resolve(target, names: model_lookup_names(target), session: thinking_override).first
     rescue StandardError
       Thinking::DEFAULT
     end
@@ -2470,7 +2501,7 @@ module Samagotchi
         model_key: -> { @model_key },
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch },
-        llm_context: -> { @session&.llm_context },
+        setup: -> { SessionSetup.of(@session) },
         frontend: -> { interface }
       )
     end

data/lib/samagotchi/engine_peers.rb

@@ -17,6 +17,7 @@ module Samagotchi
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
       def relay = engine.relay_peer
       def model_ref = engine.effective_model_ref
+      def thinking = engine.thinking_override
     end
 
     # What the approval relay needs from the parent's Engine (Peers#relay):

data/lib/samagotchi/host_config.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "config"
+require_relative "host_model"
+require_relative "llm_context_strategy"
+
+module Samagotchi
+  # One config.yml hosts: entry, parsed and checked (ConfigFile.hosts_config
+  # holds them by lowercased name; HostRegistry builds its HostEntry from
+  # one). A worker gets its parent's hosts back through
+  # SAMAGOTCHI_HOSTS_JSON: #to_env_h writes every field, and .parse reads
+  # it back to an equal HostConfig.
+  #
+  # name: the lowercased entry name; host, port, scheme: where it is (from
+  # url: when given); url: the configured url, nil when host/port; transport,
+  # api: symbols, nil when unset; the rest as HostRegistry::HostEntry
+  # describes them, nil when unset; models: {downcased id => HostModel}.
+  HostConfig = Data.define(:name, :host, :port, :scheme, :url, :transport, :api, :api_key_env, :profile,
+                           :first_token_timeout, :vision, :sampling, :thinking, :remote, :window_tokens,
+                           :llm_context_strategy, :llm_context_apply, :llm_context_budget_tokens, :models) do
+    # Every field but name may be left out: nil, models {}.
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, models: {}, **fields)
+    end
+
+    # A hosts: entry as written (YAML, or a worker's SAMAGOTCHI_HOSTS_JSON),
+    # or nil when it is disabled (enabled: false) or invalid. An invalid
+    # one warns once, naming the entry, the way each reader of a setting
+    # does for a bad value (that value is then unset).
+    # @param raw_name [String, Symbol]
+    # @param raw [Hash] string or symbol keys
+    # @return [HostConfig, nil]
+    def self.parse(raw_name, raw)
+      name = raw_name.to_s.strip
+      return nil if name.empty?
+      return invalid(name, "must match /[a-z0-9][a-z0-9._-]*/i") unless name.match?(ConfigFile::HOST_NAME_RE)
+      return invalid(name, "expected mapping") unless raw.is_a?(Hash)
+      return nil if disabled?(raw)
+
+      value = ->(key) { raw.key?(key.to_s) ? raw[key.to_s] : raw[key.to_sym] }
+      where = "hosts entry '#{name}'"
+      fields = {
+        api_key_env: value.call(:api_key_env).to_s.strip.then { |v| v.empty? ? nil : v },
+        # Kept as written; ModelProfile.resolve warns about an unknown one.
+        profile: value.call(:profile).to_s.strip.downcase.then { |v| v.empty? ? nil : v },
+        first_token_timeout: value.call(:first_token_timeout),
+        vision: ConfigFile.vision_flag(value.call(:vision), where),
+        remote: ConfigFile.bool_flag(value.call(:remote), where, "remote"),
+        window_tokens: ConfigFile.window_tokens(value.call(:window_tokens), where),
+        sampling: ConfigFile.sampling_map(value.call(:sampling), where),
+        thinking: Thinking.level(value.call(:thinking), where),
+        llm_context_strategy: LLMContextStrategy.parse(value.call(LLMContextStrategy::KEY), where),
+        llm_context_apply: LLMContextStrategy.parse_apply(value.call(LLMContextStrategy::APPLY_KEY), where),
+        models: HostModel.parse_map(value.call(:models), name),
+        llm_context_budget_tokens: LLMContextStrategy.parse_budget(value.call(LLMContextStrategy::BUDGET_KEY), where)
+      }
+      timeout = fields[:first_token_timeout]
+      unless timeout.nil? || (timeout.is_a?(Numeric) && !timeout.negative?)
+        ConfigFile.warn_once "Warning: #{where}: first_token_timeout must be seconds (0 = off); using the default"
+        fields[:first_token_timeout] = nil
+      end
+      api_key_env = fields[:api_key_env]
+      unless api_key_env.nil? || api_key_env.match?(ConfigFile::ENV_NAME_RE)
+        return invalid(name, "api_key_env must be an environment variable name")
+      end
+
+      location = parse_location(name, value) or return nil
+      kinds = parse_kinds(name, value.call(:transport), value.call(:api)) or return nil
+      new(name: name.downcase, **location, **kinds, **fields)
+    rescue StandardError => e
+      # One entry that trips a reader is dropped on its own, and said so;
+      # the other hosts stay (the worker's copy too).
+      invalid(name || raw_name, "#{e.class}: #{e.message}")
+    end
+
+    # A literal Hash of fields (specs and in-memory callers building a
+    # HostRegistry) as a HostConfig, unchecked; a HostConfig as it is.
+    # @param name [String] the entry's name
+    # @param cfg [HostConfig, Hash] symbol keys, as #to_h gives them
+    def self.coerce(name, cfg)
+      return cfg if cfg.is_a?(HostConfig)
+
+      new(**cfg.to_h.slice(*members), name: name.to_s.downcase)
+    end
+
+    # enabled: false (or "false", any case) in a hosts entry as written.
+    def self.disabled?(raw)
+      enabled = if raw.key?("enabled")
+                  raw["enabled"]
+                else
+                  (raw.key?(:enabled) ? raw[:enabled] : true)
+                end
+      enabled == false || enabled.to_s.strip.downcase == "false"
+    end
+
+    # host/port/scheme/url from url:, or from host: and port:; nil (warned)
+    # when they are wrong.
+    def self.parse_location(name, value)
+      host = value.call(:host)
+      port = value.call(:port)
+      url = value.call(:url).to_s.strip
+      scheme = "http"
+      unless url.empty?
+        return invalid(name, "give url or host/port, not both") unless host.to_s.strip.empty? && port.to_s.strip.empty?
+
+        uri = begin
+          URI.parse(url)
+        rescue URI::InvalidURIError
+          nil
+        end
+        return invalid(name, "url must be an http(s) URL") unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+        host = uri.host
+        port = uri.port
+        scheme = uri.scheme
+        url = url.chomp("/")
+      end
+      host = host.to_s.strip
+      return invalid(name, "host is required") if host.empty?
+
+      port = port.to_s.strip.empty? ? 8080 : port.to_i
+      return invalid(name, "invalid port") if port <= 0 || port > 65_535
+
+      { host: host, port: port, scheme: scheme, url: url.empty? ? nil : url }
+    end
+    private_class_method :parse_location
+
+    # transport: and api: as symbols; a raw-prompt api is also the
+    # transport. nil (warned) when unknown or contradicting each other.
+    def self.parse_kinds(name, transport, api)
+      transport = transport.to_s.strip.downcase
+      if transport.empty?
+        transport = nil
+      elsif !ConfigFile::VALID_TRANSPORTS_FOR_CONFIG.include?(transport)
+        return invalid(name, "unknown transport '#{transport}'")
+      end
+      api = api.to_s.strip.downcase
+      if api.empty?
+        api = nil
+      elsif !ConfigFile::VALID_APIS_FOR_CONFIG.include?(api)
+        return invalid(name, "unknown api '#{api}'")
+      elsif ConfigFile::VALID_TRANSPORTS_FOR_CONFIG.include?(api)
+        # A raw-prompt api is the transport; a different transport contradicts it.
+        return invalid(name, "api '#{api}' conflicts with transport '#{transport}'") if transport && transport != api
+
+        transport = api
+      end
+      { transport: transport&.to_sym, api: api&.to_sym }
+    end
+    private_class_method :parse_kinds
+
+    def self.invalid(name, reason)
+      ConfigFile.warn_once "Warning: ignoring hosts entry '#{name}': #{reason}"
+      nil
+    end
+    private_class_method :invalid
+
+    # The entry as a worker's SAMAGOTCHI_HOSTS_JSON carries it (string keys,
+    # unset fields left out); .parse(name, to_env_h) gives it back. A url
+    # entry travels as its url (host/port come from it); the API key stays
+    # in the environment, which workers inherit.
+    # @return [Hash{String => Object}]
+    def to_env_h
+      location = url ? { "url" => url } : { "host" => host, "port" => port }
+      location.merge("transport" => transport&.to_s, "api" => api&.to_s, "api_key_env" => api_key_env,
+                     "profile" => profile, "first_token_timeout" => first_token_timeout,
+                     "vision" => vision, "sampling" => sampling, "thinking" => thinking&.to_s,
+                     "remote" => remote, "window_tokens" => window_tokens,
+                     "llm_context_strategy" => llm_context_strategy&.map(&:to_s),
+                     "llm_context_apply" => llm_context_apply&.to_s,
+                     "llm_context_budget_tokens" => llm_context_budget_tokens,
+                     "models" => models_config).compact
+    end
+
+    private
+
+    # hosts.<name>.models as written back (HostModel#to_config), nil when none.
+    def models_config
+      models.values.to_h { |m| [m.id, m.to_config] } unless models.nil? || models.empty?
+    end
+  end
+end

data/lib/samagotchi/host_registry.rb

@@ -98,16 +98,11 @@ module Samagotchi
       raw = hosts_config || ConfigFile.hosts_config(env: env)
       @entries = {}
       raw.each do |key, cfg|
-        # cfg: {name:, host:, port:, transport:, original_name:}
-        transport = cfg[:transport]
-        entry = HostEntry.new(name: key.to_s.downcase, host: cfg[:host], port: cfg[:port].to_i, transport: transport,
-                              api: cfg[:api]&.to_sym, scheme: cfg[:scheme], url: cfg[:url], api_key_env: cfg[:api_key_env],
-                              profile: cfg[:profile], first_token_timeout: cfg[:first_token_timeout],
-                              vision: cfg[:vision], sampling: cfg[:sampling], thinking: cfg[:thinking],
-                              remote: cfg[:remote], window_tokens: cfg[:window_tokens],
-                              llm_context_strategy: cfg[:llm_context_strategy], llm_context_apply: cfg[:llm_context_apply],
-                              llm_context_budget_tokens: cfg[:llm_context_budget_tokens], models: cfg[:models] || {})
-        entry.client = Client.new(host: cfg[:host], port: cfg[:port], transport: transport, scheme: cfg[:scheme],
+        cfg = HostConfig.coerce(key, cfg)
+        # Every HostConfig field is a HostEntry member (a new one must be added there too).
+        fields = cfg.to_h.merge(name: key.to_s.downcase, port: cfg.port.to_i, api: cfg.api&.to_sym, models: cfg.models || {})
+        entry = HostEntry.new(**fields)
+        entry.client = Client.new(host: cfg.host, port: cfg.port, transport: cfg.transport, scheme: cfg.scheme,
                                   first_token_timeout: entry.first_token_limit, name: entry.name,
                                   api_key_env: entry.api_key_env, env: env)
         @entries[entry.name] = entry

data/lib/samagotchi/last_turn.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # How a session's last turn ended (Session#last_turn), saved as
+  # session.json's "last_turn" and sent in the web's session summary.
+  # Engine#record_last_turn writes it at every turn's end, ContinueOffer
+  # when a Stop answered the step-limit question (no turn ran).
+  #
+  # outcome: "completed", "failed", "canceled" or "not_continued";
+  # ended_at: iso8601; seconds: Float; origin: "client", "reminder",
+  # "delegate", "delegate_report" (a turn a parent ran for its delegate
+  # children's reports) or "context" (one an attached context source's
+  # change started); exhausted/limit: the turn ran out of iterations at
+  # limit. The rest are its stop facts (LastTurn::STOP_FACTS), only what is
+  # known. A field may be nil (unset; left out of the file).
+  LastTurn = Data.define(:outcome, :ended_at, :seconds, :origin, :exhausted, :limit,
+                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by) do
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, **fields)
+    end
+
+    # A saved record (string keys; symbol keys read too, a key we don't
+    # know dropped), a LastTurn as it is; nil for anything else.
+    # @return [LastTurn, nil]
+    def self.from_file(raw)
+      return raw if raw.is_a?(LastTurn)
+      return nil unless raw.is_a?(Hash)
+
+      new(**members.to_h { |m| [m, raw.key?(m.to_s) ? raw[m.to_s] : raw[m]] })
+    end
+
+    # The session file's record: string keys, in member order, unset
+    # fields left out.
+    # @return [Hash{String => Object}]
+    def to_file = to_h.compact.transform_keys(&:to_s)
+
+    # The stop facts this turn has (LastTurn::STOP_FACTS), symbol keys.
+    # @return [Hash{Symbol => Object}]
+    def stop_facts = to_h.slice(*self.class::STOP_FACTS).compact
+  end
+
+  # Why a turn stopped, for a parent agent's wait (ReplyWait::Result takes
+  # them by these names): a failed turn's provider error kind, whether a
+  # retry may help and whether its work stayed (kept_steps: a parent must
+  # not send the task again); a canceled one's reason and the hook that
+  # stopped it.
+  LastTurn::STOP_FACTS = %i[error_kind retryable kept_steps cancel_reason stopped_by].freeze
+end

data/lib/samagotchi/live_versions.rb

@@ -36,12 +36,6 @@ module Samagotchi
       workers(state_dir: state_dir).reject { |w| w.version == version }
     end
 
-    # The version a chi web on host:port runs, or nil when nothing (or not
-    # chi web) answers.
-    def web_version(host, port, timeout: WEB_TIMEOUT)
-      web_info(host, port, timeout: timeout)&.fetch("version", nil).to_s.then { |v| v.empty? ? nil : v }
-    end
-
     # The /api/info of a chi web on host:port, or nil when nothing (or not
     # chi web) answers.
     def web_info(host, port, timeout: WEB_TIMEOUT)

data/lib/samagotchi/llm/native_tool_normalizer.rb

@@ -26,11 +26,6 @@ module Samagotchi
           Tools::BuiltinCalls.build(call.name.to_s, args_for(call))
         end
 
-        # Map an Array of tool calls to internal call hashes (nils dropped).
-        def normalize_all(calls)
-          Array(calls).map { |call| normalize(call) }.compact
-        end
-
         private
 
         # args_for: arguments is normally a Hash. Defensively handle nil /

data/lib/samagotchi/llm_context_override.rb

@@ -48,7 +48,6 @@ module Samagotchi
     FIELDS = %i[strategy apply budget_tokens].freeze
     # A field's word for "unset: follow the model" (/llm-context strategy default).
     DEFAULT_WORD = "default"
-    OFF_WORDS = %w[off 0].freeze
     # The start flags (chi, chi send --new), by field.
     FLAGS = { strategy: "--llm-context", apply: "--llm-context-apply", budget_tokens: "--llm-context-budget" }.freeze
     # The session command, and its words by field.
@@ -111,7 +110,7 @@ module Samagotchi
     end
 
     def self.file_budget(raw)
-      raw.is_a?(Integer) ? check_budget(raw) : nil
+      raw.is_a?(Integer) ? LLMContextStrategy.check_budget(raw) : nil
     end
 
     # +current+ with +words+ (field => what the user typed) applied: each
@@ -153,27 +152,9 @@ module Samagotchi
       rule || raise(ArgumentError, "unknown llm_context apply #{text} (#{LLMContextStrategy::APPLIES.join(", ")})")
     end
 
-    # The smallest and largest budget a session may set.
-    MIN_BUDGET = 4_000
-    MAX_BUDGET = 10_000_000
-
-    # "64000", "64k" or "off" (0).
+    # "64000", "64k" or "off" (0): LLMContextStrategy.budget_tokens.
     # @return [Integer] 0 for off
-    def self.parse_budget_tokens(text)
-      return 0 if OFF_WORDS.include?(text.downcase)
-
-      match = /\A(\d[\d_]*)(k)?\z/i.match(text)
-      raise ArgumentError, "a budget is a number of tokens (64000 or 64k) or off" unless match
-
-      check_budget(match[1].delete("_").to_i * (match[2] ? 1000 : 1))
-    end
-
-    # +tokens+, when 0 (off) or between MIN_BUDGET and MAX_BUDGET.
-    def self.check_budget(tokens)
-      return tokens if tokens.zero? || tokens.between?(MIN_BUDGET, MAX_BUDGET)
-
-      raise ArgumentError, "a budget of #{tokens} tokens is out of range: #{MIN_BUDGET} (4k) to #{MAX_BUDGET} (10000k), or off"
-    end
+    def self.parse_budget_tokens(text) = LLMContextStrategy.budget_tokens(text)
 
     private_class_method :file_value, :file_strategy, :file_budget
   end

data/lib/samagotchi/llm_context_strategy.rb

@@ -23,7 +23,7 @@ module Samagotchi
   # (false: edit-driven stale stubs are opt-in, experimental) are global only.
   #
   # A soft context budget, llm_context.budget_tokens, and per model or host
-  # the flat key llm_context_budget_tokens (a positive number of tokens),
+  # the flat key llm_context_budget_tokens (tokens or k, 4k to 10M, or off),
   # resolved as the apply rule is, each on its own: off (nil) by default.
   # When set, ContextStatus counts its bands against it instead of the
   # window (the smaller of the two), so the forget layer's offers come
@@ -103,21 +103,52 @@ module Samagotchi
       DEFAULT_APPLY
     end
 
-    # +raw+ as written, a context budget in tokens; nil for unset or 0
-    # (off). Anything but a number of tokens warns, naming +where+, and is
-    # unset.
+    # +raw+ as written in config (llm_context.budget_tokens, a models: or
+    # hosts: entry's llm_context_budget_tokens), read as /llm-context
+    # budget reads it (.budget_tokens); nil for unset, 0 or off. Anything
+    # else warns, naming +where+, and is unset.
     # @return [Integer, nil]
     def parse_budget(raw, where)
       return nil if raw.nil? || raw.to_s.strip.empty?
 
-      tokens = Integer(raw.to_s.strip, exception: false)
-      return nil if tokens&.zero?
-      return tokens if tokens&.positive?
-
-      warn_once "Warning: #{where}: llm_context budget_tokens must be a positive number of tokens; ignored"
+      tokens = budget_tokens(raw)
+      tokens.zero? ? nil : tokens
+    rescue ArgumentError => e
+      warn_once "Warning: #{where}: #{e.message}; ignored"
       nil
     end
 
+    # The smallest and largest budget a session or the config may set.
+    MIN_BUDGET = 4_000
+    MAX_BUDGET = 10_000_000
+    BUDGET_OFF_WORDS = %w[off 0].freeze
+
+    # A budget in tokens: an Integer, "64000", "64_000", "64k", or "off"
+    # (0); the one grammar for /llm-context budget, chi
+    # --llm-context-budget and the config.
+    # @return [Integer] 0 for off
+    # @raise [ArgumentError] not a budget, or one out of MIN_BUDGET..MAX_BUDGET
+    def budget_tokens(raw)
+      return check_budget(raw) if raw.is_a?(Integer)
+
+      text = raw.to_s.strip
+      return 0 if BUDGET_OFF_WORDS.include?(text.downcase)
+
+      match = /\A(\d[\d_]*)(k)?\z/i.match(text)
+      raise ArgumentError, "a budget is a number of tokens (64000 or 64k) or off" unless match
+
+      check_budget(match[1].delete("_").to_i * (match[2] ? 1000 : 1))
+    end
+
+    # +tokens+, when 0 (off) or between MIN_BUDGET and MAX_BUDGET.
+    # @return [Integer]
+    # @raise [ArgumentError]
+    def check_budget(tokens)
+      return tokens if tokens.zero? || tokens.between?(MIN_BUDGET, MAX_BUDGET)
+
+      raise ArgumentError, "a budget of #{tokens} tokens is out of range: #{MIN_BUDGET} (4k) to #{MAX_BUDGET} (10000k), or off"
+    end
+
     # Where one value came from: :session, :model_setting, :host_setting
     # or :config, and the place as a warning names it ("the session",
     # "models: deepseek", "hosts entry 'box'", "llm_context.apply").
@@ -143,7 +174,7 @@ module Samagotchi
     # The strategy for +target+'s turn.
     # @param target [HostRegistry::ModelTarget, nil]
     # @param names [Array<String>] HostRegistry#lookup_names
-    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
     # @param session [Array<Symbol>, nil] the session's own layers ([]: none)
     # @param session_apply [Symbol, nil] the session's own apply rule
     # @param session_budget [Integer, nil] the session's own budget (0: off)
@@ -210,8 +241,9 @@ module Samagotchi
     def budget_for(target, names, models, session_budget)
       return [session_budget.positive? ? session_budget : nil, SESSION_ORIGIN] unless session_budget.nil?
 
-      key, budget = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)
-      return [budget, Origin.new(source: :model_setting, where: "models: #{key}")] if budget
+      if (setting = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models))
+        return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
+      end
 
       budget = target&.entry&.llm_context_budget_tokens
       return [budget, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if budget
@@ -222,8 +254,9 @@ module Samagotchi
     def layers_for(target, names, models, session)
       return [session, :session, SESSION_ORIGIN.where] if session
 
-      key, layers = ConfigFile.model_setting(names, :llm_context_strategy, models: models)
-      return [layers, :model_setting, "models: #{key}"] if layers
+      if (setting = ConfigFile.model_setting(names, :llm_context_strategy, models: models))
+        return [setting.value, :model_setting, "models: #{setting.key}"]
+      end
 
       layers = target&.entry&.llm_context_strategy
       return [layers, :host_setting, "hosts entry '#{target.entry.name}'"] if layers
@@ -235,8 +268,9 @@ module Samagotchi
     def apply_for(target, names, models, session_apply)
       return [session_apply, SESSION_ORIGIN] if session_apply
 
-      key, apply = ConfigFile.model_setting(names, :llm_context_apply, models: models)
-      return [apply, Origin.new(source: :model_setting, where: "models: #{key}")] if apply
+      if (setting = ConfigFile.model_setting(names, :llm_context_apply, models: models))
+        return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
+      end
 
       apply = target&.entry&.llm_context_apply
       return [apply, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if apply

data/lib/samagotchi/memory_bundle/placeholder.rb

@@ -18,11 +18,6 @@ module Samagotchi
         new(content: content).placeholders
       end
 
-      # Returns a sorted list of unique placeholder names found.
-      def unique_names
-        @placeholders.map(&:strip).uniq.sort
-      end
-
       def any?
         !@placeholders.empty?
       end

data/lib/samagotchi/model_profile.rb

@@ -227,7 +227,7 @@ module Samagotchi
       host = parsed.host_name
       return nil unless host
       # Declared under hosts.<name>.models: served whatever the host lists.
-      return nil if hosts[host.to_s.strip.downcase]&.dig(:models)&.key?(parsed.id.to_s.strip.downcase)
+      return nil if hosts[host.to_s.strip.downcase]&.models&.key?(parsed.id.to_s.strip.downcase)
 
       list = lists.read(env: env)[host.to_s.strip.downcase]
       return nil if list.nil? || list.stale? || list.known?(parsed.id)
@@ -433,10 +433,10 @@ module Samagotchi
       end
 
       names.map(&:downcase).uniq.each do |key|
-        setting = models[key]
-        next unless setting && setting[:profile]
+        configured_profile = models[key]&.profile
+        next unless configured_profile
 
-        profile = configured(setting[:profile], "models: #{key}")
+        profile = configured(configured_profile, "models: #{key}")
         return Resolution.new(profile: profile, source: :config, detail: "models: #{key}", retry: false) if profile
       end
 

data/lib/samagotchi/model_settings.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "llm_context_strategy"
+
+module Samagotchi
+  # One config.yml models: entry (per-model settings keyed by model id or
+  # alias), parsed and checked; ConfigFile.model_settings holds them by
+  # downcased key. Each field is nil when unset: profile kept as written
+  # (downcased; ModelProfile.resolve validates it), vision true/false,
+  # sampling a request-field map, thinking a level, window_tokens, and the
+  # LLM context strategy, apply rule and budget (LLMContextStrategy). The
+  # same per-model fields a hosts: entry carries (HostConfig).
+  ModelSettings = Data.define(:profile, :vision, :sampling, :thinking, :window_tokens,
+                              :llm_context_strategy, :llm_context_apply, :llm_context_budget_tokens) do
+    # Every field may be left out (nil).
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, **fields)
+    end
+
+    # A models: entry as written, or nil when it is not a map (or the key is
+    # blank). A bad value warns, naming the entry, and is left unset.
+    # @param key [String] the downcased model id or alias
+    # @param raw [Hash] string or symbol keys
+    # @return [ModelSettings, nil]
+    def self.parse(key, raw)
+      return nil if key.to_s.empty? || !raw.is_a?(Hash)
+
+      value = ->(name) { raw.key?(name.to_s) ? raw[name.to_s] : raw[name.to_sym] }
+      where = "models: #{key}"
+      profile = value.call(:profile).to_s.strip.downcase
+      new(profile: profile.empty? ? nil : profile,
+          vision: ConfigFile.vision_flag(value.call(:vision), where),
+          sampling: ConfigFile.sampling_map(value.call(:sampling), where),
+          thinking: Thinking.level(value.call(:thinking), where),
+          window_tokens: ConfigFile.window_tokens(value.call(:window_tokens), where),
+          llm_context_strategy: LLMContextStrategy.parse(value.call(LLMContextStrategy::KEY), where),
+          llm_context_apply: LLMContextStrategy.parse_apply(value.call(LLMContextStrategy::APPLY_KEY), where),
+          llm_context_budget_tokens: LLMContextStrategy.parse_budget(value.call(LLMContextStrategy::BUDGET_KEY), where))
+    end
+  end
+
+  # One field ConfigFile.model_setting found: the models: key that set it
+  # and its value.
+  ModelSetting = Data.define(:key, :value)
+end