feat(provider): advanced model caching to prevent fetching models every time.

* Remove deprecated tests

* Remove providers for the sake of config provider setup

* Current state of providers v2

* Make more robust

* docs: update provider examples in readme

* Remove thinking stuff and prepare for new solution

* Fix test and bug

* Attempt to fix pipeline

* Rename provider

- fix tests
- add new checks to verify provider configs

* Polish multi provider

* feat: online model caching with fallback to pre-defined models

* Add model cache expiration config to readme

* Move import to top

* Use logger and add todo

Author: frankroeder

README.md

@@ -373,6 +373,10 @@ to consider a visual selection within an API request.
     -- if false it also frees up the buffer cursor for further editing elsewhere
     command_auto_select_response = true,
 
+    -- Time in hours until the model cache is refreshed
+    -- Set to 0 to deactive model caching
+    model_cache_expiry_hours = 48,
+
     -- fzf_lua options for PrtModel and PrtChatFinder when plugin is installed
     fzf_lua_opts = {
         ["--ansi"] = true,

lua/parrot/chat_handler.lua

@@ -1176,10 +1176,19 @@ function ChatHandler:model(params)
   local has_fzf, fzf_lua = pcall(require, "fzf-lua")
   local has_telescope, telescope = pcall(require, "telescope")
 
+  -- Get models with caching support
+  local models
+  if prov:online_model_fetching() and self.options.model_cache_expiry_hours > 0 then
+    local spinner = self.options.enable_spinner and Spinner:new(self.options.spinner_type) or nil
+    models = prov:get_available_models_cached(self.state, self.options.model_cache_expiry_hours, spinner)
+  else
+    models = prov:get_available_models()
+  end
+
   if model_name ~= "" then
     self:switch_model(is_chat, model_name, prov)
   elseif has_fzf then
-    fzf_lua.fzf_exec(prov:get_available_models(), {
+    fzf_lua.fzf_exec(models, {
       prompt = "Model selection ❯",
       fzf_opts = self.options.fzf_lua_opts,
       actions = {
@@ -1203,7 +1212,7 @@ function ChatHandler:model(params)
       .new({}, {
         prompt_title = "Model selection",
         finder = finders.new_table({
-          results = prov:get_available_models(),
+          results = models,
         }),
         sorter = sorters.values.generic_sorter({}),
         attach_mappings = function(_, map)
@@ -1225,7 +1234,7 @@ function ChatHandler:model(params)
       })
       :find()
   else
-    vim.ui.select(prov:get_available_models(), {
+    vim.ui.select(models, {
       prompt = "Select your model:",
     }, function(selected_model)
       self:switch_model(is_chat, selected_model, prov)

lua/parrot/config.lua

@@ -1,5 +1,8 @@
 local ChatHandler = require("parrot.chat_handler")
 local init_provider = require("parrot.provider").init_provider
+local utils = require("parrot.utils")
+local Spinner = require("parrot.spinner")
+local State = require("parrot.state")
 
 local M = {
   ui = require("parrot.ui"),
@@ -56,6 +59,7 @@ local defaults = {
   style_popup_max_width = 160,
   command_prompt_prefix_template = "🤖 {{llm}} ~ ",
   command_auto_select_response = true,
+  model_cache_expiry_hours = 48,
   fzf_lua_opts = {
     ["--ansi"] = true,
     ["--sort"] = "",
@@ -282,17 +286,46 @@ function M.setup(opts)
 
   M.available_providers = vim.tbl_keys(M.providers)
 
+  -- Initialize state early to enable caching
+  local temp_state = State:new(M.options.state_dir)
+
+  -- Clean up cache for removed providers
+  temp_state:cleanup_cache(M.available_providers)
+
   local available_models = {}
+
+  -- Check each provider individually and fetch models
   for _, prov_name in ipairs(M.available_providers) do
     -- Create the new provider config format
     local provider_config = vim.tbl_deep_extend("force", {
       name = prov_name,
     }, M.providers[prov_name])
     local _prov = init_provider(provider_config)
 
-    -- do not make an API call on startup
-    available_models[prov_name] = _prov.models -- or _prov:get_available_models()
+    -- Use cached model fetching if provider has model_endpoint
+    if _prov:online_model_fetching() and M.options.model_cache_expiry_hours > 0 then
+      -- Check cache validity for this specific provider
+      local endpoint_hash = utils.generate_endpoint_hash(_prov)
+      local needs_update = not temp_state:is_cache_valid(prov_name, M.options.model_cache_expiry_hours, endpoint_hash)
+
+      -- Show spinner only for this provider if needed
+      local spinner = nil
+      if needs_update and M.options.enable_spinner then
+        spinner = Spinner:new(M.options.spinner_type)
+        M.logger.info("Updating model cache for " .. prov_name)
+      end
+
+      available_models[prov_name] =
+        _prov:get_available_models_cached(temp_state, M.options.model_cache_expiry_hours, spinner)
+    else
+      -- Fall back to static models for providers without model_endpoint
+      available_models[prov_name] = _prov.models
+    end
   end
+
+  -- Now refresh the state with all available models
+  temp_state:refresh(M.available_providers, available_models)
+
   M.available_models = available_models
 
   table.sort(M.available_providers)
@@ -382,7 +415,12 @@ M.add_default_commands = function(commands, hooks, options)
             return completions[cmd]
           end
           if cmd == "Model" then
-            return M.available_models[M.chat_handler.state:get_provider()]
+            -- TODO: Should detect the respective mode --
+            local current_provider = M.chat_handler.state:get_provider(true) -- Use chat provider by default
+            if current_provider and M.available_models[current_provider] then
+              return M.available_models[current_provider]
+            end
+            return {}
           elseif cmd == "Provider" then
             return M.available_providers
           end

lua/parrot/provider/multi_provider.lua

@@ -238,6 +238,10 @@ function MultiProvider:new(config)
   return self
 end
 
+function MultiProvider:online_model_fetching()
+  return self.model_endpoint and self.model_endpoint ~= ""
+end
+
 -- Validates the MultiProvider configuration
 function MultiProvider:validate_config()
   local logger = require("parrot.logger")
@@ -264,7 +268,7 @@ function MultiProvider:validate_config()
   end
 
   -- Validate model endpoint format if provided (allow functions)
-  if self.model_endpoint and self.model_endpoint ~= "" then
+  if self:online_model_fetching() then
     if type(self.model_endpoint) == "string" and not self.model_endpoint:match("^https?://") then
       logger.error(vim.inspect({
         msg = "Invalid model endpoint format for provider",
@@ -411,7 +415,7 @@ end
 -- Returns the list of available models
 ---@return string[]
 function MultiProvider:get_available_models()
-  if self.model_endpoint ~= "" and self:verify() then
+  if self:online_model_fetching() and self:verify() then
     local hdrs = type(self.headers) == "function" and self.headers(self) or (self.headers or {})
 
     -- Handle model_endpoint as function or string/table
@@ -440,4 +444,51 @@ function MultiProvider:get_available_models()
   return self.models
 end
 
+-- Returns the list of available models with caching support
+---@param state table # State object for caching
+---@param cache_expiry_hours number # Cache expiry time in hours
+---@param spinner table|nil # Optional spinner for loading indication
+---@return string[]
+function MultiProvider:get_available_models_cached(state, cache_expiry_hours, spinner)
+  -- Only use caching if model_endpoint is configured
+  -- otherwise return fallback models
+  if not self:online_model_fetching() and cache_expiry_hours == 0 then
+    return self.models
+  end
+
+  -- Generate endpoint hash for cache validation
+  local endpoint_hash = utils.generate_endpoint_hash(self)
+
+  -- Try to get from cache first
+  local cached_models = state:get_cached_models(self.name, cache_expiry_hours, endpoint_hash)
+  if cached_models then
+    return cached_models
+  end
+
+  -- Cache miss or expired - fetch fresh models
+  if spinner then
+    spinner:start("Fetching models for " .. self.name .. "...")
+  end
+
+  local fresh_models = self:get_available_models()
+
+  if spinner then
+    spinner:stop()
+  end
+
+  -- Ensure we always have models - fallback to static if fresh fetch failed
+  if not fresh_models or #fresh_models == 0 then
+    fresh_models = self.models
+  end
+
+  -- Cache the fresh models if we successfully fetched from API and they differ from static
+  if #fresh_models > 0 and not vim.deep_equal(fresh_models, self.models) then
+    state:set_cached_models(self.name, fresh_models, endpoint_hash)
+    state:save()
+  end
+
+  -- Final safety check - always return at least static models
+  return fresh_models and #fresh_models > 0 and fresh_models or self.models
+end
+
 return MultiProvider

lua/parrot/state.lua

@@ -21,8 +21,22 @@ function State:init_file_state(available_providers)
       self.file_state[prov] = {
         chat_model = nil,
         command_model = nil,
+        cached_models = {},
       }
     end
+  else
+    -- Ensure existing providers have cached_models initialized
+    for _, prov in ipairs(available_providers) do
+      if self.file_state[prov] then
+        self.file_state[prov].cached_models = self.file_state[prov].cached_models or {}
+      else
+        self.file_state[prov] = {
+          chat_model = nil,
+          command_model = nil,
+          cached_models = {},
+        }
+      end
+    end
   end
   self.file_state.current_provider = self.file_state.current_provider or { chat = nil, command = nil }
 end
@@ -33,12 +47,23 @@ end
 function State:init_state(available_providers, available_models)
   self._state.current_provider = self._state.current_provider or { chat = nil, command = nil }
   for _, provider in ipairs(available_providers) do
-    self._state[provider] = self._state[provider] or {
-      chat_model = nil,
-      command_model = nil,
-    }
-    self:load_models(provider, "chat_model", available_models)
-    self:load_models(provider, "command_model", available_models)
+    self._state[provider] = self._state[provider]
+      or {
+        chat_model = nil,
+        command_model = nil,
+        cached_models = {},
+      }
+
+    -- Copy cached_models from file_state if they exist
+    if self.file_state[provider] and self.file_state[provider].cached_models then
+      self._state[provider].cached_models = self.file_state[provider].cached_models
+    end
+
+    -- Only load models if the provider has available models
+    if available_models[provider] and #available_models[provider] > 0 then
+      self:load_models(provider, "chat_model", available_models)
+      self:load_models(provider, "command_model", available_models)
+    end
   end
 end
 
@@ -47,6 +72,11 @@ end
 --- @param model_type string # Type of model (e.g., "chat_model", "command_model").
 --- @param available_models table
 function State:load_models(provider, model_type, available_models)
+  -- Ensure provider exists in available_models and has models
+  if not available_models[provider] or not available_models[provider][1] then
+    return
+  end
+
   local state_model = self.file_state and self.file_state[provider] and self.file_state[provider][model_type]
   local is_valid_model = state_model and utils.contains(available_models[provider], state_model)
 
@@ -85,6 +115,13 @@ end
 
 --- Saves the current state to the state file.
 function State:save()
+  -- Merge cached_models from file_state into _state before saving
+  for provider, data in pairs(self.file_state) do
+    if type(data) == "table" and data.cached_models and self._state[provider] then
+      self._state[provider].cached_models = data.cached_models
+    end
+  end
+
   futils.table_to_file(self._state, self.state_file)
 end
 
@@ -141,4 +178,108 @@ function State:get_last_chat()
   return self._state.last_chat
 end
 
+--- Sets cached models for a provider with timestamp
+--- @param provider string # Provider name
+--- @param models table # Array of model names
+--- @param endpoint_hash string|nil # Hash of the endpoint configuration for validation
+function State:set_cached_models(provider, models, endpoint_hash)
+  -- Ensure provider exists in file_state
+  if not self.file_state[provider] then
+    self.file_state[provider] = {
+      chat_model = nil,
+      command_model = nil,
+      cached_models = {},
+    }
+  end
+
+  -- Ensure cached_models table exists for this provider
+  self.file_state[provider].cached_models = self.file_state[provider].cached_models or {}
+
+  local cache_entry = {
+    models = models,
+    timestamp = os.time(),
+    endpoint_hash = endpoint_hash,
+  }
+
+  self.file_state[provider].cached_models = cache_entry
+
+  -- Also sync to _state if it exists for immediate availability
+  if self._state[provider] then
+    self._state[provider].cached_models = cache_entry
+  end
+end
+
+--- Gets cached models for a provider if they exist and are valid
+--- @param provider string # Provider name
+--- @param cache_expiry_hours number # Cache expiry time in hours
+--- @param endpoint_hash string|nil # Current endpoint hash for validation
+--- @return table|nil # Array of cached model names or nil if cache is invalid/expired
+function State:get_cached_models(provider, cache_expiry_hours, endpoint_hash)
+  if not self.file_state[provider] or not self.file_state[provider].cached_models then
+    return nil
+  end
+
+  local cached = self.file_state[provider].cached_models
+  -- If cached_models is empty table, return nil
+  if not cached.models or not cached.timestamp then
+    return nil
+  end
+
+  local now = os.time()
+  local expiry_seconds = cache_expiry_hours * 3600
+
+  -- Check if cache is expired
+  if (now - cached.timestamp) > expiry_seconds then
+    return nil
+  end
+
+  -- Check if endpoint configuration changed (if hash is provided)
+  if endpoint_hash and cached.endpoint_hash and cached.endpoint_hash ~= endpoint_hash then
+    return nil
+  end
+
+  return cached.models
+end
+
+--- Checks if cached models are valid for a provider
+--- @param provider string # Provider name
+--- @param cache_expiry_hours number # Cache expiry time in hours
+--- @param endpoint_hash string|nil # Current endpoint hash for validation
+--- @return boolean
+function State:is_cache_valid(provider, cache_expiry_hours, endpoint_hash)
+  return self:get_cached_models(provider, cache_expiry_hours, endpoint_hash) ~= nil
+end
+
+--- Clears cached models for a provider or all providers
+--- @param provider string|nil # Provider name, or nil to clear all caches
+function State:clear_cache(provider)
+  if provider then
+    -- Clear cache for specific provider
+    if self.file_state[provider] and self.file_state[provider].cached_models then
+      self.file_state[provider].cached_models = {}
+    end
+  else
+    -- Clear all caches
+    for prov_name, prov_data in pairs(self.file_state) do
+      if type(prov_data) == "table" and prov_data.cached_models then
+        prov_data.cached_models = {}
+      end
+    end
+  end
+end
+
+--- Cleans up cache entries for providers that no longer exist
+--- @param available_providers table # Current list of available providers
+function State:cleanup_cache(available_providers)
+  -- Remove entire provider entries that no longer exist
+  for prov_name, _ in pairs(self.file_state) do
+    -- Skip special keys like current_provider
+    if prov_name ~= "current_provider" and prov_name ~= "last_chat" then
+      if not utils.contains(available_providers, prov_name) then
+        self.file_state[prov_name] = nil
+      end
+    end
+  end
+end
+
 return State