ollama_chat 0.0.134 → 0.0.136

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: affb84ab9e8755cad2b29f047efccc92a9483c155889075b4ee001cf58935f2c
-  data.tar.gz: 6e50f2280a13eb4d43cc702b750e2b649c7481d8a49337ebc86b0a5c4a70c6e3
+  metadata.gz: e22822d0b02f1f0dad3fe7e9b2902fc727a6dc2d13ffcd192da3fda3980fdefc
+  data.tar.gz: 2bb58b895a48bceefb16600def20f1ea8bb16deeeabd4a307f7fea27749a9139
 SHA512:
-  metadata.gz: 8e571cba1334e97fe44c0c102414d7fd61ab8ffe6ef3d1c68c73b18359e139a7fd143d140c6e291bb1bcc46adcebb0bc014f20469d8889519d3b2b0ac3ca6e75
-  data.tar.gz: 74ac387728f8dbe3a7b176ebf578b9bd1fdcabdfc7557f0858c5a78021aa596145b59f104b047ceb5fb0c3b73eea69242fd6d16b5c6a87c476db21db33fdec08
+  metadata.gz: 41e74251f4318137993e985f97beba5626b9d200b460d827ce04bddfb6dc316df6dae2d78024dd1c7d4486f3b7f4f7febd4e38d666fdf1e5f00f0e3e246b7c70
+  data.tar.gz: 1cd96acf7bca275337aaaad85c41d65c2bd75101ccfa1f0924d72eda254f4fffe04c019c9c2ee12285df6ea2e91da96cf702753059c0a7e7d7aa4bde8c13b0f4

data/CHANGES.md

@@ -1,5 +1,126 @@
 # Changes
 
+## 2026-10-21 v0.0.136
+
+### Features
+
+- Added a `machine` key to the static runtime information, injecting a compact
+  host description into the system prompt via a new `machine_profile` method in
+  `information.rb`.
+- Introduced a new `OC::FASTFETCH` configuration option to resolve the
+  `fastfetch` executable path.
+- Added a new `fastfetch-profile.jsonc` configuration file to define the
+  modules used for the machine profile.
+- Added `always-allow` and `direct` modes to the `execute_shell` tool, allowing
+  users to remember command approvals for the session.
+- Extended the `execute_shell` confirmation prompt to include `a` (always allow
+  with pager) and `d` (always allow direct to `STDOUT`) options.
+
+### Fixes
+
+- Updated the `kramdown_ansi` table separator spec to use pipe-bounded syntax
+  (`| Name | Age |`) to align with `kramdown-ansi` **0.6** requirements,
+  preventing literal dashes from leaking into the output.
+- Renamed the `/last` command option from `-p` to `-d` for consistency with the
+  `execute_shell` direct mode flag.
+
+### Improvements
+
+- Refactored `execute_shell` output display to use a shared `write_output`
+  helper for both pager and direct output paths.
+- Updated the `execute_shell` tool description to document the new
+  `always-allow` and `direct` options.
+
+### Build & CI
+
+- Updated the `kramdown-ansi` dependency constraint from **0.5** to **0.6** in
+  `Rakefile` and `ollama_chat.gemspec`.
+- Added `lib/ollama_chat/ollama_chat_config/fastfetch-profile.jsonc` to the
+  gemspec files list.
+- Added `git config --global --add safe.directory /work` to the CI test script
+  in `.all_images.yml`.
+
+### Testing
+
+- Added four new specs for `execute_shell` covering `always-allow` and `direct`
+  mode behaviors, including repeat execution and command differentiation.
+- Updated `commands_spec.rb` to reflect the rename of the `/last` command
+  option from `-p` to `-d`.
+- Added a `before` block in `execute_shell_spec.rb` to clear the
+  `always_allowed` hash and prevent cross-spec contamination.
+
+## 2026-10-19 v0.0.135
+
+### Features
+
+- Introduced `OllamaChat::ModelHandling::ModelCache` to manage model metadata
+  and sizes with two-tier storage (names/sizes and full metadata), supporting
+  lazy registration and per-client isolation.
+- Added `-r` flag to the `/model change` command to flush the model cache
+  before re-listing models.
+- Added `OllamaChat::ToolCallProcessor` to encapsulate the tool call lifecycle,
+  including execution, result storage, and draining of results for the chat
+  loop.
+- Enabled searching sessions by ID in the session chooser by including the
+  session ID in the search value.
+
+### Fixes
+
+- Rescued `Ollama::Errors::BadRequestError` in `model_present?` to prevent
+  unhandled exceptions for model names rejected by the server with a 400
+  status.
+- Fixed persona leakage in new sessions by using `config.persona&.default_name`
+  instead of the current session's persona in `Session.with_defaults`.
+- Synchronized session triggers with the active persona via `sync_trigger` in
+  `PersonaeManagement`, ensuring triggers are rekeyed, cleared, or seeded
+  correctly on persona changes.
+
+### Improvements
+
+- Refactored `model_present?` to use the new `ModelCache` instead of an inline
+  hash, improving cache management and reducing repeated API calls.
+- Updated `choose_model` to skip the `all_models` API call if the requested
+  model is already confirmed present via `model_present?`.
+- Renamed the prompt context for report templates from `session` to `report` in
+  `default_config.yml` and `SessionManagement` to better reflect its purpose.
+- Renamed `OllamaChat::Database::SessionLocking` to
+  `OllamaChat::Database::RowLocking` to reflect its generic row-level locking
+  behavior, removing the `chat:` keyword argument from `lock?` and moving
+  feedback emission to the caller.
+- Replaced `Kramdown::ANSI::Width.truncate` and `Kramdown::ANSI::Width.wrap`
+  with bare `truncate` and `wrap` in multiple modules where ANSI sequences are
+  not present at measurement time.
+- Truncated session names in the `/sessions` list to fit terminal width,
+  preventing long names from wrapping or pushing metadata off-screen.
+- Decoupled `model_with_size` from the `Ollama::Tag` shape, now accepting model
+  name and size directly.
+
+### Build & CI
+
+- Updated `gem_hadar` development dependency to **2.20.1**.
+- Regenerated gem metadata to include new files (`tool_call_processor.rb`,
+  `model_cache.rb`, `row_locking.rb`) and updated file lists.
+
+### Testing
+
+- Added `spec/ollama_chat/model_handling/model_cache_spec.rb` with 18 examples
+  covering cache operations, lazy registration, per-instance isolation, and
+  flushing.
+- Added `spec/ollama_chat/personae_management_spec.rb` with 5 examples covering
+  `sync_trigger` state transitions.
+- Added `spec/ollama_chat/tool_call_processor_spec.rb` covering `drain`,
+  `clear!`, and result storage.
+- Updated `spec/ollama_chat/commands_spec.rb` to test the `-r` flag for `/model
+  change`.
+- Updated `spec/ollama_chat/session_management_spec.rb` to verify persona and
+  trigger behavior in new and duplicated sessions, and adjusted lock
+  expectations.
+- Updated `spec/ollama_chat/information_spec.rb` to reflect the correct persona
+  display after initialization.
+- Removed `#handle_tool_call_results?` tests from
+  `spec/ollama_chat/tool_calling_spec.rb` as the method was moved to
+  `ToolCallProcessor`.
+
 ## 2026-10-17 v0.0.134
 
 * Removed the local dependency on the `ollama-ruby` gem from the `Gemfile`.

data/Rakefile

@@ -47,7 +47,7 @@ GemHadar do
   dependency             'redis',                 '~> 5.0'
   dependency             'mime-types',            '~> 3.0'
   dependency             'reverse_markdown',      '~> 3.0'
-  dependency             'kramdown-ansi',         '~> 0.5'
+  dependency             'kramdown-ansi',         '~> 0.6'
   dependency             'complex_config',        '~> 0.22', '>= 0.22.2'
   dependency             'tins',                  '~> 1.61'
   dependency             'search_ui',             '>= 0.2'

data/lib/ollama_chat/chat.rb

@@ -116,6 +116,7 @@ class OllamaChat::Chat
     setup_switches
     setup_session
     setup_state_selectors(config)
+    @model_cache = ModelCache.new
     connect_ollama
     connect_embedding_ollama
     @documents = setup_documents
@@ -123,7 +124,7 @@ class OllamaChat::Chat
     @cache                = setup_cache
     @images               = []
     @kramdown_ansi_styles = configure_kramdown_ansi_styles
-    @tool_call_results    = Hash.new { |h, name| h[name] = [] }
+    @tool_call_processor  = OllamaChat::ToolCallProcessor.new(chat: self)
     setup_personae_directory
     @opts[?S] and init_server_socket
   rescue ComplexConfig::AttributeMissing, ComplexConfig::ConfigurationSyntaxError => e
@@ -166,6 +167,11 @@ class OllamaChat::Chat
   # @return [OllamaChat::RedisCache, nil] the cache instance
   attr_reader :cache
 
+  # The model_cache method provides read-only access to the model cache.
+  #
+  # @return [ ModelCache ] the model cache instance
+  attr_reader :model_cache
+
   # Returns the voice handler class based on the configuration.
   #
   # This method resolves the voice handler class specified in the config.
@@ -341,6 +347,12 @@ class OllamaChat::Chat
     "#<#{self.class}: #{base_url.to_s}>"
   end
 
+  # Returns the tool call processor instance.
+  #
+  # @return [OllamaChat::ToolCallProcessor] the processor that handles
+  #   tool execution and result storage
+  attr_reader :tool_call_processor
+
   private
 
   # Wrapper for ollama.chat to provide consistent logging of all arguments.
@@ -462,7 +474,7 @@ class OllamaChat::Chat
       type         = :terminal_input
       input_prompt = bold { color(172) { message_type(@images) + " user" } } + bold { "> " }
       begin
-        tools_were_called = handle_tool_call_results? { |index, tool_name, content|
+        tools_were_called = tool_call_processor.drain { |index, tool_name, content|
           messages << OllamaChat::Message.new(
             role:        'user', # XXX this should be 'tool' but it doesn't currently seem to work in Ollama API
             sender_name: tool_name,

data/lib/ollama_chat/commands.rb

@@ -285,15 +285,15 @@ module OllamaChat::Commands
 
   command(
     name: :last,
-    regexp:  %r(^/last((?:\s+(?:-[ptsv]))*)(?:\s+(\d*))?$),
-    options: '[-p|-t|-s|n=1]',
+    regexp:  %r(^/last((?:\s+(?:-[dtsv]))*)(?:\s+(\d*))?$),
+    options: '[-d|-t|-s|n=1]',
     help: <<~EOT
       🔍 Show or speak last message(s)
-         Options: -p (plain), -t (show thinking),
-                  -s (hide thinking) -v (voice output)
+          Options: -d (direct), -t (show thinking),
+                   -s (hide thinking) -v (voice output)
     EOT
   ) do |opts,number|
-    opts = go_command('ptsv', opts.to_s)
+    opts = go_command('dtsv', opts.to_s)
     n    = number.to_i.clamp(1..)
     if opts[?v]
       messages.speak_last(n)
@@ -306,7 +306,7 @@ module OllamaChat::Commands
         else
           self.think_loud.on?
         end
-      messages.show_last(n, think_loud:, pager: !opts[?p])
+      messages.show_last(n, think_loud:, pager: !opts[?d])
     end
     :next
   end
@@ -552,12 +552,12 @@ module OllamaChat::Commands
 
   command(
     name: :model,
-    regexp: %r(^/model(?:\s+(change|options(?: copy| delete| export| import)?|options from session|options to session))?((?:\s+(?:-m|-p\s+[\S]+))*)$),
+    regexp: %r(^/model(?:\s+(change|options(?: copy| delete| export| import)?|options from session|options to session))?((?:\s+(?:-m|-r|-p\s+[\S]+))*)$),
     complete: [ 'model', %w[ change options options\ copy options\ delete options\ export options\ import options\ from\ session options\ to\ session ] ],
-    options: '[-m|-p pattern]',
+    options: '[-m|-r|-p pattern]',
     help: <<~EOT
       🤖 Manage AI models & profiles:
-         - change: Switch active model
+         - change: Switch active model (-r to refresh)
          - options: Edit saved profile config
          - options copy: Copy profile from another model
          - options delete: Delete a saved profile
@@ -565,11 +565,14 @@ module OllamaChat::Commands
          - options import: Selectively import profiles from JSON
          - options from session: Save live → Saved
          - options to session: Apply Saved → Live
-         -m interactively choose a model
-         -p PATTERN narrow file search for import
+           -m interactively choose a model
+           -r  refresh model list (flush cache)
+           -p PATTERN narrow file search for import
     EOT
   ) do |subcommand, opts|
     if subcommand == 'change'
+      opts = go_command('mr', opts)
+      @model_cache.flush if opts[?r]
       begin
         model   = choose_model('', @model)
         profile = choose_profile_for_model(model) || 'default'

data/lib/ollama_chat/database/models/session.rb

@@ -5,7 +5,7 @@
 # the JSON serialization of complex attributes such as `tools_default_enabled`
 # and `model_options`.
 class OllamaChat::Database::Models::Session < Sequel::Model(OllamaChat::DB)
-  include OllamaChat::Database::SessionLocking
+  include OllamaChat::Database::RowLocking
   include OllamaChat::Database::Duplicatable
 
   plugin :timestamps, update_on_create: true
@@ -200,7 +200,7 @@ class OllamaChat::Database::Models::Session < Sequel::Model(OllamaChat::DB)
       name:                     ,
       current_model:            ,
       current_collection:       chat.initial_collection,
-      default_persona_name:     chat.initial_persona_name,
+      default_persona_name:     chat.config.persona&.default_name,
       current_system_prompt:    chat.initial_system_prompt,
       tools_enabled:            chat.config.tools.enabled,
       tools_default_enabled:    ,

data/lib/ollama_chat/database/{session_locking.rb → row_locking.rb}

@@ -1,15 +1,15 @@
-# The SessionLocking module provides a mechanism for exclusive session access,
+# The RowLocking module provides a mechanism for exclusive row access,
 # similar to the swap-file locking used by Vim.
 #
 # It prevents multiple concurrent instances of the application from modifying
-# the same session, thereby avoiding race conditions and context collision.
+# the same database row, thereby avoiding race conditions and state collision.
 # The lock is based on the Process ID (PID) and is validated by checking if
 # the owning process is still active on the system.
 #
-# This module is intended to be mixed into models that persist session state,
-# such as OllamaChat::Database::Models::Session.
-module OllamaChat::Database::SessionLocking
-  # Checks if the session is currently locked by an active process.
+# This module is intended to be mixed into any Sequel model that has a
+# `locked_by_pid` column.
+module OllamaChat::Database::RowLocking
+  # Checks if the row is currently locked by an active process.
   #
   # @return [Integer, nil] the PID of the locking process if active, or nil if unlocked/stale.
   def locked?
@@ -23,17 +23,12 @@ module OllamaChat::Database::SessionLocking
     end
   end
 
-  # Attempts to acquire a lock on the session.
+  # Attempts to acquire a lock on the row.
   #
-  # @param chat [OllamaChat] the chat instance that receives feedback
   # @return [Boolean] true if the lock was successfully acquired, false if already locked.
-  def lock?(chat:)
-    if running_pid = locked?
-      chat.feedback("session #{id} locked by running process #{running_pid}", type: :warn)
-      false
-    else
-      lock
-    end
+  def lock?
+    return false if locked?
+    !!lock
   end
 
   # Sets the lock for the current process.
@@ -43,7 +38,7 @@ module OllamaChat::Database::SessionLocking
     update(locked_by_pid: $$)
   end
 
-  # Releases the lock on the session.
+  # Releases the lock on the row.
   #
   # @return [Boolean] true if the update was successful.
   def unlock

data/lib/ollama_chat/database.rb

@@ -51,4 +51,4 @@ module OllamaChat::Database
   end
 end
 require 'ollama_chat/database/duplicatable'
-require 'ollama_chat/database/session_locking'
+require 'ollama_chat/database/row_locking'

data/lib/ollama_chat/follow_chat.rb

@@ -89,147 +89,13 @@ class OllamaChat::FollowChat
 
     output_eval_stats(response)
 
-    handle_tool_calls(response)
+    chat.tool_call_processor.handle(response)
 
     self
   end
 
   private
 
-  # The handle_tool_calls method processes tool calls from a response and
-  # executes them.
-  #
-  # This method checks if the response contains tool calls, and if so, iterates
-  # through each tool call to execute the corresponding tool from the
-  # registered tools. The results of the tool execution are stored in the
-  # chat's tool_call_results hash using the tool name as the key.
-  #
-  # @param response [Object] the response object containing tool calls to
-  #   process
-  def handle_tool_calls(response)
-    return unless response.message.ask_and_send(:tool_calls)
-
-    tools_used = {}
-
-    response.message.tool_calls.each do |tool_call|
-      name = tool_call.function.name
-      if %r(.*[/:](?<new_name>.+)) =~ name
-        msg = "Received namespaced tool call for #{name}, correcting to #{new_name}"
-        chat.log(:warn, msg, data: { tool: name, new_name: })
-        name = new_name
-      end
-      unless chat.tool_configured?(name)
-        msg = "Error: Unconfigured tool named %s ignored => Skip.\n" % name
-        chat.tool_call_results[name] << msg
-        chat.log(:error, msg, data: { tool: name, reason: :unconfigured })
-        next
-      end
-      unless chat.tool_registered?(name)
-        msg = "Error: Unregistered tool named %s ignored => Skip.\n" % name
-        chat.tool_call_results[name] << msg
-        chat.log(:error, msg, data: { tool: name, reason: :unregistered })
-        next
-      end
-      unless chat.tool_enabled?(name)
-        msg = "Error: Disabled tool named %s ignored => Skip.\n" % name
-        chat.tool_call_results[name] << msg
-        chat.log(:error, msg, data: { tool: name, reason: :disabled })
-        next
-      end
-      feedback(?\n, output:)
-      confirmed = :implicit
-      resolve   = nil
-      function  = JSON.pretty_generate(tool_call.function)
-      chat.log(:info, "Tool call received", data: { tool: name, function: })
-      if chat.tool_function(name).require_confirmation?
-        feedback(
-          ("I want to execute tool %s\n%s\n" % [ bold { name }, italic { function }, ]),
-          type: :alarm
-        )
-        prompt  = '❓ Allow ✅[y]es / ⛔️[n]o / 📝[i]nstruct? '
-        answer  = chat.confirm?(prompt:)&.to_s&.downcase
-        resolve = 'You **MUST** ask the user for instructions on how to proceed!!!'
-        case answer
-        when 'y'
-          confirmed = :explicit
-        when 'n'
-          confirmed = :denied
-        else
-          confirmed = :denied
-          instr     = chat.ask?(prompt: '📝 Instructions: ')&.strip
-          resolve   = instr.full? ||  resolve
-        end
-      else
-        feedback(
-          "Executing tool %s\n%s" % [ bold { name }, italic { function }, ]
-        )
-      end
-      start  = Time.now
-      result = nil
-      case confirmed
-      when :denied
-        result = JSON(message: 'User denied confirmation!', resolve:)
-        feedback(?\n)
-        feedback(
-          ("Execution of tool %s denied by user.\n\n" % [ bold { name } ]),
-          type: :denied
-        )
-        chat.log(:warn, "Tool execution denied", data: { tool: name, reason: :denied })
-      else
-        symbol = confirmed == :implicit ? '☑️ ' : '✅'
-        feedback(
-          ("\n%s Execution of tool %s confirmed.\n\n" % [ symbol, bold { name } ])
-        )
-        result = OllamaChat::Tools.registered_tool(name, chat:).execute(tool_call)
-        chat.log(:info, "Tool execution confirmed", data: { tool: name, confirmed: })
-      end
-
-      chat.tool_call_results[name] << result
-      data    = nil
-      message = begin
-                   data = JSON.parse(result)
-                   chat.log(:info, "Tool result", data: { result: data })
-                   data.to_hash['message'] if data.respond_to?(:to_hash)
-                 rescue
-                   chat.log(:info, "Tool result", data: { result: })
-                   nil
-                 end
-      warn =
-        begin
-          !!data.ask_and_send(:[], 'error') || data.ask_and_send(:[], 'success') == false
-        rescue
-          false
-        end
-
-      es = OllamaChat::TokenEstimator.estimate(result.to_s)
-
-      tools_used[name] = {
-        message:,
-        warn:     ,
-        size:     es.bytes_formatted,
-        tokens:   es.tokens_formatted,
-        duration: Tins::Duration.new(Time.now - start).to_s,
-      }
-    end
-
-    if tools_used.full?
-      infobar.reset
-      tools_used.each do |name, info|
-        feedback_message =
-          if info[:message]
-            "\n%s %s\n\n" % [ info[:warn] ? '⚠️' : '💡', info[:message] ]
-          end
-        feedback(<<~EOT.strip)
-          🔧 Tool functions #{name} returned result (#{info[:size]}/#{info[:tokens]} in #{info[:duration]}).
-          #{feedback_message}
-        EOT
-        feedback(?\n)
-        timeout = chat.tool_function(name).result_display_timeout?
-        chat.confirm?(prompt: '⏎  Press any key to continue (%s). ', timeout:)
-      end
-    end
-  end
-
   # The truncate_for_terminal method processes text to fit within a specified
   # number of lines.
   #

data/lib/ollama_chat/information.rb

@@ -74,7 +74,7 @@ module OllamaChat::Information
   def collection_stats(output: STDOUT)
     col          = database_collection?(collection)
     length       = (Tins::Terminal.cols - 10).clamp(0..)
-    wrapped_tags = Kramdown::ANSI::Width.
+    wrapped_tags =
       wrap(@documents.tags.to_a.join(', '), length:).
       gsub(/(?<!\A)^/, ' ' * 4)
     output.puts <<~EOT
@@ -341,6 +341,7 @@ module OllamaChat::Information
       current_directory:    Pathname.pwd.expand_path.to_path,
       languages:            config.languages * ', ',
       location:             location.on?.full? { location_description } || 'n/a',
+      machine:              machine_profile || 'n/a',
       user:                 ,
     }
   end
@@ -474,6 +475,63 @@ module OllamaChat::Information
 
   private
 
+  # Builds and caches a compact, single-line description of the host
+  # machine, derived from a `fastfetch` run against the bundled profile
+  # (+OC::FASTFETCH+). The profile requests a focused set of modules
+  # (os, kernel, cpu, gpu, de, wm, terminal, memory, editor, packages,
+  # chassis, board, bios) so the result stays small enough to inject into
+  # the system prompt at zero per-turn cost.
+  #
+  # Gracefully degrades to `'n/a'` when +fastfetch+ is not installed or
+  # the config is missing, so a missing optional dependency never breaks
+  # session startup.
+  #
+  # @return [String] e.g.
+  #   `C64 1541 (c64) · 6502@1MHz m64 · MOS Technology 6502 ·
+  #    NVIDIA GeForce RTX 5090 (32GB) · VIC-II (no DE) · Home Computer ·
+  #    PET2001N-Board · MOS 3.0 UEFI 4000 · 64 KiB · vim 1.0 · 1 pkgs`
+  def machine_profile
+    return @machine_profile if defined?(@machine_profile)
+    @machine_profile = nil
+    unless fastfetch = OC::FASTFETCH?
+      log(:warn, 'Fastfetch executable not found, skipping machine profile!')
+      return
+    end
+    config = Shellwords.escape(File.join(__dir__, 'ollama_chat_config', 'fastfetch-profile.jsonc'))
+    out = `#{fastfetch} -c #{config} --format json 2>/dev/null`.full? or return
+    mods = JSON.parse(out, object_class: JSON::GenericObject)
+    @machine_profile =
+      mods.map do |m|
+        r = m.result or next
+        case m.type
+        when 'OS'
+          "%s %s (%s)" % [ r.name, r.versionID, r.idLike ]
+        when 'Kernel'
+          "%s %s" % [ r.release, r.architecture ]
+        when 'CPU'
+          r.cpu
+        when 'GPU'
+          (r.find { _1.type == 'Discrete' } || r.first)&.name
+        when 'WM'
+          suffix = mods.any? { _1.type == 'DE' && _1.result } ? '' : ' (no DE)'
+          "%s/%s%s" % [ r.processName, r.protocolName, suffix ]
+        when 'Memory'
+          format_bytes(r.total)
+        when 'Editor'
+          "%s %s" % [ r.exe, r.version ]
+        when 'Packages'
+          "%s pkgs" % r.all
+        when 'Chassis'
+          r.type
+        when 'Board'
+          r.name
+        when 'BIOS'
+          "%s %s" % [ r.type, r.version ]
+        end
+      end.compact * ' · '
+  rescue JSON::ParserError
+  end
+
   # Lazily builds and caches the {ContextUsage} bound to this chat,
   # which owns the ANSI/emoji presentation logic for context usage.
   #

data/lib/ollama_chat/model_handling/model_cache.rb

@@ -0,0 +1,106 @@
+module OllamaChat::ModelHandling
+  # Caches model metadata for one or more Ollama instances.
+  #
+  # This class provides a simple in-memory cache to store and retrieve
+  # model metadata, reducing the need for repeated `ollama show` calls.
+  # It supports multiple Ollama instances by using the instance's
+  # object ID as part of the cache key.
+  class ModelCache
+    # Initializes a new model cache.
+    def initialize
+      @models     = Hash.new { |h, k| h[k] = {} }
+      @sizes      = Hash.new { |h, k| h[k] = {} }
+      @registered = Hash.new(false)
+    end
+
+    # Caches model metadata (and optionally size) for a given Ollama
+    # instance and model name.
+    #
+    # Existing metadata is never overwritten (`||=`); only missing
+    # entries are filled in. Size, when provided, overwrites unconditionally.
+    #
+    # @param ollama [Ollama::Client] the Ollama client instance
+    # @param name [String, Symbol] the model name
+    # @param value [ModelMetadata, nil] the metadata to cache (defaults to nil)
+    # @param size [Integer, nil] the model size in bytes (optional)
+    # @return [ModelMetadata, nil] the cached metadata
+    def cache(ollama, name, value = nil, size: nil)
+      name = name.to_s
+      @models[ollama.__id__][name]         ||= value
+      size and @sizes[ollama.__id__][name]   = size
+      @models[ollama.__id__][name]
+    end
+
+    # Returns the cached `ModelMetadata` for a given model, if it has
+    # been fetched. Note: this is a *metadata* predicate, not an
+    # existence check. A model can be registered (via `models`) and
+    # have a size, yet still return `nil` here until metadata is
+    # explicitly cached (e.g. by `model_present?`).
+    #
+    # @param ollama [Ollama::Client] the Ollama client instance
+    # @param name [String, Symbol] the model name
+    # @return [ModelMetadata, nil] the metadata if fetched, nil otherwise
+    def cached?(ollama, name)
+      name = name.to_s
+      @models[ollama.__id__][name]
+    end
+
+    # Returns the cached size in bytes for a given model.
+    #
+    # @param ollama [Ollama::Client] the Ollama client instance
+    # @param name [String, Symbol] the model name
+    # @return [Integer] the size in bytes, 0 if not cached
+    def model_size(ollama, name)
+      @sizes[ollama.__id__][name].to_i
+    end
+
+    # Returns a list of cached model names for the given Ollama instance.
+    #
+    # @param ollama [Ollama::Client] the Ollama client instance
+    # @return [Array<String>] the cached model names
+    def models(ollama)
+      registered?(ollama) or register_all(ollama)
+      @models[ollama.__id__].keys
+    end
+
+    # Flushes cached metadata and sizes for one or all Ollama instances.
+    #
+    # @param ollama [Ollama::Client, Integer, nil] an Ollama client instance,
+    #   a raw object ID, or `nil` to flush all instances (default: nil)
+    # @return [true]
+    def flush(ollama = nil)
+      if ollama
+        ollama_id = ollama.ask_and_send(:to_int) || ollama.__id__
+        @models[ollama_id].clear
+        @sizes[ollama_id].clear
+        @registered[ollama_id] = false
+      else
+        @models.each_key { |ollama_id| flush(ollama_id) }
+      end
+      true
+    end
+
+    private
+
+    # Checks whether model registration has been completed for the instance.
+    #
+    # @param ollama [Ollama::Client] the Ollama client instance
+    # @return [Boolean]
+    def registered?(ollama)
+      @registered[ollama.__id__]
+    end
+
+    # Registers multiple model names as cached for the given Ollama instance.
+    #
+    # @param ollama [Ollama::Client] the Ollama client instance
+    #
+    # @return [ ModelCache ] this cache instance
+    def register_all(ollama)
+      ollama.tags.models.each do |model|
+        cache(ollama, model.name, size: model.size)
+      end
+      @registered[ollama.__id__] = true
+      self
+    end
+  end
+end