fix(loader): authenticate huggingface.co downloads via HF_TOKEN

_resolve_to_local_path fetched URLs with plain urllib (no auth), so private HF
dataset h5ads returned HTTP 401 on the Space. For /resolve/ URLs with a token,
use hf_hub_download (handles the LFS redirect + HF_TOKEN auth); fall back to
urllib for public/non-HF hosts. Requires an HF_TOKEN Space secret with read
access to the private data repo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/tools/bulk_dataset_tools.py

@@ -79,9 +79,39 @@ def _resolve_to_local_path(path_or_url: str) -> tuple[str, bool]:
     caller is responsible for its own existence check.
     """
     if path_or_url.startswith(("http://", "https://", "ftp://")):
+        import os
         import tempfile
         import urllib.request
 
+        # Private huggingface.co repos need an authenticated request. Use
+        # hf_hub_download for resolve URLs when a token is present — it handles
+        # the LFS redirect and HF_TOKEN auth correctly. Fall back to plain
+        # urllib otherwise (public files, non-HF hosts).
+        if "huggingface.co/" in path_or_url and "/resolve/" in path_or_url:
+            _hf_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+            if _hf_token:
+                try:
+                    from huggingface_hub import hf_hub_download
+
+                    _after = path_or_url.split("huggingface.co/", 1)[1]
+                    _repo_type = "model"
+                    if _after.startswith("datasets/"):
+                        _repo_type, _after = "dataset", _after[len("datasets/"):]
+                    elif _after.startswith("spaces/"):
+                        _repo_type, _after = "space", _after[len("spaces/"):]
+                    _repo_id, _file = _after.split("/resolve/", 1)
+                    _revision, _filename = _file.split("/", 1)
+                    local = hf_hub_download(
+                        repo_id=_repo_id,
+                        filename=_filename,
+                        repo_type=_repo_type,
+                        revision=_revision,
+                        token=_hf_token,
+                    )
+                    return local, False  # HF cache file — caller must not delete it
+                except Exception:
+                    pass  # fall through to unauthenticated urllib (e.g. public file)
+
         suffix = Path(path_or_url.split("?", 1)[0]).suffix or ".h5ad"
         with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
             with urllib.request.urlopen(path_or_url) as resp: