feat: materialize Hugging Face model artifacts (#10825)

* feat(config): add model artifact source contract

Assisted-by: Codex:GPT-5 [Codex]

* feat(downloader): add authenticated raw-byte progress

Assisted-by: Codex:GPT-5 [Codex]

* feat(huggingface): resolve immutable snapshot manifests

Assisted-by: Codex:GPT-5 [Codex]

* feat(models): add artifact storage primitives

Assisted-by: Codex:GPT-5 [Codex]

* feat(models): materialize pinned Hugging Face snapshots

Assisted-by: Codex:GPT-5 [Codex]

* feat(models): bind managed snapshots at runtime

Assisted-by: Codex:GPT-5 [Codex]

* feat(gallery): materialize model artifacts during install

Assisted-by: Codex:GPT-5 [Codex]

* feat(gallery): declare managed Hugging Face artifacts

Assisted-by: Codex:GPT-5 [Codex]

* feat(models): preload managed model artifacts

Assisted-by: Codex:GPT-5 [Codex]

* fix(gallery): retain shared artifact caches on delete

Assisted-by: Codex:GPT-5 [Codex]

* feat(models): report artifact acquisition progress

Assisted-by: Codex:GPT-5 [Codex]

* refactor(backends): load managed models from ModelFile

Assisted-by: Codex:GPT-5 [Codex]

* refactor(backends): load staged speech model snapshots

Assisted-by: Codex:GPT-5 [Codex]

* refactor(backends): use staged snapshots in engine backends

Assisted-by: Codex:GPT-5 [Codex]

* test(distributed): cover staged artifact snapshots

Assisted-by: Codex:GPT-5 [Codex]

* docs: explain managed model artifacts

Assisted-by: Codex:GPT-5 [Codex]

* docs: add product design context

Assisted-by: Codex:GPT-5 [Codex]

* feat(ui): show model artifact download progress

Assisted-by: Codex:GPT-5 [Codex]

* Eagerly materialize Hugging Face artifacts

Materialize HF-backed model references as managed GGUF artifacts during load, with lazy download retained only as fallback.

Assisted-by: Codex:GPT-5 [shell]

* Refactor HF
  downloads through a shared executor

Assisted-by: Codex:GPT-5 [shell]

* drop

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

---------

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>
Co-authored-by: Ettore Di Giacinto <mudler@localai.io>

backend/python/liquid-audio/backend.py

@@ -23,6 +23,7 @@ import grpc
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'common'))
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'common'))
 from grpc_auth import get_auth_interceptors  # noqa: E402
+from model_utils import resolve_model_reference  # noqa: E402
 from python_utils import parse_options  # noqa: E402
 
 import backend_pb2  # noqa: E402
@@ -172,19 +173,14 @@ class BackendServicer(backend_pb2_grpc.BackendServicer):
                 "fp32":     torch.float32,
             }.get(dtype_name, torch.bfloat16)
 
-            # request.Model holds the raw `parameters.model` value (an HF
-            # repo id like "LiquidAI/LFM2.5-Audio-1.5B"); request.ModelFile
-            # is LocalAI's ModelPath-prefixed local copy that exists only
-            # when the gallery supplied a `files:` list. Mirror the
-            # transformers/vibevoice convention: prefer the repo id and
-            # only switch to the local path if it's been staged on disk.
-            model_id = request.Model
-            if not model_id:
-                model_id = request.ModelFile
+            # `_local_only` distinguishes a staged snapshot from the legacy
+            # repository fallback. liquid_audio has no matching Hub keyword,
+            # so the compatibility shim below enforces local loading instead.
+            model_id, _local_only = resolve_model_reference(
+                request, "LiquidAI/LFM2.5-Audio-1.5B"
+            )
             if not model_id:
                 return backend_pb2.Result(success=False, message="No model identifier provided")
-            if request.ModelFile and os.path.isdir(request.ModelFile):
-                model_id = request.ModelFile
             self.model_id = model_id
 
             # Pure fine-tune jobs don't need an in-memory inference model — the