Hugging Face

tensoris.lib.integrations.huggingface

Hugging Face Hub Integration Helper.

Classes

HuggingFaceIntegration

Hugging Face Hub helper for downloading datasets/models and pushing PyTorch checkpoints.

References

Hugging Face Hub Python SDK: https://huggingface.co/docs/huggingface_hub/

Source code in src/tensoris/lib/integrations/huggingface.py

class HuggingFaceIntegration:
    """Hugging Face Hub helper for downloading datasets/models and pushing PyTorch checkpoints.

    References:
        Hugging Face Hub Python SDK: https://huggingface.co/docs/huggingface_hub/
    """

    def __init__(self, token: str | None = None) -> None:
        """Initialize Hugging Face Hub client.

        Args:
            token: Optional Hugging Face User Access Token (defaults to HF_TOKEN env var).
        """
        self.token = token or os.environ.get("HF_TOKEN")

    @property
    def is_available(self) -> bool:
        """Check if huggingface_hub library is installed."""
        return _HF_AVAILABLE

    def push_model(
        self,
        repo_id: str,
        local_dir: str | Path,
        commit_message: str = "Upload model checkpoint",
    ) -> str:
        """Upload local model directory or checkpoint files to Hugging Face Hub repository.

        Args:
            repo_id: Target Hugging Face Hub repo ID (e.g. 'username/model-name').
            local_dir: Local folder path containing checkpoint weights and configs.
            commit_message: Git commit message on Hub repo.

        Returns:
            URL string of published Hugging Face repository.
        """
        if not self.is_available:
            raise RuntimeError(
                "huggingface_hub package is not installed. Install via `pip install huggingface_hub`."
            )
        api = huggingface_hub.HfApi(token=self.token)
        api.create_repo(repo_id=repo_id, exist_ok=True)
        return api.upload_folder(
            folder_path=str(local_dir),
            repo_id=repo_id,
            commit_message=commit_message,
        )

    def download_file(
        self, repo_id: str, filename: str, local_dir: str | Path = "inputs/models"
    ) -> Path:
        """Download a single model weight file from Hugging Face Hub.

        Args:
            repo_id: Source Hugging Face Hub repository ID.
            filename: Target file name (e.g. 'pytorch_model.bin').
            local_dir: Destination folder path.

        Returns:
            Path object pointing to downloaded file.
        """
        if not self.is_available:
            raise RuntimeError("huggingface_hub package is not installed.")
        downloaded = huggingface_hub.hf_hub_download(
            repo_id=repo_id,
            filename=filename,
            local_dir=str(local_dir),
            token=self.token,
        )
        return Path(downloaded)

Attributes

is_available property

is_available

Check if huggingface_hub library is installed.

Methods:

__init__

__init__(token=None)

Initialize Hugging Face Hub client.

Parameters:

Name	Type	Description	Default
token	str | None	Optional Hugging Face User Access Token (defaults to HF_TOKEN env var).	None

Source code in src/tensoris/lib/integrations/huggingface.py

def __init__(self, token: str | None = None) -> None:
    """Initialize Hugging Face Hub client.

    Args:
        token: Optional Hugging Face User Access Token (defaults to HF_TOKEN env var).
    """
    self.token = token or os.environ.get("HF_TOKEN")

download_file

download_file(repo_id, filename, local_dir='inputs/models')

Download a single model weight file from Hugging Face Hub.

Parameters:

Name	Type	Description	Default
repo_id	str	Source Hugging Face Hub repository ID.	required
filename	str	Target file name (e.g. 'pytorch_model.bin').	required
local_dir	str | Path	Destination folder path.	'inputs/models'

Returns:

Type	Description
Path	Path object pointing to downloaded file.

Source code in src/tensoris/lib/integrations/huggingface.py

def download_file(
    self, repo_id: str, filename: str, local_dir: str | Path = "inputs/models"
) -> Path:
    """Download a single model weight file from Hugging Face Hub.

    Args:
        repo_id: Source Hugging Face Hub repository ID.
        filename: Target file name (e.g. 'pytorch_model.bin').
        local_dir: Destination folder path.

    Returns:
        Path object pointing to downloaded file.
    """
    if not self.is_available:
        raise RuntimeError("huggingface_hub package is not installed.")
    downloaded = huggingface_hub.hf_hub_download(
        repo_id=repo_id,
        filename=filename,
        local_dir=str(local_dir),
        token=self.token,
    )
    return Path(downloaded)

push_model

push_model(
    repo_id,
    local_dir,
    commit_message="Upload model checkpoint",
)

Upload local model directory or checkpoint files to Hugging Face Hub repository.

Parameters:

Name	Type	Description	Default
repo_id	str	Target Hugging Face Hub repo ID (e.g. 'username/model-name').	required
local_dir	str | Path	Local folder path containing checkpoint weights and configs.	required
commit_message	str	Git commit message on Hub repo.	'Upload model checkpoint'

Returns:

Type	Description
str	URL string of published Hugging Face repository.

Source code in src/tensoris/lib/integrations/huggingface.py

def push_model(
    self,
    repo_id: str,
    local_dir: str | Path,
    commit_message: str = "Upload model checkpoint",
) -> str:
    """Upload local model directory or checkpoint files to Hugging Face Hub repository.

    Args:
        repo_id: Target Hugging Face Hub repo ID (e.g. 'username/model-name').
        local_dir: Local folder path containing checkpoint weights and configs.
        commit_message: Git commit message on Hub repo.

    Returns:
        URL string of published Hugging Face repository.
    """
    if not self.is_available:
        raise RuntimeError(
            "huggingface_hub package is not installed. Install via `pip install huggingface_hub`."
        )
    api = huggingface_hub.HfApi(token=self.token)
    api.create_repo(repo_id=repo_id, exist_ok=True)
    return api.upload_folder(
        folder_path=str(local_dir),
        repo_id=repo_id,
        commit_message=commit_message,
    )