studio: reuse HF cached repo casing to prevent duplicate downloads (#4822)

* fix(studio): reuse HF cached repo casing to prevent duplicate downloads

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Move cache case resolution tests to separate PR

Tests for resolve_cached_repo_id_case and get_model_config case resolution
belong in their own PR to keep this change focused on the runtime fix.

* fix(studio): debug-log HF_HUB_CACHE fallback in path_utils

* Fix stale memoization in resolve_cached_repo_id_case

- Check exact-case path before memo to ensure a newly-appeared exact
  match always wins over a previously memoized variant
- Validate memoized entries still exist on disk before returning them
  to prevent stale results when cache dirs are deleted/recreated

* Minor cleanups for cache case resolution

- Use .is_dir() instead of .exists() for exact-case cache check
  (cache entries are always directories)
- Remove redundant fallback in _detect_audio_from_tokenizer since
  get_cache_path already handles case resolution and returns None
  when the model is not cached

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>

studio/backend/utils/paths/path_utils.py

@@ -14,6 +14,20 @@ from loggers import get_logger
 
 logger = get_logger(__name__)
 
+# Per-process cache to avoid repeated cache-dir scans for the same identifier.
+_CACHE_CASE_RESOLUTION_MEMO: dict[str, str] = {}
+
+# Lightweight instrumentation counters for operational visibility.
+_CACHE_CASE_RESOLUTION_STATS: dict[str, int] = {
+    "calls": 0,
+    "memo_hits": 0,
+    "exact_hits": 0,
+    "variant_hits": 0,
+    "tie_breaks": 0,
+    "fallbacks": 0,
+    "errors": 0,
+}
+
 
 def _is_wsl() -> bool:
     """Detect if we are running inside WSL (Windows Subsystem for Linux)."""
@@ -94,8 +108,9 @@ def is_local_path(path: str) -> bool:
 
 def get_cache_path(model_name: str) -> Optional[Path]:
     """Get HuggingFace cache path for a model if it exists."""
-    cache_dir = Path.home() / ".cache" / "huggingface" / "hub"
-    model_cache_name = model_name.replace("/", "--")
+    cache_dir = _hf_hub_cache_dir()
+    resolved_name = resolve_cached_repo_id_case(model_name)
+    model_cache_name = resolved_name.replace("/", "--")
     model_cache_path = cache_dir / f"models--{model_cache_name}"
 
     return model_cache_path if model_cache_path.exists() else None
@@ -113,3 +128,102 @@ def is_model_cached(model_name: str) -> bool:
             return True
 
     return False
+
+
+def _hf_hub_cache_dir() -> Path:
+    """Return HF cache root honoring HF_HUB_CACHE when available."""
+    try:
+        from huggingface_hub.constants import HF_HUB_CACHE
+
+        return Path(HF_HUB_CACHE)
+    except Exception as exc:
+        logger.debug(
+            "Could not read huggingface_hub HF_HUB_CACHE, using default hub path: %s",
+            exc,
+        )
+        return Path.home() / ".cache" / "huggingface" / "hub"
+
+
+def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
+    """Resolve repo_id to the exact casing already present in local HF cache.
+
+    Policy: prefer the requested/canonical repo_id, but if a case-variant already
+    exists in local HF cache, reuse that exact cached spelling. This avoids
+    duplicate downloads while preserving user intent whenever possible.
+    """
+    _CACHE_CASE_RESOLUTION_STATS["calls"] += 1
+
+    if not model_name or "/" not in model_name:
+        _CACHE_CASE_RESOLUTION_STATS["fallbacks"] += 1
+        return model_name
+
+    cache_dir = _hf_hub_cache_dir()
+    if not cache_dir.exists():
+        _CACHE_CASE_RESOLUTION_STATS["fallbacks"] += 1
+        return model_name
+
+    expected_dir = f"models--{model_name.replace('/', '--')}"
+
+    # Always check the exact-case path first so a newly-appeared exact match
+    # wins over any previously memoized variant.
+    exact_path = cache_dir / expected_dir
+    if exact_path.is_dir():
+        if use_memo:
+            _CACHE_CASE_RESOLUTION_MEMO[model_name] = model_name
+        _CACHE_CASE_RESOLUTION_STATS["exact_hits"] += 1
+        return model_name
+
+    # Validate memoized entries still exist on disk before returning them.
+    # This prevents stale results when cache dirs are deleted/recreated.
+    if use_memo:
+        cached = _CACHE_CASE_RESOLUTION_MEMO.get(model_name)
+        if cached is not None:
+            cached_path = cache_dir / f"models--{cached.replace('/', '--')}"
+            if cached_path.is_dir():
+                _CACHE_CASE_RESOLUTION_STATS["memo_hits"] += 1
+                return cached
+            # Stale entry -- drop it and re-scan below.
+            _CACHE_CASE_RESOLUTION_MEMO.pop(model_name, None)
+
+    expected_lower = expected_dir.lower()
+    try:
+        candidates: list[str] = []
+        for entry in cache_dir.iterdir():
+            if not entry.is_dir():
+                continue
+            if entry.name.lower() != expected_lower:
+                continue
+            if not entry.name.startswith("models--"):
+                continue
+            repo_part = entry.name[len("models--") :]
+            if not repo_part:
+                continue
+            candidates.append(repo_part.replace("--", "/"))
+
+        if candidates:
+            # Deterministic tie-break if multiple case variants coexist.
+            resolved = sorted(candidates)[0]
+            if len(candidates) > 1:
+                _CACHE_CASE_RESOLUTION_STATS["tie_breaks"] += 1
+            _CACHE_CASE_RESOLUTION_STATS["variant_hits"] += 1
+            if use_memo:
+                _CACHE_CASE_RESOLUTION_MEMO[model_name] = resolved
+            return resolved
+    except Exception as exc:
+        _CACHE_CASE_RESOLUTION_STATS["errors"] += 1
+        logger.debug(f"Could not resolve cached repo_id case for '{model_name}': {exc}")
+
+    _CACHE_CASE_RESOLUTION_STATS["fallbacks"] += 1
+    return model_name
+
+
+def get_cache_case_resolution_stats() -> dict[str, int]:
+    """Return a copy of case-resolution instrumentation counters."""
+    return dict(_CACHE_CASE_RESOLUTION_STATS)
+
+
+def reset_cache_case_resolution_state() -> None:
+    """Clear resolver memo and counters (primarily for tests)."""
+    _CACHE_CASE_RESOLUTION_MEMO.clear()
+    for key in _CACHE_CASE_RESOLUTION_STATS:
+        _CACHE_CASE_RESOLUTION_STATS[key] = 0