samagotchi 0.10.0 → 0.11.0

data/lib/samagotchi/config.rb

@@ -8,6 +8,7 @@ require "set"
 require_relative "atomic_file"
 require_relative "config_text_edit"
 require_relative "log"
+require_relative "model_ref"
 require_relative "paths"
 
 module Samagotchi
@@ -436,7 +437,44 @@ module Samagotchi
           else
             [key_problem(key)].compact
           end
+        end + model_ref_problems(data)
+      end
+
+      # What a model ref in config.yml won't do as written: an alias whose
+      # target is another alias (aliases apply once, ModelRef), a ref that
+      # starts with "<host>/" (only ':' names a host).
+      def model_ref_problems(data)
+        hosts = data["hosts"].is_a?(Hash) ? data["hosts"] : {}
+        aliases = data["model_aliases"].is_a?(Hash) ? data["model_aliases"] : {}
+        default = data["default"]["model"] if data["default"].is_a?(Hash)
+        refs = [["default.model", default], *aliases.map { |name, target| ["model_aliases.#{name}", target] }]
+        slash = refs.filter_map { |where, ref| host_slash_problem(where, ref, hosts) }
+        names = aliases.keys.map { |k| k.to_s.strip.downcase }
+        chains = aliases.filter_map do |name, target|
+          _, inner = ModelRef.split(target, hosts: hosts)
+          next unless names.include?(inner.downcase)
+
+          "config: model_aliases.#{name} points to the alias '#{inner}'; aliases don't chain, so '#{inner}' is sent as written"
         end
+        slash + chains + hosts.keys.filter_map { |name| family_host_problem(name.to_s) }
+      end
+
+      # Model families whose ids carry a ':' tag on Ollama and friends
+      # (qwen3:8b, llama3.1:70b): a host named like one takes those refs.
+      MODEL_FAMILY_HOST_RE = /\A(?:qwen|llama|codellama|gemma|mistral|mixtral|deepseek|phi|granite|starcoder|smollm|olmo)[\d.]*\z/i
+
+      def family_host_problem(name)
+        return nil unless name.match?(MODEL_FAMILY_HOST_RE)
+
+        "config: hosts.#{name} is named like a model family: a ref such as '#{name}:8b' (an Ollama tag) " \
+          "goes to host #{name} as '8b'; rename the host if you use such ids"
+      end
+
+      def host_slash_problem(where, ref, hosts)
+        prefix, rest = ref.to_s.strip.split("/", 2)
+        return nil if rest.to_s.empty? || !hosts.keys.map { |k| k.to_s.downcase }.include?(prefix.downcase)
+
+        "config: #{where} '#{ref}' starts with the host '#{prefix}' and '/': only ':' names a host now (#{prefix}:#{rest})"
       end
 
       # Dotted keys config.yml may set: config-exposed entries (snake and kebab
@@ -831,28 +869,9 @@ module Samagotchi
     end
 
     # Parse a model string that may be qualified as "host_alias:model"
-    # Returns [host_alias_or_nil, bare_model]
+    # Returns [host_alias_or_nil, bare_model] (ModelRef.split)
     def parse_host_qualified_model(raw, hosts: nil)
-      value = raw.to_s.strip
-      return [nil, value] if value.empty?
-      # Try split on first ':' or '/' where prefix matches a known host
-      hosts_map = hosts || {}
-      # Normalize keys downcase
-      lowered_keys = hosts_map.keys.map(&:downcase)
-      # Check ':' split
-      if value.include?(":")
-        prefix, rest = value.split(":", 2)
-        if lowered_keys.include?(prefix.strip.downcase) && !rest.strip.empty?
-          return [prefix.strip.downcase, rest.strip]
-        end
-      end
-      if value.include?("/")
-        prefix, rest = value.split("/", 2)
-        if lowered_keys.include?(prefix.strip.downcase) && !rest.strip.empty?
-          return [prefix.strip.downcase, rest.strip]
-        end
-      end
-      [nil, value]
+      ModelRef.split(raw, hosts: hosts)
     end
 
     # Hosted providers' names, which no local model family uses: as a
@@ -989,25 +1008,10 @@ module Samagotchi
       nil
     end
 
-    def resolve_model_alias(raw, env: ENV, path: global_path(env: env), hosts: nil)
-      value = raw.to_s.strip
-      return value if value.empty?
-
-      aliases = model_aliases(env: env, path: path)
-      # Host-qualified handling: "host:alias" -> "host:resolved"
-      # This allows /model small-box:small where "small" is an alias.
-      if value.include?(":") || value.include?("/")
-        hosts_map = hosts || hosts_config(env: env, path: path)
-        host, bare = parse_host_qualified_model(value, hosts: hosts_map)
-        if host && !bare.to_s.strip.empty?
-          resolved_bare = aliases.fetch(bare.downcase, bare)
-          # Preserve the separator the user used (: or /)
-          sep = value.downcase.include?("#{host}:") ? ":" : (value.downcase.include?("#{host}/") ? "/" : ":")
-          return "#{host}#{sep}#{resolved_bare}"
-        end
-      end
-
-      aliases.fetch(value.downcase, value)
+    # +raw+ parsed against config.yml's hosts (or +hosts+) and aliases.
+    # @return [ModelRef]
+    def model_ref(raw, env: ENV, path: global_path(env: env), hosts: nil)
+      ModelRef.parse(raw, hosts: hosts || hosts_config(env: env, path: path), aliases: model_aliases(env: env, path: path))
     end
 
     # Words /model takes as arguments (clear/default/none/off reset the

data/lib/samagotchi/context_status.rb

@@ -5,7 +5,7 @@ require_relative "context_usage"
 require_relative "context_window"
 
 module Samagotchi
-  # One turn's context tracking for KernelLoop#run: how full the window is
+  # One turn's context tracking for either loop: how full the window is
   # before each request (the server's last prompt count plus an estimate for
   # what the turn appended since, else a chars-per-token estimate), the
   # bucket that puts it in, and what comes of that:
@@ -95,18 +95,18 @@ module Samagotchi
 
     def enabled? = @enabled
 
-    # Before a request: estimate +prompt+'s usage against +window+ (this
-    # request's ContextWindow::Resolved) and update the status line's
-    # value. A rise into a bucket that asks the model for a change leaves
-    # a line for #take_guidance.
-    # +image_tokens+: the images' estimate (their base64 is not in +prompt+).
+    # Before a request: estimate the usage of a prompt of +prompt_chars+
+    # against +window+ (this request's ContextWindow::Resolved) and update
+    # the status line's value. A rise into a bucket that asks the model for
+    # a change leaves a line for #take_guidance.
+    # +image_tokens+: the images' estimate (their base64 is not in the chars).
     #
     # @return [Hash, nil] the :context_status event's fields (without
     #   :type/:iteration) when the emit gate fires, else nil
-    def observe(prompt, iteration_index:, window:, image_tokens: 0)
+    def observe(prompt_chars, iteration_index:, window:, image_tokens: 0)
       return nil unless @enabled
 
-      usage = estimate(prompt, server_usage: @server_usage, window: window, image_tokens: image_tokens, counted: @counted)
+      usage = estimate(prompt_chars, server_usage: @server_usage, window: window, image_tokens: image_tokens, counted: @counted)
       bucket = bucket_for(usage[:estimated_pct])
       # The status line's value, every iteration; the gate below decides
       # only the event and the model's guidance line.
@@ -135,7 +135,8 @@ module Samagotchi
       normalized
     end
 
-    # After a generation: +usage+ is its own server counts (nil: none), for
+    # After a generation: +usage+ is its own server counts ({prompt_tokens:,
+    # total_tokens:, context_window_tokens:}; nil: none), for
     # +prompt_chars+/+image_tokens+ as sent. The next estimate adds only
     # what the turn appended since (answer, tool results), and the status
     # line's value counts the answer. Without counts the pre-generation
@@ -161,21 +162,21 @@ module Samagotchi
     # `window` is this request's ContextWindow::Resolved. A window the
     # stream payload reports itself still wins.
     # +counted+: the prompt the server's prompt_tokens counted ({chars:,
-    # image_tokens:}); what +prompt+ has on top of it (the answer, tool
+    # image_tokens:}); what the prompt has on top of it (the answer, tool
     # results since) is added as an estimate, so the value doesn't read low
     # during a long tool loop. A prompt shorter than that one (trimmed) or
     # none known: the server's count alone.
-    def estimate(prompt, window:, server_usage: nil, image_tokens: 0, counted: nil)
+    def estimate(prompt_chars, window:, server_usage: nil, image_tokens: 0, counted: nil)
       window_source = window.source
       window_source = :server if server_usage && server_usage[:context_window_tokens]
 
       if server_usage && server_usage[:prompt_tokens]
         window_tokens = server_usage[:context_window_tokens] || window.tokens
-        used_tokens = server_usage[:prompt_tokens] + appended_tokens(prompt, image_tokens, counted)
+        used_tokens = server_usage[:prompt_tokens] + appended_tokens(prompt_chars, image_tokens, counted)
         source = "server"
       else
         window_tokens = window.tokens
-        used_tokens = (prompt.length / @chars_per_token).ceil + image_tokens
+        used_tokens = (prompt_chars / @chars_per_token).ceil + image_tokens
         source = "estimate"
       end
 
@@ -191,11 +192,11 @@ module Samagotchi
 
     private
 
-    # The estimate for what +prompt+ added since the +counted+ one.
-    def appended_tokens(prompt, image_tokens, counted)
+    # The estimate for what the prompt added since the +counted+ one.
+    def appended_tokens(prompt_chars, image_tokens, counted)
       return 0 unless counted
 
-      chars = prompt.length - counted[:chars]
+      chars = prompt_chars - counted[:chars]
       return 0 unless chars.positive?
 
       (chars / @chars_per_token).ceil + [image_tokens - counted[:image_tokens].to_i, 0].max

data/lib/samagotchi/empty_answer_retry.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "config"
+require_relative "log"
 require_relative "turn_note"
 
 module Samagotchi
   # Asking the model again, in the same turn, when a generation ends with no
   # visible text and no tool calls (thinking only, or nothing): a hidden
-  # nudge (TurnNote.empty_retry), then another generation. Both loops use
-  # it; the Engine's TurnNote.empty is what's left when the retries run out.
-  module EmptyAnswerRetry
+  # nudge (TurnNote.empty_retry), then another generation. A generation a
+  # plugin cut (stop_generation) spends the same budget with its own nudge.
+  # Both loops keep one per turn; the Engine's TurnNote.empty is what's left
+  # when the retries run out.
+  class EmptyAnswerRetry
     MAX = 3
     # Greedy decoding on a near-identical prompt would likely loop again:
     # the retry runs at this temperature unless one is configured.
@@ -17,10 +20,8 @@ module Samagotchi
     # is retried unless the context is this full.
     CONTEXT_FULL_RATIO = 0.9
 
-    module_function
-
     # retry.empty_answer, 0..MAX.
-    def limit
+    def self.limit
       Config.get("retry.empty_answer").to_i.clamp(0, MAX)
     rescue StandardError
       1
@@ -28,16 +29,74 @@ module Samagotchi
 
     # The request options of a retry generation: the turn's sampling, with
     # TEMPERATURE when it sets none (a configured nil keeps "don't send").
-    def sampling(base)
+    def self.sampling(base)
       base = base || {}
       base.key?(:temperature) ? base : base.merge(temperature: TEMPERATURE)
     end
 
     # The prompt filled the window (a length stop is then no loop to break).
-    def context_full?(used_tokens, window_tokens)
+    def self.context_full?(used_tokens, window_tokens)
       return false unless used_tokens.to_i.positive? && window_tokens.to_i.positive?
 
       used_tokens.to_f / window_tokens >= CONTEXT_FULL_RATIO
     end
+
+    attr_reader :limit
+
+    def initialize(limit: self.class.limit)
+      @limit = limit
+      @attempts = 0
+      @armed = false
+    end
+
+    # An attempt is left.
+    def left? = @attempts < @limit
+
+    # A nudge went out this turn.
+    def used? = @attempts.positive?
+
+    # An empty answer is asked again: an attempt is left, the turn wasn't
+    # cancelled, and the answer wasn't cut short by a full context (a
+    # length stop while thinking is retried: a thinking loop cut by the
+    # output cap, not a full window).
+    def retry_empty?(iteration:, cancelled:, finish_reason: nil, used_tokens: nil, window_tokens: nil)
+      return false if !left? || cancelled
+
+      if finish_reason.to_s == "length" && self.class.context_full?(used_tokens, window_tokens)
+        Log.info(:turn, "empty_answer_not_retried", iteration: iteration, why: "context full")
+        return false
+      end
+      true
+    end
+
+    # Spends an attempt: :empty_answer_retry (with +fields+) goes out, +note+
+    # goes on the tail, and the next request runs at the retry sampling.
+    # Returns true.
+    def nudge!(conversation, note, emit:, iteration:, **fields)
+      @attempts += 1
+      @armed = true
+      emit.call({ type: :empty_answer_retry, iteration: iteration, attempt: @attempts, of: @limit, **fields })
+      conversation << note
+      true
+    end
+
+    # Whether this request is the retry (once per nudge).
+    def take_sampling!
+      armed = @armed
+      @armed = false
+      armed
+    end
+
+    # This request's sampling: the retry's once after a nudge, else +base+.
+    def request_sampling(base)
+      take_sampling! ? self.class.sampling(base) : base
+    end
+
+    # The last spent nudge goes (a retry that failed too: the Engine's
+    # TurnNote.empty says it all).
+    def drop_nudge!(conversation)
+      index = conversation.rindex { |entry| TurnNote.retry_nudge?(entry) }
+      conversation.delete_at(index) if index
+    end
   end
 end

data/lib/samagotchi/engine.rb

@@ -76,20 +76,27 @@ module Samagotchi
     # @param client             [Client, nil] defaults to Client.new
     # @param profile            [ModelProfile, Symbol, String, nil]
     # @param session_id         [String, nil] resume an existing session
-    # @param no_interrupt       [Boolean]
+    # @param no_interrupt       [Boolean] --no-interrupt: every turn runs with
+    #   NO_INTERRUPT_MAX_ITERATIONS, whichever loop runs it
     # @param model_name         [String, nil] defaults from SAMAGOTCHI_DEFAULT_MODEL
+    # @param model_typed        [String, nil] the name the model was given as (a session's
+    #   model_typed: an alias), for the models: lookup; model_name by default
     # @param memories           [Array<String>] explicit --memory preload list (merged with the config.yml `memories:` baseline)
     # @param muted_memories     [Array<String>] --mute list: memories hidden from this session (not in the
     #   prompt's index, dropped from the preloads, refused by memory_read); a mute wins over a preload
     # What memory_write answers in a scratch session.
     SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
+    # A turn's iteration limit with no_interrupt (the worker's own
+    # --no-interrupt turns pass the same).
+    NO_INTERRUPT_MAX_ITERATIONS = 1000
 
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
     def initialize(client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, model_name: nil, memories: [], muted_memories: [], kernel: nil, recap: nil, reminders: nil,
-                   plugins: true, scratch: false)
+                   plugins: true, scratch: false, model_typed: nil)
       @scratch = scratch
+      @no_interrupt = no_interrupt
       @chat_backend = nil
       @chat_backend_mutex = Mutex.new
       @host_registry = host_registry || HostRegistry.new
@@ -106,7 +113,7 @@ module Samagotchi
       # #profile_resolution decides on first need (see there), so building an
       # Engine makes no network call.
       @given_profile = profile ? ModelProfile.normalize(profile) : nil
-      @typed_model_name = @default_model_name
+      @typed_model_name = model_typed.to_s.strip.empty? ? @default_model_name : model_typed.to_s.strip
       @profile_resolution = nil
       # Ensure the built-in system bundle is installed (lazy, warn-only).
       # This is the single seam for both TUI and non-TUI (web/worker) paths.
@@ -196,11 +203,10 @@ module Samagotchi
       @reminders = build_reminders(auto_turn_callback: callback)
       # Track whether this is the first turn in the session (for session_start event)
       @first_turn = true
-      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, no_interrupt: no_interrupt, hooks: @hooks, reminder_store: @reminder_store,
+      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, hooks: @hooks, reminder_store: @reminder_store,
                                          tools: @tools)
       sync_kernel_client!
-      @model_key = ModelOverlay.key_for(bare_model_name(@effective_model_name))
-      @kernel.sync_model_key!(@model_key) if @kernel.respond_to?(:sync_model_key!)
+      sync_model_key!
       # The mutes never change during a session, so no re-sync: the kernel's
       # memory_read guard reads the same list for every turn.
       @muted_memory_names = MutedMemories.normalize_list(muted_memories)
@@ -426,7 +432,30 @@ module Samagotchi
 
     # @return [SessionMetrics] the per-session analytics collector
     attr_reader :metrics
-    attr_reader :default_model_name, :effective_model_name
+    # effective_model_name: the model as given (maybe an alias; HostRegistry#resolve
+    # applies it); typed_model_name: as typed at start or at the last /model.
+    attr_reader :default_model_name, :effective_model_name, :typed_model_name
+
+    # The resolved ref a session stores for the effective model (ModelRef#ref:
+    # the alias applied, "host:id" when it names a host).
+    def effective_model_ref
+      model_ref_for(@effective_model_name)
+    end
+
+    # +name+'s resolved ref (ModelRef#ref).
+    def model_ref_for(name)
+      @host_registry.model_ref(name).ref
+    end
+
+    # Writes the effective model to +session+: the resolved ref, and the
+    # name as typed when that differs (model_typed: an alias, for the
+    # models: lookup after a resume).
+    def store_model!(session)
+      ref = effective_model_ref
+      session.model_name = ref
+      session.model_typed = @typed_model_name.to_s == ref ? nil : @typed_model_name if session.respond_to?(:model_typed=)
+      session
+    end
 
     # The effective model's key (ModelOverlay.key_for its bare name): memory
     # overlays, guardrail rules' models:.
@@ -453,10 +482,23 @@ module Samagotchi
     #   built-ins, and the ones bundle plugins add
     attr_reader :command_registry
 
+    # The model id sent for +full_ref+ (its alias applied, the host prefix off).
     def bare_model_name(full_ref)
       @host_registry.bare_name(full_ref)
     end
 
+    # The memory overlay key follows the model sent (ModelOverlay.key_for
+    # its id). A model typed as an alias used to key overlays by the alias
+    # (before aliases were applied there): that key is read when the
+    # target's overlay is missing (KernelLoop#sync_model_key!).
+    def sync_model_key!
+      @model_key = ModelOverlay.key_for(bare_model_name(@effective_model_name))
+      typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(@typed_model_name).last)
+      fallback = typed_key == @model_key ? nil : typed_key
+      @kernel.sync_model_key!(@model_key, fallback: fallback) if @kernel.respond_to?(:sync_model_key!)
+    end
+    private :sync_model_key!
+
     # The effective model's bare name for the guardrails' models: rules;
     # nil without a model name.
     def guardrail_model_name
@@ -762,27 +804,29 @@ module Samagotchi
 
     # ── Model switching ────────────────────────────────────────────────────────
 
-    def switch_model!(model_name, persist_default: false)
-      # Resolve alias first (alias may point to qualified ref)
-      aliased = ConfigFile.resolve_model_alias(model_name)
-      resolved = ModelProfile.check_host!(ModelProfile.required_model_name(aliased), hosts: @host_registry.entries)
+    # @param typed [String, nil] the name the model was typed as when
+    #   +model_name+ is a stored ref (a resumed session's model_typed)
+    # @return [String] the resolved ref the session stores (ModelRef#ref)
+    def switch_model!(model_name, persist_default: false, typed: nil)
+      # The alias is applied where the model is resolved (HostRegistry#resolve),
+      # once; checked here: an unknown host, an alias naming another host.
+      resolved = ModelProfile.check_host!(ModelProfile.required_model_name(model_name), hosts: @host_registry.entries)
       @effective_model_name = resolved
-      bare = bare_model_name(resolved)
-      @typed_model_name = model_name
+      @typed_model_name = typed.to_s.strip.empty? ? model_name : typed.to_s.strip
       # A profile given to .new was for the starting model.
       @given_profile = nil
       @profile_resolution = nil
-      @model_key = ModelOverlay.key_for(bare)
-      @kernel.sync_model_key!(@model_key) if @kernel.respond_to?(:sync_model_key!)
+      sync_model_key!
       @prompt_builder.reset!
       sync_kernel_client!
       @client.invalidate_context_window! if @client.respond_to?(:invalidate_context_window!)
       @metrics.forget_model_reports!
+      ref = effective_model_ref
       if persist_default
-        ConfigFile.write_default_model!(resolved)
-        @default_model_name = resolved
+        ConfigFile.write_default_model!(ref)
+        @default_model_name = ref
       end
-      resolved
+      ref
     end
 
     # ── Hooks API ──────────────────────────────────────────────────────────────
@@ -968,7 +1012,7 @@ module Samagotchi
         preloaded_memory_names: preloaded_memory_names,
         muted_memory_names: @muted_memory_names.dup,
         parent_id: @session&.parent_id,
-        model_name: @effective_model_name,
+        model_name: effective_model_ref,
         served_model: served_pair[0],
         served_model_for: served_pair[1],
         context_status: @last_context_status&.dup || saved_context_status(metrics[:context]),
@@ -1580,7 +1624,7 @@ module Samagotchi
 
         result = backend.complete(
           messages: messages,
-          max_iterations: max_iterations,
+          max_iterations: @no_interrupt ? NO_INTERRUPT_MAX_ITERATIONS : max_iterations,
           on_stream_event: build_stream_event_handler(on_event, cancel_controller: effective_controller),
           cancel_controller: effective_controller,
           model_name: bare_for_backend,