llama-router: add --import-dir for custom model collections

New CLI flag --import-dir <path> recursively scans local directories
and imports GGUF models as manual state (spawn on-demand only)

Features:
- Smart mmproj detection: skips mmproj files as standalone models
- Auto-associates mmproj to models in same directory
- Priority: BF16 > F16 > F32 when multiple mmproj variants exist
- All quants of same model share the same prioritized mmproj
- Idempotent: won't duplicate existing models on re-import
- Manifest-optional: works without HF manifests for local collections

Fixes:
- Robust manifest handling: no crash if manifest JSON missing
- PATH binary check: only validates paths with separators

Example directory structure:
/mnt/models/
├─ unsloth/
│  ├─ Qwen3-VL-32B-Instruct-GGUF/
│  │  ├─ Qwen3-VL-32B-Instruct-Q4_K_M.gguf ─┐
│  │  ├─ Qwen3-VL-32B-Instruct-Q5_K_M.gguf ─┼─> all use mmproj-BF16.gguf
│  │  ├─ Qwen3-VL-32B-Instruct-Q6_K.gguf   ─┘
│  │  ├─ mmproj-BF16.gguf <- priority 1 (selected)
│  │  ├─ mmproj-F16.gguf  <- priority 2
│  │  └─ mmproj-F32.gguf  <- priority 3
│  └── DeepSeek-R1-Distill-Qwen-32B-GGUF/
│      ├─ DeepSeek-R1-Distill-Qwen-32B-Q5_K_M.gguf
│      └─ DeepSeek-R1-Distill-Qwen-32B-Q6_K.gguf
└── bartowski/
    └─ Valkyrie-49B-v2-GGUF/
       ├─ Valkyrie-49B-v2-Q4_K_M.gguf
       └─ Valkyrie-49B-v2-IQ4_NL.gguf

Usage:
  llama-router --import-dir /mnt/models/
  llama-router --import-dir ~/my-gguf-collection

All imported models are set to manual state (never auto-removed by rescan)

Author: ServeurpersoCom

tools/router/router-admin.cpp

@@ -31,9 +31,8 @@ void register_admin_routes(httplib::Server & server, RouterApp & app, const std:
         if (!authorize_admin(app.get_config(), req, res)) {
             return;
         }
-        LOG_INF("Reloading router application: stopping and auto-starting models\n");
+        LOG_INF("Reloading router application: stopping managed models\n");
         app.stop_all();
-        app.start_auto_models();
         res.set_content("{\"status\":\"reloaded\"}", "application/json");
     });
 

tools/router/router-app.cpp

@@ -30,19 +30,6 @@ SpawnConfig RouterApp::get_spawn_config(const std::string & model_name) {
     return resolve_spawn_config(it->second);
 }
 
-void RouterApp::start_auto_models() {
-    for (const auto & model : config.models) {
-        if (model.state == "auto") {
-            std::string err;
-            if (!ensure_running(model.name, err)) {
-                LOG_WRN("auto-start for %s failed: %s\n", model.name.c_str(), err.c_str());
-            } else {
-                LOG_INF("auto-started %s\n", model.name.c_str());
-            }
-        }
-    }
-}
-
 bool RouterApp::ensure_running(const std::string & model_name, std::string & error) {
     std::lock_guard<std::mutex> lock(mutex);
     auto it_cfg = model_lookup.find(model_name);

tools/router/router-app.h

@@ -13,7 +13,6 @@ class RouterApp {
     explicit RouterApp(RouterConfig cfg);
     ~RouterApp();
 
-    void start_auto_models();
     bool ensure_running(const std::string & model_name, std::string & error);
     std::string upstream_for(const std::string & model_name);
     std::string get_last_spawned_model();

tools/router/router-scanner.cpp

@@ -152,3 +152,80 @@ std::vector<ModelConfig> scan_default_models() {
     LOG_INF("Model scanner found %zu candidates in %s\n", models.size(), cache_dir.c_str());
     return models;
 }
+
+static std::string find_mmproj_in_dir(const std::filesystem::path & dir) {
+    static const std::vector<std::string> priorities = {"bf16.gguf", "f16.gguf", "f32.gguf"};
+
+    std::error_code ec;
+    for (const auto & priority : priorities) {
+        for (std::filesystem::directory_iterator it(dir, ec), end; it != end && !ec; ++it) {
+            if (!it->is_regular_file()) {
+                continue;
+            }
+
+            std::string filename = it->path().filename().string();
+            std::transform(filename.begin(), filename.end(), filename.begin(), [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+
+            if (filename.find("mmproj") == std::string::npos) {
+                continue;
+            }
+
+            if (filename.size() < priority.size() || filename.rfind(priority) != filename.size() - priority.size()) {
+                continue;
+            }
+
+            return it->path().string();
+        }
+    }
+
+    return {};
+}
+
+std::vector<ModelConfig> scan_custom_dir(const std::string & path, const std::string & state) {
+    std::vector<ModelConfig> models;
+
+    std::error_code ec;
+    if (!std::filesystem::exists(path, ec) || !std::filesystem::is_directory(path, ec) || ec) {
+        return models;
+    }
+
+    std::unordered_set<std::string> seen;
+
+    for (std::filesystem::recursive_directory_iterator it(path, ec), end; it != end && !ec; ++it) {
+        if (!it->is_regular_file()) {
+            continue;
+        }
+        std::string ext = it->path().extension().string();
+        std::transform(ext.begin(), ext.end(), ext.begin(), [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+        if (ext != ".gguf") {
+            continue;
+        }
+
+        std::string full_path = it->path().string();
+        if (seen.count(full_path)) {
+            continue;
+        }
+        seen.insert(full_path);
+
+        std::string filename = it->path().filename().string();
+        std::transform(filename.begin(), filename.end(), filename.begin(), [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+
+        if (filename.find("mmproj") != std::string::npos) {
+            continue;
+        }
+
+        ModelConfig mc;
+        mc.name  = it->path().filename().string();
+        mc.path  = full_path;
+        mc.state = state;
+        if (auto mmproj_path = find_mmproj_in_dir(it->path().parent_path()); !mmproj_path.empty()) {
+            mc.spawn = get_default_spawn();
+            mc.spawn.command.push_back("--mmproj");
+            mc.spawn.command.push_back(mmproj_path);
+        }
+
+        models.push_back(std::move(mc));
+    }
+
+    return models;
+}

tools/router/router-scanner.h

@@ -2,6 +2,8 @@
 
 #include "router-config.h"
 
+#include <string>
 #include <vector>
 
 std::vector<ModelConfig> scan_default_models();
+std::vector<ModelConfig> scan_custom_dir(const std::string & path, const std::string & state);

tools/router/router.cpp

@@ -5,6 +5,7 @@
 #include "router-app.h"
 #include "router-config.h"
 #include "router-constants.h"
+#include "router-scanner.h"
 #include "router-admin.h"
 #include "router-endpoints.h"
 
@@ -17,6 +18,7 @@
 #include <cstdlib>
 #include <string>
 #include <thread>
+#include <unordered_set>
 
 static std::atomic<bool> g_shutdown{false};
 static httplib::Server *  g_server = nullptr;
@@ -33,6 +35,7 @@ struct CliOptions {
     std::string hf_repo;
     std::string hf_file;
     std::string config_path;
+    std::string import_dir;
 };
 
 static bool parse_cli(int argc, char ** argv, CliOptions & out) {
@@ -58,6 +61,12 @@ static bool parse_cli(int argc, char ** argv, CliOptions & out) {
                 return false;
             }
             out.config_path = argv[++i];
+        } else if (arg == "--import-dir") {
+            if (i + 1 >= argc) {
+                fprintf(stderr, "error: missing value for --import-dir\n");
+                return false;
+            }
+            out.import_dir = argv[++i];
         } else {
             fprintf(stderr, "warning: unknown argument %s\n", arg.c_str());
         }
@@ -72,6 +81,7 @@ static void print_help() {
     printf("  --config <path>         Override config path (default: ~/.config/llama.cpp/router-config.json)\n");
     printf("  -hf, -hfr, --hf-repo    Hugging Face repository to download (format <user>/<repo>[:quant])\n");
     printf("  -hff, --hf-file         Specific GGUF filename to fetch from repository\n");
+    printf("  --import-dir <path>     Recursively import GGUF models from directory\n");
 }
 
 static bool handle_download(const CliOptions & opts) {
@@ -112,6 +122,47 @@ static bool handle_download(const CliOptions & opts) {
     return true;
 }
 
+static bool handle_import(const CliOptions & opts, const std::string & config_path, int & exit_code) {
+    if (opts.import_dir.empty()) {
+        return false;
+    }
+
+    exit_code = 0;
+
+    const std::string import_dir = expand_user_path(opts.import_dir);
+    auto               scanned   = scan_custom_dir(import_dir, "manual");
+
+    RouterConfig cfg;
+    try {
+        cfg = load_config(config_path);
+    } catch (const std::exception & e) {
+        fprintf(stderr, "%s\n", e.what());
+        exit_code = 1;
+        return true;
+    }
+
+    std::unordered_set<std::string> existing_paths;
+    for (const auto & model : cfg.models) {
+        existing_paths.insert(expand_user_path(model.path));
+    }
+
+    size_t added = 0;
+    for (auto & model : scanned) {
+        const auto expanded = expand_user_path(model.path);
+        if (existing_paths.insert(expanded).second) {
+            cfg.models.push_back(std::move(model));
+            ++added;
+        }
+    }
+
+    if (added > 0) {
+        write_config_file(cfg, config_path);
+    }
+
+    LOG_INF("Imported %zu models from %s\n", added, import_dir.c_str());
+    return true;
+}
+
 int main(int argc, char ** argv) {
     CliOptions cli;
     router_log_init();
@@ -127,12 +178,17 @@ int main(int argc, char ** argv) {
         return 0;
     }
 
+    std::string config_path = !cli.config_path.empty() ? expand_user_path(cli.config_path) : get_default_config_path();
+
     if (handle_download(cli)) {
         LOG_INF("Download-only mode completed, exiting\n");
         return 0;
     }
 
-    std::string config_path = !cli.config_path.empty() ? expand_user_path(cli.config_path) : get_default_config_path();
+    int import_exit_code = 0;
+    if (handle_import(cli, config_path, import_exit_code)) {
+        return import_exit_code;
+    }
     LOG_INF("Loading router configuration from %s\n", config_path.c_str());
 
     RouterConfig cfg;
@@ -148,8 +204,6 @@ int main(int argc, char ** argv) {
 
     RouterApp app(cfg);
     LOG_INF("Initialized RouterApp with default spawn command size=%zu\n", cfg.default_spawn.command.size());
-    app.start_auto_models();
-    LOG_INF("Auto-start requested, last spawned model: %s\n", app.get_last_spawned_model().c_str());
 
     httplib::Server server;
     g_server = &server;