feat(lemonade): serve models by their canonical Hugging Face name (#80)

* Serve canonical Hugging Face names via Lemonade

`rocm serve --engine lemonade <owner/repo:variant>` previously failed:
the name was passed straight to `lemonade load`, which only resolves
built-in/registered models. Lemonade's model registry cannot preserve an
`owner/repo:variant` name either — a bare pull derives a `repo-variant`
name, custom registration forces a `user.` prefix, and the resulting
entries load inconsistently.

Serve such a checkpoint by bypassing the registry: pull it once to
download the GGUF, then run a packaged llama.cpp `llama-server` on the
file directly with `--alias <canonical>`, which serves it under exactly
that name (the same id vLLM already uses). The server binary is discovered
under `bin/llamacpp/<backend>/` so this works with whatever backend is
installed — `vulkan` (e.g. WSL2) or `rocm-stable` (native ROCm). The GGUF
is located in the HF hub cache with Lemonade-style variant matching
(exact filename, else a quantization-label match). Built-in models are
unaffected; the direct-serve path is generalized and reused for them.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>

* Address review: GPU-only direct serve, explicit variant, direct-serve readiness

- Drop `cpu` from the direct-serve backend allowlist so an HF checkpoint is
  never silently served on CPU under gpu_required (AGENTS.md §6).
- Require an explicit `:variant` for HF checkpoints and refuse an ambiguous
  variant (one matching multiple cached GGUFs) instead of picking arbitrarily.
- Recognize the direct-serve stock `llama-server` as ready: its `/v1/models`
  entry has no `recipe_options`, so accept it by name (that path is GPU-only)
  while still requiring a ROCm/expected backend for Lemonade-router entries.
  Applied in both the engine healthcheck and `apps/rocm` readiness.
- Kill the child and mark the service failed if the direct server never
  becomes ready, instead of leaking it and leaving state `running`.
- Add tests (variant ambiguity, readiness shapes, backend discovery, GGUF
  collection) and doc fixes.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>

---------

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>

Author: rominf

apps/rocm/src/main.rs

@@ -15152,11 +15152,23 @@ fn model_list_ready_for_model(
                     .into_iter()
                     .filter_map(|field| model.get(field).and_then(serde_json::Value::as_str))
                     .any(|loaded| service_model_names_match(loaded, canonical_model_id));
-                name_matches && (!require_rocm_backend || service_model_reports_rocm_backend(model))
+                name_matches && (!require_rocm_backend || service_model_gpu_ready(model))
             })
         })
 }
 
+/// Whether a lemonade `/v1/models` entry is served on GPU. A stock `llama-server`
+/// (direct-serve) entry has no `recipe_options` and is accepted (that path only runs
+/// GPU backends); a Lemonade-router entry carries `recipe_options`, so it must report a
+/// ROCm backend — which keeps a registered-but-unloaded model (empty `recipe_options`)
+/// from reading as ready.
+fn service_model_gpu_ready(model: &serde_json::Value) -> bool {
+    match model.get("recipe_options") {
+        None => true,
+        Some(_) => service_model_reports_rocm_backend(model),
+    }
+}
+
 fn service_model_reports_rocm_backend(model: &serde_json::Value) -> bool {
     model
         .get("recipe_options")
@@ -15605,6 +15617,36 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn lemonade_direct_serve_model_reads_ready_without_recipe_options() {
+        // The HF direct-serve path runs a stock llama-server whose `/v1/models` entry
+        // has no `recipe_options`. It must read as ready by name (that path is GPU-only),
+        // while a registered-but-unloaded lemonade entry (empty `recipe_options`) must not.
+        let direct = json!({
+            "data": [{ "id": "LiquidAI/LFM2.5-230M-GGUF:Q4_0", "object": "model" }]
+        })
+        .to_string();
+        assert!(service_http_readiness_response_ready(
+            "lemonade",
+            "/v1/models",
+            200,
+            &direct,
+            "LiquidAI/LFM2.5-230M-GGUF:Q4_0"
+        ));
+
+        let registered = json!({
+            "data": [{ "id": "LiquidAI/LFM2.5-230M-GGUF:Q4_0", "recipe_options": {} }]
+        })
+        .to_string();
+        assert!(!service_http_readiness_response_ready(
+            "lemonade",
+            "/v1/models",
+            200,
+            &registered,
+            "LiquidAI/LFM2.5-230M-GGUF:Q4_0"
+        ));
+    }
+
     #[test]
     fn lemonade_stop_unloads_selected_model_over_http() -> Result<()> {
         use std::io::{Read, Write};