feat(server): add model registration endpoint (#3118)

* feat(server): add model registration endpoint

* feat(server): add model registration endpoint

* small name catch

Author: fl0rianr

docs/api/lemonade.md

@@ -10,6 +10,7 @@ We have designed a set of Lemonade-specific endpoints to enable client applicati
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `POST` | [`/v1/pull`](#post-v1pull) | Install a model |
+| `POST` | [`/v1/models/register`](#post-v1modelsregister) | Register or update a user model definition without downloading it |
 | `GET` | [`/v1/downloads`](#get-v1downloads) | List server-owned model download jobs |
 | `POST` | [`/v1/downloads/control`](#post-v1downloadscontrol) | Pause, cancel, or remove server-owned model download jobs |
 | `GET` | [`/v1/registry/search`](#get-v1registrysearch) | Search Hugging Face or ModelScope for model repositories |
@@ -222,6 +223,72 @@ When `include_paths=true` is supplied, each file entry also includes `path`:
 | `files[].size_bytes` | File size in bytes. Directories are summed recursively. Missing files report `0`. |
 | `files[].exists` | Whether the resolved path currently exists on disk. |
 
+## `POST /v1/models/register`
+<sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
+
+Register or update a `user.*` model definition without downloading model files.
+Use this endpoint when registration and installation are separate actions.
+`POST /v1/pull` remains the install/download path and performs the same internal
+registration step before downloading.
+
+The endpoint is available at:
+
+- `/v1/models/register`
+- `/api/v1/models/register`
+- `/v0/models/register`
+- `/api/v0/models/register`
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `model_name` | Yes | Non-empty namespaced model name under `user.*`. |
+| `recipe` | Yes | Lemonade recipe associated with the model definition. |
+| `checkpoint` | No | Main checkpoint, when the recipe uses one. |
+| `checkpoints` | No | Named checkpoints for multi-checkpoint models. |
+| `source` | No | Registry or local source. Remote values are `huggingface` or `modelscope`. |
+| `labels` | No | Additional model labels. |
+| `components` | No | Already-registered component model names for collection recipes. |
+
+A checkpoint is intentionally not universally required: registration is a model
+metadata operation and some present or future model types may not have local
+weights. `/pull` remains the operation that attempts installation/download.
+
+The endpoint accepts one model definition. An embedded `models` array represents
+multiple definitions and remains a collection-import concern; register those
+component definitions first when using this endpoint.
+
+Example request:
+
+```bash
+curl -X POST http://localhost:13305/v1/models/register \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "model_name": "user.Phi-4-Mini-GGUF",
+    "checkpoint": "unsloth/Phi-4-mini-instruct-GGUF:Q4_K_M",
+    "recipe": "llamacpp"
+  }'
+```
+
+Example response:
+
+```json
+{
+  "status": "success",
+  "model_name": "Phi-4-Mini-GGUF",
+  "canonical_model_name": "user.Phi-4-Mini-GGUF",
+  "model": {
+    "id": "Phi-4-Mini-GGUF",
+    "recipe": "llamacpp",
+    "downloaded": false
+  }
+}
+```
+
+`model_name` is the public ID exposed by `/v1/models`; `canonical_model_name` is
+the stable `user.*` registration ID. Registration updates `user_models.json` and
+invalidates the model cache, but does not start a model download.
+
 ## `POST /v1/pull`
 <sub>![Status](https://img.shields.io/badge/status-fully_available-green)</sub>
 

src/cpp/include/lemon/model_manager.h

@@ -210,6 +210,13 @@ class ModelManager {
                             const json& model_data,
                             const std::string& source = "");
 
+    // Register or validate a model definition without downloading its files.
+    // Uses the same registration path as download_model.
+    void register_model(const std::string& model_name,
+                       const json& model_data,
+                       bool allow_missing_checkpoint = false,
+                       bool replace_existing = false);
+
     // Register (if needed) and download a model
     void download_model(const std::string& model_name,
                        const json& model_data,
@@ -315,7 +322,10 @@ class ModelManager {
                        const json& model_data,
                        bool do_not_upgrade,
                        DownloadProgressCallback progress_callback,
-                       std::set<std::string>& visited);
+                       std::set<std::string>& visited,
+                       bool register_only,
+                       bool allow_missing_checkpoint,
+                       bool replace_existing);
 
     json load_server_models();
     json load_architecture_defaults();

src/cpp/include/lemon/server.h

@@ -107,6 +107,21 @@ class Server {
     void handle_health(const httplib::Request& req, httplib::Response& res);
     void handle_live(const httplib::Request& req, httplib::Response& res);
     void handle_models(const httplib::Request& req, httplib::Response& res);
+    void handle_model_register(const httplib::Request& req, httplib::Response& res);
+    void validate_model_registration_name(const std::string& model_name,
+                                         bool require_user_namespace);
+    void normalize_model_registration_source(nlohmann::json& request_json,
+                                             bool local_import);
+    void validate_and_canonicalize_collection_registration(
+        const std::string& model_name,
+        nlohmann::json& request_json,
+        bool allow_embedded_models);
+    std::string register_model_definition_internal(
+        const std::string& model_name,
+        nlohmann::json& request_json,
+        bool require_definition,
+        bool allow_embedded_models,
+        bool local_import);
     void handle_model_by_id(const httplib::Request& req, httplib::Response& res);
     void handle_model_update_check(const httplib::Request& req, httplib::Response& res);
     void handle_model_files(const httplib::Request& req, httplib::Response& res);

src/cpp/server/model_manager.cpp

@@ -3371,19 +3371,32 @@ void ModelManager::populate_collection_components_from_cache_locked(ModelInfo& i
     }
 }
 
+void ModelManager::register_model(const std::string& model_name,
+                                 const json& model_data,
+                                 bool allow_missing_checkpoint,
+                                 bool replace_existing) {
+    std::set<std::string> visited;
+    download_model(model_name, model_data, true, nullptr, visited,
+                   true, allow_missing_checkpoint, replace_existing);
+}
+
 void ModelManager::download_model(const std::string& model_name,
                                  const json& model_data,
                                  bool do_not_upgrade,
                                  DownloadProgressCallback progress_callback) {
     std::set<std::string> visited;
-    download_model(model_name, model_data, do_not_upgrade, progress_callback, visited);
+    download_model(model_name, model_data, do_not_upgrade, progress_callback, visited,
+                   false, false, false);
 }
 
 void ModelManager::download_model(const std::string& model_name,
                                  const json& model_data,
                                  bool do_not_upgrade,
                                  DownloadProgressCallback progress_callback,
-                                 std::set<std::string>& visited) {
+                                 std::set<std::string>& visited,
+                                 bool register_only,
+                                 bool allow_missing_checkpoint,
+                                 bool replace_existing) {
     // Keep a mutable registration payload so legacy re-pulls that omit the
     // registry retain the source recorded on the existing model. The original
     // request remains untouched for validation and download semantics.
@@ -3446,8 +3459,13 @@ void ModelManager::download_model(const std::string& model_name,
             }
             LOG(INFO, "ModelManager") << "Registering new collection: " << model_name << std::endl;
         } else {
-            // Check that required arguments are provided
-            if (actual_checkpoint.empty() || actual_recipe.empty()) {
+            if (actual_recipe.empty()) {
+                throw std::runtime_error(
+                    "Model " + model_name + " is not registered with Lemonade Server. "
+                    "To register it, provide the `recipe` argument."
+                );
+            }
+            if (actual_checkpoint.empty() && !allow_missing_checkpoint) {
                 throw std::runtime_error(
                     "Model " + model_name + " is not registered with Lemonade Server. "
                     "To register and install it, provide the `checkpoint` and `recipe` "
@@ -3456,10 +3474,12 @@ void ModelManager::download_model(const std::string& model_name,
             }
 
             // Backend-specific checkpoint validation (llamacpp: GGUF needs :variant).
-            if (auto err = backends::ops_for(actual_recipe)->validate_registration_checkpoint(
-                    actual_checkpoint);
-                !err.empty()) {
-                throw std::runtime_error(err);
+            if (!actual_checkpoint.empty()) {
+                if (auto err = backends::ops_for(actual_recipe)->validate_registration_checkpoint(
+                        actual_checkpoint);
+                    !err.empty()) {
+                    throw std::runtime_error(err);
+                }
             }
 
             LOG(INFO, "ModelManager") << "Registering new user model: " << model_name << std::endl;
@@ -3477,34 +3497,49 @@ void ModelManager::download_model(const std::string& model_name,
             registration_data["source"] = effective_registry_source(info);
         }
 
-        bool is_collection_overwrite = is_model_collection_recipe(actual_recipe) &&
-                                        model_data.contains("components");
-        if (is_collection_overwrite) {
-            // Validate the original user-authored request, not registration_data:
-            // the latter is enriched with the persisted registry source, which is
-            // not part of the public routing-policy document the parser accepts.
-            if (auto err = validate_collection_request(model_name, model_data)) {
-                throw std::runtime_error(*err);
+        const bool explicit_definition =
+            !actual_recipe.empty() || !actual_checkpoint.empty() ||
+            model_data.contains("checkpoints") || model_data.contains("components");
+        if (register_only && replace_existing &&
+            is_user_model_name(model_name) && explicit_definition) {
+            if (is_model_collection_recipe(actual_recipe)) {
+                if (auto err = validate_collection_request(model_name, model_data)) {
+                    throw std::runtime_error(*err);
+                }
             }
             model_registered = false;
-            LOG(INFO, "ModelManager") << "Overwriting collection: "
+            LOG(INFO, "ModelManager") << "Replacing user model definition: "
                                       << model_name << std::endl;
-        } else if (actual_checkpoint.empty()) {
-            actual_checkpoint = info.checkpoint();
-            actual_recipe = info.recipe;
         } else {
-            std::string conflict = describe_registration_conflict(info, registration_data);
-            if (!conflict.empty()) {
-                throw std::runtime_error(
-                    "Model '" + model_name + "' is already registered with different "
-                    "model metadata: " + conflict + ". Choose a different model name "
-                    "for this registry checkpoint."
-                );
-            }
-            if (actual_recipe.empty()) {
+            bool is_collection_overwrite = is_model_collection_recipe(actual_recipe) &&
+                                            model_data.contains("components");
+            if (is_collection_overwrite) {
+                // Validate the original user-authored request, not registration_data:
+                // the latter is enriched with the persisted registry source, which is
+                // not part of the public routing-policy document the parser accepts.
+                if (auto err = validate_collection_request(model_name, model_data)) {
+                    throw std::runtime_error(*err);
+                }
+                model_registered = false;
+                LOG(INFO, "ModelManager") << "Overwriting collection: "
+                                          << model_name << std::endl;
+            } else if (actual_checkpoint.empty()) {
+                actual_checkpoint = info.checkpoint();
                 actual_recipe = info.recipe;
             } else {
-                model_registered = false;
+                std::string conflict = describe_registration_conflict(info, registration_data);
+                if (!conflict.empty()) {
+                    throw std::runtime_error(
+                        "Model '" + model_name + "' is already registered with different "
+                        "model metadata: " + conflict + ". Choose a different model name "
+                        "for this registry checkpoint."
+                    );
+                }
+                if (actual_recipe.empty()) {
+                    actual_recipe = info.recipe;
+                } else {
+                    model_registered = false;
+                }
             }
         }
     }
@@ -3529,6 +3564,10 @@ void ModelManager::download_model(const std::string& model_name,
         collection_registered_this_call = true;
     }
 
+    if (register_only && is_model_collection_recipe(actual_recipe)) {
+        return;
+    }
+
     // Collections don't have their own backend - download each component instead.
     //
     // Persistence follows one rule, uniform across models and collections: a
@@ -3635,7 +3674,7 @@ void ModelManager::download_model(const std::string& model_name,
             }
             LOG(INFO, "ModelManager") << "Downloading component: " << component << std::endl;
             json comp_data = json::object();
-            download_model(component, comp_data, do_not_upgrade, forward, visited);
+            download_model(component, comp_data, do_not_upgrade, forward, visited, false, false, false);
         }
 
         // A registry-backed collection's in-memory components were empty until the
@@ -3676,20 +3715,6 @@ void ModelManager::download_model(const std::string& model_name,
         );
     }
 
-    LOG(INFO, "ModelManager") << "Downloading model: " << repo_id;
-    if (!variant.empty()) {
-        LOG(INFO, "ModelManager") << " (variant: " << variant << ")";
-    }
-    LOG(INFO, "ModelManager") << std::endl;
-
-    // Check if offline mode
-    if (auto* cfg = RuntimeConfig::global()) {
-        if (cfg->offline()) {
-            LOG(INFO, "ModelManager") << "Offline mode enabled, skipping download" << std::endl;
-            return;
-        }
-    }
-
     // Persist registration and recipe options BEFORE the cache-first shortcut
     // below. A registration/import/overwrite that targets an already-downloaded
     // model must still update user_models.json and recipe_options.json. The
@@ -3716,6 +3741,24 @@ void ModelManager::download_model(const std::string& model_name,
         save_model_options(model_info);
     }
 
+    if (register_only) {
+        return;
+    }
+
+    LOG(INFO, "ModelManager") << "Downloading model: " << repo_id;
+    if (!variant.empty()) {
+        LOG(INFO, "ModelManager") << " (variant: " << variant << ")";
+    }
+    LOG(INFO, "ModelManager") << std::endl;
+
+    // Check if offline mode
+    if (auto* cfg = RuntimeConfig::global()) {
+        if (cfg->offline()) {
+            LOG(INFO, "ModelManager") << "Offline mode enabled, skipping download" << std::endl;
+            return;
+        }
+    }
+
     // CRITICAL: If do_not_upgrade=true AND model is already downloaded, skip the
     // remote-registry update check. Registration and recipe options were already
     // persisted above, so an import/overwrite still takes effect on disk.