chore: handle gated HF dataset and add CI authentication support

- Improved [src/spatial_transcript_former/data/download.py] to catch 401
  Unauthorized errors from Hugging Face and output clear instructions
  for accepting dataset terms and authenticating.
- Updated [.github/workflows/ci.yml] to utilize the `HF_TOKEN` secret
  during data download and test execution steps.

Author: BenjaminIsaac0111

.github/workflows/ci.yml

@@ -31,9 +31,13 @@ jobs:
         black --check .
 
     - name: Download test data
+      env:
+        HF_TOKEN: ${{ secrets.HF_TOKEN }}
       run: |
         python scripts/download_hest.py --id TENX29 --skip-wsis --skip-patches --yes
 
     - name: Test with pytest
+      env:
+        HF_TOKEN: ${{ secrets.HF_TOKEN }}
       run: |
         pytest tests/

src/spatial_transcript_former/data/download.py

@@ -42,6 +42,23 @@ def download_metadata(local_dir: str, force: bool = False) -> str:
         logger.info(f"Metadata downloaded to {path}")
         return path
     except Exception as e:
+        if "401" in str(e) or "Unauthorized" in str(e):
+            logger.error("\n" + "=" * 60)
+            logger.error("AUTHENTICATION REQUIRED: The HEST dataset is gated.")
+            logger.error(
+                "1. Accept the dataset terms at: https://huggingface.co/datasets/MahmoodLab/hest"
+            )
+            logger.error(
+                "2. Get an access token from: https://huggingface.co/settings/tokens"
+            )
+            logger.error(
+                "3. Run 'huggingface-cli login' OR set the HF_TOKEN environment variable."
+            )
+            logger.error("=" * 60 + "\n")
+            import sys
+
+            sys.exit(1)
+
         logger.error(f"Failed to download metadata: {e}")
         raise
 
@@ -129,6 +146,23 @@ def download_hest_subset(
         )
         logger.info("Download completed successfully.")
     except Exception as e:
+        if "401" in str(e) or "Unauthorized" in str(e):
+            logger.error("\n" + "=" * 60)
+            logger.error("AUTHENTICATION REQUIRED: The HEST dataset is gated.")
+            logger.error(
+                "1. Accept the dataset terms at: https://huggingface.co/datasets/MahmoodLab/hest"
+            )
+            logger.error(
+                "2. Get an access token from: https://huggingface.co/settings/tokens"
+            )
+            logger.error(
+                "3. Run 'huggingface-cli login' OR set the HF_TOKEN environment variable."
+            )
+            logger.error("=" * 60 + "\n")
+            import sys
+
+            sys.exit(1)
+
         logger.error(f"Download failed: {e}")
         raise