Initialisation du repository de Beta

venv/lib/python3.12/site-packages/huggingface_hub/_commit_api.py

@@ -0,0 +1,966 @@
+"""
+Type definitions and utilities for the `create_commit` API
+"""
+
+import base64
+import io
+import os
+import warnings
+from collections import defaultdict
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from itertools import groupby
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING, Any, BinaryIO, Iterable, Iterator, Literal, Optional, Union
+
+from tqdm.contrib.concurrent import thread_map
+
+from . import constants
+from .errors import EntryNotFoundError, HfHubHTTPError, XetAuthorizationError, XetRefreshTokenError
+from .file_download import hf_hub_url
+from .lfs import UploadInfo, lfs_upload, post_lfs_batch_info
+from .utils import (
+    FORBIDDEN_FOLDERS,
+    XetTokenType,
+    are_progress_bars_disabled,
+    chunk_iterable,
+    fetch_xet_connection_info_from_repo_info,
+    get_session,
+    hf_raise_for_status,
+    http_backoff,
+    logging,
+    sha,
+    tqdm_stream_file,
+    validate_hf_hub_args,
+)
+from .utils import tqdm as hf_tqdm
+from .utils._runtime import is_xet_available
+
+
+if TYPE_CHECKING:
+    from .hf_api import RepoFile
+
+
+logger = logging.get_logger(__name__)
+
+
+UploadMode = Literal["lfs", "regular"]
+
+# Max is 1,000 per request on the Hub for HfApi.get_paths_info
+# Otherwise we get:
+# HfHubHTTPError: 413 Client Error: Payload Too Large for url: https://huggingface.co/api/datasets/xxx (Request ID: xxx)\n\ntoo many parameters
+# See https://github.com/huggingface/huggingface_hub/issues/1503
+FETCH_LFS_BATCH_SIZE = 500
+
+UPLOAD_BATCH_MAX_NUM_FILES = 256
+
+
+@dataclass
+class CommitOperationDelete:
+    """
+    Data structure holding necessary info to delete a file or a folder from a repository
+    on the Hub.
+
+    Args:
+        path_in_repo (`str`):
+            Relative filepath in the repo, for example: `"checkpoints/1fec34a/weights.bin"`
+            for a file or `"checkpoints/1fec34a/"` for a folder.
+        is_folder (`bool` or `Literal["auto"]`, *optional*)
+            Whether the Delete Operation applies to a folder or not. If "auto", the path
+            type (file or folder) is guessed automatically by looking if path ends with
+            a "/" (folder) or not (file). To explicitly set the path type, you can set
+            `is_folder=True` or `is_folder=False`.
+    """
+
+    path_in_repo: str
+    is_folder: Union[bool, Literal["auto"]] = "auto"
+
+    def __post_init__(self):
+        self.path_in_repo = _validate_path_in_repo(self.path_in_repo)
+
+        if self.is_folder == "auto":
+            self.is_folder = self.path_in_repo.endswith("/")
+        if not isinstance(self.is_folder, bool):
+            raise ValueError(
+                f"Wrong value for `is_folder`. Must be one of [`True`, `False`, `'auto'`]. Got '{self.is_folder}'."
+            )
+
+
+@dataclass
+class CommitOperationCopy:
+    """
+    Data structure holding necessary info to copy a file in a repository on the Hub.
+
+    Limitations:
+      - Only LFS files can be copied. To copy a regular file, you need to download it locally and re-upload it
+      - Cross-repository copies are not supported.
+
+    Note: you can combine a [`CommitOperationCopy`] and a [`CommitOperationDelete`] to rename an LFS file on the Hub.
+
+    Args:
+        src_path_in_repo (`str`):
+            Relative filepath in the repo of the file to be copied, e.g. `"checkpoints/1fec34a/weights.bin"`.
+        path_in_repo (`str`):
+            Relative filepath in the repo where to copy the file, e.g. `"checkpoints/1fec34a/weights_copy.bin"`.
+        src_revision (`str`, *optional*):
+            The git revision of the file to be copied. Can be any valid git revision.
+            Default to the target commit revision.
+    """
+
+    src_path_in_repo: str
+    path_in_repo: str
+    src_revision: Optional[str] = None
+    # set to the OID of the file to be copied if it has already been uploaded
+    # useful to determine if a commit will be empty or not.
+    _src_oid: Optional[str] = None
+    # set to the OID of the file to copy to if it has already been uploaded
+    # useful to determine if a commit will be empty or not.
+    _dest_oid: Optional[str] = None
+
+    def __post_init__(self):
+        self.src_path_in_repo = _validate_path_in_repo(self.src_path_in_repo)
+        self.path_in_repo = _validate_path_in_repo(self.path_in_repo)
+
+
+@dataclass
+class CommitOperationAdd:
+    """
+    Data structure holding necessary info to upload a file to a repository on the Hub.
+
+    Args:
+        path_in_repo (`str`):
+            Relative filepath in the repo, for example: `"checkpoints/1fec34a/weights.bin"`
+        path_or_fileobj (`str`, `Path`, `bytes`, or `BinaryIO`):
+            Either:
+            - a path to a local file (as `str` or `pathlib.Path`) to upload
+            - a buffer of bytes (`bytes`) holding the content of the file to upload
+            - a "file object" (subclass of `io.BufferedIOBase`), typically obtained
+                with `open(path, "rb")`. It must support `seek()` and `tell()` methods.
+
+    Raises:
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If `path_or_fileobj` is not one of `str`, `Path`, `bytes` or `io.BufferedIOBase`.
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If `path_or_fileobj` is a `str` or `Path` but not a path to an existing file.
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If `path_or_fileobj` is a `io.BufferedIOBase` but it doesn't support both
+            `seek()` and `tell()`.
+    """
+
+    path_in_repo: str
+    path_or_fileobj: Union[str, Path, bytes, BinaryIO]
+    upload_info: UploadInfo = field(init=False, repr=False)
+
+    # Internal attributes
+
+    # set to "lfs" or "regular" once known
+    _upload_mode: Optional[UploadMode] = field(init=False, repr=False, default=None)
+
+    # set to True if .gitignore rules prevent the file from being uploaded as LFS
+    # (server-side check)
+    _should_ignore: Optional[bool] = field(init=False, repr=False, default=None)
+
+    # set to the remote OID of the file if it has already been uploaded
+    # useful to determine if a commit will be empty or not
+    _remote_oid: Optional[str] = field(init=False, repr=False, default=None)
+
+    # set to True once the file has been uploaded as LFS
+    _is_uploaded: bool = field(init=False, repr=False, default=False)
+
+    # set to True once the file has been committed
+    _is_committed: bool = field(init=False, repr=False, default=False)
+
+    def __post_init__(self) -> None:
+        """Validates `path_or_fileobj` and compute `upload_info`."""
+        self.path_in_repo = _validate_path_in_repo(self.path_in_repo)
+
+        # Validate `path_or_fileobj` value
+        if isinstance(self.path_or_fileobj, Path):
+            self.path_or_fileobj = str(self.path_or_fileobj)
+        if isinstance(self.path_or_fileobj, str):
+            path_or_fileobj = os.path.normpath(os.path.expanduser(self.path_or_fileobj))
+            if not os.path.isfile(path_or_fileobj):
+                raise ValueError(f"Provided path: '{path_or_fileobj}' is not a file on the local file system")
+        elif not isinstance(self.path_or_fileobj, (io.BufferedIOBase, bytes)):
+            # ^^ Inspired from: https://stackoverflow.com/questions/44584829/how-to-determine-if-file-is-opened-in-binary-or-text-mode
+            raise ValueError(
+                "path_or_fileobj must be either an instance of str, bytes or"
+                " io.BufferedIOBase. If you passed a file-like object, make sure it is"
+                " in binary mode."
+            )
+        if isinstance(self.path_or_fileobj, io.BufferedIOBase):
+            try:
+                self.path_or_fileobj.tell()
+                self.path_or_fileobj.seek(0, os.SEEK_CUR)
+            except (OSError, AttributeError) as exc:
+                raise ValueError(
+                    "path_or_fileobj is a file-like object but does not implement seek() and tell()"
+                ) from exc
+
+        # Compute "upload_info" attribute
+        if isinstance(self.path_or_fileobj, str):
+            self.upload_info = UploadInfo.from_path(self.path_or_fileobj)
+        elif isinstance(self.path_or_fileobj, bytes):
+            self.upload_info = UploadInfo.from_bytes(self.path_or_fileobj)
+        else:
+            self.upload_info = UploadInfo.from_fileobj(self.path_or_fileobj)
+
+    @contextmanager
+    def as_file(self, with_tqdm: bool = False) -> Iterator[BinaryIO]:
+        """
+        A context manager that yields a file-like object allowing to read the underlying
+        data behind `path_or_fileobj`.
+
+        Args:
+            with_tqdm (`bool`, *optional*, defaults to `False`):
+                If True, iterating over the file object will display a progress bar. Only
+                works if the file-like object is a path to a file. Pure bytes and buffers
+                are not supported.
+
+        Example:
+
+        ```python
+        >>> operation = CommitOperationAdd(
+        ...        path_in_repo="remote/dir/weights.h5",
+        ...        path_or_fileobj="./local/weights.h5",
+        ... )
+        CommitOperationAdd(path_in_repo='remote/dir/weights.h5', path_or_fileobj='./local/weights.h5')
+
+        >>> with operation.as_file() as file:
+        ...     content = file.read()
+
+        >>> with operation.as_file(with_tqdm=True) as file:
+        ...     while True:
+        ...         data = file.read(1024)
+        ...         if not data:
+        ...              break
+        config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]
+
+        >>> with operation.as_file(with_tqdm=True) as file:
+        ...     httpx.put(..., data=file)
+        config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]
+        ```
+        """
+        if isinstance(self.path_or_fileobj, str) or isinstance(self.path_or_fileobj, Path):
+            if with_tqdm:
+                with tqdm_stream_file(self.path_or_fileobj) as file:
+                    yield file
+            else:
+                with open(self.path_or_fileobj, "rb") as file:
+                    yield file
+        elif isinstance(self.path_or_fileobj, bytes):
+            yield io.BytesIO(self.path_or_fileobj)
+        elif isinstance(self.path_or_fileobj, io.BufferedIOBase):
+            prev_pos = self.path_or_fileobj.tell()
+            yield self.path_or_fileobj
+            self.path_or_fileobj.seek(prev_pos, io.SEEK_SET)
+
+    def b64content(self) -> bytes:
+        """
+        The base64-encoded content of `path_or_fileobj`
+
+        Returns: `bytes`
+        """
+        with self.as_file() as file:
+            return base64.b64encode(file.read())
+
+    @property
+    def _local_oid(self) -> Optional[str]:
+        """Return the OID of the local file.
+
+        This OID is then compared to `self._remote_oid` to check if the file has changed compared to the remote one.
+        If the file did not change, we won't upload it again to prevent empty commits.
+
+        For LFS files, the OID corresponds to the SHA256 of the file content (used a LFS ref).
+        For regular files, the OID corresponds to the SHA1 of the file content.
+        Note: this is slightly different to git OID computation since the oid of an LFS file is usually the git-SHA1 of the
+              pointer file content (not the actual file content). However, using the SHA256 is enough to detect changes
+              and more convenient client-side.
+        """
+        if self._upload_mode is None:
+            return None
+        elif self._upload_mode == "lfs":
+            return self.upload_info.sha256.hex()
+        else:
+            # Regular file => compute sha1
+            # => no need to read by chunk since the file is guaranteed to be <=5MB.
+            with self.as_file() as file:
+                return sha.git_hash(file.read())
+
+
+def _validate_path_in_repo(path_in_repo: str) -> str:
+    # Validate `path_in_repo` value to prevent a server-side issue
+    if path_in_repo.startswith("/"):
+        path_in_repo = path_in_repo[1:]
+    if path_in_repo == "." or path_in_repo == ".." or path_in_repo.startswith("../"):
+        raise ValueError(f"Invalid `path_in_repo` in CommitOperation: '{path_in_repo}'")
+    if path_in_repo.startswith("./"):
+        path_in_repo = path_in_repo[2:]
+    for forbidden in FORBIDDEN_FOLDERS:
+        if any(part == forbidden for part in path_in_repo.split("/")):
+            raise ValueError(
+                f"Invalid `path_in_repo` in CommitOperation: cannot update files under a '{forbidden}/' folder (path:"
+                f" '{path_in_repo}')."
+            )
+    return path_in_repo
+
+
+CommitOperation = Union[CommitOperationAdd, CommitOperationCopy, CommitOperationDelete]
+
+
+def _warn_on_overwriting_operations(operations: list[CommitOperation]) -> None:
+    """
+    Warn user when a list of operations is expected to overwrite itself in a single
+    commit.
+
+    Rules:
+    - If a filepath is updated by multiple `CommitOperationAdd` operations, a warning
+      message is triggered.
+    - If a filepath is updated at least once by a `CommitOperationAdd` and then deleted
+      by a `CommitOperationDelete`, a warning is triggered.
+    - If a `CommitOperationDelete` deletes a filepath that is then updated by a
+      `CommitOperationAdd`, no warning is triggered. This is usually useless (no need to
+      delete before upload) but can happen if a user deletes an entire folder and then
+      add new files to it.
+    """
+    nb_additions_per_path: dict[str, int] = defaultdict(int)
+    for operation in operations:
+        path_in_repo = operation.path_in_repo
+        if isinstance(operation, CommitOperationAdd):
+            if nb_additions_per_path[path_in_repo] > 0:
+                warnings.warn(
+                    "About to update multiple times the same file in the same commit:"
+                    f" '{path_in_repo}'. This can cause undesired inconsistencies in"
+                    " your repo."
+                )
+            nb_additions_per_path[path_in_repo] += 1
+            for parent in PurePosixPath(path_in_repo).parents:
+                # Also keep track of number of updated files per folder
+                # => warns if deleting a folder overwrite some contained files
+                nb_additions_per_path[str(parent)] += 1
+        if isinstance(operation, CommitOperationDelete):
+            if nb_additions_per_path[str(PurePosixPath(path_in_repo))] > 0:
+                if operation.is_folder:
+                    warnings.warn(
+                        "About to delete a folder containing files that have just been"
+                        f" updated within the same commit: '{path_in_repo}'. This can"
+                        " cause undesired inconsistencies in your repo."
+                    )
+                else:
+                    warnings.warn(
+                        "About to delete a file that have just been updated within the"
+                        f" same commit: '{path_in_repo}'. This can cause undesired"
+                        " inconsistencies in your repo."
+                    )
+
+
+@validate_hf_hub_args
+def _upload_files(
+    *,
+    additions: list[CommitOperationAdd],
+    repo_type: str,
+    repo_id: str,
+    headers: dict[str, str],
+    endpoint: Optional[str] = None,
+    num_threads: int = 5,
+    revision: Optional[str] = None,
+    create_pr: Optional[bool] = None,
+):
+    """
+    Negotiates per-file transfer (LFS vs Xet) and uploads in batches.
+    """
+    xet_additions: list[CommitOperationAdd] = []
+    lfs_actions: list[dict[str, Any]] = []
+    lfs_oid2addop: dict[str, CommitOperationAdd] = {}
+
+    for chunk in chunk_iterable(additions, chunk_size=UPLOAD_BATCH_MAX_NUM_FILES):
+        chunk_list = [op for op in chunk]
+
+        transfers: list[str] = ["basic", "multipart"]
+        has_buffered_io_data = any(isinstance(op.path_or_fileobj, io.BufferedIOBase) for op in chunk_list)
+        if is_xet_available():
+            if not has_buffered_io_data:
+                transfers.append("xet")
+            else:
+                logger.warning(
+                    "Uploading files as a binary IO buffer is not supported by Xet Storage. "
+                    "Falling back to HTTP upload."
+                )
+
+        actions_chunk, errors_chunk, chosen_transfer = post_lfs_batch_info(
+            upload_infos=[op.upload_info for op in chunk_list],
+            repo_id=repo_id,
+            repo_type=repo_type,
+            revision=revision,
+            endpoint=endpoint,
+            headers=headers,
+            token=None,  # already passed in 'headers'
+            transfers=transfers,
+        )
+        if errors_chunk:
+            message = "\n".join(
+                [
+                    f"Encountered error for file with OID {err.get('oid')}: `{err.get('error', {}).get('message')}"
+                    for err in errors_chunk
+                ]
+            )
+            raise ValueError(f"LFS batch API returned errors:\n{message}")
+
+        # If server returns a transfer we didn't offer (e.g "xet" while uploading from BytesIO),
+        # fall back to LFS for this chunk.
+        if chosen_transfer == "xet" and ("xet" in transfers):
+            xet_additions.extend(chunk_list)
+        else:
+            lfs_actions.extend(actions_chunk)
+            for op in chunk_list:
+                lfs_oid2addop[op.upload_info.sha256.hex()] = op
+
+    if len(lfs_actions) > 0:
+        _upload_lfs_files(
+            actions=lfs_actions,
+            oid2addop=lfs_oid2addop,
+            headers=headers,
+            endpoint=endpoint,
+            num_threads=num_threads,
+        )
+
+    if len(xet_additions) > 0:
+        _upload_xet_files(
+            additions=xet_additions,
+            repo_type=repo_type,
+            repo_id=repo_id,
+            headers=headers,
+            endpoint=endpoint,
+            revision=revision,
+            create_pr=create_pr,
+        )
+
+
+@validate_hf_hub_args
+def _upload_lfs_files(
+    *,
+    actions: list[dict[str, Any]],
+    oid2addop: dict[str, CommitOperationAdd],
+    headers: dict[str, str],
+    endpoint: Optional[str] = None,
+    num_threads: int = 5,
+):
+    """
+    Uploads the content of `additions` to the Hub using the large file storage protocol.
+
+    Relevant external documentation:
+        - LFS Batch API: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md
+
+    Args:
+        actions (`list[dict[str, Any]]`):
+            LFS batch actions returned by the server.
+        oid2addop (`dict[str, CommitOperationAdd]`):
+            A dictionary mapping the OID of the file to the corresponding `CommitOperationAdd` object.
+        headers (`dict[str, str]`):
+            Headers to use for the request, including authorization headers and user agent.
+        endpoint (`str`, *optional*):
+            The endpoint to use for the request. Defaults to `constants.ENDPOINT`.
+        num_threads (`int`, *optional*):
+            The number of concurrent threads to use when uploading. Defaults to 5.
+
+    Raises:
+        [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+            If an upload failed for any reason
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`.
+        repo_id (`str`):
+            A namespace (user or an organization) and a repo name separated
+            by a `/`.
+        headers (`dict[str, str]`):
+            Headers to use for the request, including authorization headers and user agent.
+        num_threads (`int`, *optional*):
+            The number of concurrent threads to use when uploading. Defaults to 5.
+        revision (`str`, *optional*):
+            The git revision to upload to.
+
+    Raises:
+        [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+            If an upload failed for any reason
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If the server returns malformed responses
+        [`HfHubHTTPError`]
+            If the LFS batch endpoint returned an HTTP error.
+    """
+    # Filter out files already present upstream
+    filtered_actions = []
+    for action in actions:
+        if action.get("actions") is None:
+            logger.debug(
+                f"Content of file {oid2addop[action['oid']].path_in_repo} is already present upstream - skipping upload."
+            )
+        else:
+            filtered_actions.append(action)
+
+    # Upload according to server-provided actions
+    def _wrapped_lfs_upload(batch_action) -> None:
+        try:
+            operation = oid2addop[batch_action["oid"]]
+            lfs_upload(operation=operation, lfs_batch_action=batch_action, headers=headers, endpoint=endpoint)
+        except Exception as exc:
+            raise RuntimeError(f"Error while uploading '{operation.path_in_repo}' to the Hub.") from exc
+
+    if len(filtered_actions) == 1:
+        logger.debug("Uploading 1 LFS file to the Hub")
+        _wrapped_lfs_upload(filtered_actions[0])
+    else:
+        logger.debug(
+            f"Uploading {len(filtered_actions)} LFS files to the Hub using up to {num_threads} threads concurrently"
+        )
+        thread_map(
+            _wrapped_lfs_upload,
+            filtered_actions,
+            desc=f"Upload {len(filtered_actions)} LFS files",
+            max_workers=num_threads,
+            tqdm_class=hf_tqdm,
+        )
+
+
+@validate_hf_hub_args
+def _upload_xet_files(
+    *,
+    additions: list[CommitOperationAdd],
+    repo_type: str,
+    repo_id: str,
+    headers: dict[str, str],
+    endpoint: Optional[str] = None,
+    revision: Optional[str] = None,
+    create_pr: Optional[bool] = None,
+):
+    """
+    Uploads the content of `additions` to the Hub using the xet storage protocol.
+    This chunks the files and deduplicates the chunks before uploading them to xetcas storage.
+
+    Args:
+        additions (`` of `CommitOperationAdd`):
+            The files to be uploaded.
+        repo_type (`str`):
+            Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`.
+        repo_id (`str`):
+            A namespace (user or an organization) and a repo name separated
+            by a `/`.
+        headers (`dict[str, str]`):
+            Headers to use for the request, including authorization headers and user agent.
+        endpoint: (`str`, *optional*):
+            The endpoint to use for the xetcas service. Defaults to `constants.ENDPOINT`.
+        revision (`str`, *optional*):
+            The git revision to upload to.
+        create_pr (`bool`, *optional*):
+            Whether or not to create a Pull Request with that commit.
+
+    Raises:
+        [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+            If an upload failed for any reason.
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If the server returns malformed responses or if the user is unauthorized to upload to xet storage.
+        [`HfHubHTTPError`]
+            If the LFS batch endpoint returned an HTTP error.
+
+    **How it works:**
+        The file download system uses Xet storage, which is a content-addressable storage system that breaks files into chunks
+            for efficient storage and transfer.
+
+        `hf_xet.upload_files` manages uploading files by:
+            - Taking a list of file paths to upload
+            - Breaking files into smaller chunks for efficient storage
+            - Avoiding duplicate storage by recognizing identical chunks across files
+            - Connecting to a storage server (CAS server) that manages these chunks
+
+        The upload process works like this:
+        1. Create a local folder at ~/.cache/huggingface/xet/chunk-cache to store file chunks for reuse.
+        2. Process files in parallel (up to 8 files at once):
+            2.1. Read the file content.
+            2.2. Split the file content into smaller chunks based on content patterns: each chunk gets a unique ID based on what's in it.
+            2.3. For each chunk:
+                - Check if it already exists in storage.
+                - Skip uploading chunks that already exist.
+            2.4. Group chunks into larger blocks for efficient transfer.
+            2.5. Upload these blocks to the storage server.
+            2.6. Create and upload information about how the file is structured.
+        3. Return reference files that contain information about the uploaded files, which can be used later to download them.
+    """
+    if len(additions) == 0:
+        return
+
+    # at this point, we know that hf_xet is installed
+    from hf_xet import upload_bytes, upload_files
+
+    from .utils._xet_progress_reporting import XetProgressReporter
+
+    try:
+        xet_connection_info = fetch_xet_connection_info_from_repo_info(
+            token_type=XetTokenType.WRITE,
+            repo_id=repo_id,
+            repo_type=repo_type,
+            revision=revision,
+            headers=headers,
+            endpoint=endpoint,
+            params={"create_pr": "1"} if create_pr else None,
+        )
+    except HfHubHTTPError as e:
+        if e.response.status_code == 401:
+            raise XetAuthorizationError(
+                f"You are unauthorized to upload to xet storage for {repo_type}/{repo_id}. "
+                f"Please check that you have configured your access token with write access to the repo."
+            ) from e
+        raise
+
+    xet_endpoint = xet_connection_info.endpoint
+    access_token_info = (xet_connection_info.access_token, xet_connection_info.expiration_unix_epoch)
+
+    def token_refresher() -> tuple[str, int]:
+        new_xet_connection = fetch_xet_connection_info_from_repo_info(
+            token_type=XetTokenType.WRITE,
+            repo_id=repo_id,
+            repo_type=repo_type,
+            revision=revision,
+            headers=headers,
+            endpoint=endpoint,
+            params={"create_pr": "1"} if create_pr else None,
+        )
+        if new_xet_connection is None:
+            raise XetRefreshTokenError("Failed to refresh xet token")
+        return new_xet_connection.access_token, new_xet_connection.expiration_unix_epoch
+
+    if not are_progress_bars_disabled():
+        progress = XetProgressReporter()
+        progress_callback = progress.update_progress
+    else:
+        progress, progress_callback = None, None
+
+    try:
+        all_bytes_ops = [op for op in additions if isinstance(op.path_or_fileobj, bytes)]
+        all_paths_ops = [op for op in additions if isinstance(op.path_or_fileobj, (str, Path))]
+
+        if len(all_paths_ops) > 0:
+            all_paths = [str(op.path_or_fileobj) for op in all_paths_ops]
+            upload_files(
+                all_paths,
+                xet_endpoint,
+                access_token_info,
+                token_refresher,
+                progress_callback,
+                repo_type,
+            )
+
+        if len(all_bytes_ops) > 0:
+            all_bytes = [op.path_or_fileobj for op in all_bytes_ops]
+            upload_bytes(
+                all_bytes,
+                xet_endpoint,
+                access_token_info,
+                token_refresher,
+                progress_callback,
+                repo_type,
+            )
+
+    finally:
+        if progress is not None:
+            progress.close(False)
+
+    return
+
+
+def _validate_preupload_info(preupload_info: dict):
+    files = preupload_info.get("files")
+    if not isinstance(files, list):
+        raise ValueError("preupload_info is improperly formatted")
+    for file_info in files:
+        if not (
+            isinstance(file_info, dict)
+            and isinstance(file_info.get("path"), str)
+            and isinstance(file_info.get("uploadMode"), str)
+            and (file_info["uploadMode"] in ("lfs", "regular"))
+        ):
+            raise ValueError("preupload_info is improperly formatted:")
+    return preupload_info
+
+
+@validate_hf_hub_args
+def _fetch_upload_modes(
+    additions: Iterable[CommitOperationAdd],
+    repo_type: str,
+    repo_id: str,
+    headers: dict[str, str],
+    revision: str,
+    endpoint: Optional[str] = None,
+    create_pr: bool = False,
+    gitignore_content: Optional[str] = None,
+) -> None:
+    """
+    Requests the Hub "preupload" endpoint to determine whether each input file should be uploaded as a regular git blob,
+    as a git LFS blob, or as a XET file. Input `additions` are mutated in-place with the upload mode.
+
+    Args:
+        additions (`Iterable` of :class:`CommitOperationAdd`):
+            Iterable of :class:`CommitOperationAdd` describing the files to
+            upload to the Hub.
+        repo_type (`str`):
+            Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`.
+        repo_id (`str`):
+            A namespace (user or an organization) and a repo name separated
+            by a `/`.
+        headers (`dict[str, str]`):
+            Headers to use for the request, including authorization headers and user agent.
+        revision (`str`):
+            The git revision to upload the files to. Can be any valid git revision.
+        gitignore_content (`str`, *optional*):
+            The content of the `.gitignore` file to know which files should be ignored. The order of priority
+            is to first check if `gitignore_content` is passed, then check if the `.gitignore` file is present
+            in the list of files to commit and finally default to the `.gitignore` file already hosted on the Hub
+            (if any).
+    Raises:
+        [`~utils.HfHubHTTPError`]
+            If the Hub API returned an error.
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If the Hub API response is improperly formatted.
+    """
+    endpoint = endpoint if endpoint is not None else constants.ENDPOINT
+
+    # Fetch upload mode (LFS or regular) chunk by chunk.
+    upload_modes: dict[str, UploadMode] = {}
+    should_ignore_info: dict[str, bool] = {}
+    oid_info: dict[str, Optional[str]] = {}
+
+    for chunk in chunk_iterable(additions, 256):
+        payload: dict = {
+            "files": [
+                {
+                    "path": op.path_in_repo,
+                    "sample": base64.b64encode(op.upload_info.sample).decode("ascii"),
+                    "size": op.upload_info.size,
+                }
+                for op in chunk
+            ]
+        }
+        if gitignore_content is not None:
+            payload["gitIgnore"] = gitignore_content
+
+        resp = http_backoff(
+            "POST",
+            f"{endpoint}/api/{repo_type}s/{repo_id}/preupload/{revision}",
+            json=payload,
+            headers=headers,
+            params={"create_pr": "1"} if create_pr else None,
+        )
+        hf_raise_for_status(resp)
+        preupload_info = _validate_preupload_info(resp.json())
+        upload_modes.update(**{file["path"]: file["uploadMode"] for file in preupload_info["files"]})
+        should_ignore_info.update(**{file["path"]: file["shouldIgnore"] for file in preupload_info["files"]})
+        oid_info.update(**{file["path"]: file.get("oid") for file in preupload_info["files"]})
+
+    # Set upload mode for each addition operation
+    for addition in additions:
+        addition._upload_mode = upload_modes[addition.path_in_repo]
+        addition._should_ignore = should_ignore_info[addition.path_in_repo]
+        addition._remote_oid = oid_info[addition.path_in_repo]
+
+    # Empty files cannot be uploaded as LFS (S3 would fail with a 501 Not Implemented)
+    # => empty files are uploaded as "regular" to still allow users to commit them.
+    for addition in additions:
+        if addition.upload_info.size == 0:
+            addition._upload_mode = "regular"
+
+
+@validate_hf_hub_args
+def _fetch_files_to_copy(
+    copies: Iterable[CommitOperationCopy],
+    repo_type: str,
+    repo_id: str,
+    headers: dict[str, str],
+    revision: str,
+    endpoint: Optional[str] = None,
+) -> dict[tuple[str, Optional[str]], Union["RepoFile", bytes]]:
+    """
+    Fetch information about the files to copy.
+
+    For LFS files, we only need their metadata (file size and sha256) while for regular files
+    we need to download the raw content from the Hub.
+
+    Args:
+        copies (`Iterable` of :class:`CommitOperationCopy`):
+            Iterable of :class:`CommitOperationCopy` describing the files to
+            copy on the Hub.
+        repo_type (`str`):
+            Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`.
+        repo_id (`str`):
+            A namespace (user or an organization) and a repo name separated
+            by a `/`.
+        headers (`dict[str, str]`):
+            Headers to use for the request, including authorization headers and user agent.
+        revision (`str`):
+            The git revision to upload the files to. Can be any valid git revision.
+
+    Returns: `dict[tuple[str, Optional[str]], Union[RepoFile, bytes]]]`
+        Key is the file path and revision of the file to copy.
+        Value is the raw content as bytes (for regular files) or the file information as a RepoFile (for LFS files).
+
+    Raises:
+        [`~utils.HfHubHTTPError`]
+            If the Hub API returned an error.
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If the Hub API response is improperly formatted.
+    """
+    from .hf_api import HfApi, RepoFolder
+
+    hf_api = HfApi(endpoint=endpoint, headers=headers)
+    files_to_copy: dict[tuple[str, Optional[str]], Union["RepoFile", bytes]] = {}
+    # Store (path, revision) -> oid mapping
+    oid_info: dict[tuple[str, Optional[str]], Optional[str]] = {}
+    # 1. Fetch OIDs for destination paths in batches.
+    dest_paths = [op.path_in_repo for op in copies]
+    for offset in range(0, len(dest_paths), FETCH_LFS_BATCH_SIZE):
+        dest_repo_files = hf_api.get_paths_info(
+            repo_id=repo_id,
+            paths=dest_paths[offset : offset + FETCH_LFS_BATCH_SIZE],
+            revision=revision,
+            repo_type=repo_type,
+        )
+        for file in dest_repo_files:
+            if not isinstance(file, RepoFolder):
+                oid_info[(file.path, revision)] = file.blob_id
+
+    # 2. Group by source revision and fetch source file info in batches.
+    for src_revision, operations in groupby(copies, key=lambda op: op.src_revision):
+        operations = list(operations)  # type: ignore
+        src_paths = [op.src_path_in_repo for op in operations]
+        for offset in range(0, len(src_paths), FETCH_LFS_BATCH_SIZE):
+            src_repo_files = hf_api.get_paths_info(
+                repo_id=repo_id,
+                paths=src_paths[offset : offset + FETCH_LFS_BATCH_SIZE],
+                revision=src_revision or revision,
+                repo_type=repo_type,
+            )
+
+            for src_repo_file in src_repo_files:
+                if isinstance(src_repo_file, RepoFolder):
+                    raise NotImplementedError("Copying a folder is not implemented.")
+                oid_info[(src_repo_file.path, src_revision)] = src_repo_file.blob_id
+                # If it's an LFS file, store the RepoFile object. Otherwise, download raw bytes.
+                if src_repo_file.lfs:
+                    files_to_copy[(src_repo_file.path, src_revision)] = src_repo_file
+                else:
+                    # TODO: (optimization) download regular files to copy concurrently
+                    url = hf_hub_url(
+                        endpoint=endpoint,
+                        repo_type=repo_type,
+                        repo_id=repo_id,
+                        revision=src_revision or revision,
+                        filename=src_repo_file.path,
+                    )
+                    response = get_session().get(url, headers=headers)
+                    hf_raise_for_status(response)
+                    files_to_copy[(src_repo_file.path, src_revision)] = response.content
+        # 3. Ensure all operations found a corresponding file in the Hub
+        #  and track src/dest OIDs for each operation.
+        for operation in operations:
+            if (operation.src_path_in_repo, src_revision) not in files_to_copy:
+                raise EntryNotFoundError(
+                    f"Cannot copy {operation.src_path_in_repo} at revision "
+                    f"{src_revision or revision}: file is missing on repo."
+                )
+            operation._src_oid = oid_info.get((operation.src_path_in_repo, operation.src_revision))
+            operation._dest_oid = oid_info.get((operation.path_in_repo, revision))
+    return files_to_copy
+
+
+def _prepare_commit_payload(
+    operations: Iterable[CommitOperation],
+    files_to_copy: dict[tuple[str, Optional[str]], Union["RepoFile", bytes]],
+    commit_message: str,
+    commit_description: Optional[str] = None,
+    parent_commit: Optional[str] = None,
+) -> Iterable[dict[str, Any]]:
+    """
+    Builds the payload to POST to the `/commit` API of the Hub.
+
+    Payload is returned as an iterator so that it can be streamed as a ndjson in the
+    POST request.
+
+    For more information, see:
+        - https://github.com/huggingface/huggingface_hub/issues/1085#issuecomment-1265208073
+        - http://ndjson.org/
+    """
+    commit_description = commit_description if commit_description is not None else ""
+
+    # 1. Send a header item with the commit metadata
+    header_value = {"summary": commit_message, "description": commit_description}
+    if parent_commit is not None:
+        header_value["parentCommit"] = parent_commit
+    yield {"key": "header", "value": header_value}
+
+    nb_ignored_files = 0
+
+    # 2. Send operations, one per line
+    for operation in operations:
+        # Skip ignored files
+        if isinstance(operation, CommitOperationAdd) and operation._should_ignore:
+            logger.debug(f"Skipping file '{operation.path_in_repo}' in commit (ignored by gitignore file).")
+            nb_ignored_files += 1
+            continue
+
+        # 2.a. Case adding a regular file
+        if isinstance(operation, CommitOperationAdd) and operation._upload_mode == "regular":
+            yield {
+                "key": "file",
+                "value": {
+                    "content": operation.b64content().decode(),
+                    "path": operation.path_in_repo,
+                    "encoding": "base64",
+                },
+            }
+        # 2.b. Case adding an LFS file
+        elif isinstance(operation, CommitOperationAdd) and operation._upload_mode == "lfs":
+            yield {
+                "key": "lfsFile",
+                "value": {
+                    "path": operation.path_in_repo,
+                    "algo": "sha256",
+                    "oid": operation.upload_info.sha256.hex(),
+                    "size": operation.upload_info.size,
+                },
+            }
+        # 2.c. Case deleting a file or folder
+        elif isinstance(operation, CommitOperationDelete):
+            yield {
+                "key": "deletedFolder" if operation.is_folder else "deletedFile",
+                "value": {"path": operation.path_in_repo},
+            }
+        # 2.d. Case copying a file or folder
+        elif isinstance(operation, CommitOperationCopy):
+            file_to_copy = files_to_copy[(operation.src_path_in_repo, operation.src_revision)]
+            if isinstance(file_to_copy, bytes):
+                yield {
+                    "key": "file",
+                    "value": {
+                        "content": base64.b64encode(file_to_copy).decode(),
+                        "path": operation.path_in_repo,
+                        "encoding": "base64",
+                    },
+                }
+            elif file_to_copy.lfs:
+                yield {
+                    "key": "lfsFile",
+                    "value": {
+                        "path": operation.path_in_repo,
+                        "algo": "sha256",
+                        "oid": file_to_copy.lfs.sha256,
+                    },
+                }
+            else:
+                raise ValueError(
+                    "Malformed files_to_copy (should be raw file content as bytes or RepoFile objects with LFS info."
+                )
+        # 2.e. Never expected to happen
+        else:
+            raise ValueError(
+                f"Unknown operation to commit. Operation: {operation}. Upload mode:"
+                f" {getattr(operation, '_upload_mode', None)}"
+            )
+
+    if nb_ignored_files > 0:
+        logger.info(f"Skipped {nb_ignored_files} file(s) in commit (ignored by gitignore file).")

venv/lib/python3.12/site-packages/huggingface_hub/_commit_scheduler.py

@@ -0,0 +1,353 @@
+import atexit
+import logging
+import os
+import time
+from concurrent.futures import Future
+from dataclasses import dataclass
+from io import SEEK_END, SEEK_SET, BytesIO
+from pathlib import Path
+from threading import Lock, Thread
+from typing import Optional, Union
+
+from .hf_api import DEFAULT_IGNORE_PATTERNS, CommitInfo, CommitOperationAdd, HfApi
+from .utils import filter_repo_objects
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class _FileToUpload:
+    """Temporary dataclass to store info about files to upload. Not meant to be used directly."""
+
+    local_path: Path
+    path_in_repo: str
+    size_limit: int
+    last_modified: float
+
+
+class CommitScheduler:
+    """
+    Scheduler to upload a local folder to the Hub at regular intervals (e.g. push to hub every 5 minutes).
+
+    The recommended way to use the scheduler is to use it as a context manager. This ensures that the scheduler is
+    properly stopped and the last commit is triggered when the script ends. The scheduler can also be stopped manually
+    with the `stop` method. Checkout the [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#scheduled-uploads)
+    to learn more about how to use it.
+
+    Args:
+        repo_id (`str`):
+            The id of the repo to commit to.
+        folder_path (`str` or `Path`):
+            Path to the local folder to upload regularly.
+        every (`int` or `float`, *optional*):
+            The number of minutes between each commit. Defaults to 5 minutes.
+        path_in_repo (`str`, *optional*):
+            Relative path of the directory in the repo, for example: `"checkpoints/"`. Defaults to the root folder
+            of the repository.
+        repo_type (`str`, *optional*):
+            The type of the repo to commit to. Defaults to `model`.
+        revision (`str`, *optional*):
+            The revision of the repo to commit to. Defaults to `main`.
+        private (`bool`, *optional*):
+            Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists.
+        token (`str`, *optional*):
+            The token to use to commit to the repo. Defaults to the token saved on the machine.
+        allow_patterns (`list[str]` or `str`, *optional*):
+            If provided, only files matching at least one pattern are uploaded.
+        ignore_patterns (`list[str]` or `str`, *optional*):
+            If provided, files matching any of the patterns are not uploaded.
+        squash_history (`bool`, *optional*):
+            Whether to squash the history of the repo after each commit. Defaults to `False`. Squashing commits is
+            useful to avoid degraded performances on the repo when it grows too large.
+        hf_api (`HfApi`, *optional*):
+            The [`HfApi`] client to use to commit to the Hub. Can be set with custom settings (user agent, token,...).
+
+    Example:
+    ```py
+    >>> from pathlib import Path
+    >>> from huggingface_hub import CommitScheduler
+
+    # Scheduler uploads every 10 minutes
+    >>> csv_path = Path("watched_folder/data.csv")
+    >>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10)
+
+    >>> with csv_path.open("a") as f:
+    ...     f.write("first line")
+
+    # Some time later (...)
+    >>> with csv_path.open("a") as f:
+    ...     f.write("second line")
+    ```
+
+    Example using a context manager:
+    ```py
+    >>> from pathlib import Path
+    >>> from huggingface_hub import CommitScheduler
+
+    >>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler:
+    ...     csv_path = Path("watched_folder/data.csv")
+    ...     with csv_path.open("a") as f:
+    ...         f.write("first line")
+    ...     (...)
+    ...     with csv_path.open("a") as f:
+    ...         f.write("second line")
+
+    # Scheduler is now stopped and last commit have been triggered
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        repo_id: str,
+        folder_path: Union[str, Path],
+        every: Union[int, float] = 5,
+        path_in_repo: Optional[str] = None,
+        repo_type: Optional[str] = None,
+        revision: Optional[str] = None,
+        private: Optional[bool] = None,
+        token: Optional[str] = None,
+        allow_patterns: Optional[Union[list[str], str]] = None,
+        ignore_patterns: Optional[Union[list[str], str]] = None,
+        squash_history: bool = False,
+        hf_api: Optional["HfApi"] = None,
+    ) -> None:
+        self.api = hf_api or HfApi(token=token)
+
+        # Folder
+        self.folder_path = Path(folder_path).expanduser().resolve()
+        self.path_in_repo = path_in_repo or ""
+        self.allow_patterns = allow_patterns
+
+        if ignore_patterns is None:
+            ignore_patterns = []
+        elif isinstance(ignore_patterns, str):
+            ignore_patterns = [ignore_patterns]
+        self.ignore_patterns = ignore_patterns + DEFAULT_IGNORE_PATTERNS
+
+        if self.folder_path.is_file():
+            raise ValueError(f"'folder_path' must be a directory, not a file: '{self.folder_path}'.")
+        self.folder_path.mkdir(parents=True, exist_ok=True)
+
+        # Repository
+        repo_url = self.api.create_repo(repo_id=repo_id, private=private, repo_type=repo_type, exist_ok=True)
+        self.repo_id = repo_url.repo_id
+        self.repo_type = repo_type
+        self.revision = revision
+        self.token = token
+
+        # Keep track of already uploaded files
+        self.last_uploaded: dict[Path, float] = {}  # key is local path, value is timestamp
+
+        # Scheduler
+        if not every > 0:
+            raise ValueError(f"'every' must be a positive integer, not '{every}'.")
+        self.lock = Lock()
+        self.every = every
+        self.squash_history = squash_history
+
+        logger.info(f"Scheduled job to push '{self.folder_path}' to '{self.repo_id}' every {self.every} minutes.")
+        self._scheduler_thread = Thread(target=self._run_scheduler, daemon=True)
+        self._scheduler_thread.start()
+        atexit.register(self._push_to_hub)
+
+        self.__stopped = False
+
+    def stop(self) -> None:
+        """Stop the scheduler.
+
+        A stopped scheduler cannot be restarted. Mostly for tests purposes.
+        """
+        self.__stopped = True
+
+    def __enter__(self) -> "CommitScheduler":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        # Upload last changes before exiting
+        self.trigger().result()
+        self.stop()
+        return
+
+    def _run_scheduler(self) -> None:
+        """Dumb thread waiting between each scheduled push to Hub."""
+        while True:
+            self.last_future = self.trigger()
+            time.sleep(self.every * 60)
+            if self.__stopped:
+                break
+
+    def trigger(self) -> Future:
+        """Trigger a `push_to_hub` and return a future.
+
+        This method is automatically called every `every` minutes. You can also call it manually to trigger a commit
+        immediately, without waiting for the next scheduled commit.
+        """
+        return self.api.run_as_future(self._push_to_hub)
+
+    def _push_to_hub(self) -> Optional[CommitInfo]:
+        if self.__stopped:  # If stopped, already scheduled commits are ignored
+            return None
+
+        logger.info("(Background) scheduled commit triggered.")
+        try:
+            value = self.push_to_hub()
+            if self.squash_history:
+                logger.info("(Background) squashing repo history.")
+                self.api.super_squash_history(repo_id=self.repo_id, repo_type=self.repo_type, branch=self.revision)
+            return value
+        except Exception as e:
+            logger.error(f"Error while pushing to Hub: {e}")  # Depending on the setup, error might be silenced
+            raise
+
+    def push_to_hub(self) -> Optional[CommitInfo]:
+        """
+        Push folder to the Hub and return the commit info.
+
+        > [!WARNING]
+        > This method is not meant to be called directly. It is run in the background by the scheduler, respecting a
+        > queue mechanism to avoid concurrent commits. Making a direct call to the method might lead to concurrency
+        > issues.
+
+        The default behavior of `push_to_hub` is to assume an append-only folder. It lists all files in the folder and
+        uploads only changed files. If no changes are found, the method returns without committing anything. If you want
+        to change this behavior, you can inherit from [`CommitScheduler`] and override this method. This can be useful
+        for example to compress data together in a single file before committing. For more details and examples, check
+        out our [integration guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload#scheduled-uploads).
+        """
+        # Check files to upload (with lock)
+        with self.lock:
+            logger.debug("Listing files to upload for scheduled commit.")
+
+            # List files from folder (taken from `_prepare_upload_folder_additions`)
+            relpath_to_abspath = {
+                path.relative_to(self.folder_path).as_posix(): path
+                for path in sorted(self.folder_path.glob("**/*"))  # sorted to be deterministic
+                if path.is_file()
+            }
+            prefix = f"{self.path_in_repo.strip('/')}/" if self.path_in_repo else ""
+
+            # Filter with pattern + filter out unchanged files + retrieve current file size
+            files_to_upload: list[_FileToUpload] = []
+            for relpath in filter_repo_objects(
+                relpath_to_abspath.keys(), allow_patterns=self.allow_patterns, ignore_patterns=self.ignore_patterns
+            ):
+                local_path = relpath_to_abspath[relpath]
+                stat = local_path.stat()
+                if self.last_uploaded.get(local_path) is None or self.last_uploaded[local_path] != stat.st_mtime:
+                    files_to_upload.append(
+                        _FileToUpload(
+                            local_path=local_path,
+                            path_in_repo=prefix + relpath,
+                            size_limit=stat.st_size,
+                            last_modified=stat.st_mtime,
+                        )
+                    )
+
+        # Return if nothing to upload
+        if len(files_to_upload) == 0:
+            logger.debug("Dropping schedule commit: no changed file to upload.")
+            return None
+
+        # Convert `_FileToUpload` as `CommitOperationAdd` (=> compute file shas + limit to file size)
+        logger.debug("Removing unchanged files since previous scheduled commit.")
+        add_operations = [
+            CommitOperationAdd(
+                # Cap the file to its current size, even if the user append data to it while a scheduled commit is happening
+                path_or_fileobj=PartialFileIO(file_to_upload.local_path, size_limit=file_to_upload.size_limit),
+                path_in_repo=file_to_upload.path_in_repo,
+            )
+            for file_to_upload in files_to_upload
+        ]
+
+        # Upload files (append mode expected - no need for lock)
+        logger.debug("Uploading files for scheduled commit.")
+        commit_info = self.api.create_commit(
+            repo_id=self.repo_id,
+            repo_type=self.repo_type,
+            operations=add_operations,
+            commit_message="Scheduled Commit",
+            revision=self.revision,
+        )
+
+        # Successful commit: keep track of the latest "last_modified" for each file
+        for file in files_to_upload:
+            self.last_uploaded[file.local_path] = file.last_modified
+        return commit_info
+
+
+class PartialFileIO(BytesIO):
+    """A file-like object that reads only the first part of a file.
+
+    Useful to upload a file to the Hub when the user might still be appending data to it. Only the first part of the
+    file is uploaded (i.e. the part that was available when the filesystem was first scanned).
+
+    In practice, only used internally by the CommitScheduler to regularly push a folder to the Hub with minimal
+    disturbance for the user. The object is passed to `CommitOperationAdd`.
+
+    Only supports `read`, `tell` and `seek` methods.
+
+    Args:
+        file_path (`str` or `Path`):
+            Path to the file to read.
+        size_limit (`int`):
+            The maximum number of bytes to read from the file. If the file is larger than this, only the first part
+            will be read (and uploaded).
+    """
+
+    def __init__(self, file_path: Union[str, Path], size_limit: int) -> None:
+        self._file_path = Path(file_path)
+        self._file = self._file_path.open("rb")
+        self._size_limit = min(size_limit, os.fstat(self._file.fileno()).st_size)
+
+    def __del__(self) -> None:
+        self._file.close()
+        return super().__del__()
+
+    def __repr__(self) -> str:
+        return f"<PartialFileIO file_path={self._file_path} size_limit={self._size_limit}>"
+
+    def __len__(self) -> int:
+        return self._size_limit
+
+    def __getattribute__(self, name: str):
+        if name.startswith("_") or name in ("read", "tell", "seek", "fileno"):  # only 4 public methods supported
+            return super().__getattribute__(name)
+        raise NotImplementedError(f"PartialFileIO does not support '{name}'.")
+
+    def fileno(self):
+        raise AttributeError("PartialFileIO does not have a fileno.")
+
+    def tell(self) -> int:
+        """Return the current file position."""
+        return self._file.tell()
+
+    def seek(self, __offset: int, __whence: int = SEEK_SET) -> int:
+        """Change the stream position to the given offset.
+
+        Behavior is the same as a regular file, except that the position is capped to the size limit.
+        """
+        if __whence == SEEK_END:
+            # SEEK_END => set from the truncated end
+            __offset = len(self) + __offset
+            __whence = SEEK_SET
+
+        pos = self._file.seek(__offset, __whence)
+        if pos > self._size_limit:
+            return self._file.seek(self._size_limit)
+        return pos
+
+    def read(self, __size: Optional[int] = -1) -> bytes:
+        """Read at most `__size` bytes from the file.
+
+        Behavior is the same as a regular file, except that it is capped to the size limit.
+        """
+        current = self._file.tell()
+        if __size is None or __size < 0:
+            # Read until file limit
+            truncated_size = self._size_limit - current
+        else:
+            # Read until file limit or __size
+            truncated_size = min(__size, self._size_limit - current)
+        return self._file.read(truncated_size)

venv/lib/python3.12/site-packages/huggingface_hub/_inference_endpoints.py

@@ -0,0 +1,418 @@
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import TYPE_CHECKING, Optional, Union
+
+from huggingface_hub.errors import InferenceEndpointError, InferenceEndpointTimeoutError
+
+from .utils import get_session, logging, parse_datetime
+
+
+if TYPE_CHECKING:
+    from .hf_api import HfApi
+    from .inference._client import InferenceClient
+    from .inference._generated._async_client import AsyncInferenceClient
+
+logger = logging.get_logger(__name__)
+
+
+class InferenceEndpointStatus(str, Enum):
+    PENDING = "pending"
+    INITIALIZING = "initializing"
+    UPDATING = "updating"
+    UPDATE_FAILED = "updateFailed"
+    RUNNING = "running"
+    PAUSED = "paused"
+    FAILED = "failed"
+    SCALED_TO_ZERO = "scaledToZero"
+
+
+class InferenceEndpointType(str, Enum):
+    PUBlIC = "public"
+    PROTECTED = "protected"
+    PRIVATE = "private"
+
+
+class InferenceEndpointScalingMetric(str, Enum):
+    PENDING_REQUESTS = "pendingRequests"
+    HARDWARE_USAGE = "hardwareUsage"
+
+
+@dataclass
+class InferenceEndpoint:
+    """
+    Contains information about a deployed Inference Endpoint.
+
+    Args:
+        name (`str`):
+            The unique name of the Inference Endpoint.
+        namespace (`str`):
+            The namespace where the Inference Endpoint is located.
+        repository (`str`):
+            The name of the model repository deployed on this Inference Endpoint.
+        status ([`InferenceEndpointStatus`]):
+            The current status of the Inference Endpoint.
+        url (`str`, *optional*):
+            The URL of the Inference Endpoint, if available. Only a deployed Inference Endpoint will have a URL.
+        framework (`str`):
+            The machine learning framework used for the model.
+        revision (`str`):
+            The specific model revision deployed on the Inference Endpoint.
+        task (`str`):
+            The task associated with the deployed model.
+        created_at (`datetime.datetime`):
+            The timestamp when the Inference Endpoint was created.
+        updated_at (`datetime.datetime`):
+            The timestamp of the last update of the Inference Endpoint.
+        type ([`InferenceEndpointType`]):
+            The type of the Inference Endpoint (public, protected, private).
+        raw (`dict`):
+            The raw dictionary data returned from the API.
+        token (`str` or `bool`, *optional*):
+            Authentication token for the Inference Endpoint, if set when requesting the API. Will default to the
+            locally saved token if not provided. Pass `token=False` if you don't want to send your token to the server.
+
+    Example:
+        ```python
+        >>> from huggingface_hub import get_inference_endpoint
+        >>> endpoint = get_inference_endpoint("my-text-to-image")
+        >>> endpoint
+        InferenceEndpoint(name='my-text-to-image', ...)
+
+        # Get status
+        >>> endpoint.status
+        'running'
+        >>> endpoint.url
+        'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud'
+
+        # Run inference
+        >>> endpoint.client.text_to_image(...)
+
+        # Pause endpoint to save $$$
+        >>> endpoint.pause()
+
+        # ...
+        # Resume and wait for deployment
+        >>> endpoint.resume()
+        >>> endpoint.wait()
+        >>> endpoint.client.text_to_image(...)
+        ```
+    """
+
+    # Field in __repr__
+    name: str = field(init=False)
+    namespace: str
+    repository: str = field(init=False)
+    status: InferenceEndpointStatus = field(init=False)
+    health_route: str = field(init=False)
+    url: Optional[str] = field(init=False)
+
+    # Other fields
+    framework: str = field(repr=False, init=False)
+    revision: str = field(repr=False, init=False)
+    task: str = field(repr=False, init=False)
+    created_at: datetime = field(repr=False, init=False)
+    updated_at: datetime = field(repr=False, init=False)
+    type: InferenceEndpointType = field(repr=False, init=False)
+
+    # Raw dict from the API
+    raw: dict = field(repr=False)
+
+    # Internal fields
+    _token: Union[str, bool, None] = field(repr=False, compare=False)
+    _api: "HfApi" = field(repr=False, compare=False)
+
+    @classmethod
+    def from_raw(
+        cls, raw: dict, namespace: str, token: Union[str, bool, None] = None, api: Optional["HfApi"] = None
+    ) -> "InferenceEndpoint":
+        """Initialize object from raw dictionary."""
+        if api is None:
+            from .hf_api import HfApi
+
+            api = HfApi()
+        if token is None:
+            token = api.token
+
+        # All other fields are populated in __post_init__
+        return cls(raw=raw, namespace=namespace, _token=token, _api=api)
+
+    def __post_init__(self) -> None:
+        """Populate fields from raw dictionary."""
+        self._populate_from_raw()
+
+    @property
+    def client(self) -> "InferenceClient":
+        """Returns a client to make predictions on this Inference Endpoint.
+
+        Returns:
+            [`InferenceClient`]: an inference client pointing to the deployed endpoint.
+
+        Raises:
+            [`InferenceEndpointError`]: If the Inference Endpoint is not yet deployed.
+        """
+        if self.url is None:
+            raise InferenceEndpointError(
+                "Cannot create a client for this Inference Endpoint as it is not yet deployed. "
+                "Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again."
+            )
+        from .inference._client import InferenceClient
+
+        return InferenceClient(
+            model=self.url,
+            token=self._token,  # type: ignore[arg-type] # boolean token shouldn't be possible. In practice it's ok.
+        )
+
+    @property
+    def async_client(self) -> "AsyncInferenceClient":
+        """Returns a client to make predictions on this Inference Endpoint.
+
+        Returns:
+            [`AsyncInferenceClient`]: an asyncio-compatible inference client pointing to the deployed endpoint.
+
+        Raises:
+            [`InferenceEndpointError`]: If the Inference Endpoint is not yet deployed.
+        """
+        if self.url is None:
+            raise InferenceEndpointError(
+                "Cannot create a client for this Inference Endpoint as it is not yet deployed. "
+                "Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again."
+            )
+        from .inference._generated._async_client import AsyncInferenceClient
+
+        return AsyncInferenceClient(
+            model=self.url,
+            token=self._token,  # type: ignore[arg-type] # boolean token shouldn't be possible. In practice it's ok.
+        )
+
+    def wait(self, timeout: Optional[int] = None, refresh_every: int = 5) -> "InferenceEndpoint":
+        """Wait for the Inference Endpoint to be deployed.
+
+        Information from the server will be fetched every 1s. If the Inference Endpoint is not deployed after `timeout`
+        seconds, a [`InferenceEndpointTimeoutError`] will be raised. The [`InferenceEndpoint`] will be mutated in place with the latest
+        data.
+
+        Args:
+            timeout (`int`, *optional*):
+                The maximum time to wait for the Inference Endpoint to be deployed, in seconds. If `None`, will wait
+                indefinitely.
+            refresh_every (`int`, *optional*):
+                The time to wait between each fetch of the Inference Endpoint status, in seconds. Defaults to 5s.
+
+        Returns:
+            [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data.
+
+        Raises:
+            [`InferenceEndpointError`]
+                If the Inference Endpoint ended up in a failed state.
+            [`InferenceEndpointTimeoutError`]
+                If the Inference Endpoint is not deployed after `timeout` seconds.
+        """
+        if timeout is not None and timeout < 0:
+            raise ValueError("`timeout` cannot be negative.")
+        if refresh_every <= 0:
+            raise ValueError("`refresh_every` must be positive.")
+
+        start = time.time()
+        while True:
+            if self.status == InferenceEndpointStatus.FAILED:
+                raise InferenceEndpointError(
+                    f"Inference Endpoint {self.name} failed to deploy. Please check the logs for more information."
+                )
+            if self.status == InferenceEndpointStatus.UPDATE_FAILED:
+                raise InferenceEndpointError(
+                    f"Inference Endpoint {self.name} failed to update. Please check the logs for more information."
+                )
+            if self.status == InferenceEndpointStatus.RUNNING and self.url is not None:
+                # Verify the endpoint is actually reachable
+                _health_url = f"{self.url.rstrip('/')}/{self.health_route.lstrip('/')}"
+                response = get_session().get(_health_url, headers=self._api._build_hf_headers(token=self._token))
+                if response.status_code == 200:
+                    logger.info("Inference Endpoint is ready to be used.")
+                    return self
+
+            if timeout is not None:
+                if time.time() - start > timeout:
+                    raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.")
+            logger.info(f"Inference Endpoint is not deployed yet ({self.status}). Waiting {refresh_every}s...")
+            time.sleep(refresh_every)
+            self.fetch()
+
+    def fetch(self) -> "InferenceEndpoint":
+        """Fetch latest information about the Inference Endpoint.
+
+        Returns:
+            [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data.
+        """
+        obj = self._api.get_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token)  # type: ignore [arg-type]
+        self.raw = obj.raw
+        self._populate_from_raw()
+        return self
+
+    def update(
+        self,
+        *,
+        # Compute update
+        accelerator: Optional[str] = None,
+        instance_size: Optional[str] = None,
+        instance_type: Optional[str] = None,
+        min_replica: Optional[int] = None,
+        max_replica: Optional[int] = None,
+        scale_to_zero_timeout: Optional[int] = None,
+        # Model update
+        repository: Optional[str] = None,
+        framework: Optional[str] = None,
+        revision: Optional[str] = None,
+        task: Optional[str] = None,
+        custom_image: Optional[dict] = None,
+        secrets: Optional[dict[str, str]] = None,
+    ) -> "InferenceEndpoint":
+        """Update the Inference Endpoint.
+
+        This method allows the update of either the compute configuration, the deployed model, or both. All arguments are
+        optional but at least one must be provided.
+
+        This is an alias for [`HfApi.update_inference_endpoint`]. The current object is mutated in place with the
+        latest data from the server.
+
+        Args:
+            accelerator (`str`, *optional*):
+                The hardware accelerator to be used for inference (e.g. `"cpu"`).
+            instance_size (`str`, *optional*):
+                The size or type of the instance to be used for hosting the model (e.g. `"x4"`).
+            instance_type (`str`, *optional*):
+                The cloud instance type where the Inference Endpoint will be deployed (e.g. `"intel-icl"`).
+            min_replica (`int`, *optional*):
+                The minimum number of replicas (instances) to keep running for the Inference Endpoint.
+            max_replica (`int`, *optional*):
+                The maximum number of replicas (instances) to scale to for the Inference Endpoint.
+            scale_to_zero_timeout (`int`, *optional*):
+                The duration in minutes before an inactive endpoint is scaled to zero.
+
+            repository (`str`, *optional*):
+                The name of the model repository associated with the Inference Endpoint (e.g. `"gpt2"`).
+            framework (`str`, *optional*):
+                The machine learning framework used for the model (e.g. `"custom"`).
+            revision (`str`, *optional*):
+                The specific model revision to deploy on the Inference Endpoint (e.g. `"6c0e6080953db56375760c0471a8c5f2929baf11"`).
+            task (`str`, *optional*):
+                The task on which to deploy the model (e.g. `"text-classification"`).
+            custom_image (`dict`, *optional*):
+                A custom Docker image to use for the Inference Endpoint. This is useful if you want to deploy an
+                Inference Endpoint running on the `text-generation-inference` (TGI) framework (see examples).
+            secrets (`dict[str, str]`, *optional*):
+                Secret values to inject in the container environment.
+        Returns:
+            [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data.
+        """
+        # Make API call
+        obj = self._api.update_inference_endpoint(
+            name=self.name,
+            namespace=self.namespace,
+            accelerator=accelerator,
+            instance_size=instance_size,
+            instance_type=instance_type,
+            min_replica=min_replica,
+            max_replica=max_replica,
+            scale_to_zero_timeout=scale_to_zero_timeout,
+            repository=repository,
+            framework=framework,
+            revision=revision,
+            task=task,
+            custom_image=custom_image,
+            secrets=secrets,
+            token=self._token,  # type: ignore [arg-type]
+        )
+
+        # Mutate current object
+        self.raw = obj.raw
+        self._populate_from_raw()
+        return self
+
+    def pause(self) -> "InferenceEndpoint":
+        """Pause the Inference Endpoint.
+
+        A paused Inference Endpoint will not be charged. It can be resumed at any time using [`InferenceEndpoint.resume`].
+        This is different from scaling the Inference Endpoint to zero with [`InferenceEndpoint.scale_to_zero`], which
+        would be automatically restarted when a request is made to it.
+
+        This is an alias for [`HfApi.pause_inference_endpoint`]. The current object is mutated in place with the
+        latest data from the server.
+
+        Returns:
+            [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data.
+        """
+        obj = self._api.pause_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token)  # type: ignore [arg-type]
+        self.raw = obj.raw
+        self._populate_from_raw()
+        return self
+
+    def resume(self, running_ok: bool = True) -> "InferenceEndpoint":
+        """Resume the Inference Endpoint.
+
+        This is an alias for [`HfApi.resume_inference_endpoint`]. The current object is mutated in place with the
+        latest data from the server.
+
+        Args:
+            running_ok (`bool`, *optional*):
+                If `True`, the method will not raise an error if the Inference Endpoint is already running. Defaults to
+                `True`.
+
+        Returns:
+            [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data.
+        """
+        obj = self._api.resume_inference_endpoint(
+            name=self.name, namespace=self.namespace, running_ok=running_ok, token=self._token
+        )  # type: ignore [arg-type]
+        self.raw = obj.raw
+        self._populate_from_raw()
+        return self
+
+    def scale_to_zero(self) -> "InferenceEndpoint":
+        """Scale Inference Endpoint to zero.
+
+        An Inference Endpoint scaled to zero will not be charged. It will be resumed on the next request to it, with a
+        cold start delay. This is different from pausing the Inference Endpoint with [`InferenceEndpoint.pause`], which
+        would require a manual resume with [`InferenceEndpoint.resume`].
+
+        This is an alias for [`HfApi.scale_to_zero_inference_endpoint`]. The current object is mutated in place with the
+        latest data from the server.
+
+        Returns:
+            [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data.
+        """
+        obj = self._api.scale_to_zero_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token)  # type: ignore [arg-type]
+        self.raw = obj.raw
+        self._populate_from_raw()
+        return self
+
+    def delete(self) -> None:
+        """Delete the Inference Endpoint.
+
+        This operation is not reversible. If you don't want to be charged for an Inference Endpoint, it is preferable
+        to pause it with [`InferenceEndpoint.pause`] or scale it to zero with [`InferenceEndpoint.scale_to_zero`].
+
+        This is an alias for [`HfApi.delete_inference_endpoint`].
+        """
+        self._api.delete_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token)  # type: ignore [arg-type]
+
+    def _populate_from_raw(self) -> None:
+        """Populate fields from raw dictionary.
+
+        Called in __post_init__ + each time the Inference Endpoint is updated.
+        """
+        # Repr fields
+        self.name = self.raw["name"]
+        self.repository = self.raw["model"]["repository"]
+        self.status = self.raw["status"]["state"]
+        self.url = self.raw["status"].get("url")
+        self.health_route = self.raw["healthRoute"]
+
+        # Other fields
+        self.framework = self.raw["model"]["framework"]
+        self.revision = self.raw["model"]["revision"]
+        self.task = self.raw["model"]["task"]
+        self.created_at = parse_datetime(self.raw["status"]["createdAt"])
+        self.updated_at = parse_datetime(self.raw["status"]["updatedAt"])
+        self.type = self.raw["type"]

venv/lib/python3.12/site-packages/huggingface_hub/_jobs_api.py

@@ -0,0 +1,389 @@
+# coding=utf-8
+# Copyright 2025-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional, Union
+
+from huggingface_hub import constants
+from huggingface_hub._space_api import SpaceHardware
+from huggingface_hub.utils._datetime import parse_datetime
+
+
+class JobStage(str, Enum):
+    """
+    Enumeration of possible stage of a Job on the Hub.
+
+    Value can be compared to a string:
+    ```py
+    assert JobStage.COMPLETED == "COMPLETED"
+    ```
+    Possible values are: `COMPLETED`, `CANCELED`, `ERROR`, `DELETED`, `RUNNING`.
+    Taken from https://github.com/huggingface/moon-landing/blob/main/server/job_types/JobInfo.ts#L61 (private url).
+    """
+
+    # Copied from moon-landing > server > lib > Job.ts
+    COMPLETED = "COMPLETED"
+    CANCELED = "CANCELED"
+    ERROR = "ERROR"
+    DELETED = "DELETED"
+    RUNNING = "RUNNING"
+
+
+@dataclass
+class JobStatus:
+    stage: JobStage
+    message: Optional[str]
+
+
+@dataclass
+class JobOwner:
+    id: str
+    name: str
+    type: str
+
+
+@dataclass
+class JobInfo:
+    """
+    Contains information about a Job.
+
+    Args:
+        id (`str`):
+            Job ID.
+        created_at (`datetime` or `None`):
+            When the Job was created.
+        docker_image (`str` or `None`):
+            The Docker image from Docker Hub used for the Job.
+            Can be None if space_id is present instead.
+        space_id (`str` or `None`):
+            The Docker image from Hugging Face Spaces used for the Job.
+            Can be None if docker_image is present instead.
+        command (`list[str]` or `None`):
+            Command of the Job, e.g. `["python", "-c", "print('hello world')"]`
+        arguments (`list[str]` or `None`):
+            Arguments passed to the command
+        environment (`dict[str]` or `None`):
+            Environment variables of the Job as a dictionary.
+        secrets (`dict[str]` or `None`):
+            Secret environment variables of the Job (encrypted).
+        flavor (`str` or `None`):
+            Flavor for the hardware, as in Hugging Face Spaces. See [`SpaceHardware`] for possible values.
+            E.g. `"cpu-basic"`.
+        status: (`JobStatus` or `None`):
+            Status of the Job, e.g. `JobStatus(stage="RUNNING", message=None)`
+            See [`JobStage`] for possible stage values.
+        owner: (`JobOwner` or `None`):
+            Owner of the Job, e.g. `JobOwner(id="5e9ecfc04957053f60648a3e", name="lhoestq", type="user")`
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub import run_job
+    >>> job = run_job(
+    ...     image="python:3.12",
+    ...     command=["python", "-c", "print('Hello from the cloud!')"]
+    ... )
+    >>> job
+    JobInfo(id='687fb701029421ae5549d998', created_at=datetime.datetime(2025, 7, 22, 16, 6, 25, 79000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='RUNNING', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq', type='user'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998')
+    >>> job.id
+    '687fb701029421ae5549d998'
+    >>> job.url
+    'https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998'
+    >>> job.status.stage
+    'RUNNING'
+    ```
+    """
+
+    id: str
+    created_at: Optional[datetime]
+    docker_image: Optional[str]
+    space_id: Optional[str]
+    command: Optional[list[str]]
+    arguments: Optional[list[str]]
+    environment: Optional[dict[str, Any]]
+    secrets: Optional[dict[str, Any]]
+    flavor: Optional[SpaceHardware]
+    status: JobStatus
+    owner: JobOwner
+
+    # Inferred fields
+    endpoint: str
+    url: str
+
+    def __init__(self, **kwargs) -> None:
+        self.id = kwargs["id"]
+        created_at = kwargs.get("createdAt") or kwargs.get("created_at")
+        self.created_at = parse_datetime(created_at) if created_at else None
+        self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image")
+        self.space_id = kwargs.get("spaceId") or kwargs.get("space_id")
+        owner = kwargs.get("owner", {})
+        self.owner = JobOwner(id=owner["id"], name=owner["name"], type=owner["type"])
+        self.command = kwargs.get("command")
+        self.arguments = kwargs.get("arguments")
+        self.environment = kwargs.get("environment")
+        self.secrets = kwargs.get("secrets")
+        self.flavor = kwargs.get("flavor")
+        status = kwargs.get("status", {})
+        self.status = JobStatus(stage=status["stage"], message=status.get("message"))
+
+        # Inferred fields
+        self.endpoint = kwargs.get("endpoint", constants.ENDPOINT)
+        self.url = f"{self.endpoint}/jobs/{self.owner.name}/{self.id}"
+
+
+@dataclass
+class JobSpec:
+    docker_image: Optional[str]
+    space_id: Optional[str]
+    command: Optional[list[str]]
+    arguments: Optional[list[str]]
+    environment: Optional[dict[str, Any]]
+    secrets: Optional[dict[str, Any]]
+    flavor: Optional[SpaceHardware]
+    timeout: Optional[int]
+    tags: Optional[list[str]]
+    arch: Optional[str]
+
+    def __init__(self, **kwargs) -> None:
+        self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image")
+        self.space_id = kwargs.get("spaceId") or kwargs.get("space_id")
+        self.command = kwargs.get("command")
+        self.arguments = kwargs.get("arguments")
+        self.environment = kwargs.get("environment")
+        self.secrets = kwargs.get("secrets")
+        self.flavor = kwargs.get("flavor")
+        self.timeout = kwargs.get("timeout")
+        self.tags = kwargs.get("tags")
+        self.arch = kwargs.get("arch")
+
+
+@dataclass
+class LastJobInfo:
+    id: str
+    at: datetime
+
+    def __init__(self, **kwargs) -> None:
+        self.id = kwargs["id"]
+        self.at = parse_datetime(kwargs["at"])
+
+
+@dataclass
+class ScheduledJobStatus:
+    last_job: Optional[LastJobInfo]
+    next_job_run_at: Optional[datetime]
+
+    def __init__(self, **kwargs) -> None:
+        last_job = kwargs.get("lastJob") or kwargs.get("last_job")
+        self.last_job = LastJobInfo(**last_job) if last_job else None
+        next_job_run_at = kwargs.get("nextJobRunAt") or kwargs.get("next_job_run_at")
+        self.next_job_run_at = parse_datetime(str(next_job_run_at)) if next_job_run_at else None
+
+
+@dataclass
+class ScheduledJobInfo:
+    """
+    Contains information about a Job.
+
+    Args:
+        id (`str`):
+            Scheduled Job ID.
+        created_at (`datetime` or `None`):
+            When the scheduled Job was created.
+        tags (`list[str]` or `None`):
+            The tags of the scheduled Job.
+        schedule (`str` or `None`):
+            One of "@annually", "@yearly", "@monthly", "@weekly", "@daily", "@hourly", or a
+            CRON schedule expression (e.g., '0 9 * * 1' for 9 AM every Monday).
+        suspend (`bool` or `None`):
+            Whether the scheduled job is suspended (paused).
+        concurrency (`bool` or `None`):
+            Whether multiple instances of this Job can run concurrently.
+        status (`ScheduledJobStatus` or `None`):
+            Status of the scheduled Job.
+        owner: (`JobOwner` or `None`):
+            Owner of the scheduled Job, e.g. `JobOwner(id="5e9ecfc04957053f60648a3e", name="lhoestq", type="user")`
+        job_spec: (`JobSpec` or `None`):
+            Specifications of the Job.
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub import run_job
+    >>> scheduled_job = create_scheduled_job(
+    ...     image="python:3.12",
+    ...     command=["python", "-c", "print('Hello from the cloud!')"],
+    ...     schedule="@hourly",
+    ... )
+    >>> scheduled_job.id
+    '687fb701029421ae5549d999'
+    >>> scheduled_job.status.next_job_run_at
+    datetime.datetime(2025, 7, 22, 17, 6, 25, 79000, tzinfo=datetime.timezone.utc)
+    ```
+    """
+
+    id: str
+    created_at: Optional[datetime]
+    job_spec: JobSpec
+    schedule: Optional[str]
+    suspend: Optional[bool]
+    concurrency: Optional[bool]
+    status: ScheduledJobStatus
+    owner: JobOwner
+
+    def __init__(self, **kwargs) -> None:
+        self.id = kwargs["id"]
+        created_at = kwargs.get("createdAt") or kwargs.get("created_at")
+        self.created_at = parse_datetime(created_at) if created_at else None
+        self.job_spec = JobSpec(**(kwargs.get("job_spec") or kwargs.get("jobSpec", {})))
+        self.schedule = kwargs.get("schedule")
+        self.suspend = kwargs.get("suspend")
+        self.concurrency = kwargs.get("concurrency")
+        status = kwargs.get("status", {})
+        self.status = ScheduledJobStatus(
+            last_job=status.get("last_job") or status.get("lastJob"),
+            next_job_run_at=status.get("next_job_run_at") or status.get("nextJobRunAt"),
+        )
+        owner = kwargs.get("owner", {})
+        self.owner = JobOwner(id=owner["id"], name=owner["name"], type=owner["type"])
+
+
+@dataclass
+class JobAccelerator:
+    """
+    Contains information about a Job accelerator (GPU).
+
+    Args:
+        type (`str`):
+            Type of accelerator, e.g. `"gpu"`.
+        model (`str`):
+            Model of accelerator, e.g. `"T4"`, `"A10G"`, `"A100"`, `"L4"`, `"L40S"`.
+        quantity (`str`):
+            Number of accelerators, e.g. `"1"`, `"2"`, `"4"`, `"8"`.
+        vram (`str`):
+            Total VRAM, e.g. `"16 GB"`, `"24 GB"`.
+        manufacturer (`str`):
+            Manufacturer of the accelerator, e.g. `"Nvidia"`.
+    """
+
+    type: str
+    model: str
+    quantity: str
+    vram: str
+    manufacturer: str
+
+    def __init__(self, **kwargs) -> None:
+        self.type = kwargs["type"]
+        self.model = kwargs["model"]
+        self.quantity = kwargs["quantity"]
+        self.vram = kwargs["vram"]
+        self.manufacturer = kwargs["manufacturer"]
+
+
+@dataclass
+class JobHardware:
+    """
+    Contains information about available Job hardware.
+
+    Args:
+        name (`str`):
+            Machine identifier, e.g. `"cpu-basic"`, `"a10g-large"`.
+        pretty_name (`str`):
+            Human-readable name, e.g. `"CPU Basic"`, `"Nvidia A10G - large"`.
+        cpu (`str`):
+            CPU specification, e.g. `"2 vCPU"`, `"12 vCPU"`.
+        ram (`str`):
+            RAM specification, e.g. `"16 GB"`, `"46 GB"`.
+        accelerator (`JobAccelerator` or `None`):
+            GPU/accelerator details if available.
+        unit_cost_micro_usd (`int`):
+            Cost in micro-dollars per unit, e.g. `167` (= $0.000167).
+        unit_cost_usd (`float`):
+            Cost in USD per unit, e.g. `0.000167`.
+        unit_label (`str`):
+            Cost unit period, e.g. `"minute"`.
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub import list_jobs_hardware
+    >>> hardware_list = list_jobs_hardware()
+    >>> hardware_list[0]
+    JobHardware(name='cpu-basic', pretty_name='CPU Basic', cpu='2 vCPU', ram='16 GB', accelerator=None, unit_cost_micro_usd=167, unit_cost_usd=0.000167, unit_label='minute')
+    >>> hardware_list[0].name
+    'cpu-basic'
+    ```
+    """
+
+    name: str
+    pretty_name: str
+    cpu: str
+    ram: str
+    accelerator: Optional[JobAccelerator]
+    unit_cost_micro_usd: int
+    unit_cost_usd: float
+    unit_label: str
+
+    def __init__(self, **kwargs) -> None:
+        self.name = kwargs["name"]
+        self.pretty_name = kwargs["prettyName"]
+        self.cpu = kwargs["cpu"]
+        self.ram = kwargs["ram"]
+        accelerator = kwargs.get("accelerator")
+        self.accelerator = JobAccelerator(**accelerator) if accelerator else None
+        self.unit_cost_micro_usd = kwargs["unitCostMicroUSD"]
+        self.unit_cost_usd = kwargs["unitCostUSD"]
+        self.unit_label = kwargs["unitLabel"]
+
+
+def _create_job_spec(
+    *,
+    image: str,
+    command: list[str],
+    env: Optional[dict[str, Any]],
+    secrets: Optional[dict[str, Any]],
+    flavor: Optional[SpaceHardware],
+    timeout: Optional[Union[int, float, str]],
+) -> dict[str, Any]:
+    # prepare job spec to send to HF Jobs API
+    job_spec: dict[str, Any] = {
+        "command": command,
+        "arguments": [],
+        "environment": env or {},
+        "flavor": flavor or SpaceHardware.CPU_BASIC,
+    }
+    # secrets are optional
+    if secrets:
+        job_spec["secrets"] = secrets
+    # timeout is optional
+    if timeout:
+        time_units_factors = {"s": 1, "m": 60, "h": 3600, "d": 3600 * 24}
+        if isinstance(timeout, str) and timeout[-1] in time_units_factors:
+            job_spec["timeoutSeconds"] = int(float(timeout[:-1]) * time_units_factors[timeout[-1]])
+        else:
+            job_spec["timeoutSeconds"] = int(timeout)
+    # input is either from docker hub or from HF spaces
+    for prefix in (
+        "https://huggingface.co/spaces/",
+        "https://hf.co/spaces/",
+        "huggingface.co/spaces/",
+        "hf.co/spaces/",
+    ):
+        if image.startswith(prefix):
+            job_spec["spaceId"] = image[len(prefix) :]
+            break
+    else:
+        job_spec["dockerImage"] = image
+    return job_spec

venv/lib/python3.12/site-packages/huggingface_hub/_local_folder.py

@@ -0,0 +1,451 @@
+# coding=utf-8
+# Copyright 2024-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains utilities to handle the `../.cache/huggingface` folder in local directories.
+
+First discussed in https://github.com/huggingface/huggingface_hub/issues/1738 to store
+download metadata when downloading files from the hub to a local directory (without
+using the cache).
+
+./.cache/huggingface folder structure:
+[4.0K]  data
+├── [4.0K]  .cache
+│   └── [4.0K]  huggingface
+│       └── [4.0K]  download
+│           ├── [  16]  file.parquet.metadata
+│           ├── [  16]  file.txt.metadata
+│           └── [4.0K]  folder
+│               └── [  16]  file.parquet.metadata
+│
+├── [6.5G]  file.parquet
+├── [1.5K]  file.txt
+└── [4.0K]  folder
+    └── [   16]  file.parquet
+
+
+Download metadata file structure:
+```
+# file.txt.metadata
+11c5a3d5811f50298f278a704980280950aedb10
+a16a55fda99d2f2e7b69cce5cf93ff4ad3049930
+1712656091.123
+
+# file.parquet.metadata
+11c5a3d5811f50298f278a704980280950aedb10
+7c5d3f4b8b76583b422fcb9189ad6c89d5d97a094541ce8932dce3ecabde1421
+1712656091.123
+}
+```
+"""
+
+import base64
+import hashlib
+import logging
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .utils import WeakFileLock
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LocalDownloadFilePaths:
+    """
+    Paths to the files related to a download process in a local dir.
+
+    Returned by [`get_local_download_paths`].
+
+    Attributes:
+        file_path (`Path`):
+            Path where the file will be saved.
+        lock_path (`Path`):
+            Path to the lock file used to ensure atomicity when reading/writing metadata.
+        metadata_path (`Path`):
+            Path to the metadata file.
+    """
+
+    file_path: Path
+    lock_path: Path
+    metadata_path: Path
+
+    def incomplete_path(self, etag: str) -> Path:
+        """Return the path where a file will be temporarily downloaded before being moved to `file_path`."""
+        path = self.metadata_path.parent / f"{_short_hash(self.metadata_path.name)}.{etag}.incomplete"
+        resolved_path = str(path.resolve())
+        # Some Windows versions do not allow for paths longer than 255 characters.
+        # In this case, we must specify it as an extended path by using the "\\?\" prefix.
+        if os.name == "nt" and len(resolved_path) > 255 and not resolved_path.startswith("\\\\?\\"):
+            path = Path("\\\\?\\" + resolved_path)
+        return path
+
+
+@dataclass(frozen=True)
+class LocalUploadFilePaths:
+    """
+    Paths to the files related to an upload process in a local dir.
+
+    Returned by [`get_local_upload_paths`].
+
+    Attributes:
+        path_in_repo (`str`):
+            Path of the file in the repo.
+        file_path (`Path`):
+            Path where the file will be saved.
+        lock_path (`Path`):
+            Path to the lock file used to ensure atomicity when reading/writing metadata.
+        metadata_path (`Path`):
+            Path to the metadata file.
+    """
+
+    path_in_repo: str
+    file_path: Path
+    lock_path: Path
+    metadata_path: Path
+
+
+@dataclass
+class LocalDownloadFileMetadata:
+    """
+    Metadata about a file in the local directory related to a download process.
+
+    Attributes:
+        filename (`str`):
+            Path of the file in the repo.
+        commit_hash (`str`):
+            Commit hash of the file in the repo.
+        etag (`str`):
+            ETag of the file in the repo. Used to check if the file has changed.
+            For LFS files, this is the sha256 of the file. For regular files, it corresponds to the git hash.
+        timestamp (`int`):
+            Unix timestamp of when the metadata was saved i.e. when the metadata was accurate.
+    """
+
+    filename: str
+    commit_hash: str
+    etag: str
+    timestamp: float
+
+
+@dataclass
+class LocalUploadFileMetadata:
+    """
+    Metadata about a file in the local directory related to an upload process.
+    """
+
+    size: int
+
+    # Default values correspond to "we don't know yet"
+    timestamp: Optional[float] = None
+    should_ignore: Optional[bool] = None
+    sha256: Optional[str] = None
+    upload_mode: Optional[str] = None
+    remote_oid: Optional[str] = None
+    is_uploaded: bool = False
+    is_committed: bool = False
+
+    def save(self, paths: LocalUploadFilePaths) -> None:
+        """Save the metadata to disk."""
+        with WeakFileLock(paths.lock_path):
+            with paths.metadata_path.open("w") as f:
+                new_timestamp = time.time()
+                f.write(str(new_timestamp) + "\n")
+
+                f.write(str(self.size))  # never None
+                f.write("\n")
+
+                if self.should_ignore is not None:
+                    f.write(str(int(self.should_ignore)))
+                f.write("\n")
+
+                if self.sha256 is not None:
+                    f.write(self.sha256)
+                f.write("\n")
+
+                if self.upload_mode is not None:
+                    f.write(self.upload_mode)
+                f.write("\n")
+
+                if self.remote_oid is not None:
+                    f.write(self.remote_oid)
+                f.write("\n")
+
+                f.write(str(int(self.is_uploaded)) + "\n")
+                f.write(str(int(self.is_committed)) + "\n")
+
+            self.timestamp = new_timestamp
+
+
+def get_local_download_paths(local_dir: Path, filename: str) -> LocalDownloadFilePaths:
+    """Compute paths to the files related to a download process.
+
+    Folders containing the paths are all guaranteed to exist.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory in which files are downloaded.
+        filename (`str`):
+            Path of the file in the repo.
+
+    Return:
+        [`LocalDownloadFilePaths`]: the paths to the files (file_path, lock_path, metadata_path, incomplete_path).
+    """
+    # filename is the path in the Hub repository (separated by '/')
+    # make sure to have a cross-platform transcription
+    sanitized_filename = os.path.join(*filename.split("/"))
+    if os.name == "nt":
+        if sanitized_filename.startswith("..\\") or "\\..\\" in sanitized_filename:
+            raise ValueError(
+                f"Invalid filename: cannot handle filename '{sanitized_filename}' on Windows. Please ask the repository"
+                " owner to rename this file."
+            )
+    file_path = local_dir / sanitized_filename
+    metadata_path = _huggingface_dir(local_dir) / "download" / f"{sanitized_filename}.metadata"
+    lock_path = metadata_path.with_suffix(".lock")
+
+    # Some Windows versions do not allow for paths longer than 255 characters.
+    # In this case, we must specify it as an extended path by using the "\\?\" prefix
+    if os.name == "nt":
+        if not str(local_dir).startswith("\\\\?\\") and len(os.path.abspath(lock_path)) > 255:
+            file_path = Path("\\\\?\\" + os.path.abspath(file_path))
+            lock_path = Path("\\\\?\\" + os.path.abspath(lock_path))
+            metadata_path = Path("\\\\?\\" + os.path.abspath(metadata_path))
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    metadata_path.parent.mkdir(parents=True, exist_ok=True)
+    return LocalDownloadFilePaths(file_path=file_path, lock_path=lock_path, metadata_path=metadata_path)
+
+
+def get_local_upload_paths(local_dir: Path, filename: str) -> LocalUploadFilePaths:
+    """Compute paths to the files related to an upload process.
+
+    Folders containing the paths are all guaranteed to exist.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory that is uploaded.
+        filename (`str`):
+            Path of the file in the repo.
+
+    Return:
+        [`LocalUploadFilePaths`]: the paths to the files (file_path, lock_path, metadata_path).
+    """
+    # filename is the path in the Hub repository (separated by '/')
+    # make sure to have a cross-platform transcription
+    sanitized_filename = os.path.join(*filename.split("/"))
+    if os.name == "nt":
+        if sanitized_filename.startswith("..\\") or "\\..\\" in sanitized_filename:
+            raise ValueError(
+                f"Invalid filename: cannot handle filename '{sanitized_filename}' on Windows. Please ask the repository"
+                " owner to rename this file."
+            )
+    file_path = local_dir / sanitized_filename
+    metadata_path = _huggingface_dir(local_dir) / "upload" / f"{sanitized_filename}.metadata"
+    lock_path = metadata_path.with_suffix(".lock")
+
+    # Some Windows versions do not allow for paths longer than 255 characters.
+    # In this case, we must specify it as an extended path by using the "\\?\" prefix
+    if os.name == "nt":
+        if not str(local_dir).startswith("\\\\?\\") and len(os.path.abspath(lock_path)) > 255:
+            file_path = Path("\\\\?\\" + os.path.abspath(file_path))
+            lock_path = Path("\\\\?\\" + os.path.abspath(lock_path))
+            metadata_path = Path("\\\\?\\" + os.path.abspath(metadata_path))
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    metadata_path.parent.mkdir(parents=True, exist_ok=True)
+    return LocalUploadFilePaths(
+        path_in_repo=filename, file_path=file_path, lock_path=lock_path, metadata_path=metadata_path
+    )
+
+
+def read_download_metadata(local_dir: Path, filename: str) -> Optional[LocalDownloadFileMetadata]:
+    """Read metadata about a file in the local directory related to a download process.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory in which files are downloaded.
+        filename (`str`):
+            Path of the file in the repo.
+
+    Return:
+        `[LocalDownloadFileMetadata]` or `None`: the metadata if it exists, `None` otherwise.
+    """
+    paths = get_local_download_paths(local_dir, filename)
+    with WeakFileLock(paths.lock_path):
+        if paths.metadata_path.exists():
+            try:
+                with paths.metadata_path.open() as f:
+                    commit_hash = f.readline().strip()
+                    etag = f.readline().strip()
+                    timestamp = float(f.readline().strip())
+                    metadata = LocalDownloadFileMetadata(
+                        filename=filename,
+                        commit_hash=commit_hash,
+                        etag=etag,
+                        timestamp=timestamp,
+                    )
+            except Exception as e:
+                # remove the metadata file if it is corrupted / not the right format
+                logger.warning(
+                    f"Invalid metadata file {paths.metadata_path}: {e}. Removing it from disk and continue."
+                )
+                try:
+                    paths.metadata_path.unlink()
+                except Exception as e:
+                    logger.warning(f"Could not remove corrupted metadata file {paths.metadata_path}: {e}")
+                return None
+
+            try:
+                # check if the file exists and hasn't been modified since the metadata was saved
+                stat = paths.file_path.stat()
+                if (
+                    stat.st_mtime - 1 <= metadata.timestamp
+                ):  # allow 1s difference as stat.st_mtime might not be precise
+                    return metadata
+                logger.info(f"Ignored metadata for '{filename}' (outdated). Will re-compute hash.")
+            except FileNotFoundError:
+                # file does not exist => metadata is outdated
+                return None
+    return None
+
+
+def read_upload_metadata(local_dir: Path, filename: str) -> LocalUploadFileMetadata:
+    """Read metadata about a file in the local directory related to an upload process.
+
+    TODO: factorize logic with `read_download_metadata`.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory in which files are downloaded.
+        filename (`str`):
+            Path of the file in the repo.
+
+    Return:
+        `[LocalUploadFileMetadata]` or `None`: the metadata if it exists, `None` otherwise.
+    """
+    paths = get_local_upload_paths(local_dir, filename)
+    with WeakFileLock(paths.lock_path):
+        if paths.metadata_path.exists():
+            try:
+                with paths.metadata_path.open() as f:
+                    timestamp = float(f.readline().strip())
+
+                    size = int(f.readline().strip())  # never None
+
+                    _should_ignore = f.readline().strip()
+                    should_ignore = None if _should_ignore == "" else bool(int(_should_ignore))
+
+                    _sha256 = f.readline().strip()
+                    sha256 = None if _sha256 == "" else _sha256
+
+                    _upload_mode = f.readline().strip()
+                    upload_mode = None if _upload_mode == "" else _upload_mode
+                    if upload_mode not in (None, "regular", "lfs"):
+                        raise ValueError(f"Invalid upload mode in metadata {paths.path_in_repo}: {upload_mode}")
+
+                    _remote_oid = f.readline().strip()
+                    remote_oid = None if _remote_oid == "" else _remote_oid
+
+                    is_uploaded = bool(int(f.readline().strip()))
+                    is_committed = bool(int(f.readline().strip()))
+
+                    metadata = LocalUploadFileMetadata(
+                        timestamp=timestamp,
+                        size=size,
+                        should_ignore=should_ignore,
+                        sha256=sha256,
+                        upload_mode=upload_mode,
+                        remote_oid=remote_oid,
+                        is_uploaded=is_uploaded,
+                        is_committed=is_committed,
+                    )
+            except Exception as e:
+                # remove the metadata file if it is corrupted / not the right format
+                logger.warning(
+                    f"Invalid metadata file {paths.metadata_path}: {e}. Removing it from disk and continue."
+                )
+                try:
+                    paths.metadata_path.unlink()
+                except Exception as e:
+                    logger.warning(f"Could not remove corrupted metadata file {paths.metadata_path}: {e}")
+
+                # corrupted metadata => we don't know anything expect its size
+                return LocalUploadFileMetadata(size=paths.file_path.stat().st_size)
+
+            # TODO: can we do better?
+            if (
+                metadata.timestamp is not None
+                and metadata.is_uploaded  # file was uploaded
+                and not metadata.is_committed  # but not committed
+                and time.time() - metadata.timestamp > 20 * 3600  # and it's been more than 20 hours
+            ):  # => we consider it as garbage-collected by S3
+                metadata.is_uploaded = False
+
+            # check if the file exists and hasn't been modified since the metadata was saved
+            try:
+                if metadata.timestamp is not None and paths.file_path.stat().st_mtime <= metadata.timestamp:
+                    return metadata
+                logger.info(f"Ignored metadata for '{filename}' (outdated). Will re-compute hash.")
+            except FileNotFoundError:
+                # file does not exist => metadata is outdated
+                pass
+
+    # empty metadata => we don't know anything expect its size
+    return LocalUploadFileMetadata(size=paths.file_path.stat().st_size)
+
+
+def write_download_metadata(local_dir: Path, filename: str, commit_hash: str, etag: str) -> None:
+    """Write metadata about a file in the local directory related to a download process.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory in which files are downloaded.
+    """
+    paths = get_local_download_paths(local_dir, filename)
+    with WeakFileLock(paths.lock_path):
+        with paths.metadata_path.open("w") as f:
+            f.write(f"{commit_hash}\n{etag}\n{time.time()}\n")
+
+
+def _huggingface_dir(local_dir: Path) -> Path:
+    """Return the path to the `.cache/huggingface` directory in a local directory."""
+    # Wrap in lru_cache to avoid overwriting the .gitignore file if called multiple times
+    path = local_dir / ".cache" / "huggingface"
+    path.mkdir(exist_ok=True, parents=True)
+
+    # Create a .gitignore file in the .cache/huggingface directory if it doesn't exist
+    # Should be thread-safe enough like this.
+    gitignore = path / ".gitignore"
+    gitignore_lock = path / ".gitignore.lock"
+    if not gitignore.exists():
+        try:
+            with WeakFileLock(gitignore_lock, timeout=0.1):
+                gitignore.write_text("*")
+        except IndexError:
+            pass
+        except OSError:  # TimeoutError, FileNotFoundError, PermissionError, etc.
+            pass
+        try:
+            gitignore_lock.unlink()
+        except OSError:
+            pass
+    return path
+
+
+def _short_hash(filename: str) -> str:
+    return base64.urlsafe_b64encode(hashlib.sha1(filename.encode()).digest()).decode()

venv/lib/python3.12/site-packages/huggingface_hub/_login.py

@@ -0,0 +1,492 @@
+# Copyright 2020 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains methods to log in to the Hub."""
+
+import os
+import subprocess
+from getpass import getpass
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import constants
+from .utils import (
+    ANSI,
+    capture_output,
+    get_token,
+    is_google_colab,
+    is_notebook,
+    list_credential_helpers,
+    logging,
+    run_subprocess,
+    set_git_credential,
+    unset_git_credential,
+)
+from .utils._auth import (
+    _get_token_by_name,
+    _get_token_from_environment,
+    _get_token_from_file,
+    _get_token_from_google_colab,
+    _save_stored_tokens,
+    _save_token,
+    get_stored_tokens,
+)
+
+
+logger = logging.get_logger(__name__)
+
+_HF_LOGO_ASCII = """
+    _|    _|  _|    _|    _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|_|_|_|    _|_|      _|_|_|  _|_|_|_|
+    _|    _|  _|    _|  _|        _|          _|    _|_|    _|  _|            _|        _|    _|  _|        _|
+    _|_|_|_|  _|    _|  _|  _|_|  _|  _|_|    _|    _|  _|  _|  _|  _|_|      _|_|_|    _|_|_|_|  _|        _|_|_|
+    _|    _|  _|    _|  _|    _|  _|    _|    _|    _|    _|_|  _|    _|      _|        _|    _|  _|        _|
+    _|    _|    _|_|      _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|        _|    _|    _|_|_|  _|_|_|_|
+"""
+
+
+def login(
+    token: Optional[str] = None,
+    *,
+    add_to_git_credential: bool = False,
+    skip_if_logged_in: bool = False,
+) -> None:
+    """Login the machine to access the Hub.
+
+    The `token` is persisted in cache and set as a git credential. Once done, the machine
+    is logged in and the access token will be available across all `huggingface_hub`
+    components. If `token` is not provided, it will be prompted to the user either with
+    a widget (in a notebook) or via the terminal.
+
+    To log in from outside of a script, one can also use `hf auth login` which is
+    a cli command that wraps [`login`].
+
+    > [!TIP]
+    > [`login`] is a drop-in replacement method for [`notebook_login`] as it wraps and
+    > extends its capabilities.
+
+    > [!TIP]
+    > When the token is not passed, [`login`] will automatically detect if the script runs
+    > in a notebook or not. However, this detection might not be accurate due to the
+    > variety of notebooks that exists nowadays. If that is the case, you can always force
+    > the UI by using [`notebook_login`] or [`interpreter_login`].
+
+    Args:
+        token (`str`, *optional*):
+            User access token to generate from https://huggingface.co/settings/token.
+        add_to_git_credential (`bool`, defaults to `False`):
+            If `True`, token will be set as git credential. If no git credential helper
+            is configured, a warning will be displayed to the user. If `token` is `None`,
+            the value of `add_to_git_credential` is ignored and will be prompted again
+            to the end user.
+        skip_if_logged_in (`bool`, defaults to `False`):
+            If `True`, do not prompt for token if user is already logged in.
+    Raises:
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If an organization token is passed. Only personal account tokens are valid
+            to log in.
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            If token is invalid.
+        [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError)
+            If running in a notebook but `ipywidgets` is not installed.
+    """
+    if token is not None:
+        if not add_to_git_credential:
+            logger.info(
+                "The token has not been saved to the git credentials helper. Pass "
+                "`add_to_git_credential=True` in this function directly or "
+                "`--add-to-git-credential` if using via `hf`CLI if "
+                "you want to set the git credential as well."
+            )
+        _login(token, add_to_git_credential=add_to_git_credential)
+    elif is_notebook():
+        notebook_login(skip_if_logged_in=skip_if_logged_in)
+    else:
+        interpreter_login(skip_if_logged_in=skip_if_logged_in)
+
+
+def logout(token_name: Optional[str] = None) -> None:
+    """Logout the machine from the Hub.
+
+    Token is deleted from the machine and removed from git credential.
+
+    Args:
+        token_name (`str`, *optional*):
+            Name of the access token to logout from. If `None`, will log out from all saved access tokens.
+    Raises:
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError):
+            If the access token name is not found.
+    """
+    if get_token() is None and not get_stored_tokens():  # No active token and no saved access tokens
+        logger.warning("Not logged in!")
+        return
+    if not token_name:
+        # Delete all saved access tokens and token
+        for file_path in (constants.HF_TOKEN_PATH, constants.HF_STORED_TOKENS_PATH):
+            try:
+                Path(file_path).unlink()
+            except FileNotFoundError:
+                pass
+        logger.info("Successfully logged out from all access tokens.")
+    else:
+        _logout_from_token(token_name)
+        logger.info(f"Successfully logged out from access token: {token_name}.")
+
+    unset_git_credential()
+
+    # Check if still logged in
+    if _get_token_from_google_colab() is not None:
+        raise EnvironmentError(
+            "You are automatically logged in using a Google Colab secret.\n"
+            "To log out, you must unset the `HF_TOKEN` secret in your Colab settings."
+        )
+    if _get_token_from_environment() is not None:
+        raise EnvironmentError(
+            "Token has been deleted from your machine but you are still logged in.\n"
+            "To log out, you must clear out both `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN` environment variables."
+        )
+
+
+def auth_switch(token_name: str, add_to_git_credential: bool = False) -> None:
+    """Switch to a different access token.
+
+    Args:
+        token_name (`str`):
+            Name of the access token to switch to.
+        add_to_git_credential (`bool`, defaults to `False`):
+            If `True`, token will be set as git credential. If no git credential helper
+            is configured, a warning will be displayed to the user. If `token` is `None`,
+            the value of `add_to_git_credential` is ignored and will be prompted again
+            to the end user.
+
+    Raises:
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError):
+            If the access token name is not found.
+    """
+    token = _get_token_by_name(token_name)
+    if not token:
+        raise ValueError(f"Access token {token_name} not found in {constants.HF_STORED_TOKENS_PATH}")
+    # Write token to HF_TOKEN_PATH
+    _set_active_token(token_name, add_to_git_credential)
+    logger.info(f"The current active token is: {token_name}")
+    token_from_environment = _get_token_from_environment()
+    if token_from_environment is not None and token_from_environment != token:
+        logger.warning(
+            "The environment variable `HF_TOKEN` is set and will override the access token you've just switched to."
+        )
+
+
+def auth_list() -> None:
+    """List all stored access tokens."""
+    tokens = get_stored_tokens()
+
+    if not tokens:
+        if _get_token_from_environment():
+            logger.info("No stored access tokens found.")
+            logger.warning("Note: Environment variable `HF_TOKEN` is set and is the current active token.")
+        else:
+            logger.info("No access tokens found.")
+        return
+    # Find current token
+    current_token = get_token()
+    current_token_name = None
+    for token_name in tokens:
+        if tokens.get(token_name) == current_token:
+            current_token_name = token_name
+    # Print header
+    max_offset = max(len("token"), max(len(token) for token in tokens)) + 2
+    print(f"  {{:<{max_offset}}}| {{:<15}}".format("name", "token"))
+    print("-" * (max_offset + 2) + "|" + "-" * 15)
+
+    # Print saved access tokens
+    for token_name in tokens:
+        token = tokens.get(token_name, "<not set>")
+        masked_token = f"{token[:3]}****{token[-4:]}" if token != "<not set>" else token
+        is_current = "*" if token == current_token else " "
+
+        print(f"{is_current} {{:<{max_offset}}}| {{:<15}}".format(token_name, masked_token))
+
+    if _get_token_from_environment():
+        logger.warning(
+            "\nNote: Environment variable `HF_TOKEN` is set and is the current active token independently from the stored tokens listed above."
+        )
+    elif current_token_name is None:
+        logger.warning(
+            "\nNote: No active token is set and no environment variable `HF_TOKEN` is found. Use `hf auth login` to log in."
+        )
+
+
+###
+# Interpreter-based login (text)
+###
+
+
+def interpreter_login(*, skip_if_logged_in: bool = False) -> None:
+    """
+    Displays a prompt to log in to the HF website and store the token.
+
+    This is equivalent to [`login`] without passing a token when not run in a notebook.
+    [`interpreter_login`] is useful if you want to force the use of the terminal prompt
+    instead of a notebook widget.
+
+    For more details, see [`login`].
+
+    Args:
+        skip_if_logged_in (`bool`, defaults to `False`):
+            If `True`, do not prompt for token if user is already logged in.
+    """
+    if not skip_if_logged_in and get_token() is not None:
+        logger.info("User is already logged in.")
+        return
+
+    print(_HF_LOGO_ASCII)
+    if get_token() is not None:
+        logger.info(
+            "    A token is already saved on your machine. Run `hf auth whoami`"
+            " to get more information or `hf auth logout` if you want"
+            " to log out."
+        )
+        logger.info("    Setting a new token will erase the existing one.")
+
+    logger.info(
+        "    To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens ."
+    )
+    if os.name == "nt":
+        logger.info("Token can be pasted using 'Right-Click'.")
+    token = getpass("Enter your token (input will not be visible): ")
+    add_to_git_credential = typer.confirm("Add token as git credential?")
+
+    _login(token=token, add_to_git_credential=add_to_git_credential)
+
+
+###
+# Notebook-based login (widget)
+###
+
+NOTEBOOK_LOGIN_PASSWORD_HTML = """<center> <img
+src=https://huggingface.co/front/assets/huggingface_logo-noborder.svg
+alt='Hugging Face'> <br> Immediately click login after typing your password or
+it might be stored in plain text in this notebook file. </center>"""
+
+
+NOTEBOOK_LOGIN_TOKEN_HTML_START = """<center> <img
+src=https://huggingface.co/front/assets/huggingface_logo-noborder.svg
+alt='Hugging Face'> <br> Copy a token from <a
+href="https://huggingface.co/settings/tokens" target="_blank">your Hugging Face
+tokens page</a> and paste it below. <br> Immediately click login after copying
+your token or it might be stored in plain text in this notebook file. </center>"""
+
+
+NOTEBOOK_LOGIN_TOKEN_HTML_END = """
+<b>Pro Tip:</b> If you don't already have one, you can create a dedicated
+'notebooks' token with 'write' access, that you can then easily reuse for all
+notebooks. </center>"""
+
+
+def notebook_login(*, skip_if_logged_in: bool = False) -> None:
+    """
+    Displays a widget to log in to the HF website and store the token.
+
+    This is equivalent to [`login`] without passing a token when run in a notebook.
+    [`notebook_login`] is useful if you want to force the use of the notebook widget
+    instead of a prompt in the terminal.
+
+    For more details, see [`login`].
+
+    Args:
+        skip_if_logged_in (`bool`, defaults to `False`):
+            If `True`, do not prompt for token if user is already logged in.
+    """
+    try:
+        import ipywidgets.widgets as widgets  # type: ignore
+        from IPython.display import display  # type: ignore
+    except ImportError:
+        raise ImportError(
+            "The `notebook_login` function can only be used in a notebook (Jupyter or"
+            " Colab) and you need the `ipywidgets` module: `pip install ipywidgets`."
+        )
+    if not skip_if_logged_in and get_token() is not None:
+        logger.info("User is already logged in.")
+        return
+
+    box_layout = widgets.Layout(display="flex", flex_flow="column", align_items="center", width="50%")
+
+    token_widget = widgets.Password(description="Token:")
+    git_checkbox_widget = widgets.Checkbox(value=True, description="Add token as git credential?")
+    token_finish_button = widgets.Button(description="Login")
+
+    login_token_widget = widgets.VBox(
+        [
+            widgets.HTML(NOTEBOOK_LOGIN_TOKEN_HTML_START),
+            token_widget,
+            git_checkbox_widget,
+            token_finish_button,
+            widgets.HTML(NOTEBOOK_LOGIN_TOKEN_HTML_END),
+        ],
+        layout=box_layout,
+    )
+    display(login_token_widget)
+
+    # On click events
+    def login_token_event(t):
+        """Event handler for the login button."""
+        token = token_widget.value
+        add_to_git_credential = git_checkbox_widget.value
+        # Erase token and clear value to make sure it's not saved in the notebook.
+        token_widget.value = ""
+        # Hide inputs
+        login_token_widget.children = [widgets.Label("Connecting...")]
+        try:
+            with capture_output() as captured:
+                _login(token, add_to_git_credential=add_to_git_credential)
+            message = captured.getvalue()
+        except Exception as error:
+            message = str(error)
+        # Print result (success message or error)
+        login_token_widget.children = [widgets.Label(line) for line in message.split("\n") if line.strip()]
+
+    token_finish_button.on_click(login_token_event)
+
+
+###
+# Login private helpers
+###
+
+
+def _login(
+    token: str,
+    add_to_git_credential: bool,
+) -> None:
+    from .hf_api import whoami  # avoid circular import
+
+    if token.startswith("api_org"):
+        raise ValueError("You must use your personal account token, not an organization token.")
+
+    token_info = whoami(token)
+    permission = token_info["auth"]["accessToken"]["role"]
+    logger.info(f"Token is valid (permission: {permission}).")
+
+    token_name = token_info["auth"]["accessToken"]["displayName"]
+    # Store token locally
+    _save_token(token=token, token_name=token_name)
+    # Set active token
+    _set_active_token(token_name=token_name, add_to_git_credential=add_to_git_credential)
+    logger.info("Login successful.")
+    if _get_token_from_environment():
+        logger.warning(
+            "Note: Environment variable`HF_TOKEN` is set and is the current active token independently from the token you've just configured."
+        )
+    else:
+        logger.info(f"The current active token is: `{token_name}`")
+
+
+def _logout_from_token(token_name: str) -> None:
+    """Logout from a specific access token.
+
+    Args:
+        token_name (`str`):
+            The name of the access token to logout from.
+    Raises:
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError):
+            If the access token name is not found.
+    """
+    stored_tokens = get_stored_tokens()
+    # If there is no access tokens saved or the access token name is not found, do nothing
+    if not stored_tokens or token_name not in stored_tokens:
+        return
+
+    token = stored_tokens.pop(token_name)
+    _save_stored_tokens(stored_tokens)
+
+    if token == _get_token_from_file():
+        logger.warning(f"Active token '{token_name}' has been deleted.")
+        Path(constants.HF_TOKEN_PATH).unlink(missing_ok=True)
+
+
+def _set_active_token(
+    token_name: str,
+    add_to_git_credential: bool,
+) -> None:
+    """Set the active access token.
+
+    Args:
+        token_name (`str`):
+            The name of the token to set as active.
+    """
+    token = _get_token_by_name(token_name)
+    if not token:
+        raise ValueError(f"Token {token_name} not found in {constants.HF_STORED_TOKENS_PATH}")
+    if add_to_git_credential:
+        if _is_git_credential_helper_configured():
+            set_git_credential(token)
+            logger.info(
+                "Your token has been saved in your configured git credential helpers"
+                + f" ({','.join(list_credential_helpers())})."
+            )
+        else:
+            logger.warning("Token has not been saved to git credential helper.")
+    # Write token to HF_TOKEN_PATH
+    path = Path(constants.HF_TOKEN_PATH)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(token)
+    logger.info(f"Your token has been saved to {constants.HF_TOKEN_PATH}")
+
+
+def _is_git_credential_helper_configured() -> bool:
+    """Check if a git credential helper is configured.
+
+    Warns user if not the case (except for Google Colab where "store" is set by default
+    by `huggingface_hub`).
+    """
+    helpers = list_credential_helpers()
+    if len(helpers) > 0:
+        return True  # Do not warn: at least 1 helper is set
+
+    # Only in Google Colab to avoid the warning message
+    # See https://github.com/huggingface/huggingface_hub/issues/1043#issuecomment-1247010710
+    if is_google_colab():
+        _set_store_as_git_credential_helper_globally()
+        return True  # Do not warn: "store" is used by default in Google Colab
+
+    # Otherwise, warn user
+    print(
+        ANSI.red(
+            "Cannot authenticate through git-credential as no helper is defined on your"
+            " machine.\nYou might have to re-authenticate when pushing to the Hugging"
+            " Face Hub.\nRun the following command in your terminal in case you want to"
+            " set the 'store' credential helper as default.\n\ngit config --global"
+            " credential.helper store\n\nRead"
+            " https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage for more"
+            " details."
+        )
+    )
+    return False
+
+
+def _set_store_as_git_credential_helper_globally() -> None:
+    """Set globally the credential.helper to `store`.
+
+    To be used only in Google Colab as we assume the user doesn't care about the git
+    credential config. It is the only particular case where we don't want to display the
+    warning message in [`notebook_login()`].
+
+    Related:
+    - https://github.com/huggingface/huggingface_hub/issues/1043
+    - https://github.com/huggingface/huggingface_hub/issues/1051
+    - https://git-scm.com/docs/git-credential-store
+    """
+    try:
+        run_subprocess("git config --global credential.helper store")
+    except subprocess.CalledProcessError as exc:
+        raise EnvironmentError(exc.stderr)

venv/lib/python3.12/site-packages/huggingface_hub/_oauth.py

@@ -0,0 +1,460 @@
+import datetime
+import hashlib
+import logging
+import os
+import time
+import urllib.parse
+import warnings
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, Optional, Union
+
+from . import constants
+from .hf_api import whoami
+from .utils import experimental, get_token
+
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    import fastapi
+
+
+@dataclass
+class OAuthOrgInfo:
+    """
+    Information about an organization linked to a user logged in with OAuth.
+
+    Attributes:
+        sub (`str`):
+            Unique identifier for the org. OpenID Connect field.
+        name (`str`):
+            The org's full name. OpenID Connect field.
+        preferred_username (`str`):
+            The org's username. OpenID Connect field.
+        picture (`str`):
+            The org's profile picture URL. OpenID Connect field.
+        is_enterprise (`bool`):
+            Whether the org is an enterprise org. Hugging Face field.
+        can_pay (`Optional[bool]`, *optional*):
+            Whether the org has a payment method set up. Hugging Face field.
+        role_in_org (`Optional[str]`, *optional*):
+            The user's role in the org. Hugging Face field.
+        security_restrictions (`Optional[list[Literal["ip", "token-policy", "mfa", "sso"]]]`, *optional*):
+            Array of security restrictions that the user hasn't completed for this org. Possible values: "ip", "token-policy", "mfa", "sso". Hugging Face field.
+    """
+
+    sub: str
+    name: str
+    preferred_username: str
+    picture: str
+    is_enterprise: bool
+    can_pay: Optional[bool] = None
+    role_in_org: Optional[str] = None
+    security_restrictions: Optional[list[Literal["ip", "token-policy", "mfa", "sso"]]] = None
+
+
+@dataclass
+class OAuthUserInfo:
+    """
+    Information about a user logged in with OAuth.
+
+    Attributes:
+        sub (`str`):
+            Unique identifier for the user, even in case of rename. OpenID Connect field.
+        name (`str`):
+            The user's full name. OpenID Connect field.
+        preferred_username (`str`):
+            The user's username. OpenID Connect field.
+        email_verified (`Optional[bool]`, *optional*):
+            Indicates if the user's email is verified. OpenID Connect field.
+        email (`Optional[str]`, *optional*):
+            The user's email address. OpenID Connect field.
+        picture (`str`):
+            The user's profile picture URL. OpenID Connect field.
+        profile (`str`):
+            The user's profile URL. OpenID Connect field.
+        website (`Optional[str]`, *optional*):
+            The user's website URL. OpenID Connect field.
+        is_pro (`bool`):
+            Whether the user is a pro user. Hugging Face field.
+        can_pay (`Optional[bool]`, *optional*):
+            Whether the user has a payment method set up. Hugging Face field.
+        orgs (`Optional[list[OrgInfo]]`, *optional*):
+            List of organizations the user is part of. Hugging Face field.
+    """
+
+    sub: str
+    name: str
+    preferred_username: str
+    email_verified: Optional[bool]
+    email: Optional[str]
+    picture: str
+    profile: str
+    website: Optional[str]
+    is_pro: bool
+    can_pay: Optional[bool]
+    orgs: Optional[list[OAuthOrgInfo]]
+
+
+@dataclass
+class OAuthInfo:
+    """
+    Information about the OAuth login.
+
+    Attributes:
+        access_token (`str`):
+            The access token.
+        access_token_expires_at (`datetime.datetime`):
+            The expiration date of the access token.
+        user_info ([`OAuthUserInfo`]):
+            The user information.
+        state (`str`, *optional*):
+            State passed to the OAuth provider in the original request to the OAuth provider.
+        scope (`str`):
+            Granted scope.
+    """
+
+    access_token: str
+    access_token_expires_at: datetime.datetime
+    user_info: OAuthUserInfo
+    state: Optional[str]
+    scope: str
+
+
+@experimental
+def attach_huggingface_oauth(app: "fastapi.FastAPI", route_prefix: str = "/"):
+    """
+    Add OAuth endpoints to a FastAPI app to enable OAuth login with Hugging Face.
+
+    How to use:
+    - Call this method on your FastAPI app to add the OAuth endpoints.
+    - Inside your route handlers, call `parse_huggingface_oauth(request)` to retrieve the OAuth info.
+    - If user is logged in, an [`OAuthInfo`] object is returned with the user's info. If not, `None` is returned.
+    - In your app, make sure to add links to `/oauth/huggingface/login` and `/oauth/huggingface/logout` for the user to log in and out.
+
+    Example:
+    ```py
+    from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth
+
+    # Create a FastAPI app
+    app = FastAPI()
+
+    # Add OAuth endpoints to the FastAPI app
+    attach_huggingface_oauth(app)
+
+    # Add a route that greets the user if they are logged in
+    @app.get("/")
+    def greet_json(request: Request):
+        # Retrieve the OAuth info from the request
+        oauth_info = parse_huggingface_oauth(request)  # e.g. OAuthInfo dataclass
+        if oauth_info is None:
+            return {"msg": "Not logged in!"}
+        return {"msg": f"Hello, {oauth_info.user_info.preferred_username}!"}
+    ```
+    """
+    # TODO: handle generic case (handling OAuth in a non-Space environment with custom dev values) (low priority)
+
+    # Add SessionMiddleware to the FastAPI app to store the OAuth info in the session.
+    # Session Middleware requires a secret key to sign the cookies. Let's use a hash
+    # of the OAuth secret key to make it unique to the Space + updated in case OAuth
+    # config gets updated. When ran locally, we use an empty string as a secret key.
+    try:
+        from starlette.middleware.sessions import SessionMiddleware
+    except ImportError as e:
+        raise ImportError(
+            "Cannot initialize OAuth to due a missing library. Please run `pip install huggingface_hub[oauth]` or add "
+            "`huggingface_hub[oauth]` to your requirements.txt file in order to install the required dependencies."
+        ) from e
+    session_secret = (constants.OAUTH_CLIENT_SECRET or "") + "-v1"
+    app.add_middleware(
+        SessionMiddleware,  # type: ignore[arg-type]
+        secret_key=hashlib.sha256(session_secret.encode()).hexdigest(),
+        same_site="none",
+        https_only=True,
+    )  # type: ignore
+
+    # Add OAuth endpoints to the FastAPI app:
+    #   - {route_prefix}/oauth/huggingface/login
+    #   - {route_prefix}/oauth/huggingface/callback
+    #   - {route_prefix}/oauth/huggingface/logout
+    # If the app is running in a Space, OAuth is enabled normally.
+    # Otherwise, we mock the endpoints to make the user log in with a fake user profile - without any calls to hf.co.
+    route_prefix = route_prefix.strip("/")
+    if os.getenv("SPACE_ID") is not None:
+        logger.info("OAuth is enabled in the Space. Adding OAuth routes.")
+        _add_oauth_routes(app, route_prefix=route_prefix)
+    else:
+        logger.info("App is not running in a Space. Adding mocked OAuth routes.")
+        _add_mocked_oauth_routes(app, route_prefix=route_prefix)
+
+
+def parse_huggingface_oauth(request: "fastapi.Request") -> Optional[OAuthInfo]:
+    """
+    Returns the information from a logged-in user as a [`OAuthInfo`] object.
+
+    For flexibility and future-proofing, this method is very lax in its parsing and does not raise errors.
+    Missing fields are set to `None` without a warning.
+
+    Return `None`, if the user is not logged in (no info in session cookie).
+
+    See [`attach_huggingface_oauth`] for an example on how to use this method.
+    """
+    if "oauth_info" not in request.session:
+        logger.debug("No OAuth info in session.")
+        return None
+
+    logger.debug("Parsing OAuth info from session.")
+    oauth_data = request.session["oauth_info"]
+    user_data = oauth_data.get("userinfo", {})
+    orgs_data = user_data.get("orgs", [])
+
+    orgs = (
+        [
+            OAuthOrgInfo(
+                sub=org.get("sub"),
+                name=org.get("name"),
+                preferred_username=org.get("preferred_username"),
+                picture=org.get("picture"),
+                is_enterprise=org.get("isEnterprise"),
+                can_pay=org.get("canPay"),
+                role_in_org=org.get("roleInOrg"),
+                security_restrictions=org.get("securityRestrictions"),
+            )
+            for org in orgs_data
+        ]
+        if orgs_data
+        else None
+    )
+
+    user_info = OAuthUserInfo(
+        sub=user_data.get("sub"),
+        name=user_data.get("name"),
+        preferred_username=user_data.get("preferred_username"),
+        email_verified=user_data.get("email_verified"),
+        email=user_data.get("email"),
+        picture=user_data.get("picture"),
+        profile=user_data.get("profile"),
+        website=user_data.get("website"),
+        is_pro=user_data.get("isPro"),
+        can_pay=user_data.get("canPay"),
+        orgs=orgs,
+    )
+
+    return OAuthInfo(
+        access_token=oauth_data.get("access_token"),
+        access_token_expires_at=datetime.datetime.fromtimestamp(oauth_data.get("expires_at")),
+        user_info=user_info,
+        state=oauth_data.get("state"),
+        scope=oauth_data.get("scope"),
+    )
+
+
+def _add_oauth_routes(app: "fastapi.FastAPI", route_prefix: str) -> None:
+    """Add OAuth routes to the FastAPI app (login, callback handler and logout)."""
+    try:
+        import fastapi
+        from authlib.integrations.base_client.errors import MismatchingStateError
+        from authlib.integrations.starlette_client import OAuth
+        from fastapi.responses import RedirectResponse
+    except ImportError as e:
+        raise ImportError(
+            "Cannot initialize OAuth to due a missing library. Please run `pip install huggingface_hub[oauth]` or add "
+            "`huggingface_hub[oauth]` to your requirements.txt file."
+        ) from e
+
+    # Check environment variables
+    msg = (
+        "OAuth is required but '{}' environment variable is not set. Make sure you've enabled OAuth in your Space by"
+        " setting `hf_oauth: true` in the Space metadata."
+    )
+    if constants.OAUTH_CLIENT_ID is None:
+        raise ValueError(msg.format("OAUTH_CLIENT_ID"))
+    if constants.OAUTH_CLIENT_SECRET is None:
+        raise ValueError(msg.format("OAUTH_CLIENT_SECRET"))
+    if constants.OAUTH_SCOPES is None:
+        raise ValueError(msg.format("OAUTH_SCOPES"))
+    if constants.OPENID_PROVIDER_URL is None:
+        raise ValueError(msg.format("OPENID_PROVIDER_URL"))
+
+    # Register OAuth server
+    oauth = OAuth()
+    oauth.register(
+        name="huggingface",
+        client_id=constants.OAUTH_CLIENT_ID,
+        client_secret=constants.OAUTH_CLIENT_SECRET,
+        client_kwargs={"scope": constants.OAUTH_SCOPES},
+        server_metadata_url=constants.OPENID_PROVIDER_URL + "/.well-known/openid-configuration",
+    )
+
+    login_uri, callback_uri, logout_uri = _get_oauth_uris(route_prefix)
+
+    # Register OAuth endpoints
+    @app.get(login_uri)
+    async def oauth_login(request: fastapi.Request) -> RedirectResponse:
+        """Endpoint that redirects to HF OAuth page."""
+        redirect_uri = _generate_redirect_uri(request)
+        return await oauth.huggingface.authorize_redirect(request, redirect_uri)  # type: ignore
+
+    @app.get(callback_uri)
+    async def oauth_redirect_callback(request: fastapi.Request) -> RedirectResponse:
+        """Endpoint that handles the OAuth callback."""
+        try:
+            oauth_info = await oauth.huggingface.authorize_access_token(request)  # type: ignore
+        except MismatchingStateError:
+            # Parse query params
+            nb_redirects = int(request.query_params.get("_nb_redirects", 0))
+            target_url = request.query_params.get("_target_url")
+
+            # Build redirect URI with the same query params as before and bump nb_redirects count
+            query_params: dict[str, Union[int, str]] = {"_nb_redirects": nb_redirects + 1}
+            if target_url:
+                query_params["_target_url"] = target_url
+
+            redirect_uri = f"{login_uri}?{urllib.parse.urlencode(query_params)}"
+
+            # If the user is redirected more than 3 times, it is very likely that the cookie is not working properly.
+            # (e.g. browser is blocking third-party cookies in iframe). In this case, redirect the user in the
+            # non-iframe view.
+            if nb_redirects > constants.OAUTH_MAX_REDIRECTS:
+                host = os.environ.get("SPACE_HOST")
+                if host is None:  # cannot happen in a Space
+                    raise RuntimeError(
+                        "App is not running in a Space (SPACE_HOST environment variable is not set). Cannot redirect to non-iframe view."
+                    ) from None
+                host_url = "https://" + host.rstrip("/")
+                return RedirectResponse(host_url + redirect_uri)
+
+            # Redirect the user to the login page again
+            return RedirectResponse(redirect_uri)
+
+        # OAuth login worked => store the user info in the session and redirect
+        logger.debug("Successfully logged in with OAuth. Storing user info in session.")
+        request.session["oauth_info"] = oauth_info
+        return RedirectResponse(_get_redirect_target(request))
+
+    @app.get(logout_uri)
+    async def oauth_logout(request: fastapi.Request) -> RedirectResponse:
+        """Endpoint that logs out the user (e.g. delete info from cookie session)."""
+        logger.debug("Logged out with OAuth. Removing user info from session.")
+        request.session.pop("oauth_info", None)
+        return RedirectResponse(_get_redirect_target(request))
+
+
+def _add_mocked_oauth_routes(app: "fastapi.FastAPI", route_prefix: str = "/") -> None:
+    """Add fake oauth routes if app is run locally and OAuth is enabled.
+
+    Using OAuth will have the same behavior as in a Space but instead of authenticating with HF, a mocked user profile
+    is added to the session.
+    """
+    try:
+        import fastapi
+        from fastapi.responses import RedirectResponse
+        from starlette.datastructures import URL
+    except ImportError as e:
+        raise ImportError(
+            "Cannot initialize OAuth to due a missing library. Please run `pip install huggingface_hub[oauth]` or add "
+            "`huggingface_hub[oauth]` to your requirements.txt file."
+        ) from e
+
+    warnings.warn(
+        "OAuth is not supported outside of a Space environment. To help you debug your app locally, the oauth endpoints"
+        " are mocked to return your profile and token. To make it work, your machine must be logged in to Huggingface."
+    )
+    mocked_oauth_info = _get_mocked_oauth_info()
+
+    login_uri, callback_uri, logout_uri = _get_oauth_uris(route_prefix)
+
+    # Define OAuth routes
+    @app.get(login_uri)
+    async def oauth_login(request: fastapi.Request) -> RedirectResponse:
+        """Fake endpoint that redirects to HF OAuth page."""
+        # Define target (where to redirect after login)
+        redirect_uri = _generate_redirect_uri(request)
+        return RedirectResponse(callback_uri + "?" + urllib.parse.urlencode({"_target_url": redirect_uri}))
+
+    @app.get(callback_uri)
+    async def oauth_redirect_callback(request: fastapi.Request) -> RedirectResponse:
+        """Endpoint that handles the OAuth callback."""
+        request.session["oauth_info"] = mocked_oauth_info
+        return RedirectResponse(_get_redirect_target(request))
+
+    @app.get(logout_uri)
+    async def oauth_logout(request: fastapi.Request) -> RedirectResponse:
+        """Endpoint that logs out the user (e.g. delete cookie session)."""
+        request.session.pop("oauth_info", None)
+        logout_url = URL("/").include_query_params(**request.query_params)
+        return RedirectResponse(url=logout_url, status_code=302)  # see https://github.com/gradio-app/gradio/pull/9659
+
+
+def _generate_redirect_uri(request: "fastapi.Request") -> str:
+    if "_target_url" in request.query_params:
+        # if `_target_url` already in query params => respect it
+        target = request.query_params["_target_url"]
+    else:
+        # otherwise => keep query params
+        target = "/?" + urllib.parse.urlencode(request.query_params)
+
+    redirect_uri = request.url_for("oauth_redirect_callback").include_query_params(_target_url=target)
+    redirect_uri_as_str = str(redirect_uri)
+    if redirect_uri.netloc.endswith(".hf.space"):
+        # In Space, FastAPI redirect as http but we want https
+        redirect_uri_as_str = redirect_uri_as_str.replace("http://", "https://")
+    return redirect_uri_as_str
+
+
+def _get_redirect_target(request: "fastapi.Request", default_target: str = "/") -> str:
+    return request.query_params.get("_target_url", default_target)
+
+
+def _get_mocked_oauth_info() -> dict:
+    token = get_token()
+    if token is None:
+        raise ValueError(
+            "Your machine must be logged in to HF to debug an OAuth app locally. Please"
+            " run `hf auth login` or set `HF_TOKEN` as environment variable "
+            "with one of your access token. You can generate a new token in your "
+            "settings page (https://huggingface.co/settings/tokens)."
+        )
+
+    user = whoami()
+    if user["type"] != "user":
+        raise ValueError(
+            "Your machine is not logged in with a personal account. Please use a "
+            "personal access token. You can generate a new token in your settings page"
+            " (https://huggingface.co/settings/tokens)."
+        )
+
+    return {
+        "access_token": token,
+        "token_type": "bearer",
+        "expires_in": 8 * 60 * 60,  # 8 hours
+        "id_token": "FOOBAR",
+        "scope": "openid profile",
+        "refresh_token": "hf_oauth__refresh_token",
+        "expires_at": int(time.time()) + 8 * 60 * 60,  # 8 hours
+        "userinfo": {
+            "sub": "0123456789",
+            "name": user["fullname"],
+            "preferred_username": user["name"],
+            "profile": f"https://huggingface.co/{user['name']}",
+            "picture": user["avatarUrl"],
+            "website": "",
+            "aud": "00000000-0000-0000-0000-000000000000",
+            "auth_time": 1691672844,
+            "nonce": "aaaaaaaaaaaaaaaaaaa",
+            "iat": 1691672844,
+            "exp": 1691676444,
+            "iss": "https://huggingface.co",
+        },
+    }
+
+
+def _get_oauth_uris(route_prefix: str = "/") -> tuple[str, str, str]:
+    route_prefix = route_prefix.strip("/")
+    if route_prefix:
+        route_prefix = f"/{route_prefix}"
+    return (
+        f"{route_prefix}/oauth/huggingface/login",
+        f"{route_prefix}/oauth/huggingface/callback",
+        f"{route_prefix}/oauth/huggingface/logout",
+    )

venv/lib/python3.12/site-packages/huggingface_hub/_snapshot_download.py

@@ -0,0 +1,465 @@
+import os
+from pathlib import Path
+from typing import Iterable, List, Literal, Optional, Union, overload
+
+import httpx
+from tqdm.auto import tqdm as base_tqdm
+from tqdm.contrib.concurrent import thread_map
+
+from . import constants
+from .errors import (
+    DryRunError,
+    GatedRepoError,
+    HfHubHTTPError,
+    LocalEntryNotFoundError,
+    RepositoryNotFoundError,
+    RevisionNotFoundError,
+)
+from .file_download import REGEX_COMMIT_HASH, DryRunFileInfo, hf_hub_download, repo_folder_name
+from .hf_api import DatasetInfo, HfApi, ModelInfo, RepoFile, SpaceInfo
+from .utils import OfflineModeIsEnabled, filter_repo_objects, is_tqdm_disabled, logging, validate_hf_hub_args
+from .utils import tqdm as hf_tqdm
+
+
+logger = logging.get_logger(__name__)
+
+LARGE_REPO_THRESHOLD = 1000  # After this limit, we don't consider `repo_info.siblings` to be reliable enough
+
+
+@overload
+def snapshot_download(
+    repo_id: str,
+    *,
+    repo_type: Optional[str] = None,
+    revision: Optional[str] = None,
+    cache_dir: Union[str, Path, None] = None,
+    local_dir: Union[str, Path, None] = None,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    user_agent: Optional[Union[dict, str]] = None,
+    etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT,
+    force_download: bool = False,
+    token: Optional[Union[bool, str]] = None,
+    local_files_only: bool = False,
+    allow_patterns: Optional[Union[list[str], str]] = None,
+    ignore_patterns: Optional[Union[list[str], str]] = None,
+    max_workers: int = 8,
+    tqdm_class: Optional[type[base_tqdm]] = None,
+    headers: Optional[dict[str, str]] = None,
+    endpoint: Optional[str] = None,
+    dry_run: Literal[False] = False,
+) -> str: ...
+
+
+@overload
+def snapshot_download(
+    repo_id: str,
+    *,
+    repo_type: Optional[str] = None,
+    revision: Optional[str] = None,
+    cache_dir: Union[str, Path, None] = None,
+    local_dir: Union[str, Path, None] = None,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    user_agent: Optional[Union[dict, str]] = None,
+    etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT,
+    force_download: bool = False,
+    token: Optional[Union[bool, str]] = None,
+    local_files_only: bool = False,
+    allow_patterns: Optional[Union[list[str], str]] = None,
+    ignore_patterns: Optional[Union[list[str], str]] = None,
+    max_workers: int = 8,
+    tqdm_class: Optional[type[base_tqdm]] = None,
+    headers: Optional[dict[str, str]] = None,
+    endpoint: Optional[str] = None,
+    dry_run: Literal[True] = True,
+) -> list[DryRunFileInfo]: ...
+
+
+@overload
+def snapshot_download(
+    repo_id: str,
+    *,
+    repo_type: Optional[str] = None,
+    revision: Optional[str] = None,
+    cache_dir: Union[str, Path, None] = None,
+    local_dir: Union[str, Path, None] = None,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    user_agent: Optional[Union[dict, str]] = None,
+    etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT,
+    force_download: bool = False,
+    token: Optional[Union[bool, str]] = None,
+    local_files_only: bool = False,
+    allow_patterns: Optional[Union[list[str], str]] = None,
+    ignore_patterns: Optional[Union[list[str], str]] = None,
+    max_workers: int = 8,
+    tqdm_class: Optional[type[base_tqdm]] = None,
+    headers: Optional[dict[str, str]] = None,
+    endpoint: Optional[str] = None,
+    dry_run: bool = False,
+) -> Union[str, list[DryRunFileInfo]]: ...
+
+
+@validate_hf_hub_args
+def snapshot_download(
+    repo_id: str,
+    *,
+    repo_type: Optional[str] = None,
+    revision: Optional[str] = None,
+    cache_dir: Union[str, Path, None] = None,
+    local_dir: Union[str, Path, None] = None,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    user_agent: Optional[Union[dict, str]] = None,
+    etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT,
+    force_download: bool = False,
+    token: Optional[Union[bool, str]] = None,
+    local_files_only: bool = False,
+    allow_patterns: Optional[Union[list[str], str]] = None,
+    ignore_patterns: Optional[Union[list[str], str]] = None,
+    max_workers: int = 8,
+    tqdm_class: Optional[type[base_tqdm]] = None,
+    headers: Optional[dict[str, str]] = None,
+    endpoint: Optional[str] = None,
+    dry_run: bool = False,
+) -> Union[str, list[DryRunFileInfo]]:
+    """Download repo files.
+
+    Download a whole snapshot of a repo's files at the specified revision. This is useful when you want all files from
+    a repo, because you don't know which ones you will need a priori. All files are nested inside a folder in order
+    to keep their actual filename relative to that folder. You can also filter which files to download using
+    `allow_patterns` and `ignore_patterns`.
+
+    If `local_dir` is provided, the file structure from the repo will be replicated in this location. When using this
+    option, the `cache_dir` will not be used and a `.cache/huggingface/` folder will be created at the root of `local_dir`
+    to store some metadata related to the downloaded files. While this mechanism is not as robust as the main
+    cache-system, it's optimized for regularly pulling the latest version of a repository.
+
+    An alternative would be to clone the repo but this requires git and git-lfs to be installed and properly
+    configured. It is also not possible to filter which files to download when cloning a repository using git.
+
+    Args:
+        repo_id (`str`):
+            A user or an organization name and a repo name separated by a `/`.
+        repo_type (`str`, *optional*):
+            Set to `"dataset"` or `"space"` if downloading from a dataset or space,
+            `None` or `"model"` if downloading from a model. Default is `None`.
+        revision (`str`, *optional*):
+            An optional Git revision id which can be a branch name, a tag, or a
+            commit hash.
+        cache_dir (`str`, `Path`, *optional*):
+            Path to the folder where cached files are stored.
+        local_dir (`str` or `Path`, *optional*):
+            If provided, the downloaded files will be placed under this directory.
+        library_name (`str`, *optional*):
+            The name of the library to which the object corresponds.
+        library_version (`str`, *optional*):
+            The version of the library.
+        user_agent (`str`, `dict`, *optional*):
+            The user-agent info in the form of a dictionary or a string.
+        etag_timeout (`float`, *optional*, defaults to `10`):
+            When fetching ETag, how many seconds to wait for the server to send
+            data before giving up which is passed to `httpx.request`.
+        force_download (`bool`, *optional*, defaults to `False`):
+            Whether the file should be downloaded even if it already exists in the local cache.
+        token (`str`, `bool`, *optional*):
+            A token to be used for the download.
+                - If `True`, the token is read from the HuggingFace config
+                  folder.
+                - If a string, it's used as the authentication token.
+        headers (`dict`, *optional*):
+            Additional headers to include in the request. Those headers take precedence over the others.
+        local_files_only (`bool`, *optional*, defaults to `False`):
+            If `True`, avoid downloading the file and return the path to the
+            local cached file if it exists.
+        allow_patterns (`list[str]` or `str`, *optional*):
+            If provided, only files matching at least one pattern are downloaded.
+        ignore_patterns (`list[str]` or `str`, *optional*):
+            If provided, files matching any of the patterns are not downloaded.
+        max_workers (`int`, *optional*):
+            Number of concurrent threads to download files (1 thread = 1 file download).
+            Defaults to 8.
+        tqdm_class (`tqdm`, *optional*):
+            If provided, overwrites the default behavior for the progress bar. Passed
+            argument must inherit from `tqdm.auto.tqdm` or at least mimic its behavior.
+            Note that the `tqdm_class` is not passed to each individual download.
+            Defaults to the custom HF progress bar that can be disabled by setting
+            `HF_HUB_DISABLE_PROGRESS_BARS` environment variable.
+        dry_run (`bool`, *optional*, defaults to `False`):
+            If `True`, perform a dry run without actually downloading the files. Returns a list of
+            [`DryRunFileInfo`] objects containing information about what would be downloaded.
+
+    Returns:
+        `str` or list of [`DryRunFileInfo`]:
+            - If `dry_run=False`: Local snapshot path.
+            - If `dry_run=True`: A list of [`DryRunFileInfo`] objects containing download information.
+
+    Raises:
+        [`~utils.RepositoryNotFoundError`]
+            If the repository to download from cannot be found. This may be because it doesn't exist,
+            or because it is set to `private` and you do not have access.
+        [`~utils.RevisionNotFoundError`]
+            If the revision to download from cannot be found.
+        [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+            If `token=True` and the token cannot be found.
+        [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) if
+            ETag cannot be determined.
+        [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+            if some parameter value is invalid.
+    """
+    if cache_dir is None:
+        cache_dir = constants.HF_HUB_CACHE
+    if revision is None:
+        revision = constants.DEFAULT_REVISION
+    if isinstance(cache_dir, Path):
+        cache_dir = str(cache_dir)
+
+    if repo_type is None:
+        repo_type = "model"
+    if repo_type not in constants.REPO_TYPES:
+        raise ValueError(f"Invalid repo type: {repo_type}. Accepted repo types are: {str(constants.REPO_TYPES)}")
+
+    storage_folder = os.path.join(cache_dir, repo_folder_name(repo_id=repo_id, repo_type=repo_type))
+
+    api = HfApi(
+        library_name=library_name,
+        library_version=library_version,
+        user_agent=user_agent,
+        endpoint=endpoint,
+        headers=headers,
+        token=token,
+    )
+
+    repo_info: Union[ModelInfo, DatasetInfo, SpaceInfo, None] = None
+    api_call_error: Optional[Exception] = None
+    if not local_files_only:
+        # try/except logic to handle different errors => taken from `hf_hub_download`
+        try:
+            # if we have internet connection we want to list files to download
+            repo_info = api.repo_info(repo_id=repo_id, repo_type=repo_type, revision=revision)
+        except httpx.ProxyError:
+            # Actually raise on proxy error
+            raise
+        except (httpx.ConnectError, httpx.TimeoutException, OfflineModeIsEnabled) as error:
+            # Internet connection is down
+            # => will try to use local files only
+            api_call_error = error
+            pass
+        except RevisionNotFoundError:
+            # The repo was found but the revision doesn't exist on the Hub (never existed or got deleted)
+            raise
+        except HfHubHTTPError as error:
+            # Multiple reasons for an http error:
+            # - Repository is private and invalid/missing token sent
+            # - Repository is gated and invalid/missing token sent
+            # - Hub is down (error 500 or 504)
+            # => let's switch to 'local_files_only=True' to check if the files are already cached.
+            #    (if it's not the case, the error will be re-raised)
+            api_call_error = error
+            pass
+
+    # At this stage, if `repo_info` is None it means either:
+    # - internet connection is down
+    # - internet connection is deactivated (local_files_only=True or HF_HUB_OFFLINE=True)
+    # - repo is private/gated and invalid/missing token sent
+    # - Hub is down
+    # => let's look if we can find the appropriate folder in the cache:
+    #    - if the specified revision is a commit hash, look inside "snapshots".
+    #    - f the specified revision is a branch or tag, look inside "refs".
+    # => if local_dir is not None, we will return the path to the local folder if it exists.
+    if repo_info is None:
+        if dry_run:
+            raise DryRunError(
+                "Dry run cannot be performed as the repository cannot be accessed. Please check your internet connection or authentication token."
+            ) from api_call_error
+
+        # Try to get which commit hash corresponds to the specified revision
+        commit_hash = None
+        if REGEX_COMMIT_HASH.match(revision):
+            commit_hash = revision
+        else:
+            ref_path = os.path.join(storage_folder, "refs", revision)
+            if os.path.exists(ref_path):
+                # retrieve commit_hash from refs file
+                with open(ref_path) as f:
+                    commit_hash = f.read()
+
+        # Try to locate snapshot folder for this commit hash
+        if commit_hash is not None and local_dir is None:
+            snapshot_folder = os.path.join(storage_folder, "snapshots", commit_hash)
+            if os.path.exists(snapshot_folder):
+                # Snapshot folder exists => let's return it
+                # (but we can't check if all the files are actually there)
+                return snapshot_folder
+
+        # If local_dir is not None, return it if it exists and is not empty
+        if local_dir is not None:
+            local_dir = Path(local_dir)
+            if local_dir.is_dir() and any(local_dir.iterdir()):
+                logger.warning(
+                    f"Returning existing local_dir `{local_dir}` as remote repo cannot be accessed in `snapshot_download` ({api_call_error})."
+                )
+                return str(local_dir.resolve())
+        # If we couldn't find the appropriate folder on disk, raise an error.
+        if local_files_only:
+            raise LocalEntryNotFoundError(
+                "Cannot find an appropriate cached snapshot folder for the specified revision on the local disk and "
+                "outgoing traffic has been disabled. To enable repo look-ups and downloads online, pass "
+                "'local_files_only=False' as input."
+            )
+        elif isinstance(api_call_error, OfflineModeIsEnabled):
+            raise LocalEntryNotFoundError(
+                "Cannot find an appropriate cached snapshot folder for the specified revision on the local disk and "
+                "outgoing traffic has been disabled. To enable repo look-ups and downloads online, set "
+                "'HF_HUB_OFFLINE=0' as environment variable."
+            ) from api_call_error
+        elif isinstance(api_call_error, (RepositoryNotFoundError, GatedRepoError)) or (
+            isinstance(api_call_error, HfHubHTTPError) and api_call_error.response.status_code == 401
+        ):
+            # Repo not found, gated, or specific authentication error => let's raise the actual error
+            raise api_call_error
+        else:
+            # Otherwise: most likely a connection issue or Hub downtime => let's warn the user
+            raise LocalEntryNotFoundError(
+                "An error happened while trying to locate the files on the Hub and we cannot find the appropriate"
+                " snapshot folder for the specified revision on the local disk. Please check your internet connection"
+                " and try again."
+            ) from api_call_error
+
+    # At this stage, internet connection is up and running
+    # => let's download the files!
+    assert repo_info.sha is not None, "Repo info returned from server must have a revision sha."
+
+    # Corner case: on very large repos, the siblings list in `repo_info` might not contain all files.
+    # In that case, we need to use the `list_repo_tree` method to prevent caching issues.
+    repo_files: Iterable[str] = [f.rfilename for f in repo_info.siblings] if repo_info.siblings is not None else []
+    unreliable_nb_files = (
+        repo_info.siblings is None or len(repo_info.siblings) == 0 or len(repo_info.siblings) > LARGE_REPO_THRESHOLD
+    )
+    if unreliable_nb_files:
+        logger.info(
+            "Number of files in the repo is unreliable. Using `list_repo_tree` to ensure all files are listed."
+        )
+        repo_files = (
+            f.rfilename
+            for f in api.list_repo_tree(repo_id=repo_id, recursive=True, revision=revision, repo_type=repo_type)
+            if isinstance(f, RepoFile)
+        )
+
+    filtered_repo_files: Iterable[str] = filter_repo_objects(
+        items=repo_files,
+        allow_patterns=allow_patterns,
+        ignore_patterns=ignore_patterns,
+    )
+
+    if not unreliable_nb_files:
+        filtered_repo_files = list(filtered_repo_files)
+        tqdm_desc = f"Fetching {len(filtered_repo_files)} files"
+    else:
+        tqdm_desc = "Fetching ... files"
+    if dry_run:
+        tqdm_desc = "[dry-run] " + tqdm_desc
+
+    commit_hash = repo_info.sha
+    snapshot_folder = os.path.join(storage_folder, "snapshots", commit_hash)
+    # if passed revision is not identical to commit_hash
+    # then revision has to be a branch name or tag name.
+    # In that case store a ref.
+    if revision != commit_hash:
+        ref_path = os.path.join(storage_folder, "refs", revision)
+        try:
+            os.makedirs(os.path.dirname(ref_path), exist_ok=True)
+            with open(ref_path, "w") as f:
+                f.write(commit_hash)
+        except OSError as e:
+            logger.warning(f"Ignored error while writing commit hash to {ref_path}: {e}.")
+
+    results: List[Union[str, DryRunFileInfo]] = []
+
+    # User can use its own tqdm class or the default one from `huggingface_hub.utils`
+    tqdm_class = tqdm_class or hf_tqdm
+
+    # Create a progress bar for the bytes downloaded
+    # This progress bar is shared across threads/files and gets updated each time we fetch
+    # metadata for a file.
+    bytes_progress = tqdm_class(
+        desc="Downloading (incomplete total...)",
+        disable=is_tqdm_disabled(log_level=logger.getEffectiveLevel()),
+        total=0,
+        initial=0,
+        unit="B",
+        unit_scale=True,
+        name="huggingface_hub.snapshot_download",
+    )
+
+    class _AggregatedTqdm:
+        """Fake tqdm object to aggregate progress into the parent `bytes_progress` bar.
+
+        In practice the `_AggregatedTqdm` object won't be displayed, it's just used to update
+        the `bytes_progress` bar from each thread/file download.
+        """
+
+        def __init__(self, *args, **kwargs):
+            # Adjust the total of the parent progress bar
+            total = kwargs.pop("total", None)
+            if total is not None:
+                bytes_progress.total += total
+                bytes_progress.refresh()
+
+            # Adjust initial of the parent progress bar
+            initial = kwargs.pop("initial", 0)
+            if initial:
+                bytes_progress.update(initial)
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc_value, traceback):
+            pass
+
+        def update(self, n: Optional[Union[int, float]] = 1) -> None:
+            bytes_progress.update(n)
+
+    # we pass the commit_hash to hf_hub_download
+    # so no network call happens if we already
+    # have the file locally.
+    def _inner_hf_hub_download(repo_file: str) -> None:
+        results.append(
+            hf_hub_download(  # type: ignore
+                repo_id,
+                filename=repo_file,
+                repo_type=repo_type,
+                revision=commit_hash,
+                endpoint=endpoint,
+                cache_dir=cache_dir,
+                local_dir=local_dir,
+                library_name=library_name,
+                library_version=library_version,
+                user_agent=user_agent,
+                etag_timeout=etag_timeout,
+                force_download=force_download,
+                token=token,
+                headers=headers,
+                tqdm_class=_AggregatedTqdm,  # type: ignore
+                dry_run=dry_run,
+            )
+        )
+
+    thread_map(
+        _inner_hf_hub_download,
+        filtered_repo_files,
+        desc=tqdm_desc,
+        max_workers=max_workers,
+        tqdm_class=tqdm_class,
+    )
+
+    bytes_progress.set_description("Download complete")
+
+    if dry_run:
+        assert all(isinstance(r, DryRunFileInfo) for r in results)
+        return results  # type: ignore
+
+    if local_dir is not None:
+        return str(os.path.realpath(local_dir))
+    return snapshot_folder

venv/lib/python3.12/site-packages/huggingface_hub/_space_api.py

@@ -0,0 +1,168 @@
+# coding=utf-8
+# Copyright 2019-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from huggingface_hub.utils import parse_datetime
+
+
+class SpaceStage(str, Enum):
+    """
+    Enumeration of possible stage of a Space on the Hub.
+
+    Value can be compared to a string:
+    ```py
+    assert SpaceStage.BUILDING == "BUILDING"
+    ```
+
+    Taken from https://github.com/huggingface/moon-landing/blob/main/server/repo_types/SpaceInfo.ts#L61 (private url).
+    """
+
+    # Copied from moon-landing > server > repo_types > SpaceInfo.ts (private repo)
+    NO_APP_FILE = "NO_APP_FILE"
+    CONFIG_ERROR = "CONFIG_ERROR"
+    BUILDING = "BUILDING"
+    BUILD_ERROR = "BUILD_ERROR"
+    RUNNING = "RUNNING"
+    RUNNING_BUILDING = "RUNNING_BUILDING"
+    RUNTIME_ERROR = "RUNTIME_ERROR"
+    DELETING = "DELETING"
+    STOPPED = "STOPPED"
+    PAUSED = "PAUSED"
+
+
+class SpaceHardware(str, Enum):
+    """
+    Enumeration of hardwares available to run your Space on the Hub.
+
+    Value can be compared to a string:
+    ```py
+    assert SpaceHardware.CPU_BASIC == "cpu-basic"
+    ```
+
+    Taken from https://github.com/huggingface-internal/moon-landing/blob/main/server/repo_types/SpaceHardwareFlavor.ts (private url).
+    """
+
+    # CPU
+    CPU_BASIC = "cpu-basic"
+    CPU_UPGRADE = "cpu-upgrade"
+    CPU_XL = "cpu-xl"
+
+    # ZeroGPU
+    ZERO_A10G = "zero-a10g"
+
+    # GPU
+    T4_SMALL = "t4-small"
+    T4_MEDIUM = "t4-medium"
+    L4X1 = "l4x1"
+    L4X4 = "l4x4"
+    L40SX1 = "l40sx1"
+    L40SX4 = "l40sx4"
+    L40SX8 = "l40sx8"
+    A10G_SMALL = "a10g-small"
+    A10G_LARGE = "a10g-large"
+    A10G_LARGEX2 = "a10g-largex2"
+    A10G_LARGEX4 = "a10g-largex4"
+    A100_LARGE = "a100-large"
+    H100 = "h100"
+    H100X8 = "h100x8"
+
+
+class SpaceStorage(str, Enum):
+    """
+    Enumeration of persistent storage available for your Space on the Hub.
+
+    Value can be compared to a string:
+    ```py
+    assert SpaceStorage.SMALL == "small"
+    ```
+
+    Taken from https://github.com/huggingface/moon-landing/blob/main/server/repo_types/SpaceHardwareFlavor.ts#L24 (private url).
+    """
+
+    SMALL = "small"
+    MEDIUM = "medium"
+    LARGE = "large"
+
+
+@dataclass
+class SpaceRuntime:
+    """
+    Contains information about the current runtime of a Space.
+
+    Args:
+        stage (`str`):
+            Current stage of the space. Example: RUNNING.
+        hardware (`str` or `None`):
+            Current hardware of the space. Example: "cpu-basic". Can be `None` if Space
+            is `BUILDING` for the first time.
+        requested_hardware (`str` or `None`):
+            Requested hardware. Can be different from `hardware` especially if the request
+            has just been made. Example: "t4-medium". Can be `None` if no hardware has
+            been requested yet.
+        sleep_time (`int` or `None`):
+            Number of seconds the Space will be kept alive after the last request. By default (if value is `None`), the
+            Space will never go to sleep if it's running on an upgraded hardware, while it will go to sleep after 48
+            hours on a free 'cpu-basic' hardware. For more details, see https://huggingface.co/docs/hub/spaces-gpus#sleep-time.
+        raw (`dict`):
+            Raw response from the server. Contains more information about the Space
+            runtime like number of replicas, number of cpu, memory size,...
+    """
+
+    stage: SpaceStage
+    hardware: Optional[SpaceHardware]
+    requested_hardware: Optional[SpaceHardware]
+    sleep_time: Optional[int]
+    storage: Optional[SpaceStorage]
+    raw: dict
+
+    def __init__(self, data: dict) -> None:
+        self.stage = data["stage"]
+        self.hardware = data.get("hardware", {}).get("current")
+        self.requested_hardware = data.get("hardware", {}).get("requested")
+        self.sleep_time = data.get("gcTimeout")
+        self.storage = data.get("storage")
+        self.raw = data
+
+
+@dataclass
+class SpaceVariable:
+    """
+    Contains information about the current variables of a Space.
+
+    Args:
+        key (`str`):
+            Variable key. Example: `"MODEL_REPO_ID"`
+        value (`str`):
+            Variable value. Example: `"the_model_repo_id"`.
+        description (`str` or None):
+            Description of the variable. Example: `"Model Repo ID of the implemented model"`.
+        updatedAt (`datetime` or None):
+            datetime of the last update of the variable (if the variable has been updated at least once).
+    """
+
+    key: str
+    value: str
+    description: Optional[str]
+    updated_at: Optional[datetime]
+
+    def __init__(self, key: str, values: dict) -> None:
+        self.key = key
+        self.value = values["value"]
+        self.description = values.get("description")
+        updated_at = values.get("updatedAt")
+        self.updated_at = parse_datetime(updated_at) if updated_at is not None else None

venv/lib/python3.12/site-packages/huggingface_hub/_tensorboard_logger.py

@@ -0,0 +1,190 @@
+# Copyright 2023 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains a logger to push training logs to the Hub, using Tensorboard."""
+
+from pathlib import Path
+from typing import Optional, Union
+
+from ._commit_scheduler import CommitScheduler
+from .errors import EntryNotFoundError
+from .repocard import ModelCard
+from .utils import experimental
+
+
+# Depending on user's setup, SummaryWriter can come either from 'tensorboardX'
+# or from 'torch.utils.tensorboard'. Both are compatible so let's try to load
+# from either of them.
+try:
+    from tensorboardX import SummaryWriter as _RuntimeSummaryWriter
+
+    is_summary_writer_available = True
+except ImportError:
+    try:
+        from torch.utils.tensorboard import SummaryWriter as _RuntimeSummaryWriter
+
+        is_summary_writer_available = True
+    except ImportError:
+        # Dummy class to avoid failing at import. Will raise on instance creation.
+        class _DummySummaryWriter:
+            pass
+
+        _RuntimeSummaryWriter = _DummySummaryWriter  # type: ignore[assignment]
+        is_summary_writer_available = False
+
+
+class HFSummaryWriter(_RuntimeSummaryWriter):
+    """
+    Wrapper around the tensorboard's `SummaryWriter` to push training logs to the Hub.
+
+    Data is logged locally and then pushed to the Hub asynchronously. Pushing data to the Hub is done in a separate
+    thread to avoid blocking the training script. In particular, if the upload fails for any reason (e.g. a connection
+    issue), the main script will not be interrupted. Data is automatically pushed to the Hub every `commit_every`
+    minutes (default to every 5 minutes).
+
+    > [!WARNING]
+    > `HFSummaryWriter` is experimental. Its API is subject to change in the future without prior notice.
+
+    Args:
+        repo_id (`str`):
+            The id of the repo to which the logs will be pushed.
+        logdir (`str`, *optional*):
+            The directory where the logs will be written. If not specified, a local directory will be created by the
+            underlying `SummaryWriter` object.
+        commit_every (`int` or `float`, *optional*):
+            The frequency (in minutes) at which the logs will be pushed to the Hub. Defaults to 5 minutes.
+        squash_history (`bool`, *optional*):
+            Whether to squash the history of the repo after each commit. Defaults to `False`. Squashing commits is
+            useful to avoid degraded performances on the repo when it grows too large.
+        repo_type (`str`, *optional*):
+            The type of the repo to which the logs will be pushed. Defaults to "model".
+        repo_revision (`str`, *optional*):
+            The revision of the repo to which the logs will be pushed. Defaults to "main".
+        repo_private (`bool`, *optional*):
+            Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists.
+        path_in_repo (`str`, *optional*):
+            The path to the folder in the repo where the logs will be pushed. Defaults to "tensorboard/".
+        repo_allow_patterns (`list[str]` or `str`, *optional*):
+            A list of patterns to include in the upload. Defaults to `"*.tfevents.*"`. Check out the
+            [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#upload-a-folder) for more details.
+        repo_ignore_patterns (`list[str]` or `str`, *optional*):
+            A list of patterns to exclude in the upload. Check out the
+            [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#upload-a-folder) for more details.
+        token (`str`, *optional*):
+            Authentication token. Will default to the stored token. See https://huggingface.co/settings/token for more
+            details
+        kwargs:
+            Additional keyword arguments passed to `SummaryWriter`.
+
+    Examples:
+    ```diff
+    # Taken from https://pytorch.org/docs/stable/tensorboard.html
+    - from torch.utils.tensorboard import SummaryWriter
+    + from huggingface_hub import HFSummaryWriter
+
+    import numpy as np
+
+    - writer = SummaryWriter()
+    + writer = HFSummaryWriter(repo_id="username/my-trained-model")
+
+    for n_iter in range(100):
+        writer.add_scalar('Loss/train', np.random.random(), n_iter)
+        writer.add_scalar('Loss/test', np.random.random(), n_iter)
+        writer.add_scalar('Accuracy/train', np.random.random(), n_iter)
+        writer.add_scalar('Accuracy/test', np.random.random(), n_iter)
+    ```
+
+    ```py
+    >>> from huggingface_hub import HFSummaryWriter
+
+    # Logs are automatically pushed every 15 minutes (5 by default) + when exiting the context manager
+    >>> with HFSummaryWriter(repo_id="test_hf_logger", commit_every=15) as logger:
+    ...     logger.add_scalar("a", 1)
+    ...     logger.add_scalar("b", 2)
+    ```
+    """
+
+    @experimental
+    def __new__(cls, *args, **kwargs) -> "HFSummaryWriter":
+        if not is_summary_writer_available:
+            raise ImportError(
+                "You must have `tensorboard` installed to use `HFSummaryWriter`. Please run `pip install --upgrade"
+                " tensorboardX` first."
+            )
+        return super().__new__(cls)
+
+    def __init__(
+        self,
+        repo_id: str,
+        *,
+        logdir: Optional[str] = None,
+        commit_every: Union[int, float] = 5,
+        squash_history: bool = False,
+        repo_type: Optional[str] = None,
+        repo_revision: Optional[str] = None,
+        repo_private: Optional[bool] = None,
+        path_in_repo: Optional[str] = "tensorboard",
+        repo_allow_patterns: Optional[Union[list[str], str]] = "*.tfevents.*",
+        repo_ignore_patterns: Optional[Union[list[str], str]] = None,
+        token: Optional[str] = None,
+        **kwargs,
+    ):
+        # Initialize SummaryWriter
+        super().__init__(logdir=logdir, **kwargs)
+
+        # Check logdir has been correctly initialized and fail early otherwise. In practice, SummaryWriter takes care of it.
+        if not isinstance(self.logdir, str):
+            raise ValueError(f"`self.logdir` must be a string. Got '{self.logdir}' of type {type(self.logdir)}.")
+
+        # Append logdir name to `path_in_repo`
+        if path_in_repo is None or path_in_repo == "":
+            path_in_repo = Path(self.logdir).name
+        else:
+            path_in_repo = path_in_repo.strip("/") + "/" + Path(self.logdir).name
+
+        # Initialize scheduler
+        self.scheduler = CommitScheduler(
+            folder_path=self.logdir,
+            path_in_repo=path_in_repo,
+            repo_id=repo_id,
+            repo_type=repo_type,
+            revision=repo_revision,
+            private=repo_private,
+            token=token,
+            allow_patterns=repo_allow_patterns,
+            ignore_patterns=repo_ignore_patterns,
+            every=commit_every,
+            squash_history=squash_history,
+        )
+
+        # Exposing some high-level info at root level
+        self.repo_id = self.scheduler.repo_id
+        self.repo_type = self.scheduler.repo_type
+        self.repo_revision = self.scheduler.revision
+
+        # Add `hf-summary-writer` tag to the model card metadata
+        try:
+            card = ModelCard.load(repo_id_or_path=self.repo_id, repo_type=self.repo_type)
+        except EntryNotFoundError:
+            card = ModelCard("")
+        tags = card.data.get("tags", [])
+        if "hf-summary-writer" not in tags:
+            tags.append("hf-summary-writer")
+            card.data["tags"] = tags
+            card.push_to_hub(repo_id=self.repo_id, repo_type=self.repo_type)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Push to hub in a non-blocking way when exiting the logger's context manager."""
+        super().__exit__(exc_type, exc_val, exc_tb)
+        future = self.scheduler.trigger()
+        future.result()

venv/lib/python3.12/site-packages/huggingface_hub/_upload_large_folder.py

@@ -0,0 +1,765 @@
+# coding=utf-8
+# Copyright 2024-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import enum
+import logging
+import os
+import queue
+import shutil
+import sys
+import threading
+import time
+import traceback
+from datetime import datetime
+from pathlib import Path
+from threading import Lock
+from typing import TYPE_CHECKING, Any, Optional, Union
+from urllib.parse import quote
+
+from ._commit_api import CommitOperationAdd, UploadInfo, _fetch_upload_modes
+from ._local_folder import LocalUploadFileMetadata, LocalUploadFilePaths, get_local_upload_paths, read_upload_metadata
+from .constants import DEFAULT_REVISION, REPO_TYPES
+from .utils import DEFAULT_IGNORE_PATTERNS, _format_size, filter_repo_objects, tqdm
+from .utils._runtime import is_xet_available
+from .utils.sha import sha_fileobj
+
+
+if TYPE_CHECKING:
+    from .hf_api import HfApi
+
+logger = logging.getLogger(__name__)
+
+WAITING_TIME_IF_NO_TASKS = 10  # seconds
+MAX_NB_FILES_FETCH_UPLOAD_MODE = 100
+COMMIT_SIZE_SCALE: list[int] = [20, 50, 75, 100, 125, 200, 250, 400, 600, 1000]
+
+UPLOAD_BATCH_SIZE_XET = 256  # Max 256 files per upload batch for XET-enabled repos
+UPLOAD_BATCH_SIZE_LFS = 1  # Otherwise, batches of 1 for regular LFS upload
+
+# Repository limits (from https://huggingface.co/docs/hub/repositories-recommendations)
+MAX_FILES_PER_REPO = 100_000  # Recommended maximum number of files per repository
+MAX_FILES_PER_FOLDER = 10_000  # Recommended maximum number of files per folder
+MAX_FILE_SIZE_GB = 200  # Recommended maximum for individual file size (split larger files)
+RECOMMENDED_FILE_SIZE_GB = 20  # Recommended maximum for individual file size
+
+
+def _validate_upload_limits(paths_list: list[LocalUploadFilePaths]) -> None:
+    """
+    Validate upload against repository limits and warn about potential issues.
+
+    Args:
+        paths_list: List of file paths to be uploaded
+
+    Warns about:
+        - Too many files in the repository (>100k)
+        - Too many entries (files or subdirectories) in a single folder (>10k)
+        - Files exceeding size limits (>20GB recommended, >200GB maximum)
+    """
+    logger.info("Running validation checks on files to upload...")
+
+    # Check 1: Total file count
+    if len(paths_list) > MAX_FILES_PER_REPO:
+        logger.warning(
+            f"You are about to upload {len(paths_list):,} files. "
+            f"This exceeds the recommended limit of {MAX_FILES_PER_REPO:,} files per repository.\n"
+            f"Consider:\n"
+            f"  - Splitting your data into multiple repositories\n"
+            f"  - Using fewer, larger files (e.g., parquet files)\n"
+            f"  - See: https://huggingface.co/docs/hub/repositories-recommendations"
+        )
+
+    # Check 2: Files and subdirectories per folder
+    # Track immediate children (files and subdirs) for each folder
+    from collections import defaultdict
+
+    entries_per_folder: dict[str, Any] = defaultdict(lambda: {"files": 0, "subdirs": set()})
+
+    for paths in paths_list:
+        path = Path(paths.path_in_repo)
+        parts = path.parts
+
+        # Count this file in its immediate parent directory
+        parent = str(path.parent) if str(path.parent) != "." else "."
+        entries_per_folder[parent]["files"] += 1
+
+        # Track immediate subdirectories for each parent folder
+        # Walk through the path components to track parent-child relationships
+        for i, child in enumerate(parts[:-1]):
+            parent = "." if i == 0 else "/".join(parts[:i])
+            entries_per_folder[parent]["subdirs"].add(child)
+
+    # Check limits for each folder
+    for folder, data in entries_per_folder.items():
+        file_count = data["files"]
+        subdir_count = len(data["subdirs"])
+        total_entries = file_count + subdir_count
+
+        if total_entries > MAX_FILES_PER_FOLDER:
+            folder_display = "root" if folder == "." else folder
+            logger.warning(
+                f"Folder '{folder_display}' contains {total_entries:,} entries "
+                f"({file_count:,} files and {subdir_count:,} subdirectories). "
+                f"This exceeds the recommended {MAX_FILES_PER_FOLDER:,} entries per folder.\n"
+                "Consider reorganising into sub-folders."
+            )
+
+    # Check 3: File sizes
+    large_files = []
+    very_large_files = []
+
+    for paths in paths_list:
+        size = paths.file_path.stat().st_size
+        size_gb = size / 1_000_000_000  # Use decimal GB as per Hub limits
+
+        if size_gb > MAX_FILE_SIZE_GB:
+            very_large_files.append((paths.path_in_repo, size_gb))
+        elif size_gb > RECOMMENDED_FILE_SIZE_GB:
+            large_files.append((paths.path_in_repo, size_gb))
+
+    # Warn about very large files (>200GB)
+    if very_large_files:
+        files_str = "\n  - ".join(f"{path}: {size:.1f}GB" for path, size in very_large_files[:5])
+        more_str = f"\n  ... and {len(very_large_files) - 5} more files" if len(very_large_files) > 5 else ""
+        logger.warning(
+            f"Found {len(very_large_files)} files exceeding the {MAX_FILE_SIZE_GB}GB recommended maximum:\n"
+            f"  - {files_str}{more_str}\n"
+            f"Consider splitting these files into smaller chunks."
+        )
+
+    # Warn about large files (>20GB)
+    if large_files:
+        files_str = "\n  - ".join(f"{path}: {size:.1f}GB" for path, size in large_files[:5])
+        more_str = f"\n  ... and {len(large_files) - 5} more files" if len(large_files) > 5 else ""
+        logger.warning(
+            f"Found {len(large_files)} files larger than {RECOMMENDED_FILE_SIZE_GB}GB (recommended limit):\n"
+            f"  - {files_str}{more_str}\n"
+            f"Large files may slow down loading and processing."
+        )
+
+    logger.info("Validation checks complete.")
+
+
+def upload_large_folder_internal(
+    api: "HfApi",
+    repo_id: str,
+    folder_path: Union[str, Path],
+    *,
+    repo_type: str,  # Repo type is required!
+    revision: Optional[str] = None,
+    private: Optional[bool] = None,
+    allow_patterns: Optional[Union[list[str], str]] = None,
+    ignore_patterns: Optional[Union[list[str], str]] = None,
+    num_workers: Optional[int] = None,
+    print_report: bool = True,
+    print_report_every: int = 60,
+):
+    """Upload a large folder to the Hub in the most resilient way possible.
+
+    See [`HfApi.upload_large_folder`] for the full documentation.
+    """
+    # 1. Check args and setup
+    if repo_type is None:
+        raise ValueError(
+            "For large uploads, `repo_type` is explicitly required. Please set it to `model`, `dataset` or `space`."
+            " If you are using the CLI, pass it as `--repo-type=model`."
+        )
+    if repo_type not in REPO_TYPES:
+        raise ValueError(f"Invalid repo type, must be one of {REPO_TYPES}")
+    if revision is None:
+        revision = DEFAULT_REVISION
+
+    folder_path = Path(folder_path).expanduser().resolve()
+    if not folder_path.is_dir():
+        raise ValueError(f"Provided path: '{folder_path}' is not a directory")
+
+    if ignore_patterns is None:
+        ignore_patterns = []
+    elif isinstance(ignore_patterns, str):
+        ignore_patterns = [ignore_patterns]
+    ignore_patterns += DEFAULT_IGNORE_PATTERNS
+
+    if num_workers is None:
+        nb_cores = os.cpu_count() or 1
+        num_workers = max(nb_cores // 2, 1)  # Use at most half of cpu cores
+
+    # 2. Create repo if missing
+    repo_url = api.create_repo(repo_id=repo_id, repo_type=repo_type, private=private, exist_ok=True)
+    logger.info(f"Repo created: {repo_url}")
+    repo_id = repo_url.repo_id
+
+    # Warn on too many commits
+    try:
+        commits = api.list_repo_commits(repo_id=repo_id, repo_type=repo_type, revision=revision)
+        commit_count = len(commits)
+        if commit_count > 500:
+            logger.warning(
+                f"\n{'=' * 80}\n"
+                f"WARNING: This repository has {commit_count} commits.\n"
+                f"Repositories with a large number of commits can experience performance issues.\n"
+                f"\n"
+                f"Consider squashing your commit history using `super_squash_history()`.\n"
+                "To do so, you need to stop this process, run the snippet below and restart the upload command."
+                f"  from huggingface_hub import super_squash_history\n"
+                f"  super_squash_history(repo_id='{repo_id}', repo_type='{repo_type}')\n"
+                f"\n"
+                f"Note: This is a non-revertible operation. See the documentation for more details:\n"
+                f"https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.super_squash_history\n"
+                f"{'=' * 80}\n"
+            )
+    except Exception as e:
+        # Don't fail the upload if we can't check commit count
+        logger.debug(f"Could not check commit count: {e}")
+
+    # 2.1 Check if xet is enabled to set batch file upload size
+    upload_batch_size = UPLOAD_BATCH_SIZE_XET if is_xet_available() else UPLOAD_BATCH_SIZE_LFS
+
+    # 3. List files to upload
+    filtered_paths_list = filter_repo_objects(
+        (path.relative_to(folder_path).as_posix() for path in folder_path.glob("**/*") if path.is_file()),
+        allow_patterns=allow_patterns,
+        ignore_patterns=ignore_patterns,
+    )
+    paths_list = [get_local_upload_paths(folder_path, relpath) for relpath in filtered_paths_list]
+    logger.info(f"Found {len(paths_list)} candidate files to upload")
+
+    # Validate upload against repository limits
+    _validate_upload_limits(paths_list)
+
+    logger.info("Starting upload...")
+
+    # Read metadata for each file
+    items = [
+        (paths, read_upload_metadata(folder_path, paths.path_in_repo))
+        for paths in tqdm(paths_list, desc="Recovering from metadata files")
+    ]
+
+    # 4. Start workers
+    status = LargeUploadStatus(items, upload_batch_size)
+    threads = [
+        threading.Thread(
+            target=_worker_job,
+            kwargs={
+                "status": status,
+                "api": api,
+                "repo_id": repo_id,
+                "repo_type": repo_type,
+                "revision": revision,
+            },
+        )
+        for _ in range(num_workers)
+    ]
+
+    for thread in threads:
+        thread.start()
+
+    # 5. Print regular reports
+    if print_report:
+        print("\n\n" + status.current_report())
+    last_report_ts = time.time()
+    while True:
+        time.sleep(1)
+        if time.time() - last_report_ts >= print_report_every:
+            if print_report:
+                _print_overwrite(status.current_report())
+            last_report_ts = time.time()
+        if status.is_done():
+            logging.info("Is done: exiting main loop")
+            break
+
+    for thread in threads:
+        thread.join()
+
+    logger.info(status.current_report())
+    logging.info("Upload is complete!")
+
+
+####################
+# Logic to manage workers and synchronize tasks
+####################
+
+
+class WorkerJob(enum.Enum):
+    SHA256 = enum.auto()
+    GET_UPLOAD_MODE = enum.auto()
+    PREUPLOAD_LFS = enum.auto()
+    COMMIT = enum.auto()
+    WAIT = enum.auto()  # if no tasks are available but we don't want to exit
+
+
+JOB_ITEM_T = tuple[LocalUploadFilePaths, LocalUploadFileMetadata]
+
+
+class LargeUploadStatus:
+    """Contains information, queues and tasks for a large upload process."""
+
+    def __init__(self, items: list[JOB_ITEM_T], upload_batch_size: int = 1):
+        self.items = items
+        self.queue_sha256: "queue.Queue[JOB_ITEM_T]" = queue.Queue()
+        self.queue_get_upload_mode: "queue.Queue[JOB_ITEM_T]" = queue.Queue()
+        self.queue_preupload_lfs: "queue.Queue[JOB_ITEM_T]" = queue.Queue()
+        self.queue_commit: "queue.Queue[JOB_ITEM_T]" = queue.Queue()
+        self.lock = Lock()
+
+        self.nb_workers_sha256: int = 0
+        self.nb_workers_get_upload_mode: int = 0
+        self.nb_workers_preupload_lfs: int = 0
+        self.upload_batch_size: int = upload_batch_size
+        self.nb_workers_commit: int = 0
+        self.nb_workers_waiting: int = 0
+        self.last_commit_attempt: Optional[float] = None
+
+        self._started_at = datetime.now()
+        self._chunk_idx: int = 1
+        self._chunk_lock: Lock = Lock()
+
+        # Setup queues
+        for item in self.items:
+            paths, metadata = item
+            if metadata.sha256 is None:
+                self.queue_sha256.put(item)
+            elif metadata.upload_mode is None:
+                self.queue_get_upload_mode.put(item)
+            elif metadata.upload_mode == "lfs" and not metadata.is_uploaded:
+                self.queue_preupload_lfs.put(item)
+            elif not metadata.is_committed:
+                self.queue_commit.put(item)
+            else:
+                logger.debug(f"Skipping file {paths.path_in_repo} (already uploaded and committed)")
+
+    def target_chunk(self) -> int:
+        with self._chunk_lock:
+            return COMMIT_SIZE_SCALE[self._chunk_idx]
+
+    def update_chunk(self, success: bool, nb_items: int, duration: float) -> None:
+        with self._chunk_lock:
+            if not success:
+                logger.warning(f"Failed to commit {nb_items} files at once. Will retry with less files in next batch.")
+                self._chunk_idx -= 1
+            elif nb_items >= COMMIT_SIZE_SCALE[self._chunk_idx] and duration < 40:
+                logger.info(f"Successfully committed {nb_items} at once. Increasing the limit for next batch.")
+                self._chunk_idx += 1
+
+            self._chunk_idx = max(0, min(self._chunk_idx, len(COMMIT_SIZE_SCALE) - 1))
+
+    def current_report(self) -> str:
+        """Generate a report of the current status of the large upload."""
+        nb_hashed = 0
+        size_hashed = 0
+        nb_preuploaded = 0
+        nb_lfs = 0
+        nb_lfs_unsure = 0
+        size_preuploaded = 0
+        nb_committed = 0
+        size_committed = 0
+        total_size = 0
+        ignored_files = 0
+        total_files = 0
+
+        with self.lock:
+            for _, metadata in self.items:
+                if metadata.should_ignore:
+                    ignored_files += 1
+                    continue
+                total_size += metadata.size
+                total_files += 1
+                if metadata.sha256 is not None:
+                    nb_hashed += 1
+                    size_hashed += metadata.size
+                if metadata.upload_mode == "lfs":
+                    nb_lfs += 1
+                if metadata.upload_mode is None:
+                    nb_lfs_unsure += 1
+                if metadata.is_uploaded:
+                    nb_preuploaded += 1
+                    size_preuploaded += metadata.size
+                if metadata.is_committed:
+                    nb_committed += 1
+                    size_committed += metadata.size
+            total_size_str = _format_size(total_size)
+
+            now = datetime.now()
+            now_str = now.strftime("%Y-%m-%d %H:%M:%S")
+            elapsed = now - self._started_at
+            elapsed_str = str(elapsed).split(".")[0]  # remove milliseconds
+
+            message = "\n" + "-" * 10
+            message += f" {now_str} ({elapsed_str}) "
+            message += "-" * 10 + "\n"
+
+            message += "Files:   "
+            message += f"hashed {nb_hashed}/{total_files} ({_format_size(size_hashed)}/{total_size_str}) | "
+            message += f"pre-uploaded: {nb_preuploaded}/{nb_lfs} ({_format_size(size_preuploaded)}/{total_size_str})"
+            if nb_lfs_unsure > 0:
+                message += f" (+{nb_lfs_unsure} unsure)"
+            message += f" | committed: {nb_committed}/{total_files} ({_format_size(size_committed)}/{total_size_str})"
+            message += f" | ignored: {ignored_files}\n"
+
+            message += "Workers: "
+            message += f"hashing: {self.nb_workers_sha256} | "
+            message += f"get upload mode: {self.nb_workers_get_upload_mode} | "
+            message += f"pre-uploading: {self.nb_workers_preupload_lfs} | "
+            message += f"committing: {self.nb_workers_commit} | "
+            message += f"waiting: {self.nb_workers_waiting}\n"
+            message += "-" * 51
+
+            return message
+
+    def is_done(self) -> bool:
+        with self.lock:
+            return all(metadata.is_committed or metadata.should_ignore for _, metadata in self.items)
+
+
+def _worker_job(
+    status: LargeUploadStatus,
+    api: "HfApi",
+    repo_id: str,
+    repo_type: str,
+    revision: str,
+):
+    """
+    Main process for a worker. The worker will perform tasks based on the priority list until all files are uploaded
+    and committed. If no tasks are available, the worker will wait for 10 seconds before checking again.
+
+    If a task fails for any reason, the item(s) are put back in the queue for another worker to pick up.
+
+    Read `upload_large_folder` docstring for more information on how tasks are prioritized.
+    """
+    while True:
+        next_job: Optional[tuple[WorkerJob, list[JOB_ITEM_T]]] = None
+
+        # Determine next task
+        next_job = _determine_next_job(status)
+        if next_job is None:
+            return
+        job, items = next_job
+
+        # Perform task
+        if job == WorkerJob.SHA256:
+            item = items[0]  # single item
+            try:
+                _compute_sha256(item)
+                status.queue_get_upload_mode.put(item)
+            except KeyboardInterrupt:
+                raise
+            except Exception as e:
+                logger.error(f"Failed to compute sha256: {e}")
+                traceback.format_exc()
+                status.queue_sha256.put(item)
+
+            with status.lock:
+                status.nb_workers_sha256 -= 1
+
+        elif job == WorkerJob.GET_UPLOAD_MODE:
+            try:
+                _get_upload_mode(items, api=api, repo_id=repo_id, repo_type=repo_type, revision=revision)
+            except KeyboardInterrupt:
+                raise
+            except Exception as e:
+                logger.error(f"Failed to get upload mode: {e}")
+                traceback.format_exc()
+
+            # Items are either:
+            # - dropped (if should_ignore)
+            # - put in LFS queue (if LFS)
+            # - put in commit queue (if regular)
+            # - or put back (if error occurred).
+            for item in items:
+                _, metadata = item
+                if metadata.should_ignore:
+                    continue
+                if metadata.upload_mode == "lfs":
+                    status.queue_preupload_lfs.put(item)
+                elif metadata.upload_mode == "regular":
+                    status.queue_commit.put(item)
+                else:
+                    status.queue_get_upload_mode.put(item)
+
+            with status.lock:
+                status.nb_workers_get_upload_mode -= 1
+
+        elif job == WorkerJob.PREUPLOAD_LFS:
+            try:
+                _preupload_lfs(items, api=api, repo_id=repo_id, repo_type=repo_type, revision=revision)
+                for item in items:
+                    status.queue_commit.put(item)
+            except KeyboardInterrupt:
+                raise
+            except Exception as e:
+                logger.error(f"Failed to preupload LFS: {e}")
+                traceback.format_exc()
+                for item in items:
+                    status.queue_preupload_lfs.put(item)
+
+            with status.lock:
+                status.nb_workers_preupload_lfs -= 1
+
+        elif job == WorkerJob.COMMIT:
+            start_ts = time.time()
+            success = True
+            try:
+                _commit(items, api=api, repo_id=repo_id, repo_type=repo_type, revision=revision)
+            except KeyboardInterrupt:
+                raise
+            except Exception as e:
+                logger.error(f"Failed to commit: {e}")
+                traceback.format_exc()
+                for item in items:
+                    status.queue_commit.put(item)
+                success = False
+            duration = time.time() - start_ts
+            status.update_chunk(success, len(items), duration)
+            with status.lock:
+                status.last_commit_attempt = time.time()
+                status.nb_workers_commit -= 1
+
+        elif job == WorkerJob.WAIT:
+            time.sleep(WAITING_TIME_IF_NO_TASKS)
+            with status.lock:
+                status.nb_workers_waiting -= 1
+
+
+def _determine_next_job(status: LargeUploadStatus) -> Optional[tuple[WorkerJob, list[JOB_ITEM_T]]]:
+    with status.lock:
+        # 1. Commit if more than 5 minutes since last commit attempt (and at least 1 file)
+        if (
+            status.nb_workers_commit == 0
+            and status.queue_commit.qsize() > 0
+            and status.last_commit_attempt is not None
+            and time.time() - status.last_commit_attempt > 5 * 60
+        ):
+            status.nb_workers_commit += 1
+            logger.debug("Job: commit (more than 5 minutes since last commit attempt)")
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
+
+        # 2. Commit if at least 100 files are ready to commit
+        elif status.nb_workers_commit == 0 and status.queue_commit.qsize() >= 150:
+            status.nb_workers_commit += 1
+            logger.debug("Job: commit (>100 files ready)")
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
+
+        # 3. Get upload mode if at least 100 files
+        elif status.queue_get_upload_mode.qsize() >= MAX_NB_FILES_FETCH_UPLOAD_MODE:
+            status.nb_workers_get_upload_mode += 1
+            logger.debug(f"Job: get upload mode (>{MAX_NB_FILES_FETCH_UPLOAD_MODE} files ready)")
+            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE))
+
+        # 4. Preupload LFS file if at least `status.upload_batch_size` files and no worker is preuploading LFS
+        elif status.queue_preupload_lfs.qsize() >= status.upload_batch_size and status.nb_workers_preupload_lfs == 0:
+            status.nb_workers_preupload_lfs += 1
+            logger.debug("Job: preupload LFS (no other worker preuploading LFS)")
+            return (WorkerJob.PREUPLOAD_LFS, _get_n(status.queue_preupload_lfs, status.upload_batch_size))
+
+        # 5. Compute sha256 if at least 1 file and no worker is computing sha256
+        elif status.queue_sha256.qsize() > 0 and status.nb_workers_sha256 == 0:
+            status.nb_workers_sha256 += 1
+            logger.debug("Job: sha256 (no other worker computing sha256)")
+            return (WorkerJob.SHA256, _get_one(status.queue_sha256))
+
+        # 6. Get upload mode if at least 1 file and no worker is getting upload mode
+        elif status.queue_get_upload_mode.qsize() > 0 and status.nb_workers_get_upload_mode == 0:
+            status.nb_workers_get_upload_mode += 1
+            logger.debug("Job: get upload mode (no other worker getting upload mode)")
+            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE))
+
+        # 7. Preupload LFS file if at least `status.upload_batch_size` files
+        elif status.queue_preupload_lfs.qsize() >= status.upload_batch_size:
+            status.nb_workers_preupload_lfs += 1
+            logger.debug("Job: preupload LFS")
+            return (WorkerJob.PREUPLOAD_LFS, _get_n(status.queue_preupload_lfs, status.upload_batch_size))
+
+        # 8. Compute sha256 if at least 1 file
+        elif status.queue_sha256.qsize() > 0:
+            status.nb_workers_sha256 += 1
+            logger.debug("Job: sha256")
+            return (WorkerJob.SHA256, _get_one(status.queue_sha256))
+
+        # 9. Get upload mode if at least 1 file
+        elif status.queue_get_upload_mode.qsize() > 0:
+            status.nb_workers_get_upload_mode += 1
+            logger.debug("Job: get upload mode")
+            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE))
+
+        # 10. Preupload LFS file if at least 1 file
+        elif status.queue_preupload_lfs.qsize() > 0:
+            status.nb_workers_preupload_lfs += 1
+            logger.debug("Job: preupload LFS")
+            return (WorkerJob.PREUPLOAD_LFS, _get_n(status.queue_preupload_lfs, status.upload_batch_size))
+
+        # 11. Commit if at least 1 file and 1 min since last commit attempt
+        elif (
+            status.nb_workers_commit == 0
+            and status.queue_commit.qsize() > 0
+            and status.last_commit_attempt is not None
+            and time.time() - status.last_commit_attempt > 1 * 60
+        ):
+            status.nb_workers_commit += 1
+            logger.debug("Job: commit (1 min since last commit attempt)")
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
+
+        # 12. Commit if at least 1 file all other queues are empty and all workers are waiting
+        #     e.g. when it's the last commit
+        elif (
+            status.nb_workers_commit == 0
+            and status.queue_commit.qsize() > 0
+            and status.queue_sha256.qsize() == 0
+            and status.queue_get_upload_mode.qsize() == 0
+            and status.queue_preupload_lfs.qsize() == 0
+            and status.nb_workers_sha256 == 0
+            and status.nb_workers_get_upload_mode == 0
+            and status.nb_workers_preupload_lfs == 0
+        ):
+            status.nb_workers_commit += 1
+            logger.debug("Job: commit")
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
+
+        # 13. If all queues are empty, exit
+        elif all(metadata.is_committed or metadata.should_ignore for _, metadata in status.items):
+            logger.info("All files have been processed! Exiting worker.")
+            return None
+
+        # 14. If no task is available, wait
+        else:
+            status.nb_workers_waiting += 1
+            logger.debug(f"No task available, waiting... ({WAITING_TIME_IF_NO_TASKS}s)")
+            return (WorkerJob.WAIT, [])
+
+
+####################
+# Atomic jobs (sha256, get_upload_mode, preupload_lfs, commit)
+####################
+
+
+def _compute_sha256(item: JOB_ITEM_T) -> None:
+    """Compute sha256 of a file and save it in metadata."""
+    paths, metadata = item
+    if metadata.sha256 is None:
+        with paths.file_path.open("rb") as f:
+            metadata.sha256 = sha_fileobj(f).hex()
+    metadata.save(paths)
+
+
+def _get_upload_mode(items: list[JOB_ITEM_T], api: "HfApi", repo_id: str, repo_type: str, revision: str) -> None:
+    """Get upload mode for each file and update metadata.
+
+    Also receive info if the file should be ignored.
+    """
+    additions = [_build_hacky_operation(item) for item in items]
+    _fetch_upload_modes(
+        additions=additions,
+        repo_type=repo_type,
+        repo_id=repo_id,
+        headers=api._build_hf_headers(),
+        revision=quote(revision, safe=""),
+        endpoint=api.endpoint,
+    )
+    for item, addition in zip(items, additions):
+        paths, metadata = item
+        metadata.upload_mode = addition._upload_mode
+        metadata.should_ignore = addition._should_ignore
+        metadata.remote_oid = addition._remote_oid
+        metadata.save(paths)
+
+
+def _preupload_lfs(items: list[JOB_ITEM_T], api: "HfApi", repo_id: str, repo_type: str, revision: str) -> None:
+    """Preupload LFS files and update metadata."""
+    additions = [_build_hacky_operation(item) for item in items]
+    api.preupload_lfs_files(
+        repo_id=repo_id,
+        repo_type=repo_type,
+        revision=revision,
+        additions=additions,
+    )
+
+    for paths, metadata in items:
+        metadata.is_uploaded = True
+        metadata.save(paths)
+
+
+def _commit(items: list[JOB_ITEM_T], api: "HfApi", repo_id: str, repo_type: str, revision: str) -> None:
+    """Commit files to the repo."""
+    additions = [_build_hacky_operation(item) for item in items]
+    api.create_commit(
+        repo_id=repo_id,
+        repo_type=repo_type,
+        revision=revision,
+        operations=additions,
+        commit_message="Add files using upload-large-folder tool",
+    )
+    for paths, metadata in items:
+        metadata.is_committed = True
+        metadata.save(paths)
+
+
+####################
+# Hacks with CommitOperationAdd to bypass checks/sha256 calculation
+####################
+
+
+class HackyCommitOperationAdd(CommitOperationAdd):
+    def __post_init__(self) -> None:
+        if isinstance(self.path_or_fileobj, Path):
+            self.path_or_fileobj = str(self.path_or_fileobj)
+
+
+def _build_hacky_operation(item: JOB_ITEM_T) -> HackyCommitOperationAdd:
+    paths, metadata = item
+    operation = HackyCommitOperationAdd(path_in_repo=paths.path_in_repo, path_or_fileobj=paths.file_path)
+    with paths.file_path.open("rb") as file:
+        sample = file.peek(512)[:512]
+    if metadata.sha256 is None:
+        raise ValueError("sha256 must have been computed by now!")
+    operation.upload_info = UploadInfo(sha256=bytes.fromhex(metadata.sha256), size=metadata.size, sample=sample)
+    operation._upload_mode = metadata.upload_mode  # type: ignore[assignment]
+    operation._should_ignore = metadata.should_ignore
+    operation._remote_oid = metadata.remote_oid
+    return operation
+
+
+####################
+# Misc helpers
+####################
+
+
+def _get_one(queue: "queue.Queue[JOB_ITEM_T]") -> list[JOB_ITEM_T]:
+    return [queue.get()]
+
+
+def _get_n(queue: "queue.Queue[JOB_ITEM_T]", n: int) -> list[JOB_ITEM_T]:
+    return [queue.get() for _ in range(min(queue.qsize(), n))]
+
+
+def _print_overwrite(report: str) -> None:
+    """Print a report, overwriting the previous lines.
+
+    Since tqdm in using `sys.stderr` to (re-)write progress bars, we need to use `sys.stdout`
+    to print the report.
+
+    Note: works well only if no other process is writing to `sys.stdout`!
+    """
+    report += "\n"
+    # Get terminal width
+    terminal_width = shutil.get_terminal_size().columns
+
+    # Count number of lines that should be cleared
+    nb_lines = sum(len(line) // terminal_width + 1 for line in report.splitlines())
+
+    # Clear previous lines based on the number of lines in the report
+    for _ in range(nb_lines):
+        sys.stdout.write("\r\033[K")  # Clear line
+        sys.stdout.write("\033[F")  # Move cursor up one line
+
+    # Print the new report, filling remaining space with whitespace
+    sys.stdout.write(report)
+    sys.stdout.write(" " * (terminal_width - len(report.splitlines()[-1])))
+    sys.stdout.flush()

venv/lib/python3.12/site-packages/huggingface_hub/_webhooks_payload.py

@@ -0,0 +1,137 @@
+# coding=utf-8
+# Copyright 2023-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains data structures to parse the webhooks payload."""
+
+from typing import Literal, Optional
+
+from .utils import is_pydantic_available
+
+
+if is_pydantic_available():
+    from pydantic import BaseModel
+else:
+    # Define a dummy BaseModel to avoid import errors when pydantic is not installed
+    # Import error will be raised when trying to use the class
+
+    class BaseModel:  # type: ignore [no-redef]
+        def __init__(self, *args, **kwargs) -> None:
+            raise ImportError(
+                "You must have `pydantic` installed to use `WebhookPayload`. This is an optional dependency that"
+                " should be installed separately. Please run `pip install --upgrade pydantic` and retry."
+            )
+
+
+# This is an adaptation of the ReportV3 interface implemented in moon-landing. V0, V1 and V2 have been ignored as they
+# are not in used anymore. To keep in sync when format is updated in
+# https://github.com/huggingface/moon-landing/blob/main/server/lib/HFWebhooks.ts (internal link).
+
+
+WebhookEvent_T = Literal[
+    "create",
+    "delete",
+    "move",
+    "update",
+]
+RepoChangeEvent_T = Literal[
+    "add",
+    "move",
+    "remove",
+    "update",
+]
+RepoType_T = Literal[
+    "dataset",
+    "model",
+    "space",
+]
+DiscussionStatus_T = Literal[
+    "closed",
+    "draft",
+    "open",
+    "merged",
+]
+SupportedWebhookVersion = Literal[3]
+
+
+class ObjectId(BaseModel):
+    id: str
+
+
+class WebhookPayloadUrl(BaseModel):
+    web: str
+    api: Optional[str] = None
+
+
+class WebhookPayloadMovedTo(BaseModel):
+    name: str
+    owner: ObjectId
+
+
+class WebhookPayloadWebhook(ObjectId):
+    version: SupportedWebhookVersion
+
+
+class WebhookPayloadEvent(BaseModel):
+    action: WebhookEvent_T
+    scope: str
+
+
+class WebhookPayloadDiscussionChanges(BaseModel):
+    base: str
+    mergeCommitId: Optional[str] = None
+
+
+class WebhookPayloadComment(ObjectId):
+    author: ObjectId
+    hidden: bool
+    content: Optional[str] = None
+    url: WebhookPayloadUrl
+
+
+class WebhookPayloadDiscussion(ObjectId):
+    num: int
+    author: ObjectId
+    url: WebhookPayloadUrl
+    title: str
+    isPullRequest: bool
+    status: DiscussionStatus_T
+    changes: Optional[WebhookPayloadDiscussionChanges] = None
+    pinned: Optional[bool] = None
+
+
+class WebhookPayloadRepo(ObjectId):
+    owner: ObjectId
+    head_sha: Optional[str] = None
+    name: str
+    private: bool
+    subdomain: Optional[str] = None
+    tags: Optional[list[str]] = None
+    type: Literal["dataset", "model", "space"]
+    url: WebhookPayloadUrl
+
+
+class WebhookPayloadUpdatedRef(BaseModel):
+    ref: str
+    oldSha: Optional[str] = None
+    newSha: Optional[str] = None
+
+
+class WebhookPayload(BaseModel):
+    event: WebhookPayloadEvent
+    repo: WebhookPayloadRepo
+    discussion: Optional[WebhookPayloadDiscussion] = None
+    comment: Optional[WebhookPayloadComment] = None
+    webhook: WebhookPayloadWebhook
+    movedTo: Optional[WebhookPayloadMovedTo] = None
+    updatedRefs: Optional[list[WebhookPayloadUpdatedRef]] = None

venv/lib/python3.12/site-packages/huggingface_hub/_webhooks_server.py

@@ -0,0 +1,376 @@
+# coding=utf-8
+# Copyright 2023-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains `WebhooksServer` and `webhook_endpoint` to create a webhook server easily."""
+
+import atexit
+import inspect
+import os
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from .utils import experimental, is_fastapi_available, is_gradio_available
+
+
+if TYPE_CHECKING:
+    import gradio as gr
+    from fastapi import Request
+
+if is_fastapi_available():
+    from fastapi import FastAPI, Request
+    from fastapi.responses import JSONResponse
+else:
+    # Will fail at runtime if FastAPI is not available
+    FastAPI = Request = JSONResponse = None  # type: ignore
+
+
+_global_app: Optional["WebhooksServer"] = None
+_is_local = os.environ.get("SPACE_ID") is None
+
+
+@experimental
+class WebhooksServer:
+    """
+    The [`WebhooksServer`] class lets you create an instance of a Gradio app that can receive Huggingface webhooks.
+    These webhooks can be registered using the [`~WebhooksServer.add_webhook`] decorator. Webhook endpoints are added to
+    the app as a POST endpoint to the FastAPI router. Once all the webhooks are registered, the `launch` method has to be
+    called to start the app.
+
+    It is recommended to accept [`WebhookPayload`] as the first argument of the webhook function. It is a Pydantic
+    model that contains all the information about the webhook event. The data will be parsed automatically for you.
+
+    Check out the [webhooks guide](../guides/webhooks_server) for a step-by-step tutorial on how to set up your
+    WebhooksServer and deploy it on a Space.
+
+    > [!WARNING]
+    > `WebhooksServer` is experimental. Its API is subject to change in the future.
+
+    > [!WARNING]
+    > You must have `gradio` installed to use `WebhooksServer` (`pip install --upgrade gradio`).
+
+    Args:
+        ui (`gradio.Blocks`, optional):
+            A Gradio UI instance to be used as the Space landing page. If `None`, a UI displaying instructions
+            about the configured webhooks is created.
+        webhook_secret (`str`, optional):
+            A secret key to verify incoming webhook requests. You can set this value to any secret you want as long as
+            you also configure it in your [webhooks settings panel](https://huggingface.co/settings/webhooks). You
+            can also set this value as the `WEBHOOK_SECRET` environment variable. If no secret is provided, the
+            webhook endpoints are opened without any security.
+
+    Example:
+
+        ```python
+        import gradio as gr
+        from huggingface_hub import WebhooksServer, WebhookPayload
+
+        with gr.Blocks() as ui:
+            ...
+
+        app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")
+
+        @app.add_webhook("/say_hello")
+        async def hello(payload: WebhookPayload):
+            return {"message": "hello"}
+
+        app.launch()
+        ```
+    """
+
+    def __new__(cls, *args, **kwargs) -> "WebhooksServer":
+        if not is_gradio_available():
+            raise ImportError(
+                "You must have `gradio` installed to use `WebhooksServer`. Please run `pip install --upgrade gradio`"
+                " first."
+            )
+        if not is_fastapi_available():
+            raise ImportError(
+                "You must have `fastapi` installed to use `WebhooksServer`. Please run `pip install --upgrade fastapi`"
+                " first."
+            )
+        return super().__new__(cls)
+
+    def __init__(
+        self,
+        ui: Optional["gr.Blocks"] = None,
+        webhook_secret: Optional[str] = None,
+    ) -> None:
+        self._ui = ui
+
+        self.webhook_secret = webhook_secret or os.getenv("WEBHOOK_SECRET")
+        self.registered_webhooks: dict[str, Callable] = {}
+        _warn_on_empty_secret(self.webhook_secret)
+
+    def add_webhook(self, path: Optional[str] = None) -> Callable:
+        """
+        Decorator to add a webhook to the [`WebhooksServer`] server.
+
+        Args:
+            path (`str`, optional):
+                The URL path to register the webhook function. If not provided, the function name will be used as the
+                path. In any case, all webhooks are registered under `/webhooks`.
+
+        Raises:
+            ValueError: If the provided path is already registered as a webhook.
+
+        Example:
+            ```python
+            from huggingface_hub import WebhooksServer, WebhookPayload
+
+            app = WebhooksServer()
+
+            @app.add_webhook
+            async def trigger_training(payload: WebhookPayload):
+                if payload.repo.type == "dataset" and payload.event.action == "update":
+                    # Trigger a training job if a dataset is updated
+                    ...
+
+            app.launch()
+        ```
+        """
+        # Usage: directly as decorator. Example: `@app.add_webhook`
+        if callable(path):
+            # If path is a function, it means it was used as a decorator without arguments
+            return self.add_webhook()(path)
+
+        # Usage: provide a path. Example: `@app.add_webhook(...)`
+        @wraps(FastAPI.post)
+        def _inner_post(*args, **kwargs):
+            func = args[0]
+            abs_path = f"/webhooks/{(path or func.__name__).strip('/')}"
+            if abs_path in self.registered_webhooks:
+                raise ValueError(f"Webhook {abs_path} already exists.")
+            self.registered_webhooks[abs_path] = func
+
+        return _inner_post
+
+    def launch(self, prevent_thread_lock: bool = False, **launch_kwargs: Any) -> None:
+        """Launch the Gradio app and register webhooks to the underlying FastAPI server.
+
+        Input parameters are forwarded to Gradio when launching the app.
+        """
+        ui = self._ui or self._get_default_ui()
+
+        # Start Gradio App
+        #   - as non-blocking so that webhooks can be added afterwards
+        #   - as shared if launch locally (to debug webhooks)
+        launch_kwargs.setdefault("share", _is_local)
+        self.fastapi_app, _, _ = ui.launch(prevent_thread_lock=True, **launch_kwargs)
+
+        # Register webhooks to FastAPI app
+        for path, func in self.registered_webhooks.items():
+            # Add secret check if required
+            if self.webhook_secret is not None:
+                func = _wrap_webhook_to_check_secret(func, webhook_secret=self.webhook_secret)
+
+            # Add route to FastAPI app
+            self.fastapi_app.post(path)(func)
+
+        # Print instructions and block main thread
+        space_host = os.environ.get("SPACE_HOST")
+        url = "https://" + space_host if space_host is not None else (ui.share_url or ui.local_url)
+        if url is None:
+            raise ValueError("Cannot find the URL of the app. Please provide a valid `ui` or update `gradio` version.")
+        url = url.strip("/")
+        message = "\nWebhooks are correctly setup and ready to use:"
+        message += "\n" + "\n".join(f"  - POST {url}{webhook}" for webhook in self.registered_webhooks)
+        message += "\nGo to https://huggingface.co/settings/webhooks to setup your webhooks."
+        print(message)
+
+        if not prevent_thread_lock:
+            ui.block_thread()
+
+    def _get_default_ui(self) -> "gr.Blocks":
+        """Default UI if not provided (lists webhooks and provides basic instructions)."""
+        import gradio as gr
+
+        with gr.Blocks() as ui:
+            gr.Markdown("# This is an app to process 🤗 Webhooks")
+            gr.Markdown(
+                "Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on"
+                " specific repos or to all repos belonging to particular set of users/organizations (not just your"
+                " repos, but any repo). Check out this [guide](https://huggingface.co/docs/hub/webhooks) to get to"
+                " know more about webhooks on the Huggingface Hub."
+            )
+            gr.Markdown(
+                f"{len(self.registered_webhooks)} webhook(s) are registered:"
+                + "\n\n"
+                + "\n ".join(
+                    f"- [{webhook_path}]({_get_webhook_doc_url(webhook.__name__, webhook_path)})"
+                    for webhook_path, webhook in self.registered_webhooks.items()
+                )
+            )
+            gr.Markdown(
+                "Go to https://huggingface.co/settings/webhooks to setup your webhooks."
+                + "\nYou app is running locally. Please look at the logs to check the full URL you need to set."
+                if _is_local
+                else (
+                    "\nThis app is running on a Space. You can find the corresponding URL in the options menu"
+                    " (top-right) > 'Embed the Space'. The URL looks like 'https://{username}-{repo_name}.hf.space'."
+                )
+            )
+        return ui
+
+
+@experimental
+def webhook_endpoint(path: Optional[str] = None) -> Callable:
+    """Decorator to start a [`WebhooksServer`] and register the decorated function as a webhook endpoint.
+
+    This is a helper to get started quickly. If you need more flexibility (custom landing page or webhook secret),
+    you can use [`WebhooksServer`] directly. You can register multiple webhook endpoints (to the same server) by using
+    this decorator multiple times.
+
+    Check out the [webhooks guide](../guides/webhooks_server) for a step-by-step tutorial on how to set up your
+    server and deploy it on a Space.
+
+    > [!WARNING]
+    > `webhook_endpoint` is experimental. Its API is subject to change in the future.
+
+    > [!WARNING]
+    > You must have `gradio` installed to use `webhook_endpoint` (`pip install --upgrade gradio`).
+
+    Args:
+        path (`str`, optional):
+            The URL path to register the webhook function. If not provided, the function name will be used as the path.
+            In any case, all webhooks are registered under `/webhooks`.
+
+    Examples:
+        The default usage is to register a function as a webhook endpoint. The function name will be used as the path.
+        The server will be started automatically at exit (i.e. at the end of the script).
+
+        ```python
+        from huggingface_hub import webhook_endpoint, WebhookPayload
+
+        @webhook_endpoint
+        async def trigger_training(payload: WebhookPayload):
+            if payload.repo.type == "dataset" and payload.event.action == "update":
+                # Trigger a training job if a dataset is updated
+                ...
+
+        # Server is automatically started at the end of the script.
+        ```
+
+        Advanced usage: register a function as a webhook endpoint and start the server manually. This is useful if you
+        are running it in a notebook.
+
+        ```python
+        from huggingface_hub import webhook_endpoint, WebhookPayload
+
+        @webhook_endpoint
+        async def trigger_training(payload: WebhookPayload):
+            if payload.repo.type == "dataset" and payload.event.action == "update":
+                # Trigger a training job if a dataset is updated
+                ...
+
+        # Start the server manually
+        trigger_training.launch()
+        ```
+    """
+    if callable(path):
+        # If path is a function, it means it was used as a decorator without arguments
+        return webhook_endpoint()(path)
+
+    @wraps(WebhooksServer.add_webhook)
+    def _inner(func: Callable) -> Callable:
+        app = _get_global_app()
+        app.add_webhook(path)(func)
+        if len(app.registered_webhooks) == 1:
+            # Register `app.launch` to run at exit (only once)
+            atexit.register(app.launch)
+
+        @wraps(app.launch)
+        def _launch_now():
+            # Run the app directly (without waiting atexit)
+            atexit.unregister(app.launch)
+            app.launch()
+
+        func.launch = _launch_now  # type: ignore
+        return func
+
+    return _inner
+
+
+def _get_global_app() -> WebhooksServer:
+    global _global_app
+    if _global_app is None:
+        _global_app = WebhooksServer()
+    return _global_app
+
+
+def _warn_on_empty_secret(webhook_secret: Optional[str]) -> None:
+    if webhook_secret is None:
+        print("Webhook secret is not defined. This means your webhook endpoints will be open to everyone.")
+        print(
+            "To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: "
+            "\n\t`app = WebhooksServer(webhook_secret='my_secret', ...)`"
+        )
+        print(
+            "For more details about webhook secrets, please refer to"
+            " https://huggingface.co/docs/hub/webhooks#webhook-secret."
+        )
+    else:
+        print("Webhook secret is correctly defined.")
+
+
+def _get_webhook_doc_url(webhook_name: str, webhook_path: str) -> str:
+    """Returns the anchor to a given webhook in the docs (experimental)"""
+    return "/docs#/default/" + webhook_name + webhook_path.replace("/", "_") + "_post"
+
+
+def _wrap_webhook_to_check_secret(func: Callable, webhook_secret: str) -> Callable:
+    """Wraps a webhook function to check the webhook secret before calling the function.
+
+    This is a hacky way to add the `request` parameter to the function signature. Since FastAPI based itself on route
+    parameters to inject the values to the function, we need to hack the function signature to retrieve the `Request`
+    object (and hence the headers). A far cleaner solution would be to use a middleware. However, since
+    `fastapi==0.90.1`, a middleware cannot be added once the app has started. And since the FastAPI app is started by
+    Gradio internals (and not by us), we cannot add a middleware.
+
+    This method is called only when a secret has been defined by the user. If a request is sent without the
+    "x-webhook-secret", the function will return a 401 error (unauthorized). If the header is sent but is incorrect,
+    the function will return a 403 error (forbidden).
+
+    Inspired by https://stackoverflow.com/a/33112180.
+    """
+    initial_sig = inspect.signature(func)
+
+    @wraps(func)
+    async def _protected_func(request: Request, **kwargs):
+        request_secret = request.headers.get("x-webhook-secret")
+        if request_secret is None:
+            return JSONResponse({"error": "x-webhook-secret header not set."}, status_code=401)
+        if request_secret != webhook_secret:
+            return JSONResponse({"error": "Invalid webhook secret."}, status_code=403)
+
+        # Inject `request` in kwargs if required
+        if "request" in initial_sig.parameters:
+            kwargs["request"] = request
+
+        # Handle both sync and async routes
+        if inspect.iscoroutinefunction(func):
+            return await func(**kwargs)
+        else:
+            return func(**kwargs)
+
+    # Update signature to include request
+    if "request" not in initial_sig.parameters:
+        _protected_func.__signature__ = initial_sig.replace(  # type: ignore
+            parameters=(
+                inspect.Parameter(name="request", kind=inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=Request),
+            )
+            + tuple(initial_sig.parameters.values())
+        )
+
+    # Return protected route
+    return _protected_func

venv/lib/python3.12/site-packages/huggingface_hub/cli/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2025 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

venv/lib/python3.12/site-packages/huggingface_hub/cli/_cli_utils.py

@@ -0,0 +1,245 @@
+# Copyright 2022 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains CLI utilities (styling, helpers)."""
+
+import dataclasses
+import datetime
+import importlib.metadata
+import os
+import time
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Literal, Optional, Union
+
+import click
+import typer
+
+from huggingface_hub import DatasetInfo, ModelInfo, SpaceInfo, __version__, constants
+from huggingface_hub.utils import ANSI, get_session, hf_raise_for_status, installation_method, logging
+
+
+logger = logging.get_logger()
+
+
+if TYPE_CHECKING:
+    from huggingface_hub.hf_api import HfApi
+
+
+def get_hf_api(token: Optional[str] = None) -> "HfApi":
+    # Import here to avoid circular import
+    from huggingface_hub.hf_api import HfApi
+
+    return HfApi(token=token, library_name="huggingface-cli", library_version=__version__)
+
+
+#### TYPER UTILS
+
+
+class AlphabeticalMixedGroup(typer.core.TyperGroup):
+    """
+    Typer Group that lists commands and sub-apps mixed and alphabetically.
+    """
+
+    def list_commands(self, ctx: click.Context) -> list[str]:  # type: ignore[name-defined]
+        # click.Group stores both commands and subgroups in `self.commands`
+        return sorted(self.commands.keys())
+
+
+def typer_factory(help: str) -> typer.Typer:
+    return typer.Typer(
+        help=help,
+        add_completion=True,
+        no_args_is_help=True,
+        cls=AlphabeticalMixedGroup,
+        # Disable rich completely for consistent experience
+        rich_markup_mode=None,
+        rich_help_panel=None,
+        pretty_exceptions_enable=False,
+    )
+
+
+class RepoType(str, Enum):
+    model = "model"
+    dataset = "dataset"
+    space = "space"
+
+
+RepoIdArg = Annotated[
+    str,
+    typer.Argument(
+        help="The ID of the repo (e.g. `username/repo-name`).",
+    ),
+]
+
+
+RepoTypeOpt = Annotated[
+    RepoType,
+    typer.Option(
+        help="The type of repository (model, dataset, or space).",
+    ),
+]
+
+TokenOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="A User Access Token generated from https://huggingface.co/settings/tokens.",
+    ),
+]
+
+PrivateOpt = Annotated[
+    Optional[bool],
+    typer.Option(
+        help="Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists.",
+    ),
+]
+
+RevisionOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="Git revision id which can be a branch name, a tag, or a commit hash.",
+    ),
+]
+
+
+LimitOpt = Annotated[
+    int,
+    typer.Option(help="Limit the number of results."),
+]
+
+AuthorOpt = Annotated[
+    Optional[str],
+    typer.Option(help="Filter by author or organization."),
+]
+
+FilterOpt = Annotated[
+    Optional[list[str]],
+    typer.Option(help="Filter by tags (e.g. 'text-classification'). Can be used multiple times."),
+]
+
+SearchOpt = Annotated[
+    Optional[str],
+    typer.Option(help="Search query."),
+]
+
+
+def repo_info_to_dict(info: Union[ModelInfo, DatasetInfo, SpaceInfo]) -> dict[str, object]:
+    """Convert repo info dataclasses to json-serializable dicts."""
+    return {
+        k: v.isoformat() if isinstance(v, datetime.datetime) else v
+        for k, v in dataclasses.asdict(info).items()
+        if v is not None
+    }
+
+
+def make_expand_properties_parser(valid_properties: list[str]):
+    """Create a callback to parse and validate comma-separated expand properties."""
+
+    def _parse_expand_properties(value: Optional[str]) -> Optional[list[str]]:
+        if value is None:
+            return None
+        properties = [p.strip() for p in value.split(",")]
+        for prop in properties:
+            if prop not in valid_properties:
+                raise typer.BadParameter(
+                    f"Invalid expand property: '{prop}'. Valid values are: {', '.join(valid_properties)}"
+                )
+        return properties
+
+    return _parse_expand_properties
+
+
+### PyPI VERSION CHECKER
+
+
+def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> None:
+    """
+    Check whether a newer version of a library is available on PyPI.
+
+    If a newer version is found, notify the user and suggest updating.
+    If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
+
+    This function is called at the entry point of the CLI. It only performs the check once every 24 hours, and any error
+    during the check is caught and logged, to avoid breaking the CLI.
+
+    Args:
+        library: The library to check for updates. Currently supports "huggingface_hub" and "transformers".
+    """
+    try:
+        _check_cli_update(library)
+    except Exception:
+        # We don't want the CLI to fail on version checks, no matter the reason.
+        logger.debug("Error while checking for CLI update.", exc_info=True)
+
+
+def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> None:
+    current_version = importlib.metadata.version(library)
+
+    # Skip if current version is a pre-release or dev version
+    if any(tag in current_version for tag in ["rc", "dev"]):
+        return
+
+    # Skip if already checked in the last 24 hours
+    if os.path.exists(constants.CHECK_FOR_UPDATE_DONE_PATH):
+        mtime = os.path.getmtime(constants.CHECK_FOR_UPDATE_DONE_PATH)
+        if (time.time() - mtime) < 24 * 3600:
+            return
+
+    # Touch the file to mark that we did the check now
+    Path(constants.CHECK_FOR_UPDATE_DONE_PATH).parent.mkdir(parents=True, exist_ok=True)
+    Path(constants.CHECK_FOR_UPDATE_DONE_PATH).touch()
+
+    # Check latest version from PyPI
+    response = get_session().get(f"https://pypi.org/pypi/{library}/json", timeout=2)
+    hf_raise_for_status(response)
+    data = response.json()
+    latest_version = data["info"]["version"]
+
+    # If latest version is different from current, notify user
+    if current_version != latest_version:
+        if library == "huggingface_hub":
+            update_command = _get_huggingface_hub_update_command()
+        else:
+            update_command = _get_transformers_update_command()
+
+        click.echo(
+            ANSI.yellow(
+                f"A new version of {library} ({latest_version}) is available! "
+                f"You are using version {current_version}.\n"
+                f"To update, run: {ANSI.bold(update_command)}\n",
+            )
+        )
+
+
+def _get_huggingface_hub_update_command() -> str:
+    """Return the command to update huggingface_hub."""
+    method = installation_method()
+    if method == "brew":
+        return "brew upgrade huggingface-cli"
+    elif method == "hf_installer" and os.name == "nt":
+        return 'powershell -NoProfile -Command "iwr -useb https://hf.co/cli/install.ps1 | iex"'
+    elif method == "hf_installer":
+        return "curl -LsSf https://hf.co/cli/install.sh | bash -"
+    else:  # unknown => likely pip
+        return "pip install -U huggingface_hub"
+
+
+def _get_transformers_update_command() -> str:
+    """Return the command to update transformers."""
+    method = installation_method()
+    if method == "hf_installer" and os.name == "nt":
+        return 'powershell -NoProfile -Command "iwr -useb https://hf.co/cli/install.ps1 | iex" -WithTransformers'
+    elif method == "hf_installer":
+        return "curl -LsSf https://hf.co/cli/install.sh | bash -s -- --with-transformers"
+    else:  # brew/unknown => likely pip
+        return "pip install -U transformers"

venv/lib/python3.12/site-packages/huggingface_hub/cli/auth.py

@@ -0,0 +1,147 @@
+# Copyright 2020 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to authenticate to the Hugging Face Hub and interact with your repositories.
+
+Usage:
+    # login and save token locally.
+    hf auth login --token=hf_*** --add-to-git-credential
+
+    # switch between tokens
+    hf auth switch
+
+    # list all tokens
+    hf auth list
+
+    # logout from all tokens
+    hf auth logout
+
+    # check which account you are logged in as
+    hf auth whoami
+"""
+
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub.constants import ENDPOINT
+from huggingface_hub.errors import HfHubHTTPError
+from huggingface_hub.hf_api import whoami
+
+from .._login import auth_list, auth_switch, login, logout
+from ..utils import ANSI, get_stored_tokens, get_token, logging
+from ._cli_utils import TokenOpt, typer_factory
+
+
+logger = logging.get_logger(__name__)
+
+
+auth_cli = typer_factory(help="Manage authentication (login, logout, etc.).")
+
+
+@auth_cli.command("login", help="Login using a token from huggingface.co/settings/tokens")
+def auth_login(
+    token: TokenOpt = None,
+    add_to_git_credential: Annotated[
+        bool,
+        typer.Option(
+            help="Save to git credential helper. Useful only if you plan to run git commands directly.",
+        ),
+    ] = False,
+) -> None:
+    login(token=token, add_to_git_credential=add_to_git_credential)
+
+
+@auth_cli.command("logout", help="Logout from a specific token")
+def auth_logout(
+    token_name: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Name of token to logout",
+        ),
+    ] = None,
+) -> None:
+    logout(token_name=token_name)
+
+
+def _select_token_name() -> Optional[str]:
+    token_names = list(get_stored_tokens().keys())
+
+    if not token_names:
+        logger.error("No stored tokens found. Please login first.")
+        return None
+
+    print("Available stored tokens:")
+    for i, token_name in enumerate(token_names, 1):
+        print(f"{i}. {token_name}")
+    while True:
+        try:
+            choice = input("Enter the number of the token to switch to (or 'q' to quit): ")
+            if choice.lower() == "q":
+                return None
+            index = int(choice) - 1
+            if 0 <= index < len(token_names):
+                return token_names[index]
+            else:
+                print("Invalid selection. Please try again.")
+        except ValueError:
+            print("Invalid input. Please enter a number or 'q' to quit.")
+
+
+@auth_cli.command("switch", help="Switch between access tokens")
+def auth_switch_cmd(
+    token_name: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Name of the token to switch to",
+        ),
+    ] = None,
+    add_to_git_credential: Annotated[
+        bool,
+        typer.Option(
+            help="Save to git credential helper. Useful only if you plan to run git commands directly.",
+        ),
+    ] = False,
+) -> None:
+    if token_name is None:
+        token_name = _select_token_name()
+    if token_name is None:
+        print("No token name provided. Aborting.")
+        raise typer.Exit()
+    auth_switch(token_name, add_to_git_credential=add_to_git_credential)
+
+
+@auth_cli.command("list", help="List all stored access tokens")
+def auth_list_cmd() -> None:
+    auth_list()
+
+
+@auth_cli.command("whoami", help="Find out which huggingface.co account you are logged in as.")
+def auth_whoami() -> None:
+    token = get_token()
+    if token is None:
+        print("Not logged in")
+        raise typer.Exit()
+    try:
+        info = whoami(token)
+        print(ANSI.bold("user: "), info["name"])
+        orgs = [org["name"] for org in info["orgs"]]
+        if orgs:
+            print(ANSI.bold("orgs: "), ",".join(orgs))
+
+        if ENDPOINT != "https://huggingface.co":
+            print(f"Authenticated through private endpoint: {ENDPOINT}")
+    except HfHubHTTPError as e:
+        print(e)
+        print(ANSI.red(e.response.text))
+        raise typer.Exit(code=1)

venv/lib/python3.12/site-packages/huggingface_hub/cli/cache.py

@@ -0,0 +1,841 @@
+# coding=utf-8
+# Copyright 2025-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains the 'hf cache' command group with cache management subcommands."""
+
+import csv
+import json
+import re
+import sys
+import time
+from collections import defaultdict
+from dataclasses import dataclass
+from enum import Enum
+from typing import Annotated, Any, Callable, Dict, List, Mapping, Optional, Tuple
+
+import typer
+
+from ..utils import (
+    ANSI,
+    CachedRepoInfo,
+    CachedRevisionInfo,
+    CacheNotFound,
+    HFCacheInfo,
+    _format_size,
+    scan_cache_dir,
+    tabulate,
+)
+from ..utils._parsing import parse_duration, parse_size
+from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api, typer_factory
+
+
+cache_cli = typer_factory(help="Manage local cache directory.")
+
+
+#### Cache helper utilities
+
+
+class OutputFormat(str, Enum):
+    table = "table"
+    json = "json"
+    csv = "csv"
+
+
+@dataclass(frozen=True)
+class _DeletionResolution:
+    revisions: frozenset[str]
+    selected: dict[CachedRepoInfo, frozenset[CachedRevisionInfo]]
+    missing: tuple[str, ...]
+
+
+_FILTER_PATTERN = re.compile(r"^(?P<key>[a-zA-Z_]+)\s*(?P<op>==|!=|>=|<=|>|<|=)\s*(?P<value>.+)$")
+_ALLOWED_OPERATORS = {"=", "!=", ">", "<", ">=", "<="}
+_FILTER_KEYS = {"accessed", "modified", "refs", "size", "type"}
+_SORT_KEYS = {"accessed", "modified", "name", "size"}
+_SORT_PATTERN = re.compile(r"^(?P<key>[a-zA-Z_]+)(?::(?P<order>asc|desc))?$")
+_SORT_DEFAULT_ORDER = {
+    # Default ordering: accessed/modified/size are descending (newest/biggest first), name is ascending
+    "accessed": "desc",
+    "modified": "desc",
+    "size": "desc",
+    "name": "asc",
+}
+
+
+# Dynamically generate SortOptions enum from _SORT_KEYS
+_sort_options_dict = {}
+for key in sorted(_SORT_KEYS):
+    _sort_options_dict[key] = key
+    _sort_options_dict[f"{key}_asc"] = f"{key}:asc"
+    _sort_options_dict[f"{key}_desc"] = f"{key}:desc"
+
+SortOptions = Enum("SortOptions", _sort_options_dict, type=str, module=__name__)  # type: ignore
+
+
+@dataclass(frozen=True)
+class CacheDeletionCounts:
+    """Simple counters summarizing cache deletions for CLI messaging."""
+
+    repo_count: int
+    partial_revision_count: int
+    total_revision_count: int
+
+
+CacheEntry = Tuple[CachedRepoInfo, Optional[CachedRevisionInfo]]
+RepoRefsMap = Dict[CachedRepoInfo, frozenset[str]]
+
+
+def summarize_deletions(
+    selected_by_repo: Mapping[CachedRepoInfo, frozenset[CachedRevisionInfo]],
+) -> CacheDeletionCounts:
+    """Summarize deletions across repositories."""
+    repo_count = 0
+    total_revisions = 0
+    revisions_in_full_repos = 0
+
+    for repo, revisions in selected_by_repo.items():
+        total_revisions += len(revisions)
+        if len(revisions) == len(repo.revisions):
+            repo_count += 1
+            revisions_in_full_repos += len(revisions)
+
+    partial_revision_count = total_revisions - revisions_in_full_repos
+    return CacheDeletionCounts(repo_count, partial_revision_count, total_revisions)
+
+
+def print_cache_selected_revisions(selected_by_repo: Mapping[CachedRepoInfo, frozenset[CachedRevisionInfo]]) -> None:
+    """Pretty-print selected cache revisions during confirmation prompts."""
+    for repo in sorted(selected_by_repo.keys(), key=lambda repo: (repo.repo_type, repo.repo_id.lower())):
+        repo_key = f"{repo.repo_type}/{repo.repo_id}"
+        revisions = sorted(selected_by_repo[repo], key=lambda rev: rev.commit_hash)
+        if len(revisions) == len(repo.revisions):
+            print(f"  - {repo_key} (entire repo)")
+            continue
+
+        print(f"  - {repo_key}:")
+        for revision in revisions:
+            refs = " ".join(sorted(revision.refs)) or "(detached)"
+            print(f"      {revision.commit_hash} [{refs}] {revision.size_on_disk_str}")
+
+
+def build_cache_index(
+    hf_cache_info: HFCacheInfo,
+) -> Tuple[
+    Dict[str, CachedRepoInfo],
+    Dict[str, Tuple[CachedRepoInfo, CachedRevisionInfo]],
+]:
+    """Create lookup tables so CLI commands can resolve repo ids and revisions quickly."""
+    repo_lookup: dict[str, CachedRepoInfo] = {}
+    revision_lookup: dict[str, tuple[CachedRepoInfo, CachedRevisionInfo]] = {}
+    for repo in hf_cache_info.repos:
+        repo_key = repo.cache_id.lower()
+        repo_lookup[repo_key] = repo
+        for revision in repo.revisions:
+            revision_lookup[revision.commit_hash.lower()] = (repo, revision)
+    return repo_lookup, revision_lookup
+
+
+def collect_cache_entries(
+    hf_cache_info: HFCacheInfo, *, include_revisions: bool
+) -> Tuple[List[CacheEntry], RepoRefsMap]:
+    """Flatten cache metadata into rows consumed by `hf cache ls`."""
+    entries: List[CacheEntry] = []
+    repo_refs_map: RepoRefsMap = {}
+    sorted_repos = sorted(hf_cache_info.repos, key=lambda repo: (repo.repo_type, repo.repo_id.lower()))
+    for repo in sorted_repos:
+        repo_refs_map[repo] = frozenset({ref for revision in repo.revisions for ref in revision.refs})
+        if include_revisions:
+            for revision in sorted(repo.revisions, key=lambda rev: rev.commit_hash):
+                entries.append((repo, revision))
+        else:
+            entries.append((repo, None))
+    if include_revisions:
+        entries.sort(
+            key=lambda entry: (
+                entry[0].cache_id,
+                entry[1].commit_hash if entry[1] is not None else "",
+            )
+        )
+    else:
+        entries.sort(key=lambda entry: entry[0].cache_id)
+    return entries, repo_refs_map
+
+
+def compile_cache_filter(
+    expr: str, repo_refs_map: RepoRefsMap
+) -> Callable[[CachedRepoInfo, Optional[CachedRevisionInfo], float], bool]:
+    """Convert a `hf cache ls` filter expression into the yes/no test we apply to each cache entry before displaying it."""
+    match = _FILTER_PATTERN.match(expr.strip())
+    if not match:
+        raise ValueError(f"Invalid filter expression: '{expr}'.")
+
+    key = match.group("key").lower()
+    op = match.group("op")
+    value_raw = match.group("value").strip()
+
+    if op not in _ALLOWED_OPERATORS:
+        raise ValueError(f"Unsupported operator '{op}' in filter '{expr}'. Must be one of {list(_ALLOWED_OPERATORS)}.")
+
+    if key not in _FILTER_KEYS:
+        raise ValueError(f"Unsupported filter key '{key}' in '{expr}'. Must be one of {list(_FILTER_KEYS)}.")
+    # at this point we know that key is in `_FILTER_KEYS`
+    if key == "size":
+        size_threshold = parse_size(value_raw)
+        return lambda repo, revision, _: _compare_numeric(
+            revision.size_on_disk if revision is not None else repo.size_on_disk,
+            op,
+            size_threshold,
+        )
+
+    if key in {"modified", "accessed"}:
+        seconds = parse_duration(value_raw.strip())
+
+        def _time_filter(repo: CachedRepoInfo, revision: Optional[CachedRevisionInfo], now: float) -> bool:
+            timestamp = (
+                repo.last_accessed
+                if key == "accessed"
+                else revision.last_modified
+                if revision is not None
+                else repo.last_modified
+            )
+            if timestamp is None:
+                return False
+            return _compare_numeric(now - timestamp, op, seconds)
+
+        return _time_filter
+
+    if key == "type":
+        expected = value_raw.lower()
+
+        if op != "=":
+            raise ValueError(f"Only '=' is supported for 'type' filters. Got '{op}'.")
+
+        def _type_filter(repo: CachedRepoInfo, revision: Optional[CachedRevisionInfo], _: float) -> bool:
+            return repo.repo_type.lower() == expected
+
+        return _type_filter
+
+    else:  # key == "refs"
+        if op != "=":
+            raise ValueError(f"Only '=' is supported for 'refs' filters. Got {op}.")
+
+        def _refs_filter(repo: CachedRepoInfo, revision: Optional[CachedRevisionInfo], _: float) -> bool:
+            refs = revision.refs if revision is not None else repo_refs_map.get(repo, frozenset())
+            return value_raw.lower() in [ref.lower() for ref in refs]
+
+        return _refs_filter
+
+
+def _build_cache_export_payload(
+    entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap
+) -> List[Dict[str, Any]]:
+    """Normalize cache entries into serializable records for JSON/CSV exports."""
+    payload: List[Dict[str, Any]] = []
+    for repo, revision in entries:
+        if include_revisions:
+            if revision is None:
+                continue
+            record: Dict[str, Any] = {
+                "repo_id": repo.repo_id,
+                "repo_type": repo.repo_type,
+                "revision": revision.commit_hash,
+                "snapshot_path": str(revision.snapshot_path),
+                "size_on_disk": revision.size_on_disk,
+                "last_accessed": repo.last_accessed,
+                "last_modified": revision.last_modified,
+                "refs": sorted(revision.refs),
+            }
+        else:
+            record = {
+                "repo_id": repo.repo_id,
+                "repo_type": repo.repo_type,
+                "size_on_disk": repo.size_on_disk,
+                "last_accessed": repo.last_accessed,
+                "last_modified": repo.last_modified,
+                "refs": sorted(repo_refs_map.get(repo, frozenset())),
+            }
+        payload.append(record)
+    return payload
+
+
+def print_cache_entries_table(
+    entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap
+) -> None:
+    """Render cache entries as a table and show a human-readable summary."""
+    if not entries:
+        message = "No cached revisions found." if include_revisions else "No cached repositories found."
+        print(message)
+        return
+    table_rows: List[List[str]]
+    if include_revisions:
+        headers = ["ID", "REVISION", "SIZE", "LAST_MODIFIED", "REFS"]
+        table_rows = [
+            [
+                repo.cache_id,
+                revision.commit_hash,
+                revision.size_on_disk_str.rjust(8),
+                revision.last_modified_str,
+                " ".join(sorted(revision.refs)),
+            ]
+            for repo, revision in entries
+            if revision is not None
+        ]
+    else:
+        headers = ["ID", "SIZE", "LAST_ACCESSED", "LAST_MODIFIED", "REFS"]
+        table_rows = [
+            [
+                repo.cache_id,
+                repo.size_on_disk_str.rjust(8),
+                repo.last_accessed_str or "",
+                repo.last_modified_str,
+                " ".join(sorted(repo_refs_map.get(repo, frozenset()))),
+            ]
+            for repo, _ in entries
+        ]
+
+    print(tabulate(table_rows, headers=headers))  # type: ignore[arg-type]
+
+    unique_repos = {repo for repo, _ in entries}
+    repo_count = len(unique_repos)
+    if include_revisions:
+        revision_count = sum(1 for _, revision in entries if revision is not None)
+        total_size = sum(revision.size_on_disk for _, revision in entries if revision is not None)
+    else:
+        revision_count = sum(len(repo.revisions) for repo in unique_repos)
+        total_size = sum(repo.size_on_disk for repo in unique_repos)
+
+    summary = f"\nFound {repo_count} repo(s) for a total of {revision_count} revision(s) and {_format_size(total_size)} on disk."
+    print(ANSI.bold(summary))
+
+
+def print_cache_entries_json(
+    entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap
+) -> None:
+    """Dump cache entries as JSON for scripting or automation."""
+    payload = _build_cache_export_payload(entries, include_revisions=include_revisions, repo_refs_map=repo_refs_map)
+    json.dump(payload, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def print_cache_entries_csv(entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap) -> None:
+    """Export cache entries as CSV rows with the shared payload format."""
+    records = _build_cache_export_payload(entries, include_revisions=include_revisions, repo_refs_map=repo_refs_map)
+    writer = csv.writer(sys.stdout)
+
+    if include_revisions:
+        headers = [
+            "repo_id",
+            "repo_type",
+            "revision",
+            "snapshot_path",
+            "size_on_disk",
+            "last_accessed",
+            "last_modified",
+            "refs",
+        ]
+    else:
+        headers = ["repo_id", "repo_type", "size_on_disk", "last_accessed", "last_modified", "refs"]
+
+    writer.writerow(headers)
+
+    if not records:
+        return
+
+    for record in records:
+        refs = record["refs"]
+        if include_revisions:
+            row = [
+                record.get("repo_id", ""),
+                record.get("repo_type", ""),
+                record.get("revision", ""),
+                record.get("snapshot_path", ""),
+                record.get("size_on_disk"),
+                record.get("last_accessed"),
+                record.get("last_modified"),
+                " ".join(refs) if refs else "",
+            ]
+        else:
+            row = [
+                record.get("repo_id", ""),
+                record.get("repo_type", ""),
+                record.get("size_on_disk"),
+                record.get("last_accessed"),
+                record.get("last_modified"),
+                " ".join(refs) if refs else "",
+            ]
+        writer.writerow(row)
+
+
+def _compare_numeric(left: Optional[float], op: str, right: float) -> bool:
+    """Evaluate numeric comparisons for filters."""
+    if left is None:
+        return False
+
+    comparisons = {
+        "=": left == right,
+        "!=": left != right,
+        ">": left > right,
+        "<": left < right,
+        ">=": left >= right,
+        "<=": left <= right,
+    }
+
+    if op not in comparisons:
+        raise ValueError(f"Unsupported numeric comparison operator: {op}")
+
+    return comparisons[op]
+
+
+def compile_cache_sort(sort_expr: str) -> tuple[Callable[[CacheEntry], tuple[Any, ...]], bool]:
+    """Convert a `hf cache ls` sort expression into a key function for sorting entries.
+
+    Returns:
+        A tuple of (key_function, reverse_flag) where reverse_flag indicates whether
+        to sort in descending order (True) or ascending order (False).
+    """
+    match = _SORT_PATTERN.match(sort_expr.strip().lower())
+    if not match:
+        raise ValueError(f"Invalid sort expression: '{sort_expr}'. Expected format: 'key' or 'key:asc' or 'key:desc'.")
+
+    key = match.group("key").lower()
+    explicit_order = match.group("order")
+
+    if key not in _SORT_KEYS:
+        raise ValueError(f"Unsupported sort key '{key}' in '{sort_expr}'. Must be one of {list(_SORT_KEYS)}.")
+
+    # Use explicit order if provided, otherwise use default for the key
+    order = explicit_order if explicit_order else _SORT_DEFAULT_ORDER[key]
+    reverse = order == "desc"
+
+    def _sort_key(entry: CacheEntry) -> tuple[Any, ...]:
+        repo, revision = entry
+
+        if key == "name":
+            # Sort by cache_id (repo type/id)
+            value: Any = repo.cache_id.lower()
+            return (value,)
+
+        if key == "size":
+            # Use revision size if available, otherwise repo size
+            value = revision.size_on_disk if revision is not None else repo.size_on_disk
+            return (value,)
+
+        if key == "accessed":
+            # For revisions, accessed is not available per-revision, use repo's last_accessed
+            # For repos, use repo's last_accessed
+            value = repo.last_accessed if repo.last_accessed is not None else 0.0
+            return (value,)
+
+        if key == "modified":
+            # Use revision's last_modified if available, otherwise repo's last_modified
+            if revision is not None:
+                value = revision.last_modified if revision.last_modified is not None else 0.0
+            else:
+                value = repo.last_modified if repo.last_modified is not None else 0.0
+            return (value,)
+
+        # Should never reach here due to validation above
+        raise ValueError(f"Unsupported sort key: {key}")
+
+    return _sort_key, reverse
+
+
+def _resolve_deletion_targets(hf_cache_info: HFCacheInfo, targets: list[str]) -> _DeletionResolution:
+    """Resolve the deletion targets into a deletion resolution."""
+    repo_lookup, revision_lookup = build_cache_index(hf_cache_info)
+
+    selected: dict[CachedRepoInfo, set[CachedRevisionInfo]] = defaultdict(set)
+    revisions: set[str] = set()
+    missing: list[str] = []
+
+    for raw_target in targets:
+        target = raw_target.strip()
+        if not target:
+            continue
+        lowered = target.lower()
+
+        if re.fullmatch(r"[0-9a-fA-F]{40}", lowered):
+            match = revision_lookup.get(lowered)
+            if match is None:
+                missing.append(raw_target)
+                continue
+            repo, revision = match
+            selected[repo].add(revision)
+            revisions.add(revision.commit_hash)
+            continue
+
+        matched_repo = repo_lookup.get(lowered)
+        if matched_repo is None:
+            missing.append(raw_target)
+            continue
+
+        for revision in matched_repo.revisions:
+            selected[matched_repo].add(revision)
+            revisions.add(revision.commit_hash)
+
+    frozen_selected = {repo: frozenset(revs) for repo, revs in selected.items()}
+    return _DeletionResolution(
+        revisions=frozenset(revisions),
+        selected=frozen_selected,
+        missing=tuple(missing),
+    )
+
+
+#### Cache CLI commands
+
+
+@cache_cli.command()
+def ls(
+    cache_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Cache directory to scan (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    revisions: Annotated[
+        bool,
+        typer.Option(
+            help="Include revisions in the output instead of aggregated repositories.",
+        ),
+    ] = False,
+    filter: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "-f",
+            "--filter",
+            help="Filter entries (e.g. 'size>1GB', 'type=model', 'accessed>7d'). Can be used multiple times.",
+        ),
+    ] = None,
+    format: Annotated[
+        OutputFormat,
+        typer.Option(
+            help="Output format.",
+        ),
+    ] = OutputFormat.table,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            "-q",
+            "--quiet",
+            help="Print only IDs (repo IDs or revision hashes).",
+        ),
+    ] = False,
+    sort: Annotated[
+        Optional[SortOptions],
+        typer.Option(
+            help="Sort entries by key. Supported keys: 'accessed', 'modified', 'name', 'size'. "
+            "Append ':asc' or ':desc' to explicitly set the order (e.g., 'modified:asc'). "
+            "Defaults: 'accessed', 'modified', 'size' default to 'desc' (newest/biggest first); "
+            "'name' defaults to 'asc' (alphabetical).",
+        ),
+    ] = None,
+    limit: Annotated[
+        Optional[int],
+        typer.Option(
+            help="Limit the number of results returned. Returns only the top N entries after sorting.",
+        ),
+    ] = None,
+) -> None:
+    """List cached repositories or revisions."""
+    try:
+        hf_cache_info = scan_cache_dir(cache_dir)
+    except CacheNotFound as exc:
+        print(f"Cache directory not found: {str(exc.cache_dir)}")
+        raise typer.Exit(code=1) from exc
+
+    filters = filter or []
+
+    entries, repo_refs_map = collect_cache_entries(hf_cache_info, include_revisions=revisions)
+    try:
+        filter_fns = [compile_cache_filter(expr, repo_refs_map) for expr in filters]
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    now = time.time()
+    for fn in filter_fns:
+        entries = [entry for entry in entries if fn(entry[0], entry[1], now)]
+
+    # Apply sorting if requested
+    if sort:
+        try:
+            sort_key_fn, reverse = compile_cache_sort(sort.value)
+            entries.sort(key=sort_key_fn, reverse=reverse)
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+
+    # Apply limit if requested
+    if limit is not None:
+        if limit < 0:
+            raise typer.BadParameter(f"Limit must be a positive integer, got {limit}.")
+        entries = entries[:limit]
+
+    if quiet:
+        for repo, revision in entries:
+            print(revision.commit_hash if revision is not None else repo.cache_id)
+        return
+
+    formatters = {
+        OutputFormat.table: print_cache_entries_table,
+        OutputFormat.json: print_cache_entries_json,
+        OutputFormat.csv: print_cache_entries_csv,
+    }
+    return formatters[format](entries, include_revisions=revisions, repo_refs_map=repo_refs_map)
+
+
+@cache_cli.command()
+def rm(
+    targets: Annotated[
+        list[str],
+        typer.Argument(
+            help="One or more repo IDs (e.g. model/bert-base-uncased) or revision hashes to delete.",
+        ),
+    ],
+    cache_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Cache directory to scan (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="Preview deletions without removing anything.",
+        ),
+    ] = False,
+) -> None:
+    """Remove cached repositories or revisions."""
+    try:
+        hf_cache_info = scan_cache_dir(cache_dir)
+    except CacheNotFound as exc:
+        print(f"Cache directory not found: {str(exc.cache_dir)}")
+        raise typer.Exit(code=1)
+
+    resolution = _resolve_deletion_targets(hf_cache_info, targets)
+
+    if resolution.missing:
+        print("Could not find the following targets in the cache:")
+        for entry in resolution.missing:
+            print(f"  - {entry}")
+
+    if len(resolution.revisions) == 0:
+        print("Nothing to delete.")
+        raise typer.Exit(code=0)
+
+    strategy = hf_cache_info.delete_revisions(*sorted(resolution.revisions))
+    counts = summarize_deletions(resolution.selected)
+
+    summary_parts: list[str] = []
+    if counts.repo_count:
+        summary_parts.append(f"{counts.repo_count} repo(s)")
+    if counts.partial_revision_count:
+        summary_parts.append(f"{counts.partial_revision_count} revision(s)")
+    if not summary_parts:
+        summary_parts.append(f"{counts.total_revision_count} revision(s)")
+
+    summary_text = " and ".join(summary_parts)
+    print(f"About to delete {summary_text} totalling {strategy.expected_freed_size_str}.")
+    print_cache_selected_revisions(resolution.selected)
+
+    if dry_run:
+        print("Dry run: no files were deleted.")
+        return
+
+    if not yes and not typer.confirm("Proceed with deletion?", default=False):
+        print("Deletion cancelled.")
+        return
+
+    strategy.execute()
+    counts = summarize_deletions(resolution.selected)
+    print(
+        f"Deleted {counts.repo_count} repo(s) and {counts.total_revision_count} revision(s); freed {strategy.expected_freed_size_str}."
+    )
+
+
+@cache_cli.command()
+def prune(
+    cache_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Cache directory to scan (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="Preview deletions without removing anything.",
+        ),
+    ] = False,
+) -> None:
+    """Remove detached revisions from the cache."""
+    try:
+        hf_cache_info = scan_cache_dir(cache_dir)
+    except CacheNotFound as exc:
+        print(f"Cache directory not found: {str(exc.cache_dir)}")
+        raise typer.Exit(code=1)
+
+    selected: dict[CachedRepoInfo, frozenset[CachedRevisionInfo]] = {}
+    revisions: set[str] = set()
+    for repo in hf_cache_info.repos:
+        detached = frozenset(revision for revision in repo.revisions if len(revision.refs) == 0)
+        if not detached:
+            continue
+        selected[repo] = detached
+        revisions.update(revision.commit_hash for revision in detached)
+
+    if len(revisions) == 0:
+        print("No unreferenced revisions found. Nothing to prune.")
+        return
+
+    resolution = _DeletionResolution(
+        revisions=frozenset(revisions),
+        selected=selected,
+        missing=(),
+    )
+    strategy = hf_cache_info.delete_revisions(*sorted(resolution.revisions))
+    counts = summarize_deletions(selected)
+
+    print(
+        f"About to delete {counts.total_revision_count} unreferenced revision(s) ({strategy.expected_freed_size_str} total)."
+    )
+    print_cache_selected_revisions(selected)
+
+    if dry_run:
+        print("Dry run: no files were deleted.")
+        return
+
+    if not yes and not typer.confirm("Proceed?"):
+        print("Pruning cancelled.")
+        return
+
+    strategy.execute()
+    print(f"Deleted {counts.total_revision_count} unreferenced revision(s); freed {strategy.expected_freed_size_str}.")
+
+
+@cache_cli.command()
+def verify(
+    repo_id: RepoIdArg,
+    repo_type: RepoTypeOpt = RepoTypeOpt.model,
+    revision: RevisionOpt = None,
+    cache_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Cache directory to use when verifying files from cache (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    local_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="If set, verify files under this directory instead of the cache.",
+        ),
+    ] = None,
+    fail_on_missing_files: Annotated[
+        bool,
+        typer.Option(
+            "--fail-on-missing-files",
+            help="Fail if some files exist on the remote but are missing locally.",
+        ),
+    ] = False,
+    fail_on_extra_files: Annotated[
+        bool,
+        typer.Option(
+            "--fail-on-extra-files",
+            help="Fail if some files exist locally but are not present on the remote revision.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Verify checksums for a single repo revision from cache or a local directory.
+
+    Examples:
+      - Verify main revision in cache: `hf cache verify gpt2`
+      - Verify specific revision: `hf cache verify gpt2 --revision refs/pr/1`
+      - Verify dataset: `hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset`
+      - Verify local dir: `hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo`
+    """
+
+    if local_dir is not None and cache_dir is not None:
+        print("Cannot pass both --local-dir and --cache-dir. Use one or the other.")
+        raise typer.Exit(code=2)
+
+    api = get_hf_api(token=token)
+
+    result = api.verify_repo_checksums(
+        repo_id=repo_id,
+        repo_type=repo_type.value if hasattr(repo_type, "value") else str(repo_type),
+        revision=revision,
+        local_dir=local_dir,
+        cache_dir=cache_dir,
+        token=token,
+    )
+
+    exit_code = 0
+
+    has_mismatches = bool(result.mismatches)
+    if has_mismatches:
+        print("❌ Checksum verification failed for the following file(s):")
+        for m in result.mismatches:
+            print(f"  - {m['path']}: expected {m['expected']} ({m['algorithm']}), got {m['actual']}")
+        exit_code = 1
+
+    if result.missing_paths:
+        if fail_on_missing_files:
+            print("Missing files (present remotely, absent locally):")
+            for p in result.missing_paths:
+                print(f"  - {p}")
+            exit_code = 1
+        else:
+            warning = (
+                f"{len(result.missing_paths)} remote file(s) are missing locally. "
+                "Use --fail-on-missing-files for details."
+            )
+            print(f"⚠️  {warning}")
+
+    if result.extra_paths:
+        if fail_on_extra_files:
+            print("Extra files (present locally, absent remotely):")
+            for p in result.extra_paths:
+                print(f"  - {p}")
+            exit_code = 1
+        else:
+            warning = (
+                f"{len(result.extra_paths)} local file(s) do not exist on the remote repo. "
+                "Use --fail-on-extra-files for details."
+            )
+            print(f"⚠️  {warning}")
+
+    verified_location = result.verified_path
+
+    if exit_code != 0:
+        print(f"❌ Verification failed for '{repo_id}' ({repo_type.value}) in {verified_location}.")
+        print(f"  Revision: {result.revision}")
+        raise typer.Exit(code=exit_code)
+
+    print(f"✅ Verified {result.checked_count} file(s) for '{repo_id}' ({repo_type.value}) in {verified_location}")
+    print("  All checksums match.")

venv/lib/python3.12/site-packages/huggingface_hub/cli/datasets.py

@@ -0,0 +1,110 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with datasets on the Hugging Face Hub.
+
+Usage:
+    # list datasets on the Hub
+    hf datasets ls
+
+    # list datasets with a search query
+    hf datasets ls --search "code"
+
+    # get info about a dataset
+    hf datasets info HuggingFaceFW/fineweb
+"""
+
+import enum
+import json
+from typing import Annotated, Optional, get_args
+
+import typer
+
+from huggingface_hub.errors import RepositoryNotFoundError, RevisionNotFoundError
+from huggingface_hub.hf_api import DatasetSort_T, ExpandDatasetProperty_T
+from huggingface_hub.utils import ANSI
+
+from ._cli_utils import (
+    AuthorOpt,
+    FilterOpt,
+    LimitOpt,
+    RevisionOpt,
+    SearchOpt,
+    TokenOpt,
+    get_hf_api,
+    make_expand_properties_parser,
+    repo_info_to_dict,
+    typer_factory,
+)
+
+
+_EXPAND_PROPERTIES = sorted(get_args(ExpandDatasetProperty_T))
+_SORT_OPTIONS = get_args(DatasetSort_T)
+DatasetSortEnum = enum.Enum("DatasetSortEnum", {s: s for s in _SORT_OPTIONS}, type=str)  # type: ignore[misc]
+
+
+ExpandOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help=f"Comma-separated properties to expand. Example: '--expand=downloads,likes,tags'. Valid: {', '.join(_EXPAND_PROPERTIES)}.",
+        callback=make_expand_properties_parser(_EXPAND_PROPERTIES),
+    ),
+]
+
+
+datasets_cli = typer_factory(help="Interact with datasets on the Hub.")
+
+
+@datasets_cli.command("ls")
+def datasets_ls(
+    search: SearchOpt = None,
+    author: AuthorOpt = None,
+    filter: FilterOpt = None,
+    sort: Annotated[
+        Optional[DatasetSortEnum],
+        typer.Option(help="Sort results."),
+    ] = None,
+    limit: LimitOpt = 10,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """List datasets on the Hub."""
+    api = get_hf_api(token=token)
+    sort_key = sort.value if sort else None
+    results = [
+        repo_info_to_dict(dataset_info)
+        for dataset_info in api.list_datasets(
+            filter=filter, author=author, search=search, sort=sort_key, limit=limit, expand=expand
+        )
+    ]
+    print(json.dumps(results, indent=2))
+
+
+@datasets_cli.command("info")
+def datasets_info(
+    dataset_id: Annotated[str, typer.Argument(help="The dataset ID (e.g. `username/repo-name`).")],
+    revision: RevisionOpt = None,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a dataset on the Hub."""
+    api = get_hf_api(token=token)
+    try:
+        info = api.dataset_info(repo_id=dataset_id, revision=revision, expand=expand)  # type: ignore[arg-type]
+    except RepositoryNotFoundError:
+        print(f"Dataset {ANSI.bold(dataset_id)} not found.")
+        raise typer.Exit(code=1)
+    except RevisionNotFoundError:
+        print(f"Revision {ANSI.bold(str(revision))} not found on {ANSI.bold(dataset_id)}.")
+        raise typer.Exit(code=1)
+    print(json.dumps(repo_info_to_dict(info), indent=2))

venv/lib/python3.12/site-packages/huggingface_hub/cli/download.py

@@ -0,0 +1,189 @@
+# coding=utf-8
+# Copyright 202-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains command to download files from the Hub with the CLI.
+
+Usage:
+    hf download --help
+
+    # Download file
+    hf download gpt2 config.json
+
+    # Download entire repo
+    hf download fffiloni/zeroscope --repo-type=space --revision=refs/pr/78
+
+    # Download repo with filters
+    hf download gpt2 --include="*.safetensors"
+
+    # Download with token
+    hf download Wauplin/private-model --token=hf_***
+
+    # Download quietly (no progress bar, no warnings, only the returned path)
+    hf download gpt2 config.json --quiet
+
+    # Download to local dir
+    hf download gpt2 --local-dir=./models/gpt2
+"""
+
+import warnings
+from typing import Annotated, Optional, Union
+
+import typer
+
+from huggingface_hub import logging
+from huggingface_hub._snapshot_download import snapshot_download
+from huggingface_hub.file_download import DryRunFileInfo, hf_hub_download
+from huggingface_hub.utils import _format_size, disable_progress_bars, enable_progress_bars, tabulate
+
+from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt
+
+
+logger = logging.get_logger(__name__)
+
+
+def download(
+    repo_id: RepoIdArg,
+    filenames: Annotated[
+        Optional[list[str]],
+        typer.Argument(
+            help="Files to download (e.g. `config.json`, `data/metadata.jsonl`).",
+        ),
+    ] = None,
+    repo_type: RepoTypeOpt = RepoTypeOpt.model,
+    revision: RevisionOpt = None,
+    include: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to include from files to download. eg: *.json",
+        ),
+    ] = None,
+    exclude: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to exclude from files to download.",
+        ),
+    ] = None,
+    cache_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Directory where to save files.",
+        ),
+    ] = None,
+    local_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="If set, the downloaded file will be placed under this directory. Check out https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-a-local-folder for more details.",
+        ),
+    ] = None,
+    force_download: Annotated[
+        bool,
+        typer.Option(
+            help="If True, the files will be downloaded even if they are already cached.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="If True, perform a dry run without actually downloading the file.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            help="If True, progress bars are disabled and only the path to the download files is printed.",
+        ),
+    ] = False,
+    max_workers: Annotated[
+        int,
+        typer.Option(
+            help="Maximum number of workers to use for downloading files. Default is 8.",
+        ),
+    ] = 8,
+) -> None:
+    """Download files from the Hub."""
+
+    def run_download() -> Union[str, DryRunFileInfo, list[DryRunFileInfo]]:
+        filenames_list = filenames if filenames is not None else []
+        # Warn user if patterns are ignored
+        if len(filenames_list) > 0:
+            if include is not None and len(include) > 0:
+                warnings.warn("Ignoring `--include` since filenames have being explicitly set.")
+            if exclude is not None and len(exclude) > 0:
+                warnings.warn("Ignoring `--exclude` since filenames have being explicitly set.")
+
+        # Single file to download: use `hf_hub_download`
+        if len(filenames_list) == 1:
+            return hf_hub_download(
+                repo_id=repo_id,
+                repo_type=repo_type.value,
+                revision=revision,
+                filename=filenames_list[0],
+                cache_dir=cache_dir,
+                force_download=force_download,
+                token=token,
+                local_dir=local_dir,
+                library_name="huggingface-cli",
+                dry_run=dry_run,
+            )
+
+        # Otherwise: use `snapshot_download` to ensure all files comes from same revision
+        if len(filenames_list) == 0:
+            allow_patterns = include
+            ignore_patterns = exclude
+        else:
+            allow_patterns = filenames_list
+            ignore_patterns = None
+
+        return snapshot_download(
+            repo_id=repo_id,
+            repo_type=repo_type.value,
+            revision=revision,
+            allow_patterns=allow_patterns,
+            ignore_patterns=ignore_patterns,
+            force_download=force_download,
+            cache_dir=cache_dir,
+            token=token,
+            local_dir=local_dir,
+            library_name="huggingface-cli",
+            max_workers=max_workers,
+            dry_run=dry_run,
+        )
+
+    def _print_result(result: Union[str, DryRunFileInfo, list[DryRunFileInfo]]) -> None:
+        if isinstance(result, str):
+            print(result)
+            return
+
+        # Print dry run info
+        if isinstance(result, DryRunFileInfo):
+            result = [result]
+        print(
+            f"[dry-run] Will download {len([r for r in result if r.will_download])} files (out of {len(result)}) totalling {_format_size(sum(r.file_size for r in result if r.will_download))}."
+        )
+        columns = ["File", "Bytes to download"]
+        items: list[list[Union[str, int]]] = []
+        for info in sorted(result, key=lambda x: x.filename):
+            items.append([info.filename, _format_size(info.file_size) if info.will_download else "-"])
+        print(tabulate(items, headers=columns))
+
+    if quiet:
+        disable_progress_bars()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            _print_result(run_download())
+        enable_progress_bars()
+    else:
+        _print_result(run_download())
+        logging.set_verbosity_warning()

venv/lib/python3.12/site-packages/huggingface_hub/cli/hf.py

@@ -0,0 +1,68 @@
+# Copyright 2020 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from huggingface_hub import constants
+from huggingface_hub.cli._cli_utils import check_cli_update, typer_factory
+from huggingface_hub.cli.auth import auth_cli
+from huggingface_hub.cli.cache import cache_cli
+from huggingface_hub.cli.datasets import datasets_cli
+from huggingface_hub.cli.download import download
+from huggingface_hub.cli.inference_endpoints import ie_cli
+from huggingface_hub.cli.jobs import jobs_cli
+from huggingface_hub.cli.lfs import lfs_enable_largefiles, lfs_multipart_upload
+from huggingface_hub.cli.models import models_cli
+from huggingface_hub.cli.repo import repo_cli
+from huggingface_hub.cli.repo_files import repo_files_cli
+from huggingface_hub.cli.spaces import spaces_cli
+from huggingface_hub.cli.system import env, version
+from huggingface_hub.cli.upload import upload
+from huggingface_hub.cli.upload_large_folder import upload_large_folder
+from huggingface_hub.utils import logging
+
+
+app = typer_factory(help="Hugging Face Hub CLI")
+
+
+# top level single commands (defined in their respective files)
+app.command(help="Download files from the Hub.")(download)
+app.command(help="Upload a file or a folder to the Hub.")(upload)
+app.command(help="Upload a large folder to the Hub. Recommended for resumable uploads.")(upload_large_folder)
+app.command(name="env", help="Print information about the environment.")(env)
+app.command(help="Print information about the hf version.")(version)
+app.command(help="Configure your repository to enable upload of files > 5GB.", hidden=True)(lfs_enable_largefiles)
+app.command(help="Upload large files to the Hub.", hidden=True)(lfs_multipart_upload)
+
+
+# command groups
+app.add_typer(auth_cli, name="auth")
+app.add_typer(cache_cli, name="cache")
+app.add_typer(datasets_cli, name="datasets")
+app.add_typer(jobs_cli, name="jobs")
+app.add_typer(models_cli, name="models")
+app.add_typer(repo_cli, name="repo")
+app.add_typer(repo_files_cli, name="repo-files")
+app.add_typer(spaces_cli, name="spaces")
+app.add_typer(ie_cli, name="endpoints")
+
+
+def main():
+    if not constants.HF_DEBUG:
+        logging.set_verbosity_info()
+    check_cli_update("huggingface_hub")
+    app()
+
+
+if __name__ == "__main__":
+    main()

venv/lib/python3.12/site-packages/huggingface_hub/cli/inference_endpoints.py

@@ -0,0 +1,426 @@
+"""CLI commands for Hugging Face Inference Endpoints."""
+
+import json
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub._inference_endpoints import InferenceEndpoint, InferenceEndpointScalingMetric
+from huggingface_hub.errors import HfHubHTTPError
+
+from ._cli_utils import TokenOpt, get_hf_api, typer_factory
+
+
+ie_cli = typer_factory(help="Manage Hugging Face Inference Endpoints.")
+
+catalog_app = typer_factory(help="Interact with the Inference Endpoints catalog.")
+
+NameArg = Annotated[
+    str,
+    typer.Argument(help="Endpoint name."),
+]
+NameOpt = Annotated[
+    Optional[str],
+    typer.Option(help="Endpoint name."),
+]
+
+NamespaceOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="The namespace associated with the Inference Endpoint. Defaults to the current user's namespace.",
+    ),
+]
+
+
+def _print_endpoint(endpoint: InferenceEndpoint) -> None:
+    typer.echo(json.dumps(endpoint.raw, indent=2, sort_keys=True))
+
+
+@ie_cli.command()
+def ls(
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Lists all Inference Endpoints for the given namespace."""
+    api = get_hf_api(token=token)
+    try:
+        endpoints = api.list_inference_endpoints(namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Listing failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    typer.echo(
+        json.dumps(
+            {"items": [endpoint.raw for endpoint in endpoints]},
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+@ie_cli.command(name="deploy")
+def deploy(
+    name: NameArg,
+    repo: Annotated[
+        str,
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ],
+    framework: Annotated[
+        str,
+        typer.Option(
+            help="The machine learning framework used for the model (e.g. 'vllm').",
+        ),
+    ],
+    accelerator: Annotated[
+        str,
+        typer.Option(
+            help="The hardware accelerator to be used for inference (e.g. 'cpu').",
+        ),
+    ],
+    instance_size: Annotated[
+        str,
+        typer.Option(
+            help="The size or type of the instance to be used for hosting the model (e.g. 'x4').",
+        ),
+    ],
+    instance_type: Annotated[
+        str,
+        typer.Option(
+            help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').",
+        ),
+    ],
+    region: Annotated[
+        str,
+        typer.Option(
+            help="The cloud region in which the Inference Endpoint will be created (e.g. 'us-east-1').",
+        ),
+    ],
+    vendor: Annotated[
+        str,
+        typer.Option(
+            help="The cloud provider or vendor where the Inference Endpoint will be hosted (e.g. 'aws').",
+        ),
+    ],
+    *,
+    namespace: NamespaceOpt = None,
+    task: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The task on which to deploy the model (e.g. 'text-classification').",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+    min_replica: Annotated[
+        int,
+        typer.Option(
+            help="The minimum number of replicas (instances) to keep running for the Inference Endpoint.",
+        ),
+    ] = 1,
+    max_replica: Annotated[
+        int,
+        typer.Option(
+            help="The maximum number of replicas (instances) to scale to for the Inference Endpoint.",
+        ),
+    ] = 1,
+    scale_to_zero_timeout: Annotated[
+        Optional[int],
+        typer.Option(
+            help="The duration in minutes before an inactive endpoint is scaled to zero.",
+        ),
+    ] = None,
+    scaling_metric: Annotated[
+        Optional[InferenceEndpointScalingMetric],
+        typer.Option(
+            help="The metric reference for scaling.",
+        ),
+    ] = None,
+    scaling_threshold: Annotated[
+        Optional[float],
+        typer.Option(
+            help="The scaling metric threshold used to trigger a scale up. Ignored when scaling metric is not provided.",
+        ),
+    ] = None,
+) -> None:
+    """Deploy an Inference Endpoint from a Hub repository."""
+    api = get_hf_api(token=token)
+    endpoint = api.create_inference_endpoint(
+        name=name,
+        repository=repo,
+        framework=framework,
+        accelerator=accelerator,
+        instance_size=instance_size,
+        instance_type=instance_type,
+        region=region,
+        vendor=vendor,
+        namespace=namespace,
+        task=task,
+        token=token,
+        min_replica=min_replica,
+        max_replica=max_replica,
+        scaling_metric=scaling_metric,
+        scaling_threshold=scaling_threshold,
+        scale_to_zero_timeout=scale_to_zero_timeout,
+    )
+
+    _print_endpoint(endpoint)
+
+
+@catalog_app.command(name="deploy")
+def deploy_from_catalog(
+    repo: Annotated[
+        str,
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ],
+    name: NameOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Deploy an Inference Endpoint from the Model Catalog."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.create_inference_endpoint_from_catalog(
+            repo_id=repo,
+            name=name,
+            namespace=namespace,
+            token=token,
+        )
+    except HfHubHTTPError as error:
+        typer.echo(f"Deployment failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)
+
+
+def list_catalog(
+    token: TokenOpt = None,
+) -> None:
+    """List available Catalog models."""
+    api = get_hf_api(token=token)
+    try:
+        models = api.list_inference_catalog(token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Catalog fetch failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    typer.echo(json.dumps({"models": models}, indent=2, sort_keys=True))
+
+
+catalog_app.command(name="ls")(list_catalog)
+ie_cli.command(name="list-catalog", help="List available Catalog models.", hidden=True)(list_catalog)
+
+
+ie_cli.add_typer(catalog_app, name="catalog")
+
+
+@ie_cli.command()
+def describe(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get information about an existing endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.get_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Fetch failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def update(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    repo: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ] = None,
+    accelerator: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The hardware accelerator to be used for inference (e.g. 'cpu').",
+        ),
+    ] = None,
+    instance_size: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The size or type of the instance to be used for hosting the model (e.g. 'x4').",
+        ),
+    ] = None,
+    instance_type: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').",
+        ),
+    ] = None,
+    framework: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The machine learning framework used for the model (e.g. 'custom').",
+        ),
+    ] = None,
+    revision: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The specific model revision to deploy on the Inference Endpoint (e.g. '6c0e6080953db56375760c0471a8c5f2929baf11').",
+        ),
+    ] = None,
+    task: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The task on which to deploy the model (e.g. 'text-classification').",
+        ),
+    ] = None,
+    min_replica: Annotated[
+        Optional[int],
+        typer.Option(
+            help="The minimum number of replicas (instances) to keep running for the Inference Endpoint.",
+        ),
+    ] = None,
+    max_replica: Annotated[
+        Optional[int],
+        typer.Option(
+            help="The maximum number of replicas (instances) to scale to for the Inference Endpoint.",
+        ),
+    ] = None,
+    scale_to_zero_timeout: Annotated[
+        Optional[int],
+        typer.Option(
+            help="The duration in minutes before an inactive endpoint is scaled to zero.",
+        ),
+    ] = None,
+    scaling_metric: Annotated[
+        Optional[InferenceEndpointScalingMetric],
+        typer.Option(
+            help="The metric reference for scaling.",
+        ),
+    ] = None,
+    scaling_threshold: Annotated[
+        Optional[float],
+        typer.Option(
+            help="The scaling metric threshold used to trigger a scale up. Ignored when scaling metric is not provided.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Update an existing endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.update_inference_endpoint(
+            name=name,
+            namespace=namespace,
+            repository=repo,
+            framework=framework,
+            revision=revision,
+            task=task,
+            accelerator=accelerator,
+            instance_size=instance_size,
+            instance_type=instance_type,
+            min_replica=min_replica,
+            max_replica=max_replica,
+            scale_to_zero_timeout=scale_to_zero_timeout,
+            scaling_metric=scaling_metric,
+            scaling_threshold=scaling_threshold,
+            token=token,
+        )
+    except HfHubHTTPError as error:
+        typer.echo(f"Update failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def delete(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Skip confirmation prompts."),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Delete an Inference Endpoint permanently."""
+    if not yes:
+        confirmation = typer.prompt(f"Delete endpoint '{name}'? Type the name to confirm.")
+        if confirmation != name:
+            typer.echo("Aborted.")
+            raise typer.Exit(code=2)
+
+    api = get_hf_api(token=token)
+    try:
+        api.delete_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Delete failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    typer.echo(f"Deleted '{name}'.")
+
+
+@ie_cli.command()
+def pause(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Pause an Inference Endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.pause_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Pause failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def resume(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    fail_if_already_running: Annotated[
+        bool,
+        typer.Option(
+            "--fail-if-already-running",
+            help="If `True`, the method will raise an error if the Inference Endpoint is already running.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Resume an Inference Endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.resume_inference_endpoint(
+            name=name,
+            namespace=namespace,
+            token=token,
+            running_ok=not fail_if_already_running,
+        )
+    except HfHubHTTPError as error:
+        typer.echo(f"Resume failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def scale_to_zero(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Scale an Inference Endpoint to zero."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.scale_to_zero_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Scale To Zero failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)

venv/lib/python3.12/site-packages/huggingface_hub/cli/jobs.py

@@ -0,0 +1,968 @@
+# Copyright 2025 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with jobs on the Hugging Face Hub.
+
+Usage:
+    # run a job
+    hf jobs run <image> <command>
+
+    # List running or completed jobs
+    hf jobs ps [-a] [-f key=value] [--format TEMPLATE]
+
+    # Stream logs from a job
+    hf jobs logs <job-id>
+
+    # Stream resources usage stats and metrics from a job
+    hf jobs stats <job-id>
+
+    # Inspect detailed information about a job
+    hf jobs inspect <job-id>
+
+    # Cancel a running job
+    hf jobs cancel <job-id>
+
+    # List available hardware options
+    hf jobs hardware
+
+    # Run a UV script
+    hf jobs uv run <script>
+
+    # Schedule a job
+    hf jobs scheduled run <schedule> <image> <command>
+
+    # List scheduled jobs
+    hf jobs scheduled ps [-a] [-f key=value] [--format TEMPLATE]
+
+    # Inspect a scheduled job
+    hf jobs scheduled inspect <scheduled_job_id>
+
+    # Suspend a scheduled job
+    hf jobs scheduled suspend <scheduled_job_id>
+
+    # Resume a scheduled job
+    hf jobs scheduled resume <scheduled_job_id>
+
+    # Delete a scheduled job
+    hf jobs scheduled delete <scheduled_job_id>
+
+"""
+
+import json
+import multiprocessing
+import multiprocessing.pool
+import os
+import re
+import time
+from dataclasses import asdict
+from pathlib import Path
+from queue import Empty, Queue
+from typing import Annotated, Any, Callable, Dict, Iterable, Optional, TypeVar, Union
+
+import typer
+
+from huggingface_hub import SpaceHardware, get_token
+from huggingface_hub.errors import HfHubHTTPError
+from huggingface_hub.utils import logging
+from huggingface_hub.utils._cache_manager import _format_size
+from huggingface_hub.utils._dotenv import load_dotenv
+
+from ._cli_utils import TokenOpt, get_hf_api, typer_factory
+
+
+logger = logging.get_logger(__name__)
+
+SUGGESTED_FLAVORS = [item.value for item in SpaceHardware if item.value != "zero-a10g"]
+STATS_UPDATE_MIN_INTERVAL = 0.1  # we set a limit here since there is one update per second per job
+
+# Common job-related options
+ImageArg = Annotated[
+    str,
+    typer.Argument(
+        help="The Docker image to use.",
+    ),
+]
+
+ImageOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="Use a custom Docker image with `uv` installed.",
+    ),
+]
+
+FlavorOpt = Annotated[
+    Optional[SpaceHardware],
+    typer.Option(
+        help="Flavor for the hardware, as in HF Spaces. Run 'hf jobs hardware' to list available flavors. Defaults to `cpu-basic`.",
+    ),
+]
+
+EnvOpt = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "-e",
+        "--env",
+        help="Set environment variables. E.g. --env ENV=value",
+    ),
+]
+
+SecretsOpt = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "-s",
+        "--secrets",
+        help="Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token.",
+    ),
+]
+
+EnvFileOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        "--env-file",
+        help="Read in a file of environment variables.",
+    ),
+]
+
+SecretsFileOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="Read in a file of secret environment variables.",
+    ),
+]
+
+TimeoutOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days).",
+    ),
+]
+
+DetachOpt = Annotated[
+    bool,
+    typer.Option(
+        "-d",
+        "--detach",
+        help="Run the Job in the background and print the Job ID.",
+    ),
+]
+
+NamespaceOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="The namespace where the job will be running. Defaults to the current user's namespace.",
+    ),
+]
+
+WithOpt = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "--with",
+        help="Run with the given packages installed",
+    ),
+]
+
+PythonOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        "-p",
+        "--python",
+        help="The Python interpreter to use for the run environment",
+    ),
+]
+
+SuspendOpt = Annotated[
+    Optional[bool],
+    typer.Option(
+        help="Suspend (pause) the scheduled Job",
+    ),
+]
+
+ConcurrencyOpt = Annotated[
+    Optional[bool],
+    typer.Option(
+        help="Allow multiple instances of this Job to run concurrently",
+    ),
+]
+
+ScheduleArg = Annotated[
+    str,
+    typer.Argument(
+        help="One of annually, yearly, monthly, weekly, daily, hourly, or a CRON schedule expression.",
+    ),
+]
+
+ScriptArg = Annotated[
+    str,
+    typer.Argument(
+        help="UV script to run (local file or URL)",
+    ),
+]
+
+ScriptArgsArg = Annotated[
+    Optional[list[str]],
+    typer.Argument(
+        help="Arguments for the script",
+    ),
+]
+
+CommandArg = Annotated[
+    list[str],
+    typer.Argument(
+        help="The command to run.",
+    ),
+]
+
+JobIdArg = Annotated[
+    str,
+    typer.Argument(
+        help="Job ID",
+    ),
+]
+
+JobIdsArg = Annotated[
+    Optional[list[str]],
+    typer.Argument(
+        help="Job IDs",
+    ),
+]
+
+ScheduledJobIdArg = Annotated[
+    str,
+    typer.Argument(
+        help="Scheduled Job ID",
+    ),
+]
+
+
+jobs_cli = typer_factory(help="Run and manage Jobs on the Hub.")
+
+
+@jobs_cli.command("run", help="Run a Job", context_settings={"ignore_unknown_options": True})
+def jobs_run(
+    image: ImageArg,
+    command: CommandArg,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    flavor: FlavorOpt = None,
+    timeout: TimeoutOpt = None,
+    detach: DetachOpt = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    env_map: dict[str, Optional[str]] = {}
+    if env_file:
+        env_map.update(load_dotenv(Path(env_file).read_text(), environ=os.environ.copy()))
+    for env_value in env or []:
+        env_map.update(load_dotenv(env_value, environ=os.environ.copy()))
+
+    secrets_map: dict[str, Optional[str]] = {}
+    extended_environ = _get_extended_environ()
+    if secrets_file:
+        secrets_map.update(load_dotenv(Path(secrets_file).read_text(), environ=extended_environ))
+    for secret in secrets or []:
+        secrets_map.update(load_dotenv(secret, environ=extended_environ))
+
+    api = get_hf_api(token=token)
+    job = api.run_job(
+        image=image,
+        command=command,
+        env=env_map,
+        secrets=secrets_map,
+        flavor=flavor,
+        timeout=timeout,
+        namespace=namespace,
+    )
+    # Always print the job ID to the user
+    print(f"Job started with ID: {job.id}")
+    print(f"View at: {job.url}")
+
+    if detach:
+        return
+    # Now let's stream the logs
+    for log in api.fetch_job_logs(job_id=job.id):
+        print(log)
+
+
+@jobs_cli.command("logs", help="Fetch the logs of a Job")
+def jobs_logs(
+    job_id: JobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    for log in api.fetch_job_logs(job_id=job_id, namespace=namespace):
+        print(log)
+
+
+def _matches_filters(job_properties: dict[str, str], filters: dict[str, str]) -> bool:
+    """Check if scheduled job matches all specified filters."""
+    for key, pattern in filters.items():
+        # Check if property exists
+        if key not in job_properties:
+            return False
+        # Support pattern matching with wildcards
+        if "*" in pattern or "?" in pattern:
+            # Convert glob pattern to regex
+            regex_pattern = pattern.replace("*", ".*").replace("?", ".")
+            if not re.search(f"^{regex_pattern}$", job_properties[key], re.IGNORECASE):
+                return False
+        # Simple substring matching
+        elif pattern.lower() not in job_properties[key].lower():
+            return False
+    return True
+
+
+def _print_output(
+    rows: list[list[Union[str, int]]], headers: list[str], aliases: list[str], fmt: Optional[str]
+) -> None:
+    """Print output according to the chosen format."""
+    if fmt:
+        # Use custom template if provided
+        template = fmt
+        for row in rows:
+            line = template
+            for i, field in enumerate(aliases):
+                placeholder = f"{{{{.{field}}}}}"
+                if placeholder in line:
+                    line = line.replace(placeholder, str(row[i]))
+            print(line)
+    else:
+        # Default tabular format
+        print(_tabulate(rows, headers=headers))
+
+
+def _clear_line(n: int) -> None:
+    LINE_UP = "\033[1A"
+    LINE_CLEAR = "\x1b[2K"
+    for i in range(n):
+        print(LINE_UP, end=LINE_CLEAR)
+
+
+def _get_jobs_stats_rows(
+    job_id: str, metrics_stream: Iterable[dict[str, Any]], table_headers: list[str]
+) -> Iterable[tuple[bool, str, list[list[Union[str, int]]]]]:
+    for metrics in metrics_stream:
+        row = [
+            job_id,
+            f"{metrics['cpu_usage_pct']}%",
+            round(metrics["cpu_millicores"] / 1000.0, 1),
+            f"{round(100 * metrics['memory_used_bytes'] / metrics['memory_total_bytes'], 2)}%",
+            f"{_format_size(metrics['memory_used_bytes'])}B / {_format_size(metrics['memory_total_bytes'])}B",
+            f"{_format_size(metrics['rx_bps'])}bps / {_format_size(metrics['tx_bps'])}bps",
+        ]
+        if metrics["gpus"] and isinstance(metrics["gpus"], dict):
+            rows = [row] + [[""] * len(row)] * (len(metrics["gpus"]) - 1)
+            for row, gpu_id in zip(rows, sorted(metrics["gpus"])):
+                gpu = metrics["gpus"][gpu_id]
+                row += [
+                    f"{gpu['utilization']}%",
+                    f"{round(100 * gpu['memory_used_bytes'] / gpu['memory_total_bytes'], 2)}%",
+                    f"{_format_size(gpu['memory_used_bytes'])}B / {_format_size(gpu['memory_total_bytes'])}B",
+                ]
+        else:
+            row += ["N/A"] * (len(table_headers) - len(row))
+            rows = [row]
+        yield False, job_id, rows
+    yield True, job_id, []
+
+
+@jobs_cli.command("stats", help="Fetch the resource usage statistics and metrics of Jobs")
+def jobs_stats(
+    job_ids: JobIdsArg = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    if namespace is None:
+        namespace = api.whoami()["name"]
+    if job_ids is None:
+        job_ids = [
+            job.id
+            for job in api.list_jobs(namespace=namespace)
+            if (job.status.stage if job.status else "UNKNOWN") in ("RUNNING", "UPDATING")
+        ]
+    if len(job_ids) == 0:
+        print("No running jobs found")
+        return
+    table_headers = [
+        "JOB ID",
+        "CPU %",
+        "NUM CPU",
+        "MEM %",
+        "MEM USAGE",
+        "NET I/O",
+        "GPU UTIL %",
+        "GPU MEM %",
+        "GPU MEM USAGE",
+    ]
+    headers_aliases = [
+        "id",
+        "cpu_usage_pct",
+        "cpu_millicores",
+        "memory_used_bytes_pct",
+        "memory_used_bytes_and_total_bytes",
+        "rx_bps_and_tx_bps",
+        "gpu_utilization",
+        "gpu_memory_used_bytes_pct",
+        "gpu_memory_used_bytes_and_total_bytes",
+    ]
+    with multiprocessing.pool.ThreadPool(len(job_ids)) as pool:
+        rows_per_job_id: dict[str, list[list[Union[str, int]]]] = {}
+        for job_id in job_ids:
+            row: list[Union[str, int]] = [job_id]
+            row += ["-- / --" if ("/" in header or "USAGE" in header) else "--" for header in table_headers[1:]]
+            rows_per_job_id[job_id] = [row]
+        last_update_time = time.time()
+        total_rows = [row for job_id in rows_per_job_id for row in rows_per_job_id[job_id]]
+        _print_output(total_rows, table_headers, headers_aliases, None)
+
+        kwargs_list = [
+            {
+                "job_id": job_id,
+                "metrics_stream": api.fetch_job_metrics(job_id=job_id, namespace=namespace),
+                "table_headers": table_headers,
+            }
+            for job_id in job_ids
+        ]
+        for done, job_id, rows in iflatmap_unordered(pool, _get_jobs_stats_rows, kwargs_list=kwargs_list):
+            if done:
+                rows_per_job_id.pop(job_id, None)
+            else:
+                rows_per_job_id[job_id] = rows
+            now = time.time()
+            if now - last_update_time >= STATS_UPDATE_MIN_INTERVAL:
+                _clear_line(2 + len(total_rows))
+                total_rows = [row for job_id in rows_per_job_id for row in rows_per_job_id[job_id]]
+                _print_output(total_rows, table_headers, headers_aliases, None)
+                last_update_time = now
+
+
+@jobs_cli.command("ps", help="List Jobs")
+def jobs_ps(
+    all: Annotated[
+        bool,
+        typer.Option(
+            "-a",
+            "--all",
+            help="Show all Jobs (default shows just running)",
+        ),
+    ] = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    filter: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "-f",
+            "--filter",
+            help="Filter output based on conditions provided (format: key=value)",
+        ),
+    ] = None,
+    format: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Format output using a custom template",
+        ),
+    ] = None,
+) -> None:
+    try:
+        api = get_hf_api(token=token)
+        # Fetch jobs data
+        jobs = api.list_jobs(namespace=namespace)
+        # Define table headers
+        table_headers = ["JOB ID", "IMAGE/SPACE", "COMMAND", "CREATED", "STATUS"]
+        headers_aliases = ["id", "image", "command", "created", "status"]
+        rows: list[list[Union[str, int]]] = []
+
+        filters: dict[str, str] = {}
+        for f in filter or []:
+            if "=" in f:
+                key, value = f.split("=", 1)
+                filters[key.lower()] = value
+            else:
+                print(f"Warning: Ignoring invalid filter format '{f}'. Use key=value format.")
+        # Process jobs data
+        for job in jobs:
+            # Extract job data for filtering
+            status = job.status.stage if job.status else "UNKNOWN"
+            if not all and status not in ("RUNNING", "UPDATING"):
+                # Skip job if not all jobs should be shown and status doesn't match criteria
+                continue
+            # Extract job data for output
+            job_id = job.id
+
+            # Extract image or space information
+            image_or_space = job.docker_image or "N/A"
+
+            # Extract and format command
+            cmd = job.command or []
+            command_str = " ".join(cmd) if cmd else "N/A"
+
+            # Extract creation time
+            created_at = job.created_at.strftime("%Y-%m-%d %H:%M:%S") if job.created_at else "N/A"
+
+            # Create a dict with all job properties for filtering
+            props = {"id": job_id, "image": image_or_space, "status": status.lower(), "command": command_str}
+            if not _matches_filters(props, filters):
+                continue
+
+            # Create row
+            rows.append([job_id, image_or_space, command_str, created_at, status])
+
+        # Handle empty results
+        if not rows:
+            filters_msg = (
+                f" matching filters: {', '.join([f'{k}={v}' for k, v in filters.items()])}" if filters else ""
+            )
+            print(f"No jobs found{filters_msg}")
+            return
+        # Apply custom format if provided or use default tabular format
+        _print_output(rows, table_headers, headers_aliases, format)
+
+    except HfHubHTTPError as e:
+        print(f"Error fetching jobs data: {e}")
+    except (KeyError, ValueError, TypeError) as e:
+        print(f"Error processing jobs data: {e}")
+    except Exception as e:
+        print(f"Unexpected error - {type(e).__name__}: {e}")
+
+
+@jobs_cli.command("hardware", help="List available hardware options for Jobs")
+def jobs_hardware() -> None:
+    try:
+        api = get_hf_api()
+        hardware_list = api.list_jobs_hardware()
+        table_headers = ["NAME", "PRETTY NAME", "CPU", "RAM", "ACCELERATOR", "COST/MIN", "COST/HOUR"]
+        headers_aliases = ["name", "prettyName", "cpu", "ram", "accelerator", "costMin", "costHour"]
+        rows: list[list[Union[str, int]]] = []
+
+        for hw in hardware_list:
+            accelerator_info = "N/A"
+            if hw.accelerator:
+                accelerator_info = f"{hw.accelerator.quantity}x {hw.accelerator.model} ({hw.accelerator.vram})"
+            cost_min = f"${hw.unit_cost_usd:.4f}" if hw.unit_cost_usd is not None else "N/A"
+            cost_hour = f"${hw.unit_cost_usd * 60:.2f}" if hw.unit_cost_usd is not None else "N/A"
+            rows.append([hw.name, hw.pretty_name or "N/A", hw.cpu, hw.ram, accelerator_info, cost_min, cost_hour])
+
+        if not rows:
+            print("No hardware options found")
+            return
+        _print_output(rows, table_headers, headers_aliases, None)
+
+    except HfHubHTTPError as e:
+        print(f"Error fetching hardware data: {e}")
+    except Exception as e:
+        print(f"Unexpected error - {type(e).__name__}: {e}")
+
+
+@jobs_cli.command("inspect", help="Display detailed information on one or more Jobs")
+def jobs_inspect(
+    job_ids: Annotated[
+        list[str],
+        typer.Argument(
+            help="The jobs to inspect",
+        ),
+    ],
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    jobs = [api.inspect_job(job_id=job_id, namespace=namespace) for job_id in job_ids]
+    print(json.dumps([asdict(job) for job in jobs], indent=4, default=str))
+
+
+@jobs_cli.command("cancel", help="Cancel a Job")
+def jobs_cancel(
+    job_id: JobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    api.cancel_job(job_id=job_id, namespace=namespace)
+
+
+uv_app = typer_factory(help="Run UV scripts (Python with inline dependencies) on HF infrastructure")
+jobs_cli.add_typer(uv_app, name="uv")
+
+
+@uv_app.command(
+    "run",
+    help="Run a UV script (local file or URL) on HF infrastructure",
+    context_settings={"ignore_unknown_options": True},
+)
+def jobs_uv_run(
+    script: ScriptArg,
+    script_args: ScriptArgsArg = None,
+    image: ImageOpt = None,
+    flavor: FlavorOpt = None,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    timeout: TimeoutOpt = None,
+    detach: DetachOpt = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    with_: WithOpt = None,
+    python: PythonOpt = None,
+) -> None:
+    env_map: dict[str, Optional[str]] = {}
+    if env_file:
+        env_map.update(load_dotenv(Path(env_file).read_text(), environ=os.environ.copy()))
+    for env_value in env or []:
+        env_map.update(load_dotenv(env_value, environ=os.environ.copy()))
+    secrets_map: dict[str, Optional[str]] = {}
+    extended_environ = _get_extended_environ()
+    if secrets_file:
+        secrets_map.update(load_dotenv(Path(secrets_file).read_text(), environ=extended_environ))
+    for secret in secrets or []:
+        secrets_map.update(load_dotenv(secret, environ=extended_environ))
+
+    api = get_hf_api(token=token)
+    job = api.run_uv_job(
+        script=script,
+        script_args=script_args or [],
+        dependencies=with_,
+        python=python,
+        image=image,
+        env=env_map,
+        secrets=secrets_map,
+        flavor=flavor,  # type: ignore[arg-type]
+        timeout=timeout,
+        namespace=namespace,
+    )
+    # Always print the job ID to the user
+    print(f"Job started with ID: {job.id}")
+    print(f"View at: {job.url}")
+    if detach:
+        return
+    # Now let's stream the logs
+    for log in api.fetch_job_logs(job_id=job.id):
+        print(log)
+
+
+scheduled_app = typer_factory(help="Create and manage scheduled Jobs on the Hub.")
+jobs_cli.add_typer(scheduled_app, name="scheduled")
+
+
+@scheduled_app.command("run", help="Schedule a Job", context_settings={"ignore_unknown_options": True})
+def scheduled_run(
+    schedule: ScheduleArg,
+    image: ImageArg,
+    command: CommandArg,
+    suspend: SuspendOpt = None,
+    concurrency: ConcurrencyOpt = None,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    flavor: FlavorOpt = None,
+    timeout: TimeoutOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    env_map: dict[str, Optional[str]] = {}
+    if env_file:
+        env_map.update(load_dotenv(Path(env_file).read_text(), environ=os.environ.copy()))
+    for env_value in env or []:
+        env_map.update(load_dotenv(env_value, environ=os.environ.copy()))
+    secrets_map: dict[str, Optional[str]] = {}
+    extended_environ = _get_extended_environ()
+    if secrets_file:
+        secrets_map.update(load_dotenv(Path(secrets_file).read_text(), environ=extended_environ))
+    for secret in secrets or []:
+        secrets_map.update(load_dotenv(secret, environ=extended_environ))
+
+    api = get_hf_api(token=token)
+    scheduled_job = api.create_scheduled_job(
+        image=image,
+        command=command,
+        schedule=schedule,
+        suspend=suspend,
+        concurrency=concurrency,
+        env=env_map,
+        secrets=secrets_map,
+        flavor=flavor,
+        timeout=timeout,
+        namespace=namespace,
+    )
+    print(f"Scheduled Job created with ID: {scheduled_job.id}")
+
+
+@scheduled_app.command("ps", help="List scheduled Jobs")
+def scheduled_ps(
+    all: Annotated[
+        bool,
+        typer.Option(
+            "-a",
+            "--all",
+            help="Show all scheduled Jobs (default hides suspended)",
+        ),
+    ] = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    filter: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "-f",
+            "--filter",
+            help="Filter output based on conditions provided (format: key=value)",
+        ),
+    ] = None,
+    format: Annotated[
+        Optional[str],
+        typer.Option(
+            "--format",
+            help="Format output using a custom template",
+        ),
+    ] = None,
+) -> None:
+    try:
+        api = get_hf_api(token=token)
+        scheduled_jobs = api.list_scheduled_jobs(namespace=namespace)
+        table_headers = ["ID", "SCHEDULE", "IMAGE/SPACE", "COMMAND", "LAST RUN", "NEXT RUN", "SUSPEND"]
+        headers_aliases = ["id", "schedule", "image", "command", "last", "next", "suspend"]
+        rows: list[list[Union[str, int]]] = []
+        filters: dict[str, str] = {}
+        for f in filter or []:
+            if "=" in f:
+                key, value = f.split("=", 1)
+                filters[key.lower()] = value
+            else:
+                print(f"Warning: Ignoring invalid filter format '{f}'. Use key=value format.")
+
+        for scheduled_job in scheduled_jobs:
+            suspend = scheduled_job.suspend or False
+            if not all and suspend:
+                continue
+            sj_id = scheduled_job.id
+            schedule = scheduled_job.schedule or "N/A"
+            image_or_space = scheduled_job.job_spec.docker_image or "N/A"
+            cmd = scheduled_job.job_spec.command or []
+            command_str = " ".join(cmd) if cmd else "N/A"
+            last_job_at = (
+                scheduled_job.status.last_job.at.strftime("%Y-%m-%d %H:%M:%S")
+                if scheduled_job.status.last_job
+                else "N/A"
+            )
+            next_job_run_at = (
+                scheduled_job.status.next_job_run_at.strftime("%Y-%m-%d %H:%M:%S")
+                if scheduled_job.status.next_job_run_at
+                else "N/A"
+            )
+            props = {"id": sj_id, "image": image_or_space, "suspend": str(suspend), "command": command_str}
+            if not _matches_filters(props, filters):
+                continue
+            rows.append([sj_id, schedule, image_or_space, command_str, last_job_at, next_job_run_at, suspend])
+
+        if not rows:
+            filters_msg = (
+                f" matching filters: {', '.join([f'{k}={v}' for k, v in filters.items()])}" if filters else ""
+            )
+            print(f"No scheduled jobs found{filters_msg}")
+            return
+        _print_output(rows, table_headers, headers_aliases, format)
+
+    except HfHubHTTPError as e:
+        print(f"Error fetching scheduled jobs data: {e}")
+    except (KeyError, ValueError, TypeError) as e:
+        print(f"Error processing scheduled jobs data: {e}")
+    except Exception as e:
+        print(f"Unexpected error - {type(e).__name__}: {e}")
+
+
+@scheduled_app.command("inspect", help="Display detailed information on one or more scheduled Jobs")
+def scheduled_inspect(
+    scheduled_job_ids: Annotated[
+        list[str],
+        typer.Argument(
+            help="The scheduled jobs to inspect",
+        ),
+    ],
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    scheduled_jobs = [
+        api.inspect_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+        for scheduled_job_id in scheduled_job_ids
+    ]
+    print(json.dumps([asdict(scheduled_job) for scheduled_job in scheduled_jobs], indent=4, default=str))
+
+
+@scheduled_app.command("delete", help="Delete a scheduled Job")
+def scheduled_delete(
+    scheduled_job_id: ScheduledJobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    api.delete_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+
+
+@scheduled_app.command("suspend", help="Suspend (pause) a scheduled Job")
+def scheduled_suspend(
+    scheduled_job_id: ScheduledJobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    api.suspend_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+
+
+@scheduled_app.command("resume", help="Resume (unpause) a scheduled Job")
+def scheduled_resume(
+    scheduled_job_id: ScheduledJobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    api.resume_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+
+
+scheduled_uv_app = typer_factory(help="Schedule UV scripts on HF infrastructure")
+scheduled_app.add_typer(scheduled_uv_app, name="uv")
+
+
+@scheduled_uv_app.command(
+    "run",
+    help="Run a UV script (local file or URL) on HF infrastructure",
+    context_settings={"ignore_unknown_options": True},
+)
+def scheduled_uv_run(
+    schedule: ScheduleArg,
+    script: ScriptArg,
+    script_args: ScriptArgsArg = None,
+    suspend: SuspendOpt = None,
+    concurrency: ConcurrencyOpt = None,
+    image: ImageOpt = None,
+    flavor: FlavorOpt = None,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    timeout: TimeoutOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    with_: WithOpt = None,
+    python: PythonOpt = None,
+) -> None:
+    env_map: dict[str, Optional[str]] = {}
+    if env_file:
+        env_map.update(load_dotenv(Path(env_file).read_text(), environ=os.environ.copy()))
+    for env_value in env or []:
+        env_map.update(load_dotenv(env_value, environ=os.environ.copy()))
+    secrets_map: dict[str, Optional[str]] = {}
+    extended_environ = _get_extended_environ()
+    if secrets_file:
+        secrets_map.update(load_dotenv(Path(secrets_file).read_text(), environ=extended_environ))
+    for secret in secrets or []:
+        secrets_map.update(load_dotenv(secret, environ=extended_environ))
+
+    api = get_hf_api(token=token)
+    job = api.create_scheduled_uv_job(
+        script=script,
+        script_args=script_args or [],
+        schedule=schedule,
+        suspend=suspend,
+        concurrency=concurrency,
+        dependencies=with_,
+        python=python,
+        image=image,
+        env=env_map,
+        secrets=secrets_map,
+        flavor=flavor,  # type: ignore[arg-type]
+        timeout=timeout,
+        namespace=namespace,
+    )
+    print(f"Scheduled Job created with ID: {job.id}")
+
+
+### UTILS
+
+
+def _tabulate(rows: list[list[Union[str, int]]], headers: list[str]) -> str:
+    """
+    Inspired by:
+
+    - stackoverflow.com/a/8356620/593036
+    - stackoverflow.com/questions/9535954/printing-lists-as-tabular-data
+    """
+    col_widths = [max(len(str(x)) for x in col) for col in zip(*rows, headers)]
+    terminal_width = max(os.get_terminal_size().columns, len(headers) * 12)
+    while len(headers) + sum(col_widths) > terminal_width:
+        col_to_minimize = col_widths.index(max(col_widths))
+        col_widths[col_to_minimize] //= 2
+        if len(headers) + sum(col_widths) <= terminal_width:
+            col_widths[col_to_minimize] = terminal_width - sum(col_widths) - len(headers) + col_widths[col_to_minimize]
+    row_format = ("{{:{}}} " * len(headers)).format(*col_widths)
+    lines = []
+    lines.append(row_format.format(*headers))
+    lines.append(row_format.format(*["-" * w for w in col_widths]))
+    for row in rows:
+        row_format_args = [
+            str(x)[: col_width - 3] + "..." if len(str(x)) > col_width else str(x)
+            for x, col_width in zip(row, col_widths)
+        ]
+        lines.append(row_format.format(*row_format_args))
+    return "\n".join(lines)
+
+
+def _get_extended_environ() -> Dict[str, str]:
+    extended_environ = os.environ.copy()
+    if (token := get_token()) is not None:
+        extended_environ["HF_TOKEN"] = token
+    return extended_environ
+
+
+T = TypeVar("T")
+
+
+def _write_generator_to_queue(queue: Queue[T], func: Callable[..., Iterable[T]], kwargs: dict) -> None:
+    for result in func(**kwargs):
+        queue.put(result)
+
+
+def iflatmap_unordered(
+    pool: multiprocessing.pool.ThreadPool,
+    func: Callable[..., Iterable[T]],
+    *,
+    kwargs_list: list[dict],
+) -> Iterable[T]:
+    """
+    Takes a function that returns an iterable of items, and run it in parallel using threads to return the flattened iterable of items as they arrive.
+
+    This is inspired by those three `map()` variants, and is the mix of all three:
+
+    * `imap()`: like `map()` but returns an iterable instead of a list of results
+    * `imap_unordered()`: like `imap()` but the output is sorted by time of arrival
+    * `flatmap()`: like `map()` but given a function which returns a list, `flatmap()` returns the flattened list that is the concatenation of all the output lists
+    """
+    queue: Queue[T] = Queue()
+    async_results = [pool.apply_async(_write_generator_to_queue, (queue, func, kwargs)) for kwargs in kwargs_list]
+    try:
+        while True:
+            try:
+                yield queue.get(timeout=0.05)
+            except Empty:
+                if all(async_result.ready() for async_result in async_results) and queue.empty():
+                    break
+    except KeyboardInterrupt:
+        pass
+    finally:
+        # we get the result in case there's an error to raise
+        try:
+            [async_result.get(timeout=0.05) for async_result in async_results]
+        except multiprocessing.TimeoutError:
+            pass

venv/lib/python3.12/site-packages/huggingface_hub/cli/lfs.py

@@ -0,0 +1,175 @@
+"""
+Implementation of a custom transfer agent for the transfer type "multipart" for
+git-lfs.
+
+Inspired by:
+github.com/cbartz/git-lfs-swift-transfer-agent/blob/master/git_lfs_swift_transfer.py
+
+Spec is: github.com/git-lfs/git-lfs/blob/master/docs/custom-transfers.md
+
+
+To launch debugger while developing:
+
+``` [lfs "customtransfer.multipart"]
+path = /path/to/huggingface_hub/.env/bin/python args = -m debugpy --listen 5678
+--wait-for-client
+/path/to/huggingface_hub/src/huggingface_hub/commands/huggingface_cli.py
+lfs-multipart-upload ```"""
+
+import json
+import os
+import subprocess
+import sys
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub.lfs import LFS_MULTIPART_UPLOAD_COMMAND
+
+from ..utils import get_session, hf_raise_for_status, logging
+from ..utils._lfs import SliceFileObj
+
+
+logger = logging.get_logger(__name__)
+
+
+def lfs_enable_largefiles(
+    path: Annotated[
+        str,
+        typer.Argument(
+            help="Local path to repository you want to configure.",
+        ),
+    ],
+) -> None:
+    """
+    Configure a local git repository to use the multipart transfer agent for large files.
+
+    This command sets up git-lfs to use the custom multipart transfer agent
+    which enables efficient uploading of large files in chunks.
+    """
+    local_path = os.path.abspath(path)
+    if not os.path.isdir(local_path):
+        print("This does not look like a valid git repo.")
+        raise typer.Exit(code=1)
+    subprocess.run(
+        "git config lfs.customtransfer.multipart.path hf".split(),
+        check=True,
+        cwd=local_path,
+    )
+    subprocess.run(
+        f"git config lfs.customtransfer.multipart.args {LFS_MULTIPART_UPLOAD_COMMAND}".split(),
+        check=True,
+        cwd=local_path,
+    )
+    print("Local repo set up for largefiles")
+
+
+def write_msg(msg: dict):
+    """Write out the message in Line delimited JSON."""
+    msg_str = json.dumps(msg) + "\n"
+    sys.stdout.write(msg_str)
+    sys.stdout.flush()
+
+
+def read_msg() -> Optional[dict]:
+    """Read Line delimited JSON from stdin."""
+    msg = json.loads(sys.stdin.readline().strip())
+
+    if "terminate" in (msg.get("type"), msg.get("event")):
+        # terminate message received
+        return None
+
+    if msg.get("event") not in ("download", "upload"):
+        logger.critical("Received unexpected message")
+        sys.exit(1)
+
+    return msg
+
+
+def lfs_multipart_upload() -> None:
+    """Internal git-lfs custom transfer agent for multipart uploads.
+
+    This function implements the custom transfer protocol for git-lfs multipart uploads.
+    Handles chunked uploads of large files to Hugging Face Hub.
+    """
+    # Immediately after invoking a custom transfer process, git-lfs
+    # sends initiation data to the process over stdin.
+    # This tells the process useful information about the configuration.
+    init_msg = json.loads(sys.stdin.readline().strip())
+    if not (init_msg.get("event") == "init" and init_msg.get("operation") == "upload"):
+        write_msg({"error": {"code": 32, "message": "Wrong lfs init operation"}})
+        sys.exit(1)
+
+    # The transfer process should use the information it needs from the
+    # initiation structure, and also perform any one-off setup tasks it
+    # needs to do. It should then respond on stdout with a simple empty
+    # confirmation structure, as follows:
+    write_msg({})
+
+    # After the initiation exchange, git-lfs will send any number of
+    # transfer requests to the stdin of the transfer process, in a serial sequence.
+    while True:
+        msg = read_msg()
+        if msg is None:
+            # When all transfers have been processed, git-lfs will send
+            # a terminate event to the stdin of the transfer process.
+            # On receiving this message the transfer process should
+            # clean up and terminate. No response is expected.
+            sys.exit(0)
+
+        oid = msg["oid"]
+        filepath = msg["path"]
+        completion_url = msg["action"]["href"]
+        header = msg["action"]["header"]
+        chunk_size = int(header.pop("chunk_size"))
+        presigned_urls: list[str] = list(header.values())
+
+        # Send a "started" progress event to allow other workers to start.
+        # Otherwise they're delayed until first "progress" event is reported,
+        # i.e. after the first 5GB by default (!)
+        write_msg(
+            {
+                "event": "progress",
+                "oid": oid,
+                "bytesSoFar": 1,
+                "bytesSinceLast": 0,
+            }
+        )
+
+        parts = []
+        with open(filepath, "rb") as file:
+            for i, presigned_url in enumerate(presigned_urls):
+                with SliceFileObj(
+                    file,
+                    seek_from=i * chunk_size,
+                    read_limit=chunk_size,
+                ) as data:
+                    r = get_session().put(presigned_url, data=data)
+                    hf_raise_for_status(r)
+                    parts.append(
+                        {
+                            "etag": r.headers.get("etag"),
+                            "partNumber": i + 1,
+                        }
+                    )
+                    # In order to support progress reporting while data is uploading / downloading,
+                    # the transfer process should post messages to stdout
+                    write_msg(
+                        {
+                            "event": "progress",
+                            "oid": oid,
+                            "bytesSoFar": (i + 1) * chunk_size,
+                            "bytesSinceLast": chunk_size,
+                        }
+                    )
+
+        r = get_session().post(
+            completion_url,
+            json={
+                "oid": oid,
+                "parts": parts,
+            },
+        )
+        hf_raise_for_status(r)
+
+        write_msg({"event": "complete", "oid": oid})

venv/lib/python3.12/site-packages/huggingface_hub/cli/models.py

@@ -0,0 +1,110 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with models on the Hugging Face Hub.
+
+Usage:
+    # list models on the Hub
+    hf models ls
+
+    # list models with a search query
+    hf models ls --search "llama"
+
+    # get info about a model
+    hf models info Lightricks/LTX-2
+"""
+
+import enum
+import json
+from typing import Annotated, Optional, get_args
+
+import typer
+
+from huggingface_hub.errors import RepositoryNotFoundError, RevisionNotFoundError
+from huggingface_hub.hf_api import ExpandModelProperty_T, ModelSort_T
+from huggingface_hub.utils import ANSI
+
+from ._cli_utils import (
+    AuthorOpt,
+    FilterOpt,
+    LimitOpt,
+    RevisionOpt,
+    SearchOpt,
+    TokenOpt,
+    get_hf_api,
+    make_expand_properties_parser,
+    repo_info_to_dict,
+    typer_factory,
+)
+
+
+_EXPAND_PROPERTIES = sorted(get_args(ExpandModelProperty_T))
+_SORT_OPTIONS = get_args(ModelSort_T)
+ModelSortEnum = enum.Enum("ModelSortEnum", {s: s for s in _SORT_OPTIONS}, type=str)  # type: ignore[misc]
+
+
+ExpandOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help=f"Comma-separated properties to expand. Example: '--expand=downloads,likes,tags'. Valid: {', '.join(_EXPAND_PROPERTIES)}.",
+        callback=make_expand_properties_parser(_EXPAND_PROPERTIES),
+    ),
+]
+
+
+models_cli = typer_factory(help="Interact with models on the Hub.")
+
+
+@models_cli.command("ls")
+def models_ls(
+    search: SearchOpt = None,
+    author: AuthorOpt = None,
+    filter: FilterOpt = None,
+    sort: Annotated[
+        Optional[ModelSortEnum],
+        typer.Option(help="Sort results."),
+    ] = None,
+    limit: LimitOpt = 10,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """List models on the Hub."""
+    api = get_hf_api(token=token)
+    sort_key = sort.value if sort else None
+    results = [
+        repo_info_to_dict(model_info)
+        for model_info in api.list_models(
+            filter=filter, author=author, search=search, sort=sort_key, limit=limit, expand=expand
+        )
+    ]
+    print(json.dumps(results, indent=2))
+
+
+@models_cli.command("info")
+def models_info(
+    model_id: Annotated[str, typer.Argument(help="The model ID (e.g. `username/repo-name`).")],
+    revision: RevisionOpt = None,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a model on the Hub."""
+    api = get_hf_api(token=token)
+    try:
+        info = api.model_info(repo_id=model_id, revision=revision, expand=expand)  # type: ignore[arg-type]
+    except RepositoryNotFoundError:
+        print(f"Model {ANSI.bold(model_id)} not found.")
+        raise typer.Exit(code=1)
+    except RevisionNotFoundError:
+        print(f"Revision {ANSI.bold(str(revision))} not found on {ANSI.bold(model_id)}.")
+        raise typer.Exit(code=1)
+    print(json.dumps(repo_info_to_dict(info), indent=2))

venv/lib/python3.12/site-packages/huggingface_hub/cli/repo.py

@@ -0,0 +1,304 @@
+# Copyright 2025 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with repositories on the Hugging Face Hub.
+
+Usage:
+    # create a new dataset repo on the Hub
+    hf repo create my-cool-dataset --repo-type=dataset
+
+    # create a private model repo on the Hub
+    hf repo create my-cool-model --private
+"""
+
+import enum
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub.errors import HfHubHTTPError, RepositoryNotFoundError, RevisionNotFoundError
+from huggingface_hub.utils import ANSI
+
+from ._cli_utils import PrivateOpt, RepoIdArg, RepoType, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api, typer_factory
+
+
+repo_cli = typer_factory(help="Manage repos on the Hub.")
+tag_cli = typer_factory(help="Manage tags for a repo on the Hub.")
+branch_cli = typer_factory(help="Manage branches for a repo on the Hub.")
+repo_cli.add_typer(tag_cli, name="tag")
+repo_cli.add_typer(branch_cli, name="branch")
+
+
+class GatedChoices(str, enum.Enum):
+    auto = "auto"
+    manual = "manual"
+    false = "false"
+
+
+@repo_cli.command("create", help="Create a new repo on the Hub.")
+def repo_create(
+    repo_id: RepoIdArg,
+    repo_type: RepoTypeOpt = RepoType.model,
+    space_sdk: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Hugging Face Spaces SDK type. Required when --type is set to 'space'.",
+        ),
+    ] = None,
+    private: PrivateOpt = None,
+    token: TokenOpt = None,
+    exist_ok: Annotated[
+        bool,
+        typer.Option(
+            help="Do not raise an error if repo already exists.",
+        ),
+    ] = False,
+    resource_group_id: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Resource group in which to create the repo. Resource groups is only available for Enterprise Hub organizations.",
+        ),
+    ] = None,
+) -> None:
+    api = get_hf_api(token=token)
+    repo_url = api.create_repo(
+        repo_id=repo_id,
+        repo_type=repo_type.value,
+        private=private,
+        token=token,
+        exist_ok=exist_ok,
+        resource_group_id=resource_group_id,
+        space_sdk=space_sdk,
+    )
+    print(f"Successfully created {ANSI.bold(repo_url.repo_id)} on the Hub.")
+    print(f"Your repo is now available at {ANSI.bold(repo_url)}")
+
+
+@repo_cli.command("delete", help="Delete a repo from the Hub. this is an irreversible operation.")
+def repo_delete(
+    repo_id: RepoIdArg,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+    missing_ok: Annotated[
+        bool,
+        typer.Option(
+            help="If set to True, do not raise an error if repo does not exist.",
+        ),
+    ] = False,
+) -> None:
+    api = get_hf_api(token=token)
+    api.delete_repo(
+        repo_id=repo_id,
+        repo_type=repo_type.value,
+        missing_ok=missing_ok,
+    )
+    print(f"Successfully deleted {ANSI.bold(repo_id)} on the Hub.")
+
+
+@repo_cli.command("move", help="Move a repository from a namespace to another namespace.")
+def repo_move(
+    from_id: RepoIdArg,
+    to_id: RepoIdArg,
+    token: TokenOpt = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+) -> None:
+    api = get_hf_api(token=token)
+    api.move_repo(
+        from_id=from_id,
+        to_id=to_id,
+        repo_type=repo_type.value,
+    )
+    print(f"Successfully moved {ANSI.bold(from_id)} to {ANSI.bold(to_id)} on the Hub.")
+
+
+@repo_cli.command("settings", help="Update the settings of a repository.")
+def repo_settings(
+    repo_id: RepoIdArg,
+    gated: Annotated[
+        Optional[GatedChoices],
+        typer.Option(
+            help="The gated status for the repository.",
+        ),
+    ] = None,
+    private: Annotated[
+        Optional[bool],
+        typer.Option(
+            help="Whether the repository should be private.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+) -> None:
+    api = get_hf_api(token=token)
+    api.update_repo_settings(
+        repo_id=repo_id,
+        gated=(gated.value if gated else None),  # type: ignore [arg-type]
+        private=private,
+        repo_type=repo_type.value,
+    )
+    print(f"Successfully updated the settings of {ANSI.bold(repo_id)} on the Hub.")
+
+
+@branch_cli.command("create", help="Create a new branch for a repo on the Hub.")
+def branch_create(
+    repo_id: RepoIdArg,
+    branch: Annotated[
+        str,
+        typer.Argument(
+            help="The name of the branch to create.",
+        ),
+    ],
+    revision: RevisionOpt = None,
+    token: TokenOpt = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+    exist_ok: Annotated[
+        bool,
+        typer.Option(
+            help="If set to True, do not raise an error if branch already exists.",
+        ),
+    ] = False,
+) -> None:
+    api = get_hf_api(token=token)
+    api.create_branch(
+        repo_id=repo_id,
+        branch=branch,
+        revision=revision,
+        repo_type=repo_type.value,
+        exist_ok=exist_ok,
+    )
+    print(f"Successfully created {ANSI.bold(branch)} branch on {repo_type.value} {ANSI.bold(repo_id)}")
+
+
+@branch_cli.command("delete", help="Delete a branch from a repo on the Hub.")
+def branch_delete(
+    repo_id: RepoIdArg,
+    branch: Annotated[
+        str,
+        typer.Argument(
+            help="The name of the branch to delete.",
+        ),
+    ],
+    token: TokenOpt = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+) -> None:
+    api = get_hf_api(token=token)
+    api.delete_branch(
+        repo_id=repo_id,
+        branch=branch,
+        repo_type=repo_type.value,
+    )
+    print(f"Successfully deleted {ANSI.bold(branch)} branch on {repo_type.value} {ANSI.bold(repo_id)}")
+
+
+@tag_cli.command("create", help="Create a tag for a repo.")
+def tag_create(
+    repo_id: RepoIdArg,
+    tag: Annotated[
+        str,
+        typer.Argument(
+            help="The name of the tag to create.",
+        ),
+    ],
+    message: Annotated[
+        Optional[str],
+        typer.Option(
+            "-m",
+            "--message",
+            help="The description of the tag to create.",
+        ),
+    ] = None,
+    revision: RevisionOpt = None,
+    token: TokenOpt = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+) -> None:
+    repo_type_str = repo_type.value
+    api = get_hf_api(token=token)
+    print(f"You are about to create tag {ANSI.bold(tag)} on {repo_type_str} {ANSI.bold(repo_id)}")
+    try:
+        api.create_tag(repo_id=repo_id, tag=tag, tag_message=message, revision=revision, repo_type=repo_type_str)
+    except RepositoryNotFoundError:
+        print(f"{repo_type_str.capitalize()} {ANSI.bold(repo_id)} not found.")
+        raise typer.Exit(code=1)
+    except RevisionNotFoundError:
+        print(f"Revision {ANSI.bold(str(revision))} not found.")
+        raise typer.Exit(code=1)
+    except HfHubHTTPError as e:
+        if e.response.status_code == 409:
+            print(f"Tag {ANSI.bold(tag)} already exists on {ANSI.bold(repo_id)}")
+            raise typer.Exit(code=1)
+        raise e
+    print(f"Tag {ANSI.bold(tag)} created on {ANSI.bold(repo_id)}")
+
+
+@tag_cli.command("list", help="List tags for a repo.")
+def tag_list(
+    repo_id: RepoIdArg,
+    token: TokenOpt = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+) -> None:
+    repo_type_str = repo_type.value
+    api = get_hf_api(token=token)
+    try:
+        refs = api.list_repo_refs(repo_id=repo_id, repo_type=repo_type_str)
+    except RepositoryNotFoundError:
+        print(f"{repo_type_str.capitalize()} {ANSI.bold(repo_id)} not found.")
+        raise typer.Exit(code=1)
+    except HfHubHTTPError as e:
+        print(e)
+        print(ANSI.red(e.response.text))
+        raise typer.Exit(code=1)
+    if len(refs.tags) == 0:
+        print("No tags found")
+        raise typer.Exit(code=0)
+    print(f"Tags for {repo_type_str} {ANSI.bold(repo_id)}:")
+    for t in refs.tags:
+        print(t.name)
+
+
+@tag_cli.command("delete", help="Delete a tag for a repo.")
+def tag_delete(
+    repo_id: RepoIdArg,
+    tag: Annotated[
+        str,
+        typer.Argument(
+            help="The name of the tag to delete.",
+        ),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Answer Yes to prompt automatically",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+) -> None:
+    repo_type_str = repo_type.value
+    print(f"You are about to delete tag {ANSI.bold(tag)} on {repo_type_str} {ANSI.bold(repo_id)}")
+    if not yes:
+        choice = input("Proceed? [Y/n] ").lower()
+        if choice not in ("", "y", "yes"):
+            print("Abort")
+            raise typer.Exit()
+    api = get_hf_api(token=token)
+    try:
+        api.delete_tag(repo_id=repo_id, tag=tag, repo_type=repo_type_str)
+    except RepositoryNotFoundError:
+        print(f"{repo_type_str.capitalize()} {ANSI.bold(repo_id)} not found.")
+        raise typer.Exit(code=1)
+    except RevisionNotFoundError:
+        print(f"Tag {ANSI.bold(tag)} not found on {ANSI.bold(repo_id)}")
+        raise typer.Exit(code=1)
+    print(f"Tag {ANSI.bold(tag)} deleted on {ANSI.bold(repo_id)}")

venv/lib/python3.12/site-packages/huggingface_hub/cli/repo_files.py

@@ -0,0 +1,94 @@
+# coding=utf-8
+# Copyright 2023-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains command to update or delete files in a repository using the CLI.
+
+Usage:
+    # delete all
+    hf repo-files delete <repo_id> "*"
+
+    # delete single file
+    hf repo-files delete <repo_id> file.txt
+
+    # delete single folder
+    hf repo-files delete <repo_id> folder/
+
+    # delete multiple
+    hf repo-files delete <repo_id> file.txt folder/ file2.txt
+
+    # delete multiple patterns
+    hf repo-files delete <repo_id> file.txt "*.json" "folder/*.parquet"
+
+    # delete from different revision / repo-type
+    hf repo-files delete <repo_id> file.txt --revision=refs/pr/1 --repo-type=dataset
+"""
+
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub import logging
+
+from ._cli_utils import RepoIdArg, RepoType, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api, typer_factory
+
+
+logger = logging.get_logger(__name__)
+
+
+repo_files_cli = typer_factory(help="Manage files in a repo on the Hub.")
+
+
+@repo_files_cli.command("delete")
+def repo_files_delete(
+    repo_id: RepoIdArg,
+    patterns: Annotated[
+        list[str],
+        typer.Argument(
+            help="Glob patterns to match files to delete. Based on fnmatch, '*' matches files recursively.",
+        ),
+    ],
+    repo_type: RepoTypeOpt = RepoType.model,
+    revision: RevisionOpt = None,
+    commit_message: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The summary / title / first line of the generated commit.",
+        ),
+    ] = None,
+    commit_description: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The description of the generated commit.",
+        ),
+    ] = None,
+    create_pr: Annotated[
+        bool,
+        typer.Option(
+            help="Whether to create a new Pull Request for these changes.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    url = api.delete_files(
+        delete_patterns=patterns,
+        repo_id=repo_id,
+        repo_type=repo_type.value,
+        revision=revision,
+        commit_message=commit_message,
+        commit_description=commit_description,
+        create_pr=create_pr,
+    )
+    print(f"Files correctly deleted from repo. Commit: {url}.")
+    logging.set_verbosity_warning()

venv/lib/python3.12/site-packages/huggingface_hub/cli/spaces.py

@@ -0,0 +1,110 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with spaces on the Hugging Face Hub.
+
+Usage:
+    # list spaces on the Hub
+    hf spaces ls
+
+    # list spaces with a search query
+    hf spaces ls --search "chatbot"
+
+    # get info about a space
+    hf spaces info enzostvs/deepsite
+"""
+
+import enum
+import json
+from typing import Annotated, Optional, get_args
+
+import typer
+
+from huggingface_hub.errors import RepositoryNotFoundError, RevisionNotFoundError
+from huggingface_hub.hf_api import ExpandSpaceProperty_T, SpaceSort_T
+from huggingface_hub.utils import ANSI
+
+from ._cli_utils import (
+    AuthorOpt,
+    FilterOpt,
+    LimitOpt,
+    RevisionOpt,
+    SearchOpt,
+    TokenOpt,
+    get_hf_api,
+    make_expand_properties_parser,
+    repo_info_to_dict,
+    typer_factory,
+)
+
+
+_EXPAND_PROPERTIES = sorted(get_args(ExpandSpaceProperty_T))
+_SORT_OPTIONS = get_args(SpaceSort_T)
+SpaceSortEnum = enum.Enum("SpaceSortEnum", {s: s for s in _SORT_OPTIONS}, type=str)  # type: ignore[misc]
+
+
+ExpandOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help=f"Comma-separated properties to expand. Example: '--expand=likes,tags'. Valid: {', '.join(_EXPAND_PROPERTIES)}.",
+        callback=make_expand_properties_parser(_EXPAND_PROPERTIES),
+    ),
+]
+
+
+spaces_cli = typer_factory(help="Interact with spaces on the Hub.")
+
+
+@spaces_cli.command("ls")
+def spaces_ls(
+    search: SearchOpt = None,
+    author: AuthorOpt = None,
+    filter: FilterOpt = None,
+    sort: Annotated[
+        Optional[SpaceSortEnum],
+        typer.Option(help="Sort results."),
+    ] = None,
+    limit: LimitOpt = 10,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """List spaces on the Hub."""
+    api = get_hf_api(token=token)
+    sort_key = sort.value if sort else None
+    results = [
+        repo_info_to_dict(space_info)
+        for space_info in api.list_spaces(
+            filter=filter, author=author, search=search, sort=sort_key, limit=limit, expand=expand
+        )
+    ]
+    print(json.dumps(results, indent=2))
+
+
+@spaces_cli.command("info")
+def spaces_info(
+    space_id: Annotated[str, typer.Argument(help="The space ID (e.g. `username/repo-name`).")],
+    revision: RevisionOpt = None,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a space on the Hub."""
+    api = get_hf_api(token=token)
+    try:
+        info = api.space_info(repo_id=space_id, revision=revision, expand=expand)  # type: ignore[arg-type]
+    except RepositoryNotFoundError:
+        print(f"Space {ANSI.bold(space_id)} not found.")
+        raise typer.Exit(code=1)
+    except RevisionNotFoundError:
+        print(f"Revision {ANSI.bold(str(revision))} not found on {ANSI.bold(space_id)}.")
+        raise typer.Exit(code=1)
+    print(json.dumps(repo_info_to_dict(info), indent=2))

venv/lib/python3.12/site-packages/huggingface_hub/cli/system.py

@@ -0,0 +1,33 @@
+# Copyright 2022 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to print information about the environment and version.
+
+Usage:
+    hf env
+    hf version
+"""
+
+from huggingface_hub import __version__
+
+from ..utils import dump_environment_info
+
+
+def env() -> None:
+    """Print information about the environment."""
+    dump_environment_info()
+
+
+def version() -> None:
+    """Print CLI version."""
+    print(__version__)

venv/lib/python3.12/site-packages/huggingface_hub/cli/upload.py

@@ -0,0 +1,294 @@
+# coding=utf-8
+# Copyright 2023-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains command to upload a repo or file with the CLI.
+
+Usage:
+    # Upload file (implicit)
+    hf upload my-cool-model ./my-cool-model.safetensors
+
+    # Upload file (explicit)
+    hf upload my-cool-model ./my-cool-model.safetensors  model.safetensors
+
+    # Upload directory (implicit). If `my-cool-model/` is a directory it will be uploaded, otherwise an exception is raised.
+    hf upload my-cool-model
+
+    # Upload directory (explicit)
+    hf upload my-cool-model ./models/my-cool-model .
+
+    # Upload filtered directory (example: tensorboard logs except for the last run)
+    hf upload my-cool-model ./model/training /logs --include "*.tfevents.*" --exclude "*20230905*"
+
+    # Upload with wildcard
+    hf upload my-cool-model "./model/training/*.safetensors"
+
+    # Upload private dataset
+    hf upload Wauplin/my-cool-dataset ./data . --repo-type=dataset --private
+
+    # Upload with token
+    hf upload Wauplin/my-cool-model --token=hf_****
+
+    # Sync local Space with Hub (upload new files, delete removed files)
+    hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
+
+    # Schedule commits every 30 minutes
+    hf upload Wauplin/my-cool-model --every=30
+"""
+
+import os
+import time
+import warnings
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub import logging
+from huggingface_hub._commit_scheduler import CommitScheduler
+from huggingface_hub.errors import RevisionNotFoundError
+from huggingface_hub.utils import disable_progress_bars, enable_progress_bars
+
+from ._cli_utils import PrivateOpt, RepoIdArg, RepoType, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api
+
+
+logger = logging.get_logger(__name__)
+
+
+def upload(
+    repo_id: RepoIdArg,
+    local_path: Annotated[
+        Optional[str],
+        typer.Argument(
+            help="Local path to the file or folder to upload. Wildcard patterns are supported. Defaults to current directory.",
+        ),
+    ] = None,
+    path_in_repo: Annotated[
+        Optional[str],
+        typer.Argument(
+            help="Path of the file or folder in the repo. Defaults to the relative path of the file or folder.",
+        ),
+    ] = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+    revision: RevisionOpt = None,
+    private: PrivateOpt = None,
+    include: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to match files to upload.",
+        ),
+    ] = None,
+    exclude: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to exclude from files to upload.",
+        ),
+    ] = None,
+    delete: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns for file to be deleted from the repo while committing.",
+        ),
+    ] = None,
+    commit_message: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The summary / title / first line of the generated commit.",
+        ),
+    ] = None,
+    commit_description: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The description of the generated commit.",
+        ),
+    ] = None,
+    create_pr: Annotated[
+        bool,
+        typer.Option(
+            help="Whether to upload content as a new Pull Request.",
+        ),
+    ] = False,
+    every: Annotated[
+        Optional[float],
+        typer.Option(
+            help="f set, a background job is scheduled to create commits every `every` minutes.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            help="Disable progress bars and warnings; print only the returned path.",
+        ),
+    ] = False,
+) -> None:
+    """Upload a file or a folder to the Hub. Recommended for single-commit uploads."""
+
+    if every is not None and every <= 0:
+        raise typer.BadParameter("--every must be a positive value", param_hint="every")
+
+    repo_type_str = repo_type.value
+
+    api = get_hf_api(token=token)
+
+    # Resolve local_path and path_in_repo based on implicit/explicit rules
+    resolved_local_path, resolved_path_in_repo, resolved_include = _resolve_upload_paths(
+        repo_id=repo_id, local_path=local_path, path_in_repo=path_in_repo, include=include
+    )
+
+    def run_upload() -> str:
+        if os.path.isfile(resolved_local_path):
+            if resolved_include is not None and len(resolved_include) > 0 and isinstance(resolved_include, list):
+                warnings.warn("Ignoring --include since a single file is uploaded.")
+            if exclude is not None and len(exclude) > 0:
+                warnings.warn("Ignoring --exclude since a single file is uploaded.")
+            if delete is not None and len(delete) > 0:
+                warnings.warn("Ignoring --delete since a single file is uploaded.")
+
+        # Schedule commits if `every` is set
+        if every is not None:
+            if os.path.isfile(resolved_local_path):
+                # If file => watch entire folder + use allow_patterns
+                folder_path = os.path.dirname(resolved_local_path)
+                pi = (
+                    resolved_path_in_repo[: -len(resolved_local_path)]
+                    if resolved_path_in_repo.endswith(resolved_local_path)
+                    else resolved_path_in_repo
+                )
+                allow_patterns = [resolved_local_path]
+                ignore_patterns: Optional[list[str]] = []
+            else:
+                folder_path = resolved_local_path
+                pi = resolved_path_in_repo
+                allow_patterns = (
+                    resolved_include or []
+                    if isinstance(resolved_include, list)
+                    else [resolved_include]
+                    if isinstance(resolved_include, str)
+                    else []
+                )
+                ignore_patterns = exclude or []
+                if delete is not None and len(delete) > 0:
+                    warnings.warn("Ignoring --delete when uploading with scheduled commits.")
+
+            scheduler = CommitScheduler(
+                folder_path=folder_path,
+                repo_id=repo_id,
+                repo_type=repo_type_str,
+                revision=revision,
+                allow_patterns=allow_patterns,
+                ignore_patterns=ignore_patterns,
+                path_in_repo=pi,
+                private=private,
+                every=every,
+                hf_api=api,
+            )
+            print(f"Scheduling commits every {every} minutes to {scheduler.repo_id}.")
+            try:
+                while True:
+                    time.sleep(100)
+            except KeyboardInterrupt:
+                scheduler.stop()
+                return "Stopped scheduled commits."
+
+        # Otherwise, create repo and proceed with the upload
+        if not os.path.isfile(resolved_local_path) and not os.path.isdir(resolved_local_path):
+            raise FileNotFoundError(f"No such file or directory: '{resolved_local_path}'.")
+        created = api.create_repo(
+            repo_id=repo_id,
+            repo_type=repo_type_str,
+            exist_ok=True,
+            private=private,
+            space_sdk="gradio" if repo_type_str == "space" else None,
+            # ^ We don't want it to fail when uploading to a Space => let's set Gradio by default.
+            # ^ I'd rather not add CLI args to set it explicitly as we already have `hf repo create` for that.
+        ).repo_id
+
+        # Check if branch already exists and if not, create it
+        if revision is not None and not create_pr:
+            try:
+                api.repo_info(repo_id=created, repo_type=repo_type_str, revision=revision)
+            except RevisionNotFoundError:
+                logger.info(f"Branch '{revision}' not found. Creating it...")
+                api.create_branch(repo_id=created, repo_type=repo_type_str, branch=revision, exist_ok=True)
+                # ^ `exist_ok=True` to avoid race concurrency issues
+
+        # File-based upload
+        if os.path.isfile(resolved_local_path):
+            return api.upload_file(
+                path_or_fileobj=resolved_local_path,
+                path_in_repo=resolved_path_in_repo,
+                repo_id=created,
+                repo_type=repo_type_str,
+                revision=revision,
+                commit_message=commit_message,
+                commit_description=commit_description,
+                create_pr=create_pr,
+            )
+
+        # Folder-based upload
+        return api.upload_folder(
+            folder_path=resolved_local_path,
+            path_in_repo=resolved_path_in_repo,
+            repo_id=created,
+            repo_type=repo_type_str,
+            revision=revision,
+            commit_message=commit_message,
+            commit_description=commit_description,
+            create_pr=create_pr,
+            allow_patterns=(
+                resolved_include
+                if isinstance(resolved_include, list)
+                else [resolved_include]
+                if isinstance(resolved_include, str)
+                else None
+            ),
+            ignore_patterns=exclude,
+            delete_patterns=delete,
+        )
+
+    if quiet:
+        disable_progress_bars()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            print(run_upload())
+        enable_progress_bars()
+    else:
+        print(run_upload())
+        logging.set_verbosity_warning()
+
+
+def _resolve_upload_paths(
+    *, repo_id: str, local_path: Optional[str], path_in_repo: Optional[str], include: Optional[list[str]]
+) -> tuple[str, str, Optional[list[str]]]:
+    repo_name = repo_id.split("/")[-1]
+    resolved_include = include
+
+    if local_path is not None and any(c in local_path for c in ["*", "?", "["]):
+        if include is not None:
+            raise ValueError("Cannot set --include when local_path contains a wildcard.")
+        if path_in_repo is not None and path_in_repo != ".":
+            raise ValueError("Cannot set path_in_repo when local_path contains a wildcard.")
+        return ".", local_path, ["."]  # will be adjusted below; placeholder for type
+
+    if local_path is None and os.path.isfile(repo_name):
+        return repo_name, repo_name, resolved_include
+    if local_path is None and os.path.isdir(repo_name):
+        return repo_name, ".", resolved_include
+    if local_path is None:
+        raise ValueError(f"'{repo_name}' is not a local file or folder. Please set local_path explicitly.")
+
+    if path_in_repo is None and os.path.isfile(local_path):
+        return local_path, os.path.basename(local_path), resolved_include
+    if path_in_repo is None:
+        return local_path, ".", resolved_include
+    return local_path, path_in_repo, resolved_include

venv/lib/python3.12/site-packages/huggingface_hub/cli/upload_large_folder.py

@@ -0,0 +1,117 @@
+# coding=utf-8
+# Copyright 2023-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains command to upload a large folder with the CLI."""
+
+import os
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub import logging
+from huggingface_hub.utils import ANSI, disable_progress_bars
+
+from ._cli_utils import PrivateOpt, RepoIdArg, RepoType, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api
+
+
+logger = logging.get_logger(__name__)
+
+
+def upload_large_folder(
+    repo_id: RepoIdArg,
+    local_path: Annotated[
+        str,
+        typer.Argument(
+            help="Local path to the folder to upload.",
+        ),
+    ],
+    repo_type: RepoTypeOpt = RepoType.model,
+    revision: RevisionOpt = None,
+    private: PrivateOpt = None,
+    include: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to match files to upload.",
+        ),
+    ] = None,
+    exclude: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to exclude from files to upload.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+    num_workers: Annotated[
+        Optional[int],
+        typer.Option(
+            help="Number of workers to use to hash, upload and commit files.",
+        ),
+    ] = None,
+    no_report: Annotated[
+        bool,
+        typer.Option(
+            help="Whether to disable regular status report.",
+        ),
+    ] = False,
+    no_bars: Annotated[
+        bool,
+        typer.Option(
+            help="Whether to disable progress bars.",
+        ),
+    ] = False,
+) -> None:
+    """Upload a large folder to the Hub. Recommended for resumable uploads."""
+    if not os.path.isdir(local_path):
+        raise typer.BadParameter("Large upload is only supported for folders.", param_hint="local_path")
+
+    print(
+        ANSI.yellow(
+            "You are about to upload a large folder to the Hub using `hf upload-large-folder`. "
+            "This is a new feature so feedback is very welcome!\n"
+            "\n"
+            "A few things to keep in mind:\n"
+            "  - Repository limits still apply: https://huggingface.co/docs/hub/repositories-recommendations\n"
+            "  - Do not start several processes in parallel.\n"
+            "  - You can interrupt and resume the process at any time. "
+            "The script will pick up where it left off except for partially uploaded files that would have to be entirely reuploaded.\n"
+            "  - Do not upload the same folder to several repositories. If you need to do so, you must delete the `./.cache/huggingface/` folder first.\n"
+            "\n"
+            f"Some temporary metadata will be stored under `{local_path}/.cache/huggingface`.\n"
+            "  - You must not modify those files manually.\n"
+            "  - You must not delete the `./.cache/huggingface/` folder while a process is running.\n"
+            "  - You can delete the `./.cache/huggingface/` folder to reinitialize the upload state when process is not running. Files will have to be hashed and preuploaded again, except for already committed files.\n"
+            "\n"
+            "If the process output is too verbose, you can disable the progress bars with `--no-bars`. "
+            "You can also entirely disable the status report with `--no-report`.\n"
+            "\n"
+            "For more details, run `hf upload-large-folder --help` or check the documentation at "
+            "https://huggingface.co/docs/huggingface_hub/guides/upload#upload-a-large-folder."
+        )
+    )
+
+    if no_bars:
+        disable_progress_bars()
+
+    api = get_hf_api(token=token)
+    api.upload_large_folder(
+        repo_id=repo_id,
+        folder_path=local_path,
+        repo_type=repo_type.value,
+        revision=revision,
+        private=private,
+        allow_patterns=include,
+        ignore_patterns=exclude,
+        num_workers=num_workers,
+        print_report=not no_report,
+    )

venv/lib/python3.12/site-packages/huggingface_hub/community.py

@@ -0,0 +1,363 @@
+"""
+Data structures to interact with Discussions and Pull Requests on the Hub.
+
+See [the Discussions and Pull Requests guide](https://huggingface.co/docs/hub/repositories-pull-requests-discussions)
+for more information on Pull Requests, Discussions, and the community tab.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal, Optional, TypedDict, Union
+
+from . import constants
+from .utils import parse_datetime
+
+
+DiscussionStatus = Literal["open", "closed", "merged", "draft"]
+
+
+@dataclass
+class Discussion:
+    """
+    A Discussion or Pull Request on the Hub.
+
+    This dataclass is not intended to be instantiated directly.
+
+    Attributes:
+        title (`str`):
+            The title of the Discussion / Pull Request
+        status (`str`):
+            The status of the Discussion / Pull Request.
+            It must be one of:
+                * `"open"`
+                * `"closed"`
+                * `"merged"` (only for Pull Requests )
+                * `"draft"` (only for Pull Requests )
+        num (`int`):
+            The number of the Discussion / Pull Request.
+        repo_id (`str`):
+            The id (`"{namespace}/{repo_name}"`) of the repo on which
+            the Discussion / Pull Request was open.
+        repo_type (`str`):
+            The type of the repo on which the Discussion / Pull Request was open.
+            Possible values are: `"model"`, `"dataset"`, `"space"`.
+        author (`str`):
+            The username of the Discussion / Pull Request author.
+            Can be `"deleted"` if the user has been deleted since.
+        is_pull_request (`bool`):
+            Whether or not this is a Pull Request.
+        created_at (`datetime`):
+            The `datetime` of creation of the Discussion / Pull Request.
+        endpoint (`str`):
+            Endpoint of the Hub. Default is https://huggingface.co.
+        git_reference (`str`, *optional*):
+            (property) Git reference to which changes can be pushed if this is a Pull Request, `None` otherwise.
+        url (`str`):
+            (property) URL of the discussion on the Hub.
+    """
+
+    title: str
+    status: DiscussionStatus
+    num: int
+    repo_id: str
+    repo_type: str
+    author: str
+    is_pull_request: bool
+    created_at: datetime
+    endpoint: str
+
+    @property
+    def git_reference(self) -> Optional[str]:
+        """
+        If this is a Pull Request , returns the git reference to which changes can be pushed.
+        Returns `None` otherwise.
+        """
+        if self.is_pull_request:
+            return f"refs/pr/{self.num}"
+        return None
+
+    @property
+    def url(self) -> str:
+        """Returns the URL of the discussion on the Hub."""
+        if self.repo_type is None or self.repo_type == constants.REPO_TYPE_MODEL:
+            return f"{self.endpoint}/{self.repo_id}/discussions/{self.num}"
+        return f"{self.endpoint}/{self.repo_type}s/{self.repo_id}/discussions/{self.num}"
+
+
+@dataclass
+class DiscussionWithDetails(Discussion):
+    """
+    Subclass of [`Discussion`].
+
+    Attributes:
+        title (`str`):
+            The title of the Discussion / Pull Request
+        status (`str`):
+            The status of the Discussion / Pull Request.
+            It can be one of:
+                * `"open"`
+                * `"closed"`
+                * `"merged"` (only for Pull Requests )
+                * `"draft"` (only for Pull Requests )
+        num (`int`):
+            The number of the Discussion / Pull Request.
+        repo_id (`str`):
+            The id (`"{namespace}/{repo_name}"`) of the repo on which
+            the Discussion / Pull Request was open.
+        repo_type (`str`):
+            The type of the repo on which the Discussion / Pull Request was open.
+            Possible values are: `"model"`, `"dataset"`, `"space"`.
+        author (`str`):
+            The username of the Discussion / Pull Request author.
+            Can be `"deleted"` if the user has been deleted since.
+        is_pull_request (`bool`):
+            Whether or not this is a Pull Request.
+        created_at (`datetime`):
+            The `datetime` of creation of the Discussion / Pull Request.
+        events (`list` of [`DiscussionEvent`])
+            The list of [`DiscussionEvents`] in this Discussion or Pull Request.
+        conflicting_files (`Union[list[str], bool, None]`, *optional*):
+            A list of conflicting files if this is a Pull Request.
+            `None` if `self.is_pull_request` is `False`.
+            `True` if there are conflicting files but the list can't be retrieved.
+        target_branch (`str`, *optional*):
+            The branch into which changes are to be merged if this is a
+            Pull Request . `None`  if `self.is_pull_request` is `False`.
+        merge_commit_oid (`str`, *optional*):
+            If this is a merged Pull Request , this is set to the OID / SHA of
+            the merge commit, `None` otherwise.
+        diff (`str`, *optional*):
+            The git diff if this is a Pull Request , `None` otherwise.
+        endpoint (`str`):
+            Endpoint of the Hub. Default is https://huggingface.co.
+        git_reference (`str`, *optional*):
+            (property) Git reference to which changes can be pushed if this is a Pull Request, `None` otherwise.
+        url (`str`):
+            (property) URL of the discussion on the Hub.
+    """
+
+    events: list["DiscussionEvent"]
+    conflicting_files: Union[list[str], bool, None]
+    target_branch: Optional[str]
+    merge_commit_oid: Optional[str]
+    diff: Optional[str]
+
+
+class DiscussionEventArgs(TypedDict):
+    id: str
+    type: str
+    created_at: datetime
+    author: str
+    _event: dict
+
+
+@dataclass
+class DiscussionEvent:
+    """
+    An event in a Discussion or Pull Request.
+
+    Use concrete classes:
+        * [`DiscussionComment`]
+        * [`DiscussionStatusChange`]
+        * [`DiscussionCommit`]
+        * [`DiscussionTitleChange`]
+
+    Attributes:
+        id (`str`):
+            The ID of the event. An hexadecimal string.
+        type (`str`):
+            The type of the event.
+        created_at (`datetime`):
+            A [`datetime`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime)
+            object holding the creation timestamp for the event.
+        author (`str`):
+            The username of the Discussion / Pull Request author.
+            Can be `"deleted"` if the user has been deleted since.
+    """
+
+    id: str
+    type: str
+    created_at: datetime
+    author: str
+
+    _event: dict
+    """Stores the original event data, in case we need to access it later."""
+
+
+@dataclass
+class DiscussionComment(DiscussionEvent):
+    """A comment in a Discussion / Pull Request.
+
+    Subclass of [`DiscussionEvent`].
+
+
+    Attributes:
+        id (`str`):
+            The ID of the event. An hexadecimal string.
+        type (`str`):
+            The type of the event.
+        created_at (`datetime`):
+            A [`datetime`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime)
+            object holding the creation timestamp for the event.
+        author (`str`):
+            The username of the Discussion / Pull Request author.
+            Can be `"deleted"` if the user has been deleted since.
+        content (`str`):
+            The raw markdown content of the comment. Mentions, links and images are not rendered.
+        edited (`bool`):
+            Whether or not this comment has been edited.
+        hidden (`bool`):
+            Whether or not this comment has been hidden.
+    """
+
+    content: str
+    edited: bool
+    hidden: bool
+
+    @property
+    def rendered(self) -> str:
+        """The rendered comment, as a HTML string"""
+        return self._event["data"]["latest"]["html"]
+
+    @property
+    def last_edited_at(self) -> datetime:
+        """The last edit time, as a `datetime` object."""
+        return parse_datetime(self._event["data"]["latest"]["updatedAt"])
+
+    @property
+    def last_edited_by(self) -> str:
+        """The last edit time, as a `datetime` object."""
+        return self._event["data"]["latest"].get("author", {}).get("name", "deleted")
+
+    @property
+    def edit_history(self) -> list[dict]:
+        """The edit history of the comment"""
+        return self._event["data"]["history"]
+
+    @property
+    def number_of_edits(self) -> int:
+        return len(self.edit_history)
+
+
+@dataclass
+class DiscussionStatusChange(DiscussionEvent):
+    """A change of status in a Discussion / Pull Request.
+
+    Subclass of [`DiscussionEvent`].
+
+    Attributes:
+        id (`str`):
+            The ID of the event. An hexadecimal string.
+        type (`str`):
+            The type of the event.
+        created_at (`datetime`):
+            A [`datetime`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime)
+            object holding the creation timestamp for the event.
+        author (`str`):
+            The username of the Discussion / Pull Request author.
+            Can be `"deleted"` if the user has been deleted since.
+        new_status (`str`):
+            The status of the Discussion / Pull Request after the change.
+            It can be one of:
+                * `"open"`
+                * `"closed"`
+                * `"merged"` (only for Pull Requests )
+    """
+
+    new_status: str
+
+
+@dataclass
+class DiscussionCommit(DiscussionEvent):
+    """A commit in a Pull Request.
+
+    Subclass of [`DiscussionEvent`].
+
+    Attributes:
+        id (`str`):
+            The ID of the event. An hexadecimal string.
+        type (`str`):
+            The type of the event.
+        created_at (`datetime`):
+            A [`datetime`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime)
+            object holding the creation timestamp for the event.
+        author (`str`):
+            The username of the Discussion / Pull Request author.
+            Can be `"deleted"` if the user has been deleted since.
+        summary (`str`):
+            The summary of the commit.
+        oid (`str`):
+            The OID / SHA of the commit, as a hexadecimal string.
+    """
+
+    summary: str
+    oid: str
+
+
+@dataclass
+class DiscussionTitleChange(DiscussionEvent):
+    """A rename event in a Discussion / Pull Request.
+
+    Subclass of [`DiscussionEvent`].
+
+    Attributes:
+        id (`str`):
+            The ID of the event. An hexadecimal string.
+        type (`str`):
+            The type of the event.
+        created_at (`datetime`):
+            A [`datetime`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime)
+            object holding the creation timestamp for the event.
+        author (`str`):
+            The username of the Discussion / Pull Request author.
+            Can be `"deleted"` if the user has been deleted since.
+        old_title (`str`):
+            The previous title for the Discussion / Pull Request.
+        new_title (`str`):
+            The new title.
+    """
+
+    old_title: str
+    new_title: str
+
+
+def deserialize_event(event: dict) -> DiscussionEvent:
+    """Instantiates a [`DiscussionEvent`] from a dict"""
+    event_id: str = event["id"]
+    event_type: str = event["type"]
+    created_at = parse_datetime(event["createdAt"])
+
+    common_args: DiscussionEventArgs = {
+        "id": event_id,
+        "type": event_type,
+        "created_at": created_at,
+        "author": event.get("author", {}).get("name", "deleted"),
+        "_event": event,
+    }
+
+    if event_type == "comment":
+        return DiscussionComment(
+            **common_args,
+            edited=event["data"]["edited"],
+            hidden=event["data"]["hidden"],
+            content=event["data"]["latest"]["raw"],
+        )
+    if event_type == "status-change":
+        return DiscussionStatusChange(
+            **common_args,
+            new_status=event["data"]["status"],
+        )
+    if event_type == "commit":
+        return DiscussionCommit(
+            **common_args,
+            summary=event["data"]["subject"],
+            oid=event["data"]["oid"],
+        )
+    if event_type == "title-change":
+        return DiscussionTitleChange(
+            **common_args,
+            old_title=event["data"]["from"],
+            new_title=event["data"]["to"],
+        )
+
+    return DiscussionEvent(**common_args)

venv/lib/python3.12/site-packages/huggingface_hub/constants.py

@@ -0,0 +1,279 @@
+import os
+import re
+import typing
+from typing import Literal, Optional
+
+
+# Possible values for env variables
+
+
+ENV_VARS_TRUE_VALUES = {"1", "ON", "YES", "TRUE"}
+ENV_VARS_TRUE_AND_AUTO_VALUES = ENV_VARS_TRUE_VALUES.union({"AUTO"})
+
+
+def _is_true(value: Optional[str]) -> bool:
+    if value is None:
+        return False
+    return value.upper() in ENV_VARS_TRUE_VALUES
+
+
+def _as_int(value: Optional[str]) -> Optional[int]:
+    if value is None:
+        return None
+    return int(value)
+
+
+# Constants for file downloads
+
+PYTORCH_WEIGHTS_NAME = "pytorch_model.bin"
+TF2_WEIGHTS_NAME = "tf_model.h5"
+TF_WEIGHTS_NAME = "model.ckpt"
+FLAX_WEIGHTS_NAME = "flax_model.msgpack"
+CONFIG_NAME = "config.json"
+REPOCARD_NAME = "README.md"
+DEFAULT_ETAG_TIMEOUT = 10
+DEFAULT_DOWNLOAD_TIMEOUT = 10
+DEFAULT_REQUEST_TIMEOUT = 10
+DOWNLOAD_CHUNK_SIZE = 10 * 1024 * 1024
+MAX_HTTP_DOWNLOAD_SIZE = 50 * 1000 * 1000 * 1000  # 50 GB
+
+# Constants for serialization
+
+PYTORCH_WEIGHTS_FILE_PATTERN = "pytorch_model{suffix}.bin"  # Unsafe pickle: use safetensors instead
+SAFETENSORS_WEIGHTS_FILE_PATTERN = "model{suffix}.safetensors"
+TF2_WEIGHTS_FILE_PATTERN = "tf_model{suffix}.h5"
+
+# Constants for safetensors repos
+
+SAFETENSORS_SINGLE_FILE = "model.safetensors"
+SAFETENSORS_INDEX_FILE = "model.safetensors.index.json"
+SAFETENSORS_MAX_HEADER_LENGTH = 25_000_000
+
+# Timeout of aquiring file lock and logging the attempt
+FILELOCK_LOG_EVERY_SECONDS = 10
+
+# Git-related constants
+
+DEFAULT_REVISION = "main"
+REGEX_COMMIT_OID = re.compile(r"[A-Fa-f0-9]{5,40}")
+
+HUGGINGFACE_CO_URL_HOME = "https://huggingface.co/"
+
+_staging_mode = _is_true(os.environ.get("HUGGINGFACE_CO_STAGING"))
+
+_HF_DEFAULT_ENDPOINT = "https://huggingface.co"
+_HF_DEFAULT_STAGING_ENDPOINT = "https://hub-ci.huggingface.co"
+ENDPOINT = os.getenv("HF_ENDPOINT", _HF_DEFAULT_ENDPOINT).rstrip("/")
+HUGGINGFACE_CO_URL_TEMPLATE = ENDPOINT + "/{repo_id}/resolve/{revision}/{filename}"
+
+if _staging_mode:
+    ENDPOINT = _HF_DEFAULT_STAGING_ENDPOINT
+    HUGGINGFACE_CO_URL_TEMPLATE = _HF_DEFAULT_STAGING_ENDPOINT + "/{repo_id}/resolve/{revision}/{filename}"
+
+HUGGINGFACE_HEADER_X_REPO_COMMIT = "X-Repo-Commit"
+HUGGINGFACE_HEADER_X_LINKED_ETAG = "X-Linked-Etag"
+HUGGINGFACE_HEADER_X_LINKED_SIZE = "X-Linked-Size"
+HUGGINGFACE_HEADER_X_BILL_TO = "X-HF-Bill-To"
+
+INFERENCE_ENDPOINT = os.environ.get("HF_INFERENCE_ENDPOINT", "https://api-inference.huggingface.co")
+
+# See https://huggingface.co/docs/inference-endpoints/index
+INFERENCE_ENDPOINTS_ENDPOINT = "https://api.endpoints.huggingface.cloud/v2"
+INFERENCE_CATALOG_ENDPOINT = "https://endpoints.huggingface.co/api/catalog"
+
+# See https://api.endpoints.huggingface.cloud/#post-/v2/endpoint/-namespace-
+INFERENCE_ENDPOINT_IMAGE_KEYS = [
+    "custom",
+    "huggingface",
+    "huggingfaceNeuron",
+    "llamacpp",
+    "tei",
+    "tgi",
+    "tgiNeuron",
+]
+
+# Proxy for third-party providers
+INFERENCE_PROXY_TEMPLATE = "https://router.huggingface.co/{provider}"
+
+REPO_ID_SEPARATOR = "--"
+# ^ this substring is not allowed in repo_ids on hf.co
+# and is the canonical one we use for serialization of repo ids elsewhere.
+
+
+REPO_TYPE_DATASET = "dataset"
+REPO_TYPE_SPACE = "space"
+REPO_TYPE_MODEL = "model"
+REPO_TYPES = [None, REPO_TYPE_MODEL, REPO_TYPE_DATASET, REPO_TYPE_SPACE]
+SPACES_SDK_TYPES = ["gradio", "streamlit", "docker", "static"]
+
+REPO_TYPES_URL_PREFIXES = {
+    REPO_TYPE_DATASET: "datasets/",
+    REPO_TYPE_SPACE: "spaces/",
+}
+REPO_TYPES_MAPPING = {
+    "datasets": REPO_TYPE_DATASET,
+    "spaces": REPO_TYPE_SPACE,
+    "models": REPO_TYPE_MODEL,
+}
+
+DiscussionTypeFilter = Literal["all", "discussion", "pull_request"]
+DISCUSSION_TYPES: tuple[DiscussionTypeFilter, ...] = typing.get_args(DiscussionTypeFilter)
+DiscussionStatusFilter = Literal["all", "open", "closed"]
+DISCUSSION_STATUS: tuple[DiscussionTypeFilter, ...] = typing.get_args(DiscussionStatusFilter)
+
+# Webhook subscription types
+WEBHOOK_DOMAIN_T = Literal["repo", "discussions"]
+
+# default cache
+default_home = os.path.join(os.path.expanduser("~"), ".cache")
+HF_HOME = os.path.expandvars(
+    os.path.expanduser(
+        os.getenv(
+            "HF_HOME",
+            os.path.join(os.getenv("XDG_CACHE_HOME", default_home), "huggingface"),
+        )
+    )
+)
+
+default_cache_path = os.path.join(HF_HOME, "hub")
+default_assets_cache_path = os.path.join(HF_HOME, "assets")
+
+# Legacy env variables
+HUGGINGFACE_HUB_CACHE = os.getenv("HUGGINGFACE_HUB_CACHE", default_cache_path)
+HUGGINGFACE_ASSETS_CACHE = os.getenv("HUGGINGFACE_ASSETS_CACHE", default_assets_cache_path)
+
+# New env variables
+HF_HUB_CACHE = os.path.expandvars(
+    os.path.expanduser(
+        os.getenv(
+            "HF_HUB_CACHE",
+            HUGGINGFACE_HUB_CACHE,
+        )
+    )
+)
+HF_ASSETS_CACHE = os.path.expandvars(
+    os.path.expanduser(
+        os.getenv(
+            "HF_ASSETS_CACHE",
+            HUGGINGFACE_ASSETS_CACHE,
+        )
+    )
+)
+
+HF_HUB_OFFLINE = _is_true(os.environ.get("HF_HUB_OFFLINE") or os.environ.get("TRANSFORMERS_OFFLINE"))
+
+
+def is_offline_mode() -> bool:
+    """Returns whether we are in offline mode for the Hub.
+
+    When offline mode is enabled, all HTTP requests made with `get_session` will raise an `OfflineModeIsEnabled` exception.
+
+    Example:
+        ```py
+        from huggingface_hub import is_offline_mode
+
+        def list_files(repo_id: str):
+            if is_offline_mode():
+                ... # list files from local cache (degraded experience but still functional)
+            else:
+                ... # list files from Hub (complete experience)
+        ```
+    """
+    return HF_HUB_OFFLINE
+
+
+# File created to mark that the version check has been done.
+# Check is performed once per 24 hours at most.
+CHECK_FOR_UPDATE_DONE_PATH = os.path.join(HF_HOME, ".check_for_update_done")
+
+# If set, log level will be set to DEBUG and all requests made to the Hub will be logged
+# as curl commands for reproducibility.
+HF_DEBUG = _is_true(os.environ.get("HF_DEBUG"))
+
+# Opt-out from telemetry requests
+HF_HUB_DISABLE_TELEMETRY = (
+    _is_true(os.environ.get("HF_HUB_DISABLE_TELEMETRY"))  # HF-specific env variable
+    or _is_true(os.environ.get("DISABLE_TELEMETRY"))
+    or _is_true(os.environ.get("DO_NOT_TRACK"))  # https://consoledonottrack.com/
+)
+
+HF_TOKEN_PATH = os.path.expandvars(
+    os.path.expanduser(
+        os.getenv(
+            "HF_TOKEN_PATH",
+            os.path.join(HF_HOME, "token"),
+        )
+    )
+)
+HF_STORED_TOKENS_PATH = os.path.join(os.path.dirname(HF_TOKEN_PATH), "stored_tokens")
+
+if _staging_mode:
+    # In staging mode, we use a different cache to ensure we don't mix up production and staging data or tokens
+    # In practice in `huggingface_hub` tests, we monkeypatch these values with temporary directories. The following
+    # lines are only used in third-party libraries tests (e.g. `transformers`, `diffusers`, etc.).
+    _staging_home = os.path.join(os.path.expanduser("~"), ".cache", "huggingface_staging")
+    HUGGINGFACE_HUB_CACHE = os.path.join(_staging_home, "hub")
+    HF_TOKEN_PATH = os.path.join(_staging_home, "token")
+
+# Here, `True` will disable progress bars globally without possibility of enabling it
+# programmatically. `False` will enable them without possibility of disabling them.
+# If environment variable is not set (None), then the user is free to enable/disable
+# them programmatically.
+# TL;DR: env variable has priority over code
+__HF_HUB_DISABLE_PROGRESS_BARS = os.environ.get("HF_HUB_DISABLE_PROGRESS_BARS")
+HF_HUB_DISABLE_PROGRESS_BARS: Optional[bool] = (
+    _is_true(__HF_HUB_DISABLE_PROGRESS_BARS) if __HF_HUB_DISABLE_PROGRESS_BARS is not None else None
+)
+
+# Disable warning on machines that do not support symlinks (e.g. Windows non-developer)
+HF_HUB_DISABLE_SYMLINKS_WARNING: bool = _is_true(os.environ.get("HF_HUB_DISABLE_SYMLINKS_WARNING"))
+
+# Disable warning when using experimental features
+HF_HUB_DISABLE_EXPERIMENTAL_WARNING: bool = _is_true(os.environ.get("HF_HUB_DISABLE_EXPERIMENTAL_WARNING"))
+
+# Disable sending the cached token by default is all HTTP requests to the Hub
+HF_HUB_DISABLE_IMPLICIT_TOKEN: bool = _is_true(os.environ.get("HF_HUB_DISABLE_IMPLICIT_TOKEN"))
+
+HF_XET_HIGH_PERFORMANCE: bool = _is_true(os.environ.get("HF_XET_HIGH_PERFORMANCE"))
+
+# hf_transfer is not used anymore. Let's warn user is case they set the env variable
+if _is_true(os.environ.get("HF_HUB_ENABLE_HF_TRANSFER")) and not HF_XET_HIGH_PERFORMANCE:
+    import warnings
+
+    warnings.warn(
+        "The `HF_HUB_ENABLE_HF_TRANSFER` environment variable is deprecated as 'hf_transfer' is not used anymore. "
+        "Please use `HF_XET_HIGH_PERFORMANCE` instead to enable high performance transfer with Xet. "
+        "Visit https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfxethighperformance for more details.",
+        DeprecationWarning,
+    )
+
+# Used to override the etag timeout on a system level
+HF_HUB_ETAG_TIMEOUT: int = _as_int(os.environ.get("HF_HUB_ETAG_TIMEOUT")) or DEFAULT_ETAG_TIMEOUT
+
+# Used to override the get request timeout on a system level
+HF_HUB_DOWNLOAD_TIMEOUT: int = _as_int(os.environ.get("HF_HUB_DOWNLOAD_TIMEOUT")) or DEFAULT_DOWNLOAD_TIMEOUT
+
+# Allows to add information about the requester in the user-agent (e.g. partner name)
+HF_HUB_USER_AGENT_ORIGIN: Optional[str] = os.environ.get("HF_HUB_USER_AGENT_ORIGIN")
+
+# If OAuth didn't work after 2 redirects, there's likely a third-party cookie issue in the Space iframe view.
+# In this case, we redirect the user to the non-iframe view.
+OAUTH_MAX_REDIRECTS = 2
+
+# OAuth-related environment variables injected by the Space
+OAUTH_CLIENT_ID = os.environ.get("OAUTH_CLIENT_ID")
+OAUTH_CLIENT_SECRET = os.environ.get("OAUTH_CLIENT_SECRET")
+OAUTH_SCOPES = os.environ.get("OAUTH_SCOPES")
+OPENID_PROVIDER_URL = os.environ.get("OPENID_PROVIDER_URL")
+
+# Xet constants
+HUGGINGFACE_HEADER_X_XET_ENDPOINT = "X-Xet-Cas-Url"
+HUGGINGFACE_HEADER_X_XET_ACCESS_TOKEN = "X-Xet-Access-Token"
+HUGGINGFACE_HEADER_X_XET_EXPIRATION = "X-Xet-Token-Expiration"
+HUGGINGFACE_HEADER_X_XET_HASH = "X-Xet-Hash"
+HUGGINGFACE_HEADER_X_XET_REFRESH_ROUTE = "X-Xet-Refresh-Route"
+HUGGINGFACE_HEADER_LINK_XET_AUTH_KEY = "xet-auth"
+
+default_xet_cache_path = os.path.join(HF_HOME, "xet")
+HF_XET_CACHE = os.getenv("HF_XET_CACHE", default_xet_cache_path)
+HF_HUB_DISABLE_XET: bool = _is_true(os.environ.get("HF_HUB_DISABLE_XET"))

venv/lib/python3.12/site-packages/huggingface_hub/dataclasses.py

@@ -0,0 +1,615 @@
+import inspect
+import sys
+import types
+from dataclasses import _MISSING_TYPE, MISSING, Field, field, fields, make_dataclass
+from functools import lru_cache, wraps
+from typing import (
+    Annotated,
+    Any,
+    Callable,
+    ForwardRef,
+    Literal,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    overload,
+)
+
+
+try:
+    # Python 3.11+
+    from typing import NotRequired, Required  # type: ignore
+except ImportError:
+    try:
+        # In case typing_extensions is installed
+        from typing_extensions import NotRequired, Required  # type: ignore
+    except ImportError:
+        # Fallback: create dummy types that will never match
+        Required = type("Required", (), {})  # type: ignore
+        NotRequired = type("NotRequired", (), {})  # type: ignore
+
+from .errors import (
+    StrictDataclassClassValidationError,
+    StrictDataclassDefinitionError,
+    StrictDataclassFieldValidationError,
+)
+
+
+Validator_T = Callable[[Any], None]
+T = TypeVar("T")
+TypedDictType = TypeVar("TypedDictType", bound=dict[str, Any])
+
+_TYPED_DICT_DEFAULT_VALUE = object()  # used as default value in TypedDict fields (to distinguish from None)
+
+
+# The overload decorator helps type checkers understand the different return types
+@overload
+def strict(cls: Type[T]) -> Type[T]: ...
+
+
+@overload
+def strict(*, accept_kwargs: bool = False) -> Callable[[Type[T]], Type[T]]: ...
+
+
+def strict(
+    cls: Optional[Type[T]] = None, *, accept_kwargs: bool = False
+) -> Union[Type[T], Callable[[Type[T]], Type[T]]]:
+    """
+    Decorator to add strict validation to a dataclass.
+
+    This decorator must be used on top of `@dataclass` to ensure IDEs and static typing tools
+    recognize the class as a dataclass.
+
+    Can be used with or without arguments:
+    - `@strict`
+    - `@strict(accept_kwargs=True)`
+
+    Args:
+        cls:
+            The class to convert to a strict dataclass.
+        accept_kwargs (`bool`, *optional*):
+            If True, allows arbitrary keyword arguments in `__init__`. Defaults to False.
+
+    Returns:
+        The enhanced dataclass with strict validation on field assignment.
+
+    Example:
+    ```py
+    >>> from dataclasses import dataclass
+    >>> from huggingface_hub.dataclasses import as_validated_field, strict, validated_field
+
+    >>> @as_validated_field
+    >>> def positive_int(value: int):
+    ...     if not value >= 0:
+    ...         raise ValueError(f"Value must be positive, got {value}")
+
+    >>> @strict(accept_kwargs=True)
+    ... @dataclass
+    ... class User:
+    ...     name: str
+    ...     age: int = positive_int(default=10)
+
+    # Initialize
+    >>> User(name="John")
+    User(name='John', age=10)
+
+    # Extra kwargs are accepted
+    >>> User(name="John", age=30, lastname="Doe")
+    User(name='John', age=30, *lastname='Doe')
+
+    # Invalid type => raises
+    >>> User(name="John", age="30")
+    huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
+        TypeError: Field 'age' expected int, got str (value: '30')
+
+    # Invalid value => raises
+    >>> User(name="John", age=-1)
+    huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
+        ValueError: Value must be positive, got -1
+    ```
+    """
+
+    def wrap(cls: Type[T]) -> Type[T]:
+        if not hasattr(cls, "__dataclass_fields__"):
+            raise StrictDataclassDefinitionError(
+                f"Class '{cls.__name__}' must be a dataclass before applying @strict."
+            )
+
+        # List and store validators
+        field_validators: dict[str, list[Validator_T]] = {}
+        for f in fields(cls):  # type: ignore [arg-type]
+            validators = []
+            validators.append(_create_type_validator(f))
+            custom_validator = f.metadata.get("validator")
+            if custom_validator is not None:
+                if not isinstance(custom_validator, list):
+                    custom_validator = [custom_validator]
+                for validator in custom_validator:
+                    if not _is_validator(validator):
+                        raise StrictDataclassDefinitionError(
+                            f"Invalid validator for field '{f.name}': {validator}. Must be a callable taking a single argument."
+                        )
+                validators.extend(custom_validator)
+            field_validators[f.name] = validators
+        cls.__validators__ = field_validators  # type: ignore
+
+        # Override __setattr__ to validate fields on assignment
+        original_setattr = cls.__setattr__
+
+        def __strict_setattr__(self: Any, name: str, value: Any) -> None:
+            """Custom __setattr__ method for strict dataclasses."""
+            # Run all validators
+            for validator in self.__validators__.get(name, []):
+                try:
+                    validator(value)
+                except (ValueError, TypeError) as e:
+                    raise StrictDataclassFieldValidationError(field=name, cause=e) from e
+
+            # If validation passed, set the attribute
+            original_setattr(self, name, value)
+
+        cls.__setattr__ = __strict_setattr__  # type: ignore[method-assign]
+
+        if accept_kwargs:
+            # (optional) Override __init__ to accept arbitrary keyword arguments
+            original_init = cls.__init__
+
+            @wraps(original_init)
+            def __init__(self, **kwargs: Any) -> None:
+                # Extract only the fields that are part of the dataclass
+                dataclass_fields = {f.name for f in fields(cls)}  # type: ignore [arg-type]
+                standard_kwargs = {k: v for k, v in kwargs.items() if k in dataclass_fields}
+
+                # Call the original __init__ with standard fields
+                original_init(self, **standard_kwargs)
+
+                # Add any additional kwargs as attributes
+                for name, value in kwargs.items():
+                    if name not in dataclass_fields:
+                        self.__setattr__(name, value)
+
+            cls.__init__ = __init__  # type: ignore[method-assign]
+
+            # (optional) Override __repr__ to include additional kwargs
+            original_repr = cls.__repr__
+
+            @wraps(original_repr)
+            def __repr__(self) -> str:
+                # Call the original __repr__ to get the standard fields
+                standard_repr = original_repr(self)
+
+                # Get additional kwargs
+                additional_kwargs = [
+                    # add a '*' in front of additional kwargs to let the user know they are not part of the dataclass
+                    f"*{k}={v!r}"
+                    for k, v in self.__dict__.items()
+                    if k not in cls.__dataclass_fields__  # type: ignore [attr-defined]
+                ]
+                additional_repr = ", ".join(additional_kwargs)
+
+                # Combine both representations
+                return f"{standard_repr[:-1]}, {additional_repr})" if additional_kwargs else standard_repr
+
+            cls.__repr__ = __repr__  # type: ignore [method-assign]
+
+        # List all public methods starting with `validate_` => class validators.
+        class_validators = []
+
+        for name in dir(cls):
+            if not name.startswith("validate_"):
+                continue
+            method = getattr(cls, name)
+            if not callable(method):
+                continue
+            if len(inspect.signature(method).parameters) != 1:
+                raise StrictDataclassDefinitionError(
+                    f"Class '{cls.__name__}' has a class validator '{name}' that takes more than one argument."
+                    " Class validators must take only 'self' as an argument. Methods starting with 'validate_'"
+                    " are considered to be class validators."
+                )
+            class_validators.append(method)
+
+        cls.__class_validators__ = class_validators  # type: ignore [attr-defined]
+
+        # Add `validate` method to the class, but first check if it already exists
+        def validate(self: T) -> None:
+            """Run class validators on the instance."""
+            for validator in cls.__class_validators__:  # type: ignore [attr-defined]
+                try:
+                    validator(self)
+                except (ValueError, TypeError) as e:
+                    raise StrictDataclassClassValidationError(validator=validator.__name__, cause=e) from e
+
+        # Hack to be able to raise if `.validate()` already exists except if it was created by this decorator on a parent class
+        # (in which case we just override it)
+        validate.__is_defined_by_strict_decorator__ = True  # type: ignore [attr-defined]
+
+        if hasattr(cls, "validate"):
+            if not getattr(cls.validate, "__is_defined_by_strict_decorator__", False):  # type: ignore [attr-defined]
+                raise StrictDataclassDefinitionError(
+                    f"Class '{cls.__name__}' already implements a method called 'validate'."
+                    " This method name is reserved when using the @strict decorator on a dataclass."
+                    " If you want to keep your own method, please rename it."
+                )
+
+        cls.validate = validate  # type: ignore
+
+        # Run class validators after initialization
+        initial_init = cls.__init__
+
+        @wraps(initial_init)
+        def init_with_validate(self, *args, **kwargs) -> None:
+            """Run class validators after initialization."""
+            initial_init(self, *args, **kwargs)  # type: ignore [call-arg]
+            cls.validate(self)  # type: ignore [attr-defined]
+
+        setattr(cls, "__init__", init_with_validate)
+
+        return cls
+
+    # Return wrapped class or the decorator itself
+    return wrap(cls) if cls is not None else wrap
+
+
+def validate_typed_dict(schema: type[TypedDictType], data: dict) -> None:
+    """
+    Validate that a dictionary conforms to the types defined in a TypedDict class.
+
+    Under the hood, the typed dict is converted to a strict dataclass and validated using the `@strict` decorator.
+
+    Args:
+        schema (`type[TypedDictType]`):
+            The TypedDict class defining the expected structure and types.
+        data (`dict`):
+            The dictionary to validate.
+
+    Raises:
+        `StrictDataclassFieldValidationError`:
+            If any field in the dictionary does not conform to the expected type.
+
+    Example:
+    ```py
+    >>> from typing import Annotated, TypedDict
+    >>> from huggingface_hub.dataclasses import validate_typed_dict
+
+    >>> def positive_int(value: int):
+    ...     if not value >= 0:
+    ...         raise ValueError(f"Value must be positive, got {value}")
+
+    >>> class User(TypedDict):
+    ...     name: str
+    ...     age: Annotated[int, positive_int]
+
+    >>> # Valid data
+    >>> validate_typed_dict(User, {"name": "John", "age": 30})
+
+    >>> # Invalid type for age
+    >>> validate_typed_dict(User, {"name": "John", "age": "30"})
+    huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
+        TypeError: Field 'age' expected int, got str (value: '30')
+
+    >>> # Invalid value for age
+    >>> validate_typed_dict(User, {"name": "John", "age": -1})
+    huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
+        ValueError: Value must be positive, got -1
+    ```
+    """
+    # Convert typed dict to dataclass
+    strict_cls = _build_strict_cls_from_typed_dict(schema)
+
+    # Validate the data by instantiating the strict dataclass
+    strict_cls(**data)  # will raise if validation fails
+
+
+@lru_cache
+def _build_strict_cls_from_typed_dict(schema: type[TypedDictType]) -> Type:
+    # Extract type hints from the TypedDict class
+    type_hints = _get_typed_dict_annotations(schema)
+
+    # If the TypedDict is not total, wrap fields as NotRequired (unless explicitly Required or NotRequired)
+    if not getattr(schema, "__total__", True):
+        for key, value in type_hints.items():
+            origin = get_origin(value)
+
+            if origin is Annotated:
+                base, *meta = get_args(value)
+                if not _is_required_or_notrequired(base):
+                    base = NotRequired[base]
+                type_hints[key] = Annotated[tuple([base] + list(meta))]  # type: ignore
+            elif not _is_required_or_notrequired(value):
+                type_hints[key] = NotRequired[value]
+
+    # Convert type hints to dataclass fields
+    fields = []
+    for key, value in type_hints.items():
+        if get_origin(value) is Annotated:
+            base, *meta = get_args(value)
+            fields.append((key, base, field(default=_TYPED_DICT_DEFAULT_VALUE, metadata={"validator": meta[0]})))
+        else:
+            fields.append((key, value, field(default=_TYPED_DICT_DEFAULT_VALUE)))
+
+    # Create a strict dataclass from the TypedDict fields
+    return strict(make_dataclass(schema.__name__, fields))
+
+
+def _get_typed_dict_annotations(schema: type[TypedDictType]) -> dict[str, Any]:
+    """Extract type annotations from a TypedDict class."""
+    try:
+        # Available in Python 3.14+
+        import annotationlib
+
+        return annotationlib.get_annotations(schema)
+    except ImportError:
+        return {
+            # We do not use `get_type_hints` here to avoid evaluating ForwardRefs (which might fail).
+            # ForwardRefs are not validated by @strict anyway.
+            name: value if value is not None else type(None)
+            for name, value in schema.__dict__.get("__annotations__", {}).items()
+        }
+
+
+def validated_field(
+    validator: Union[list[Validator_T], Validator_T],
+    default: Union[Any, _MISSING_TYPE] = MISSING,
+    default_factory: Union[Callable[[], Any], _MISSING_TYPE] = MISSING,
+    init: bool = True,
+    repr: bool = True,
+    hash: Optional[bool] = None,
+    compare: bool = True,
+    metadata: Optional[dict] = None,
+    **kwargs: Any,
+) -> Any:
+    """
+    Create a dataclass field with a custom validator.
+
+    Useful to apply several checks to a field. If only applying one rule, check out the [`as_validated_field`] decorator.
+
+    Args:
+        validator (`Callable` or `list[Callable]`):
+            A method that takes a value as input and raises ValueError/TypeError if the value is invalid.
+            Can be a list of validators to apply multiple checks.
+        **kwargs:
+            Additional arguments to pass to `dataclasses.field()`.
+
+    Returns:
+        A field with the validator attached in metadata
+    """
+    if not isinstance(validator, list):
+        validator = [validator]
+    if metadata is None:
+        metadata = {}
+    metadata["validator"] = validator
+    return field(  # type: ignore
+        default=default,  # type: ignore [arg-type]
+        default_factory=default_factory,  # type: ignore [arg-type]
+        init=init,
+        repr=repr,
+        hash=hash,
+        compare=compare,
+        metadata=metadata,
+        **kwargs,
+    )
+
+
+def as_validated_field(validator: Validator_T):
+    """
+    Decorates a validator function as a [`validated_field`] (i.e. a dataclass field with a custom validator).
+
+    Args:
+        validator (`Callable`):
+            A method that takes a value as input and raises ValueError/TypeError if the value is invalid.
+    """
+
+    def _inner(
+        default: Union[Any, _MISSING_TYPE] = MISSING,
+        default_factory: Union[Callable[[], Any], _MISSING_TYPE] = MISSING,
+        init: bool = True,
+        repr: bool = True,
+        hash: Optional[bool] = None,
+        compare: bool = True,
+        metadata: Optional[dict] = None,
+        **kwargs: Any,
+    ):
+        return validated_field(
+            validator,
+            default=default,
+            default_factory=default_factory,
+            init=init,
+            repr=repr,
+            hash=hash,
+            compare=compare,
+            metadata=metadata,
+            **kwargs,
+        )
+
+    return _inner
+
+
+def type_validator(name: str, value: Any, expected_type: Any) -> None:
+    """Validate that 'value' matches 'expected_type'."""
+    origin = get_origin(expected_type)
+    args = get_args(expected_type)
+
+    if expected_type is Any:
+        return
+    elif validator := _BASIC_TYPE_VALIDATORS.get(origin):
+        validator(name, value, args)
+    elif isinstance(expected_type, type):  # simple types
+        _validate_simple_type(name, value, expected_type)
+    elif isinstance(expected_type, ForwardRef) or isinstance(expected_type, str):
+        return
+    elif origin is Required:
+        if value is _TYPED_DICT_DEFAULT_VALUE:
+            raise TypeError(f"Field '{name}' is required but missing.")
+        type_validator(name, value, args[0])
+    elif origin is NotRequired:
+        if value is _TYPED_DICT_DEFAULT_VALUE:
+            return
+        type_validator(name, value, args[0])
+    else:
+        raise TypeError(f"Unsupported type for field '{name}': {expected_type}")
+
+
+def _validate_union(name: str, value: Any, args: tuple[Any, ...]) -> None:
+    """Validate that value matches one of the types in a Union."""
+    errors = []
+    for t in args:
+        try:
+            type_validator(name, value, t)
+            return  # Valid if any type matches
+        except TypeError as e:
+            errors.append(str(e))
+
+    raise TypeError(
+        f"Field '{name}' with value {repr(value)} doesn't match any type in {args}. Errors: {'; '.join(errors)}"
+    )
+
+
+def _validate_literal(name: str, value: Any, args: tuple[Any, ...]) -> None:
+    """Validate Literal type."""
+    if value not in args:
+        raise TypeError(f"Field '{name}' expected one of {args}, got {value}")
+
+
+def _validate_list(name: str, value: Any, args: tuple[Any, ...]) -> None:
+    """Validate list[T] type."""
+    if not isinstance(value, list):
+        raise TypeError(f"Field '{name}' expected a list, got {type(value).__name__}")
+
+    # Validate each item in the list
+    item_type = args[0]
+    for i, item in enumerate(value):
+        try:
+            type_validator(f"{name}[{i}]", item, item_type)
+        except TypeError as e:
+            raise TypeError(f"Invalid item at index {i} in list '{name}'") from e
+
+
+def _validate_dict(name: str, value: Any, args: tuple[Any, ...]) -> None:
+    """Validate dict[K, V] type."""
+    if not isinstance(value, dict):
+        raise TypeError(f"Field '{name}' expected a dict, got {type(value).__name__}")
+
+    # Validate keys and values
+    key_type, value_type = args
+    for k, v in value.items():
+        try:
+            type_validator(f"{name}.key", k, key_type)
+            type_validator(f"{name}[{k!r}]", v, value_type)
+        except TypeError as e:
+            raise TypeError(f"Invalid key or value in dict '{name}'") from e
+
+
+def _validate_tuple(name: str, value: Any, args: tuple[Any, ...]) -> None:
+    """Validate Tuple type."""
+    if not isinstance(value, tuple):
+        raise TypeError(f"Field '{name}' expected a tuple, got {type(value).__name__}")
+
+    # Handle variable-length tuples: tuple[T, ...]
+    if len(args) == 2 and args[1] is Ellipsis:
+        for i, item in enumerate(value):
+            try:
+                type_validator(f"{name}[{i}]", item, args[0])
+            except TypeError as e:
+                raise TypeError(f"Invalid item at index {i} in tuple '{name}'") from e
+    # Handle fixed-length tuples: tuple[T1, T2, ...]
+    elif len(args) != len(value):
+        raise TypeError(f"Field '{name}' expected a tuple of length {len(args)}, got {len(value)}")
+    else:
+        for i, (item, expected) in enumerate(zip(value, args)):
+            try:
+                type_validator(f"{name}[{i}]", item, expected)
+            except TypeError as e:
+                raise TypeError(f"Invalid item at index {i} in tuple '{name}'") from e
+
+
+def _validate_set(name: str, value: Any, args: tuple[Any, ...]) -> None:
+    """Validate set[T] type."""
+    if not isinstance(value, set):
+        raise TypeError(f"Field '{name}' expected a set, got {type(value).__name__}")
+
+    # Validate each item in the set
+    item_type = args[0]
+    for i, item in enumerate(value):
+        try:
+            type_validator(f"{name} item", item, item_type)
+        except TypeError as e:
+            raise TypeError(f"Invalid item in set '{name}'") from e
+
+
+def _validate_simple_type(name: str, value: Any, expected_type: type) -> None:
+    """Validate simple type (int, str, etc.)."""
+    if not isinstance(value, expected_type):
+        raise TypeError(
+            f"Field '{name}' expected {expected_type.__name__}, got {type(value).__name__} (value: {repr(value)})"
+        )
+
+
+def _create_type_validator(field: Field) -> Validator_T:
+    """Create a type validator function for a field."""
+    # Hacky: we cannot use a lambda here because of reference issues
+
+    def validator(value: Any) -> None:
+        type_validator(field.name, value, field.type)
+
+    return validator
+
+
+def _is_validator(validator: Any) -> bool:
+    """Check if a function is a validator.
+
+    A validator is a Callable that can be called with a single positional argument.
+    The validator can have more arguments with default values.
+
+    Basically, returns True if `validator(value)` is possible.
+    """
+    if not callable(validator):
+        return False
+
+    signature = inspect.signature(validator)
+    parameters = list(signature.parameters.values())
+    if len(parameters) == 0:
+        return False
+    if parameters[0].kind not in (
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.VAR_POSITIONAL,
+    ):
+        return False
+    for parameter in parameters[1:]:
+        if parameter.default == inspect.Parameter.empty:
+            return False
+    return True
+
+
+def _is_required_or_notrequired(type_hint: Any) -> bool:
+    """Helper to check if a type is Required/NotRequired."""
+    return type_hint in (Required, NotRequired) or (get_origin(type_hint) in (Required, NotRequired))
+
+
+_BASIC_TYPE_VALIDATORS = {
+    Union: _validate_union,
+    Literal: _validate_literal,
+    list: _validate_list,
+    dict: _validate_dict,
+    tuple: _validate_tuple,
+    set: _validate_set,
+}
+
+if sys.version_info >= (3, 10):
+    # TODO: make it first class citizen when bumping to Python 3.10+
+    _BASIC_TYPE_VALIDATORS[types.UnionType] = _validate_union  # x | y syntax, available only Python 3.10+
+
+
+__all__ = [
+    "strict",
+    "validate_typed_dict",
+    "validated_field",
+    "Validator_T",
+    "StrictDataclassClassValidationError",
+    "StrictDataclassDefinitionError",
+    "StrictDataclassFieldValidationError",
+]

venv/lib/python3.12/site-packages/huggingface_hub/errors.py

@@ -0,0 +1,404 @@
+"""Contains all custom errors."""
+
+from pathlib import Path
+from typing import Optional, Union
+
+from httpx import HTTPError, Response
+
+
+# CACHE ERRORS
+
+
+class CacheNotFound(Exception):
+    """Exception thrown when the Huggingface cache is not found."""
+
+    cache_dir: Union[str, Path]
+
+    def __init__(self, msg: str, cache_dir: Union[str, Path], *args, **kwargs):
+        super().__init__(msg, *args, **kwargs)
+        self.cache_dir = cache_dir
+
+
+class CorruptedCacheException(Exception):
+    """Exception for any unexpected structure in the Huggingface cache-system."""
+
+
+# HEADERS ERRORS
+
+
+class LocalTokenNotFoundError(EnvironmentError):
+    """Raised if local token is required but not found."""
+
+
+# HTTP ERRORS
+
+
+class OfflineModeIsEnabled(ConnectionError):
+    """Raised when a request is made but `HF_HUB_OFFLINE=1` is set as environment variable."""
+
+
+class HfHubHTTPError(HTTPError, OSError):
+    """
+    HTTPError to inherit from for any custom HTTP Error raised in HF Hub.
+
+    Any HTTPError is converted at least into a `HfHubHTTPError`. If some information is
+    sent back by the server, it will be added to the error message.
+
+    Added details:
+    - Request id from "X-Request-Id" header if exists. If not, fallback to "X-Amzn-Trace-Id" header if exists.
+    - Server error message from the header "X-Error-Message".
+    - Server error message if we can found one in the response body.
+
+    Example:
+    ```py
+        import httpx
+        from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError
+
+        response = get_session().post(...)
+        try:
+            hf_raise_for_status(response)
+        except HfHubHTTPError as e:
+            print(str(e)) # formatted message
+            e.request_id, e.server_message # details returned by server
+
+            # Complete the error message with additional information once it's raised
+            e.append_to_message("\n`create_commit` expects the repository to exist.")
+            raise
+    ```
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        response: Response,
+        server_message: Optional[str] = None,
+    ):
+        self.request_id = response.headers.get("x-request-id") or response.headers.get("X-Amzn-Trace-Id")
+        self.server_message = server_message
+        self.response = response
+        self.request = response.request
+        super().__init__(message)
+
+    def append_to_message(self, additional_message: str) -> None:
+        """Append additional information to the `HfHubHTTPError` initial message."""
+        self.args = (self.args[0] + additional_message,) + self.args[1:]
+
+    @classmethod
+    def _reconstruct_hf_hub_http_error(
+        cls, message: str, response: Response, server_message: Optional[str]
+    ) -> "HfHubHTTPError":
+        return cls(message, response=response, server_message=server_message)
+
+    def __reduce_ex__(self, protocol):
+        """Fix pickling of Exception subclass with kwargs. We need to override __reduce_ex__ of the parent class"""
+        return (self.__class__._reconstruct_hf_hub_http_error, (str(self), self.response, self.server_message))
+
+
+# INFERENCE CLIENT ERRORS
+
+
+class InferenceTimeoutError(HTTPError, TimeoutError):
+    """Error raised when a model is unavailable or the request times out."""
+
+
+# INFERENCE ENDPOINT ERRORS
+
+
+class InferenceEndpointError(Exception):
+    """Generic exception when dealing with Inference Endpoints."""
+
+
+class InferenceEndpointTimeoutError(InferenceEndpointError, TimeoutError):
+    """Exception for timeouts while waiting for Inference Endpoint."""
+
+
+# SAFETENSORS ERRORS
+
+
+class SafetensorsParsingError(Exception):
+    """Raised when failing to parse a safetensors file metadata.
+
+    This can be the case if the file is not a safetensors file or does not respect the specification.
+    """
+
+
+class NotASafetensorsRepoError(Exception):
+    """Raised when a repo is not a Safetensors repo i.e. doesn't have either a `model.safetensors` or a
+    `model.safetensors.index.json` file.
+    """
+
+
+# TEXT GENERATION ERRORS
+
+
+class TextGenerationError(HTTPError):
+    """Generic error raised if text-generation went wrong."""
+
+
+# Text Generation Inference Errors
+class ValidationError(TextGenerationError):
+    """Server-side validation error."""
+
+
+class GenerationError(TextGenerationError):
+    pass
+
+
+class OverloadedError(TextGenerationError):
+    pass
+
+
+class IncompleteGenerationError(TextGenerationError):
+    pass
+
+
+class UnknownError(TextGenerationError):
+    pass
+
+
+# VALIDATION ERRORS
+
+
+class HFValidationError(ValueError):
+    """Generic exception thrown by `huggingface_hub` validators.
+
+    Inherits from [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError).
+    """
+
+
+# FILE METADATA ERRORS
+
+
+class DryRunError(OSError):
+    """Error triggered when a dry run is requested but cannot be performed (e.g. invalid repo)."""
+
+
+class FileMetadataError(OSError):
+    """Error triggered when the metadata of a file on the Hub cannot be retrieved (missing ETag or commit_hash).
+
+    Inherits from `OSError` for backward compatibility.
+    """
+
+
+# REPOSITORY ERRORS
+
+
+class RepositoryNotFoundError(HfHubHTTPError):
+    """
+    Raised when trying to access a hf.co URL with an invalid repository name, or
+    with a private repo name the user does not have access to.
+
+    Example:
+
+    ```py
+    >>> from huggingface_hub import model_info
+    >>> model_info("<non_existent_repository>")
+    (...)
+    huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)
+
+    Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
+    Please make sure you specified the correct `repo_id` and `repo_type`.
+    If the repo is private, make sure you are authenticated.
+    Invalid username or password.
+    ```
+    """
+
+
+class GatedRepoError(RepositoryNotFoundError):
+    """
+    Raised when trying to access a gated repository for which the user is not on the
+    authorized list.
+
+    Note: derives from `RepositoryNotFoundError` to ensure backward compatibility.
+
+    Example:
+
+    ```py
+    >>> from huggingface_hub import model_info
+    >>> model_info("<gated_repository>")
+    (...)
+    huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)
+
+    Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
+    Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
+    Visit https://huggingface.co/ardent-figment/gated-model to ask for access.
+    ```
+    """
+
+
+class DisabledRepoError(HfHubHTTPError):
+    """
+    Raised when trying to access a repository that has been disabled by its author.
+
+    Example:
+
+    ```py
+    >>> from huggingface_hub import dataset_info
+    >>> dataset_info("laion/laion-art")
+    (...)
+    huggingface_hub.errors.DisabledRepoError: 403 Client Error. (Request ID: Root=1-659fc3fa-3031673e0f92c71a2260dbe2;bc6f4dfb-b30a-4862-af0a-5cfe827610d8)
+
+    Cannot access repository for url https://huggingface.co/api/datasets/laion/laion-art.
+    Access to this resource is disabled.
+    ```
+    """
+
+
+# REVISION ERROR
+
+
+class RevisionNotFoundError(HfHubHTTPError):
+    """
+    Raised when trying to access a hf.co URL with a valid repository but an invalid
+    revision.
+
+    Example:
+
+    ```py
+    >>> from huggingface_hub import hf_hub_download
+    >>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
+    (...)
+    huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)
+
+    Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.
+    ```
+    """
+
+
+# ENTRY ERRORS
+class EntryNotFoundError(Exception):
+    """
+    Raised when entry not found, either locally or remotely.
+
+    Example:
+
+    ```py
+    >>> from huggingface_hub import hf_hub_download
+    >>> hf_hub_download('bert-base-cased', '<non-existent-file>')
+    (...)
+    huggingface_hub.errors.RemoteEntryNotFoundError (...)
+    >>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
+    (...)
+    huggingface_hub.utils.errors.LocalEntryNotFoundError (...)
+    ```
+    """
+
+
+class RemoteEntryNotFoundError(HfHubHTTPError, EntryNotFoundError):
+    """
+    Raised when trying to access a hf.co URL with a valid repository and revision
+    but an invalid filename.
+
+    Example:
+
+    ```py
+    >>> from huggingface_hub import hf_hub_download
+    >>> hf_hub_download('bert-base-cased', '<non-existent-file>')
+    (...)
+    huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)
+
+    Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.
+    ```
+    """
+
+
+class LocalEntryNotFoundError(FileNotFoundError, EntryNotFoundError):
+    """
+    Raised when trying to access a file or snapshot that is not on the disk when network is
+    disabled or unavailable (connection issue). The entry may exist on the Hub.
+
+    Example:
+
+    ```py
+    >>> from huggingface_hub import hf_hub_download
+    >>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
+    (...)
+    huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.
+    ```
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+# REQUEST ERROR
+class BadRequestError(HfHubHTTPError, ValueError):
+    """
+    Raised by `hf_raise_for_status` when the server returns a HTTP 400 error.
+
+    Example:
+
+    ```py
+    >>> resp = httpx.post("hf.co/api/check", ...)
+    >>> hf_raise_for_status(resp, endpoint_name="check")
+    huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)
+    ```
+    """
+
+
+# DDUF file format ERROR
+
+
+class DDUFError(Exception):
+    """Base exception for errors related to the DDUF format."""
+
+
+class DDUFCorruptedFileError(DDUFError):
+    """Exception thrown when the DDUF file is corrupted."""
+
+
+class DDUFExportError(DDUFError):
+    """Base exception for errors during DDUF export."""
+
+
+class DDUFInvalidEntryNameError(DDUFExportError):
+    """Exception thrown when the entry name is invalid."""
+
+
+# STRICT DATACLASSES ERRORS
+
+
+class StrictDataclassError(Exception):
+    """Base exception for strict dataclasses."""
+
+
+class StrictDataclassDefinitionError(StrictDataclassError):
+    """Exception thrown when a strict dataclass is defined incorrectly."""
+
+
+class StrictDataclassFieldValidationError(StrictDataclassError):
+    """Exception thrown when a strict dataclass fails validation for a given field."""
+
+    def __init__(self, field: str, cause: Exception):
+        error_message = f"Validation error for field '{field}':"
+        error_message += f"\n    {cause.__class__.__name__}: {cause}"
+        super().__init__(error_message)
+
+
+class StrictDataclassClassValidationError(StrictDataclassError):
+    """Exception thrown when a strict dataclass fails validation on a class validator."""
+
+    def __init__(self, validator: str, cause: Exception):
+        error_message = f"Class validation error for validator '{validator}':"
+        error_message += f"\n    {cause.__class__.__name__}: {cause}"
+        super().__init__(error_message)
+
+
+# XET ERRORS
+
+
+class XetError(Exception):
+    """Base exception for errors related to Xet Storage."""
+
+
+class XetAuthorizationError(XetError):
+    """Exception thrown when the user does not have the right authorization to use Xet Storage."""
+
+
+class XetRefreshTokenError(XetError):
+    """Exception thrown when the refresh token is invalid."""
+
+
+class XetDownloadError(Exception):
+    """Exception thrown when the download from Xet Storage fails."""

venv/lib/python3.12/site-packages/huggingface_hub/fastai_utils.py

@@ -0,0 +1,414 @@
+import json
+import os
+from pathlib import Path
+from pickle import DEFAULT_PROTOCOL, PicklingError
+from typing import Any, Optional, Union
+
+from packaging import version
+
+from huggingface_hub import constants, snapshot_download
+from huggingface_hub.hf_api import HfApi
+from huggingface_hub.utils import (
+    SoftTemporaryDirectory,
+    get_fastai_version,
+    get_fastcore_version,
+    get_python_version,
+)
+
+from .utils import logging, validate_hf_hub_args
+
+
+logger = logging.get_logger(__name__)
+
+
+def _check_fastai_fastcore_versions(
+    fastai_min_version: str = "2.4",
+    fastcore_min_version: str = "1.3.27",
+):
+    """
+    Checks that the installed fastai and fastcore versions are compatible for pickle serialization.
+
+    Args:
+        fastai_min_version (`str`, *optional*):
+            The minimum fastai version supported.
+        fastcore_min_version (`str`, *optional*):
+            The minimum fastcore version supported.
+
+    > [!TIP]
+    > Raises the following error:
+    >
+    >     - [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError)
+    >       if the fastai or fastcore libraries are not available or are of an invalid version.
+    """
+
+    if (get_fastcore_version() or get_fastai_version()) == "N/A":
+        raise ImportError(
+            f"fastai>={fastai_min_version} and fastcore>={fastcore_min_version} are"
+            f" required. Currently using fastai=={get_fastai_version()} and"
+            f" fastcore=={get_fastcore_version()}."
+        )
+
+    current_fastai_version = version.Version(get_fastai_version())
+    current_fastcore_version = version.Version(get_fastcore_version())
+
+    if current_fastai_version < version.Version(fastai_min_version):
+        raise ImportError(
+            "`push_to_hub_fastai` and `from_pretrained_fastai` require a"
+            f" fastai>={fastai_min_version} version, but you are using fastai version"
+            f" {get_fastai_version()} which is incompatible. Upgrade with `pip install"
+            " fastai==2.5.6`."
+        )
+
+    if current_fastcore_version < version.Version(fastcore_min_version):
+        raise ImportError(
+            "`push_to_hub_fastai` and `from_pretrained_fastai` require a"
+            f" fastcore>={fastcore_min_version} version, but you are using fastcore"
+            f" version {get_fastcore_version()} which is incompatible. Upgrade with"
+            " `pip install fastcore==1.3.27`."
+        )
+
+
+def _check_fastai_fastcore_pyproject_versions(
+    storage_folder: str,
+    fastai_min_version: str = "2.4",
+    fastcore_min_version: str = "1.3.27",
+):
+    """
+    Checks that the `pyproject.toml` file in the directory `storage_folder` has fastai and fastcore versions
+    that are compatible with `from_pretrained_fastai` and `push_to_hub_fastai`. If `pyproject.toml` does not exist
+    or does not contain versions for fastai and fastcore, then it logs a warning.
+
+    Args:
+        storage_folder (`str`):
+            Folder to look for the `pyproject.toml` file.
+        fastai_min_version (`str`, *optional*):
+            The minimum fastai version supported.
+        fastcore_min_version (`str`, *optional*):
+            The minimum fastcore version supported.
+
+    > [!TIP]
+    > Raises the following errors:
+    >
+    >     - [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError)
+    >       if the `toml` module is not installed.
+    >     - [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError)
+    >       if the `pyproject.toml` indicates a lower than minimum supported version of fastai or fastcore.
+    """
+
+    try:
+        import toml
+    except ModuleNotFoundError:
+        raise ImportError(
+            "`push_to_hub_fastai` and `from_pretrained_fastai` require the toml module."
+            " Install it with `pip install toml`."
+        )
+
+    # Checks that a `pyproject.toml`, with `build-system` and `requires` sections, exists in the repository. If so, get a list of required packages.
+    if not os.path.isfile(f"{storage_folder}/pyproject.toml"):
+        logger.warning(
+            "There is no `pyproject.toml` in the repository that contains the fastai"
+            " `Learner`. The `pyproject.toml` would allow us to verify that your fastai"
+            " and fastcore versions are compatible with those of the model you want to"
+            " load."
+        )
+        return
+    pyproject_toml = toml.load(f"{storage_folder}/pyproject.toml")
+
+    if "build-system" not in pyproject_toml.keys():
+        logger.warning(
+            "There is no `build-system` section in the pyproject.toml of the repository"
+            " that contains the fastai `Learner`. The `build-system` would allow us to"
+            " verify that your fastai and fastcore versions are compatible with those"
+            " of the model you want to load."
+        )
+        return
+    build_system_toml = pyproject_toml["build-system"]
+
+    if "requires" not in build_system_toml.keys():
+        logger.warning(
+            "There is no `requires` section in the pyproject.toml of the repository"
+            " that contains the fastai `Learner`. The `requires` would allow us to"
+            " verify that your fastai and fastcore versions are compatible with those"
+            " of the model you want to load."
+        )
+        return
+    package_versions = build_system_toml["requires"]
+
+    # Extracts contains fastai and fastcore versions from `pyproject.toml` if available.
+    # If the package is specified but not the version (e.g. "fastai" instead of "fastai=2.4"), the default versions are the highest.
+    fastai_packages = [pck for pck in package_versions if pck.startswith("fastai")]
+    if len(fastai_packages) == 0:
+        logger.warning("The repository does not have a fastai version specified in the `pyproject.toml`.")
+    # fastai_version is an empty string if not specified
+    else:
+        fastai_version = str(fastai_packages[0]).partition("=")[2]
+        if fastai_version != "" and version.Version(fastai_version) < version.Version(fastai_min_version):
+            raise ImportError(
+                "`from_pretrained_fastai` requires"
+                f" fastai>={fastai_min_version} version but the model to load uses"
+                f" {fastai_version} which is incompatible."
+            )
+
+    fastcore_packages = [pck for pck in package_versions if pck.startswith("fastcore")]
+    if len(fastcore_packages) == 0:
+        logger.warning("The repository does not have a fastcore version specified in the `pyproject.toml`.")
+    # fastcore_version is an empty string if not specified
+    else:
+        fastcore_version = str(fastcore_packages[0]).partition("=")[2]
+        if fastcore_version != "" and version.Version(fastcore_version) < version.Version(fastcore_min_version):
+            raise ImportError(
+                "`from_pretrained_fastai` requires"
+                f" fastcore>={fastcore_min_version} version, but you are using fastcore"
+                f" version {fastcore_version} which is incompatible."
+            )
+
+
+README_TEMPLATE = """---
+tags:
+- fastai
+---
+
+# Amazing!
+
+🥳 Congratulations on hosting your fastai model on the Hugging Face Hub!
+
+# Some next steps
+1. Fill out this model card with more information (see the template below and the [documentation here](https://huggingface.co/docs/hub/model-repos))!
+
+2. Create a demo in Gradio or Streamlit using 🤗 Spaces ([documentation here](https://huggingface.co/docs/hub/spaces)).
+
+3. Join the fastai community on the [Fastai Discord](https://discord.com/invite/YKrxeNn)!
+
+Greetings fellow fastlearner 🤝! Don't forget to delete this content from your model card.
+
+
+---
+
+
+# Model card
+
+## Model description
+More information needed
+
+## Intended uses & limitations
+More information needed
+
+## Training and evaluation data
+More information needed
+"""
+
+PYPROJECT_TEMPLATE = f"""[build-system]
+requires = ["setuptools>=40.8.0", "wheel", "python={get_python_version()}", "fastai={get_fastai_version()}", "fastcore={get_fastcore_version()}"]
+build-backend = "setuptools.build_meta:__legacy__"
+"""
+
+
+def _create_model_card(repo_dir: Path):
+    """
+    Creates a model card for the repository.
+
+    Args:
+        repo_dir (`Path`):
+            Directory where model card is created.
+    """
+    readme_path = repo_dir / "README.md"
+
+    if not readme_path.exists():
+        with readme_path.open("w", encoding="utf-8") as f:
+            f.write(README_TEMPLATE)
+
+
+def _create_model_pyproject(repo_dir: Path):
+    """
+    Creates a `pyproject.toml` for the repository.
+
+    Args:
+        repo_dir (`Path`):
+            Directory where `pyproject.toml` is created.
+    """
+    pyproject_path = repo_dir / "pyproject.toml"
+
+    if not pyproject_path.exists():
+        with pyproject_path.open("w", encoding="utf-8") as f:
+            f.write(PYPROJECT_TEMPLATE)
+
+
+def _save_pretrained_fastai(
+    learner,
+    save_directory: Union[str, Path],
+    config: Optional[dict[str, Any]] = None,
+):
+    """
+    Saves a fastai learner to `save_directory` in pickle format using the default pickle protocol for the version of python used.
+
+    Args:
+        learner (`Learner`):
+            The `fastai.Learner` you'd like to save.
+        save_directory (`str` or `Path`):
+            Specific directory in which you want to save the fastai learner.
+        config (`dict`, *optional*):
+            Configuration object. Will be uploaded as a .json file. Example: 'https://huggingface.co/espejelomar/fastai-pet-breeds-classification/blob/main/config.json'.
+
+    > [!TIP]
+    > Raises the following error:
+    >
+    >     - [`RuntimeError`](https://docs.python.org/3/library/exceptions.html#RuntimeError)
+    >       if the config file provided is not a dictionary.
+    """
+    _check_fastai_fastcore_versions()
+
+    os.makedirs(save_directory, exist_ok=True)
+
+    # if the user provides config then we update it with the fastai and fastcore versions in CONFIG_TEMPLATE.
+    if config is not None:
+        if not isinstance(config, dict):
+            raise RuntimeError(f"Provided config should be a dict. Got: '{type(config)}'")
+        path = os.path.join(save_directory, constants.CONFIG_NAME)
+        with open(path, "w") as f:
+            json.dump(config, f)
+
+    _create_model_card(Path(save_directory))
+    _create_model_pyproject(Path(save_directory))
+
+    # learner.export saves the model in `self.path`.
+    learner.path = Path(save_directory)
+    os.makedirs(save_directory, exist_ok=True)
+    try:
+        learner.export(
+            fname="model.pkl",
+            pickle_protocol=DEFAULT_PROTOCOL,
+        )
+    except PicklingError:
+        raise PicklingError(
+            "You are using a lambda function, i.e., an anonymous function. `pickle`"
+            " cannot pickle function objects and requires that all functions have"
+            " names. One possible solution is to name the function."
+        )
+
+
+@validate_hf_hub_args
+def from_pretrained_fastai(
+    repo_id: str,
+    revision: Optional[str] = None,
+):
+    """
+    Load pretrained fastai model from the Hub or from a local directory.
+
+    Args:
+        repo_id (`str`):
+            The location where the pickled fastai.Learner is. It can be either of the two:
+                - Hosted on the Hugging Face Hub. E.g.: 'espejelomar/fatai-pet-breeds-classification' or 'distilgpt2'.
+                  You can add a `revision` by appending `@` at the end of `repo_id`. E.g.: `dbmdz/bert-base-german-cased@main`.
+                  Revision is the specific model version to use. Since we use a git-based system for storing models and other
+                  artifacts on the Hugging Face Hub, it can be a branch name, a tag name, or a commit id.
+                - Hosted locally. `repo_id` would be a directory containing the pickle and a pyproject.toml
+                  indicating the fastai and fastcore versions used to build the `fastai.Learner`. E.g.: `./my_model_directory/`.
+        revision (`str`, *optional*):
+            Revision at which the repo's files are downloaded. See documentation of `snapshot_download`.
+
+    Returns:
+        The `fastai.Learner` model in the `repo_id` repo.
+    """
+    _check_fastai_fastcore_versions()
+
+    # Load the `repo_id` repo.
+    # `snapshot_download` returns the folder where the model was stored.
+    # `cache_dir` will be the default '/root/.cache/huggingface/hub'
+    if not os.path.isdir(repo_id):
+        storage_folder = snapshot_download(
+            repo_id=repo_id,
+            revision=revision,
+            library_name="fastai",
+            library_version=get_fastai_version(),
+        )
+    else:
+        storage_folder = repo_id
+
+    _check_fastai_fastcore_pyproject_versions(storage_folder)
+
+    from fastai.learner import load_learner  # type: ignore
+
+    return load_learner(os.path.join(storage_folder, "model.pkl"))
+
+
+@validate_hf_hub_args
+def push_to_hub_fastai(
+    learner,
+    *,
+    repo_id: str,
+    commit_message: str = "Push FastAI model using huggingface_hub.",
+    private: Optional[bool] = None,
+    token: Optional[str] = None,
+    config: Optional[dict] = None,
+    branch: Optional[str] = None,
+    create_pr: Optional[bool] = None,
+    allow_patterns: Optional[Union[list[str], str]] = None,
+    ignore_patterns: Optional[Union[list[str], str]] = None,
+    delete_patterns: Optional[Union[list[str], str]] = None,
+    api_endpoint: Optional[str] = None,
+):
+    """
+    Upload learner checkpoint files to the Hub.
+
+    Use `allow_patterns` and `ignore_patterns` to precisely filter which files should be pushed to the hub. Use
+    `delete_patterns` to delete existing remote files in the same commit. See [`upload_folder`] reference for more
+    details.
+
+    Args:
+        learner (`Learner`):
+            The `fastai.Learner' you'd like to push to the Hub.
+        repo_id (`str`):
+            The repository id for your model in Hub in the format of "namespace/repo_name". The namespace can be your individual account or an organization to which you have write access (for example, 'stanfordnlp/stanza-de').
+        commit_message (`str`, *optional*):
+            Message to commit while pushing. Will default to :obj:`"add model"`.
+        private (`bool`, *optional*):
+            Whether or not the repository created should be private.
+            If `None` (default), will default to been public except if the organization's default is private.
+        token (`str`, *optional*):
+            The Hugging Face account token to use as HTTP bearer authorization for remote files. If :obj:`None`, the token will be asked by a prompt.
+        config (`dict`, *optional*):
+            Configuration object to be saved alongside the model weights.
+        branch (`str`, *optional*):
+            The git branch on which to push the model. This defaults to
+            the default branch as specified in your repository, which
+            defaults to `"main"`.
+        create_pr (`boolean`, *optional*):
+            Whether or not to create a Pull Request from `branch` with that commit.
+            Defaults to `False`.
+        api_endpoint (`str`, *optional*):
+            The API endpoint to use when pushing the model to the hub.
+        allow_patterns (`list[str]` or `str`, *optional*):
+            If provided, only files matching at least one pattern are pushed.
+        ignore_patterns (`list[str]` or `str`, *optional*):
+            If provided, files matching any of the patterns are not pushed.
+        delete_patterns (`list[str]` or `str`, *optional*):
+            If provided, remote files matching any of the patterns will be deleted from the repo.
+
+    Returns:
+        The url of the commit of your model in the given repository.
+
+    > [!TIP]
+    > Raises the following error:
+    >
+    >     - [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+    >       if the user is not log on to the Hugging Face Hub.
+    """
+    _check_fastai_fastcore_versions()
+    api = HfApi(endpoint=api_endpoint)
+    repo_id = api.create_repo(repo_id=repo_id, token=token, private=private, exist_ok=True).repo_id
+
+    # Push the files to the repo in a single commit
+    with SoftTemporaryDirectory() as tmp:
+        saved_path = Path(tmp) / repo_id
+        _save_pretrained_fastai(learner, saved_path, config=config)
+        return api.upload_folder(
+            repo_id=repo_id,
+            token=token,
+            folder_path=saved_path,
+            commit_message=commit_message,
+            revision=branch,
+            create_pr=create_pr,
+            allow_patterns=allow_patterns,
+            ignore_patterns=ignore_patterns,
+            delete_patterns=delete_patterns,
+        )

venv/lib/python3.12/site-packages/huggingface_hub/hub_mixin.py

@@ -0,0 +1,831 @@
+import inspect
+import json
+import os
+from dataclasses import Field, asdict, dataclass, is_dataclass
+from pathlib import Path
+from typing import Any, Callable, ClassVar, Optional, Protocol, Type, TypeVar, Union
+
+import packaging.version
+
+from . import constants
+from .errors import EntryNotFoundError, HfHubHTTPError
+from .file_download import hf_hub_download
+from .hf_api import HfApi
+from .repocard import ModelCard, ModelCardData
+from .utils import (
+    SoftTemporaryDirectory,
+    is_jsonable,
+    is_safetensors_available,
+    is_simple_optional_type,
+    is_torch_available,
+    logging,
+    unwrap_simple_optional_type,
+    validate_hf_hub_args,
+)
+
+
+if is_torch_available():
+    import torch  # type: ignore
+
+if is_safetensors_available():
+    import safetensors
+    from safetensors.torch import load_model as load_model_as_safetensor
+    from safetensors.torch import save_model as save_model_as_safetensor
+
+
+logger = logging.get_logger(__name__)
+
+
+# Type alias for dataclass instances, copied from https://github.com/python/typeshed/blob/9f28171658b9ca6c32a7cb93fbb99fc92b17858b/stdlib/_typeshed/__init__.pyi#L349
+class DataclassInstance(Protocol):
+    __dataclass_fields__: ClassVar[dict[str, Field]]
+
+
+# Generic variable that is either ModelHubMixin or a subclass thereof
+T = TypeVar("T", bound="ModelHubMixin")
+# Generic variable to represent an args type
+ARGS_T = TypeVar("ARGS_T")
+ENCODER_T = Callable[[ARGS_T], Any]
+DECODER_T = Callable[[Any], ARGS_T]
+CODER_T = tuple[ENCODER_T, DECODER_T]
+
+
+DEFAULT_MODEL_CARD = """
+---
+# For reference on model card metadata, see the spec: https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1
+# Doc / guide: https://huggingface.co/docs/hub/model-cards
+{{ card_data }}
+---
+
+This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration:
+- Code: {{ repo_url | default("[More Information Needed]", true) }}
+- Paper: {{ paper_url | default("[More Information Needed]", true) }}
+- Docs: {{ docs_url | default("[More Information Needed]", true) }}
+"""
+
+
+@dataclass
+class MixinInfo:
+    model_card_template: str
+    model_card_data: ModelCardData
+    docs_url: Optional[str] = None
+    paper_url: Optional[str] = None
+    repo_url: Optional[str] = None
+
+
+class ModelHubMixin:
+    """
+    A generic mixin to integrate ANY machine learning framework with the Hub.
+
+    To integrate your framework, your model class must inherit from this class. Custom logic for saving/loading models
+    have to be overwritten in  [`_from_pretrained`] and [`_save_pretrained`]. [`PyTorchModelHubMixin`] is a good example
+    of mixin integration with the Hub. Check out our [integration guide](../guides/integrations) for more instructions.
+
+    When inheriting from [`ModelHubMixin`], you can define class-level attributes. These attributes are not passed to
+    `__init__` but to the class definition itself. This is useful to define metadata about the library integrating
+    [`ModelHubMixin`].
+
+    For more details on how to integrate the mixin with your library, checkout the [integration guide](../guides/integrations).
+
+    Args:
+        repo_url (`str`, *optional*):
+            URL of the library repository. Used to generate model card.
+        paper_url (`str`, *optional*):
+            URL of the library paper. Used to generate model card.
+        docs_url (`str`, *optional*):
+            URL of the library documentation. Used to generate model card.
+        model_card_template (`str`, *optional*):
+            Template of the model card. Used to generate model card. Defaults to a generic template.
+        language (`str` or `list[str]`, *optional*):
+            Language supported by the library. Used to generate model card.
+        library_name (`str`, *optional*):
+            Name of the library integrating ModelHubMixin. Used to generate model card.
+        license (`str`, *optional*):
+            License of the library integrating ModelHubMixin. Used to generate model card.
+            E.g: "apache-2.0"
+        license_name (`str`, *optional*):
+            Name of the library integrating ModelHubMixin. Used to generate model card.
+            Only used if `license` is set to `other`.
+            E.g: "coqui-public-model-license".
+        license_link (`str`, *optional*):
+            URL to the license of the library integrating ModelHubMixin. Used to generate model card.
+            Only used if `license` is set to `other` and `license_name` is set.
+            E.g: "https://coqui.ai/cpml".
+        pipeline_tag (`str`, *optional*):
+            Tag of the pipeline. Used to generate model card. E.g. "text-classification".
+        tags (`list[str]`, *optional*):
+            Tags to be added to the model card. Used to generate model card. E.g. ["computer-vision"]
+        coders (`dict[Type, tuple[Callable, Callable]]`, *optional*):
+            Dictionary of custom types and their encoders/decoders. Used to encode/decode arguments that are not
+            jsonable by default. E.g. dataclasses, argparse.Namespace, OmegaConf, etc.
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub import ModelHubMixin
+
+    # Inherit from ModelHubMixin
+    >>> class MyCustomModel(
+    ...         ModelHubMixin,
+    ...         library_name="my-library",
+    ...         tags=["computer-vision"],
+    ...         repo_url="https://github.com/huggingface/my-cool-library",
+    ...         paper_url="https://arxiv.org/abs/2304.12244",
+    ...         docs_url="https://huggingface.co/docs/my-cool-library",
+    ...         # ^ optional metadata to generate model card
+    ...     ):
+    ...     def __init__(self, size: int = 512, device: str = "cpu"):
+    ...         # define how to initialize your model
+    ...         super().__init__()
+    ...         ...
+    ...
+    ...     def _save_pretrained(self, save_directory: Path) -> None:
+    ...         # define how to serialize your model
+    ...         ...
+    ...
+    ...     @classmethod
+    ...     def from_pretrained(
+    ...         cls: type[T],
+    ...         pretrained_model_name_or_path: Union[str, Path],
+    ...         *,
+    ...         force_download: bool = False,
+    ...         token: Optional[Union[str, bool]] = None,
+    ...         cache_dir: Optional[Union[str, Path]] = None,
+    ...         local_files_only: bool = False,
+    ...         revision: Optional[str] = None,
+    ...         **model_kwargs,
+    ...     ) -> T:
+    ...         # define how to deserialize your model
+    ...         ...
+
+    >>> model = MyCustomModel(size=256, device="gpu")
+
+    # Save model weights to local directory
+    >>> model.save_pretrained("my-awesome-model")
+
+    # Push model weights to the Hub
+    >>> model.push_to_hub("my-awesome-model")
+
+    # Download and initialize weights from the Hub
+    >>> reloaded_model = MyCustomModel.from_pretrained("username/my-awesome-model")
+    >>> reloaded_model.size
+    256
+
+    # Model card has been correctly populated
+    >>> from huggingface_hub import ModelCard
+    >>> card = ModelCard.load("username/my-awesome-model")
+    >>> card.data.tags
+    ["x-custom-tag", "pytorch_model_hub_mixin", "model_hub_mixin"]
+    >>> card.data.library_name
+    "my-library"
+    ```
+    """
+
+    _hub_mixin_config: Optional[Union[dict, DataclassInstance]] = None
+    # ^ optional config attribute automatically set in `from_pretrained`
+    _hub_mixin_info: MixinInfo
+    # ^ information about the library integrating ModelHubMixin (used to generate model card)
+    _hub_mixin_inject_config: bool  # whether `_from_pretrained` expects `config` or not
+    _hub_mixin_init_parameters: dict[str, inspect.Parameter]  # __init__ parameters
+    _hub_mixin_jsonable_default_values: dict[str, Any]  # default values for __init__ parameters
+    _hub_mixin_jsonable_custom_types: tuple[Type, ...]  # custom types that can be encoded/decoded
+    _hub_mixin_coders: dict[Type, CODER_T]  # encoders/decoders for custom types
+    # ^ internal values to handle config
+
+    def __init_subclass__(
+        cls,
+        *,
+        # Generic info for model card
+        repo_url: Optional[str] = None,
+        paper_url: Optional[str] = None,
+        docs_url: Optional[str] = None,
+        # Model card template
+        model_card_template: str = DEFAULT_MODEL_CARD,
+        # Model card metadata
+        language: Optional[list[str]] = None,
+        library_name: Optional[str] = None,
+        license: Optional[str] = None,
+        license_name: Optional[str] = None,
+        license_link: Optional[str] = None,
+        pipeline_tag: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        # How to encode/decode arguments with custom type into a JSON config?
+        coders: Optional[
+            dict[Type, CODER_T]
+            # Key is a type.
+            # Value is a tuple (encoder, decoder).
+            # Example: {MyCustomType: (lambda x: x.value, lambda data: MyCustomType(data))}
+        ] = None,
+    ) -> None:
+        """Inspect __init__ signature only once when subclassing + handle modelcard."""
+        super().__init_subclass__()
+
+        # Will be reused when creating modelcard
+        tags = tags or []
+        tags.append("model_hub_mixin")
+
+        # Initialize MixinInfo if not existent
+        info = MixinInfo(model_card_template=model_card_template, model_card_data=ModelCardData())
+
+        # If parent class has a MixinInfo, inherit from it as a copy
+        if hasattr(cls, "_hub_mixin_info"):
+            # Inherit model card template from parent class if not explicitly set
+            if model_card_template == DEFAULT_MODEL_CARD:
+                info.model_card_template = cls._hub_mixin_info.model_card_template
+
+            # Inherit from parent model card data
+            info.model_card_data = ModelCardData(**cls._hub_mixin_info.model_card_data.to_dict())
+
+            # Inherit other info
+            info.docs_url = cls._hub_mixin_info.docs_url
+            info.paper_url = cls._hub_mixin_info.paper_url
+            info.repo_url = cls._hub_mixin_info.repo_url
+        cls._hub_mixin_info = info
+
+        # Update MixinInfo with metadata
+        if model_card_template is not None and model_card_template != DEFAULT_MODEL_CARD:
+            info.model_card_template = model_card_template
+        if repo_url is not None:
+            info.repo_url = repo_url
+        if paper_url is not None:
+            info.paper_url = paper_url
+        if docs_url is not None:
+            info.docs_url = docs_url
+        if language is not None:
+            info.model_card_data.language = language
+        if library_name is not None:
+            info.model_card_data.library_name = library_name
+        if license is not None:
+            info.model_card_data.license = license
+        if license_name is not None:
+            info.model_card_data.license_name = license_name
+        if license_link is not None:
+            info.model_card_data.license_link = license_link
+        if pipeline_tag is not None:
+            info.model_card_data.pipeline_tag = pipeline_tag
+        if tags is not None:
+            normalized_tags = list(tags)
+            if info.model_card_data.tags is not None:
+                info.model_card_data.tags.extend(normalized_tags)
+            else:
+                info.model_card_data.tags = normalized_tags
+
+        if info.model_card_data.tags is not None:
+            info.model_card_data.tags = sorted(set(info.model_card_data.tags))
+
+        # Handle encoders/decoders for args
+        cls._hub_mixin_coders = coders or {}
+        cls._hub_mixin_jsonable_custom_types = tuple(cls._hub_mixin_coders.keys())
+
+        # Inspect __init__ signature to handle config
+        cls._hub_mixin_init_parameters = dict(inspect.signature(cls.__init__).parameters)
+        cls._hub_mixin_jsonable_default_values = {
+            param.name: cls._encode_arg(param.default)
+            for param in cls._hub_mixin_init_parameters.values()
+            if param.default is not inspect.Parameter.empty and cls._is_jsonable(param.default)
+        }
+        cls._hub_mixin_inject_config = "config" in inspect.signature(cls._from_pretrained).parameters
+
+    def __new__(cls: type[T], *args, **kwargs) -> T:
+        """Create a new instance of the class and handle config.
+
+        3 cases:
+        - If `self._hub_mixin_config` is already set, do nothing.
+        - If `config` is passed as a dataclass, set it as `self._hub_mixin_config`.
+        - Otherwise, build `self._hub_mixin_config` from default values and passed values.
+        """
+        instance = super().__new__(cls)
+
+        # If `config` is already set, return early
+        if instance._hub_mixin_config is not None:
+            return instance
+
+        # Infer passed values
+        passed_values = {
+            **{
+                key: value
+                for key, value in zip(
+                    # [1:] to skip `self` parameter
+                    list(cls._hub_mixin_init_parameters)[1:],
+                    args,
+                )
+            },
+            **kwargs,
+        }
+
+        # If config passed as dataclass => set it and return early
+        if is_dataclass(passed_values.get("config")):
+            instance._hub_mixin_config = passed_values["config"]
+            return instance
+
+        # Otherwise, build config from default + passed values
+        init_config = {
+            # default values
+            **cls._hub_mixin_jsonable_default_values,
+            # passed values
+            **{
+                key: cls._encode_arg(value)  # Encode custom types as jsonable value
+                for key, value in passed_values.items()
+                if instance._is_jsonable(value)  # Only if jsonable or we have a custom encoder
+            },
+        }
+        passed_config = init_config.pop("config", {})
+
+        # Populate `init_config` with provided config
+        if isinstance(passed_config, dict):
+            init_config.update(passed_config)
+
+        # Set `config` attribute and return
+        if init_config != {}:
+            instance._hub_mixin_config = init_config
+        return instance
+
+    @classmethod
+    def _is_jsonable(cls, value: Any) -> bool:
+        """Check if a value is JSON serializable."""
+        if is_dataclass(value):
+            return True
+        if isinstance(value, cls._hub_mixin_jsonable_custom_types):
+            return True
+        return is_jsonable(value)
+
+    @classmethod
+    def _encode_arg(cls, arg: Any) -> Any:
+        """Encode an argument into a JSON serializable format."""
+        if is_dataclass(arg):
+            return asdict(arg)  # type: ignore[arg-type]
+        for type_, (encoder, _) in cls._hub_mixin_coders.items():
+            if isinstance(arg, type_):
+                if arg is None:
+                    return None
+                return encoder(arg)
+        return arg
+
+    @classmethod
+    def _decode_arg(cls, expected_type: type[ARGS_T], value: Any) -> Optional[ARGS_T]:
+        """Decode a JSON serializable value into an argument."""
+        if is_simple_optional_type(expected_type):
+            if value is None:
+                return None
+            expected_type = unwrap_simple_optional_type(expected_type)  # type: ignore[assignment]
+        # Dataclass => handle it
+        if is_dataclass(expected_type):
+            return _load_dataclass(expected_type, value)  # type: ignore[return-value]
+        # Otherwise => check custom decoders
+        for type_, (_, decoder) in cls._hub_mixin_coders.items():
+            if inspect.isclass(expected_type) and issubclass(expected_type, type_):
+                return decoder(value)
+        # Otherwise => don't decode
+        return value
+
+    def save_pretrained(
+        self,
+        save_directory: Union[str, Path],
+        *,
+        config: Optional[Union[dict, DataclassInstance]] = None,
+        repo_id: Optional[str] = None,
+        push_to_hub: bool = False,
+        model_card_kwargs: Optional[dict[str, Any]] = None,
+        **push_to_hub_kwargs,
+    ) -> Optional[str]:
+        """
+        Save weights in local directory.
+
+        Args:
+            save_directory (`str` or `Path`):
+                Path to directory in which the model weights and configuration will be saved.
+            config (`dict` or `DataclassInstance`, *optional*):
+                Model configuration specified as a key/value dictionary or a dataclass instance.
+            push_to_hub (`bool`, *optional*, defaults to `False`):
+                Whether or not to push your model to the Huggingface Hub after saving it.
+            repo_id (`str`, *optional*):
+                ID of your repository on the Hub. Used only if `push_to_hub=True`. Will default to the folder name if
+                not provided.
+            model_card_kwargs (`dict[str, Any]`, *optional*):
+                Additional arguments passed to the model card template to customize the model card.
+            push_to_hub_kwargs:
+                Additional key word arguments passed along to the [`~ModelHubMixin.push_to_hub`] method.
+        Returns:
+            `str` or `None`: url of the commit on the Hub if `push_to_hub=True`, `None` otherwise.
+        """
+        save_directory = Path(save_directory)
+        save_directory.mkdir(parents=True, exist_ok=True)
+
+        # Remove config.json if already exists. After `_save_pretrained` we don't want to overwrite config.json
+        # as it might have been saved by the custom `_save_pretrained` already. However we do want to overwrite
+        # an existing config.json if it was not saved by `_save_pretrained`.
+        config_path = save_directory / constants.CONFIG_NAME
+        config_path.unlink(missing_ok=True)
+
+        # save model weights/files (framework-specific)
+        self._save_pretrained(save_directory)
+
+        # save config (if provided and if not serialized yet in `_save_pretrained`)
+        if config is None:
+            config = self._hub_mixin_config
+        if config is not None:
+            if is_dataclass(config):
+                config = asdict(config)  # type: ignore[arg-type]
+            if not config_path.exists():
+                config_str = json.dumps(config, sort_keys=True, indent=2)
+                config_path.write_text(config_str)
+
+        # save model card
+        model_card_path = save_directory / "README.md"
+        model_card_kwargs = model_card_kwargs if model_card_kwargs is not None else {}
+        if not model_card_path.exists():  # do not overwrite if already exists
+            self.generate_model_card(**model_card_kwargs).save(save_directory / "README.md")
+
+        # push to the Hub if required
+        if push_to_hub:
+            kwargs = push_to_hub_kwargs.copy()  # soft-copy to avoid mutating input
+            if config is not None:  # kwarg for `push_to_hub`
+                kwargs["config"] = config
+            if repo_id is None:
+                repo_id = save_directory.name  # Defaults to `save_directory` name
+            return self.push_to_hub(repo_id=repo_id, model_card_kwargs=model_card_kwargs, **kwargs)
+        return None
+
+    def _save_pretrained(self, save_directory: Path) -> None:
+        """
+        Overwrite this method in subclass to define how to save your model.
+        Check out our [integration guide](../guides/integrations) for instructions.
+
+        Args:
+            save_directory (`str` or `Path`):
+                Path to directory in which the model weights and configuration will be saved.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    @validate_hf_hub_args
+    def from_pretrained(
+        cls: type[T],
+        pretrained_model_name_or_path: Union[str, Path],
+        *,
+        force_download: bool = False,
+        token: Optional[Union[str, bool]] = None,
+        cache_dir: Optional[Union[str, Path]] = None,
+        local_files_only: bool = False,
+        revision: Optional[str] = None,
+        **model_kwargs,
+    ) -> T:
+        """
+        Download a model from the Huggingface Hub and instantiate it.
+
+        Args:
+            pretrained_model_name_or_path (`str`, `Path`):
+                - Either the `model_id` (string) of a model hosted on the Hub, e.g. `bigscience/bloom`.
+                - Or a path to a `directory` containing model weights saved using
+                    [`~transformers.PreTrainedModel.save_pretrained`], e.g., `../path/to/my_model_directory/`.
+            revision (`str`, *optional*):
+                Revision of the model on the Hub. Can be a branch name, a git tag or any commit id.
+                Defaults to the latest commit on `main` branch.
+            force_download (`bool`, *optional*, defaults to `False`):
+                Whether to force (re-)downloading the model weights and configuration files from the Hub, overriding
+                the existing cache.
+            token (`str` or `bool`, *optional*):
+                The token to use as HTTP bearer authorization for remote files. By default, it will use the token
+                cached when running `hf auth login`.
+            cache_dir (`str`, `Path`, *optional*):
+                Path to the folder where cached files are stored.
+            local_files_only (`bool`, *optional*, defaults to `False`):
+                If `True`, avoid downloading the file and return the path to the local cached file if it exists.
+            model_kwargs (`dict`, *optional*):
+                Additional kwargs to pass to the model during initialization.
+        """
+        model_id = str(pretrained_model_name_or_path)
+        config_file: Optional[str] = None
+        if os.path.isdir(model_id):
+            if constants.CONFIG_NAME in os.listdir(model_id):
+                config_file = os.path.join(model_id, constants.CONFIG_NAME)
+            else:
+                logger.warning(f"{constants.CONFIG_NAME} not found in {Path(model_id).resolve()}")
+        else:
+            try:
+                config_file = hf_hub_download(
+                    repo_id=model_id,
+                    filename=constants.CONFIG_NAME,
+                    revision=revision,
+                    cache_dir=cache_dir,
+                    force_download=force_download,
+                    token=token,
+                    local_files_only=local_files_only,
+                )
+            except HfHubHTTPError as e:
+                logger.info(f"{constants.CONFIG_NAME} not found on the HuggingFace Hub: {str(e)}")
+
+        # Read config
+        config = None
+        if config_file is not None:
+            with open(config_file, "r", encoding="utf-8") as f:
+                config = json.load(f)
+
+            # Decode custom types in config
+            for key, value in config.items():
+                if key in cls._hub_mixin_init_parameters:
+                    expected_type = cls._hub_mixin_init_parameters[key].annotation
+                    if expected_type is not inspect.Parameter.empty:
+                        config[key] = cls._decode_arg(expected_type, value)
+
+            # Populate model_kwargs from config
+            for param in cls._hub_mixin_init_parameters.values():
+                if param.name not in model_kwargs and param.name in config:
+                    model_kwargs[param.name] = config[param.name]
+
+            # Check if `config` argument was passed at init
+            if "config" in cls._hub_mixin_init_parameters and "config" not in model_kwargs:
+                # Decode `config` argument if it was passed
+                config_annotation = cls._hub_mixin_init_parameters["config"].annotation
+                config = cls._decode_arg(config_annotation, config)
+
+                # Forward config to model initialization
+                model_kwargs["config"] = config
+
+            # Inject config if `**kwargs` are expected
+            if is_dataclass(cls):
+                for key in cls.__dataclass_fields__:
+                    if key not in model_kwargs and key in config:
+                        model_kwargs[key] = config[key]
+            elif any(param.kind == inspect.Parameter.VAR_KEYWORD for param in cls._hub_mixin_init_parameters.values()):
+                for key, value in config.items():  # type: ignore[union-attr]
+                    if key not in model_kwargs:
+                        model_kwargs[key] = value
+
+            # Finally, also inject if `_from_pretrained` expects it
+            if cls._hub_mixin_inject_config and "config" not in model_kwargs:
+                model_kwargs["config"] = config
+
+        instance = cls._from_pretrained(
+            model_id=str(model_id),
+            revision=revision,
+            cache_dir=cache_dir,
+            force_download=force_download,
+            local_files_only=local_files_only,
+            token=token,
+            **model_kwargs,
+        )
+
+        # Implicitly set the config as instance attribute if not already set by the class
+        # This way `config` will be available when calling `save_pretrained` or `push_to_hub`.
+        if config is not None and (getattr(instance, "_hub_mixin_config", None) in (None, {})):
+            instance._hub_mixin_config = config
+
+        return instance
+
+    @classmethod
+    def _from_pretrained(
+        cls: type[T],
+        *,
+        model_id: str,
+        revision: Optional[str],
+        cache_dir: Optional[Union[str, Path]],
+        force_download: bool,
+        local_files_only: bool,
+        token: Optional[Union[str, bool]],
+        **model_kwargs,
+    ) -> T:
+        """Overwrite this method in subclass to define how to load your model from pretrained.
+
+        Use [`hf_hub_download`] or [`snapshot_download`] to download files from the Hub before loading them. Most
+        args taken as input can be directly passed to those 2 methods. If needed, you can add more arguments to this
+        method using "model_kwargs". For example [`PyTorchModelHubMixin._from_pretrained`] takes as input a `map_location`
+        parameter to set on which device the model should be loaded.
+
+        Check out our [integration guide](../guides/integrations) for more instructions.
+
+        Args:
+            model_id (`str`):
+                ID of the model to load from the Huggingface Hub (e.g. `bigscience/bloom`).
+            revision (`str`, *optional*):
+                Revision of the model on the Hub. Can be a branch name, a git tag or any commit id. Defaults to the
+                latest commit on `main` branch.
+            force_download (`bool`, *optional*, defaults to `False`):
+                Whether to force (re-)downloading the model weights and configuration files from the Hub, overriding
+                the existing cache.
+            token (`str` or `bool`, *optional*):
+                The token to use as HTTP bearer authorization for remote files. By default, it will use the token
+                cached when running `hf auth login`.
+            cache_dir (`str`, `Path`, *optional*):
+                Path to the folder where cached files are stored.
+            local_files_only (`bool`, *optional*, defaults to `False`):
+                If `True`, avoid downloading the file and return the path to the local cached file if it exists.
+            model_kwargs:
+                Additional keyword arguments passed along to the [`~ModelHubMixin._from_pretrained`] method.
+        """
+        raise NotImplementedError
+
+    @validate_hf_hub_args
+    def push_to_hub(
+        self,
+        repo_id: str,
+        *,
+        config: Optional[Union[dict, DataclassInstance]] = None,
+        commit_message: str = "Push model using huggingface_hub.",
+        private: Optional[bool] = None,
+        token: Optional[str] = None,
+        branch: Optional[str] = None,
+        create_pr: Optional[bool] = None,
+        allow_patterns: Optional[Union[list[str], str]] = None,
+        ignore_patterns: Optional[Union[list[str], str]] = None,
+        delete_patterns: Optional[Union[list[str], str]] = None,
+        model_card_kwargs: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """
+        Upload model checkpoint to the Hub.
+
+        Use `allow_patterns` and `ignore_patterns` to precisely filter which files should be pushed to the hub. Use
+        `delete_patterns` to delete existing remote files in the same commit. See [`upload_folder`] reference for more
+        details.
+
+        Args:
+            repo_id (`str`):
+                ID of the repository to push to (example: `"username/my-model"`).
+            config (`dict` or `DataclassInstance`, *optional*):
+                Model configuration specified as a key/value dictionary or a dataclass instance.
+            commit_message (`str`, *optional*):
+                Message to commit while pushing.
+            private (`bool`, *optional*):
+                Whether the repository created should be private.
+                If `None` (default), the repo will be public unless the organization's default is private.
+            token (`str`, *optional*):
+                The token to use as HTTP bearer authorization for remote files. By default, it will use the token
+                cached when running `hf auth login`.
+            branch (`str`, *optional*):
+                The git branch on which to push the model. This defaults to `"main"`.
+            create_pr (`boolean`, *optional*):
+                Whether or not to create a Pull Request from `branch` with that commit. Defaults to `False`.
+            allow_patterns (`list[str]` or `str`, *optional*):
+                If provided, only files matching at least one pattern are pushed.
+            ignore_patterns (`list[str]` or `str`, *optional*):
+                If provided, files matching any of the patterns are not pushed.
+            delete_patterns (`list[str]` or `str`, *optional*):
+                If provided, remote files matching any of the patterns will be deleted from the repo.
+            model_card_kwargs (`dict[str, Any]`, *optional*):
+                Additional arguments passed to the model card template to customize the model card.
+
+        Returns:
+            The url of the commit of your model in the given repository.
+        """
+        api = HfApi(token=token)
+        repo_id = api.create_repo(repo_id=repo_id, private=private, exist_ok=True).repo_id
+
+        # Push the files to the repo in a single commit
+        with SoftTemporaryDirectory() as tmp:
+            saved_path = Path(tmp) / repo_id
+            self.save_pretrained(saved_path, config=config, model_card_kwargs=model_card_kwargs)
+            return api.upload_folder(
+                repo_id=repo_id,
+                repo_type="model",
+                folder_path=saved_path,
+                commit_message=commit_message,
+                revision=branch,
+                create_pr=create_pr,
+                allow_patterns=allow_patterns,
+                ignore_patterns=ignore_patterns,
+                delete_patterns=delete_patterns,
+            )
+
+    def generate_model_card(self, *args, **kwargs) -> ModelCard:
+        card = ModelCard.from_template(
+            card_data=self._hub_mixin_info.model_card_data,
+            template_str=self._hub_mixin_info.model_card_template,
+            repo_url=self._hub_mixin_info.repo_url,
+            paper_url=self._hub_mixin_info.paper_url,
+            docs_url=self._hub_mixin_info.docs_url,
+            **kwargs,
+        )
+        return card
+
+
+class PyTorchModelHubMixin(ModelHubMixin):
+    """
+    Implementation of [`ModelHubMixin`] to provide model Hub upload/download capabilities to PyTorch models. The model
+    is set in evaluation mode by default using `model.eval()` (dropout modules are deactivated). To train the model,
+    you should first set it back in training mode with `model.train()`.
+
+    See [`ModelHubMixin`] for more details on how to use the mixin.
+
+    Example:
+
+    ```python
+    >>> import torch
+    >>> import torch.nn as nn
+    >>> from huggingface_hub import PyTorchModelHubMixin
+
+    >>> class MyModel(
+    ...         nn.Module,
+    ...         PyTorchModelHubMixin,
+    ...         library_name="keras-nlp",
+    ...         repo_url="https://github.com/keras-team/keras-nlp",
+    ...         paper_url="https://arxiv.org/abs/2304.12244",
+    ...         docs_url="https://keras.io/keras_nlp/",
+    ...         # ^ optional metadata to generate model card
+    ...     ):
+    ...     def __init__(self, hidden_size: int = 512, vocab_size: int = 30000, output_size: int = 4):
+    ...         super().__init__()
+    ...         self.param = nn.Parameter(torch.rand(hidden_size, vocab_size))
+    ...         self.linear = nn.Linear(output_size, vocab_size)
+
+    ...     def forward(self, x):
+    ...         return self.linear(x + self.param)
+    >>> model = MyModel(hidden_size=256)
+
+    # Save model weights to local directory
+    >>> model.save_pretrained("my-awesome-model")
+
+    # Push model weights to the Hub
+    >>> model.push_to_hub("my-awesome-model")
+
+    # Download and initialize weights from the Hub
+    >>> model = MyModel.from_pretrained("username/my-awesome-model")
+    >>> model.hidden_size
+    256
+    ```
+    """
+
+    def __init_subclass__(cls, *args, tags: Optional[list[str]] = None, **kwargs) -> None:
+        tags = tags or []
+        tags.append("pytorch_model_hub_mixin")
+        kwargs["tags"] = tags
+        return super().__init_subclass__(*args, **kwargs)
+
+    def _save_pretrained(self, save_directory: Path) -> None:
+        """Save weights from a Pytorch model to a local directory."""
+        model_to_save = self.module if hasattr(self, "module") else self  # type: ignore
+        save_model_as_safetensor(model_to_save, str(save_directory / constants.SAFETENSORS_SINGLE_FILE))  # type: ignore [arg-type]
+
+    @classmethod
+    def _from_pretrained(
+        cls,
+        *,
+        model_id: str,
+        revision: Optional[str],
+        cache_dir: Optional[Union[str, Path]],
+        force_download: bool,
+        local_files_only: bool,
+        token: Union[str, bool, None],
+        map_location: str = "cpu",
+        strict: bool = False,
+        **model_kwargs,
+    ):
+        """Load Pytorch pretrained weights and return the loaded model."""
+        model = cls(**model_kwargs)
+        if os.path.isdir(model_id):
+            print("Loading weights from local directory")
+            model_file = os.path.join(model_id, constants.SAFETENSORS_SINGLE_FILE)
+            return cls._load_as_safetensor(model, model_file, map_location, strict)
+        else:
+            try:
+                model_file = hf_hub_download(
+                    repo_id=model_id,
+                    filename=constants.SAFETENSORS_SINGLE_FILE,
+                    revision=revision,
+                    cache_dir=cache_dir,
+                    force_download=force_download,
+                    token=token,
+                    local_files_only=local_files_only,
+                )
+                return cls._load_as_safetensor(model, model_file, map_location, strict)
+            except EntryNotFoundError:
+                model_file = hf_hub_download(
+                    repo_id=model_id,
+                    filename=constants.PYTORCH_WEIGHTS_NAME,
+                    revision=revision,
+                    cache_dir=cache_dir,
+                    force_download=force_download,
+                    token=token,
+                    local_files_only=local_files_only,
+                )
+                return cls._load_as_pickle(model, model_file, map_location, strict)
+
+    @classmethod
+    def _load_as_pickle(cls, model: T, model_file: str, map_location: str, strict: bool) -> T:
+        state_dict = torch.load(model_file, map_location=torch.device(map_location), weights_only=True)
+        model.load_state_dict(state_dict, strict=strict)  # type: ignore
+        model.eval()  # type: ignore
+        return model
+
+    @classmethod
+    def _load_as_safetensor(cls, model: T, model_file: str, map_location: str, strict: bool) -> T:
+        if packaging.version.parse(safetensors.__version__) < packaging.version.parse("0.4.3"):  # type: ignore [attr-defined]
+            load_model_as_safetensor(model, model_file, strict=strict)  # type: ignore [arg-type]
+            if map_location != "cpu":
+                logger.warning(
+                    "Loading model weights on other devices than 'cpu' is not supported natively in your version of safetensors."
+                    " This means that the model is loaded on 'cpu' first and then copied to the device."
+                    " This leads to a slower loading time."
+                    " Please update safetensors to version 0.4.3 or above for improved performance."
+                )
+                model.to(map_location)  # type: ignore [attr-defined]
+        else:
+            safetensors.torch.load_model(model, model_file, strict=strict, device=map_location)  # type: ignore [arg-type]
+        return model
+
+
+def _load_dataclass(datacls: type[DataclassInstance], data: dict) -> DataclassInstance:
+    """Load a dataclass instance from a dictionary.
+
+    Fields not expected by the dataclass are ignored.
+    """
+    return datacls(**{k: v for k, v in data.items() if k in datacls.__dataclass_fields__})

venv/lib/python3.12/site-packages/huggingface_hub/inference/_common.py

@@ -0,0 +1,434 @@
+# coding=utf-8
+# Copyright 2023-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains utilities used by both the sync and async inference clients."""
+
+import base64
+import io
+import json
+import logging
+import mimetypes
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, AsyncIterable, BinaryIO, Iterable, Literal, NoReturn, Optional, Union, overload
+
+import httpx
+
+from huggingface_hub.errors import (
+    GenerationError,
+    HfHubHTTPError,
+    IncompleteGenerationError,
+    OverloadedError,
+    TextGenerationError,
+    UnknownError,
+    ValidationError,
+)
+
+from ..utils import get_session, is_numpy_available, is_pillow_available
+from ._generated.types import ChatCompletionStreamOutput, TextGenerationStreamOutput
+
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+
+# TYPES
+UrlT = str
+PathT = Union[str, Path]
+ContentT = Union[bytes, BinaryIO, PathT, UrlT, "Image", bytearray, memoryview]
+
+# Use to set an Accept: image/png header
+TASKS_EXPECTING_IMAGES = {"text-to-image", "image-to-image"}
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RequestParameters:
+    url: str
+    task: str
+    model: Optional[str]
+    json: Optional[Union[str, dict, list]]
+    data: Optional[bytes]
+    headers: dict[str, Any]
+
+
+class MimeBytes(bytes):
+    """
+    A bytes object with a mime type.
+    To be returned by `_prepare_payload_open_as_mime_bytes` in subclasses.
+
+    Example:
+    ```python
+        >>> b = MimeBytes(b"hello", "text/plain")
+        >>> isinstance(b, bytes)
+        True
+        >>> b.mime_type
+        'text/plain'
+    ```
+    """
+
+    mime_type: Optional[str]
+
+    def __new__(cls, data: bytes, mime_type: Optional[str] = None):
+        obj = super().__new__(cls, data)
+        obj.mime_type = mime_type
+        if isinstance(data, MimeBytes) and mime_type is None:
+            obj.mime_type = data.mime_type
+        return obj
+
+
+## IMPORT UTILS
+
+
+def _import_numpy():
+    """Make sure `numpy` is installed on the machine."""
+    if not is_numpy_available():
+        raise ImportError("Please install numpy to use deal with embeddings (`pip install numpy`).")
+    import numpy
+
+    return numpy
+
+
+def _import_pil_image():
+    """Make sure `PIL` is installed on the machine."""
+    if not is_pillow_available():
+        raise ImportError(
+            "Please install Pillow to use deal with images (`pip install Pillow`). If you don't want the image to be"
+            " post-processed, use `client.post(...)` and get the raw response from the server."
+        )
+    from PIL import Image
+
+    return Image
+
+
+## ENCODING / DECODING UTILS
+
+
+@overload
+def _open_as_mime_bytes(content: ContentT) -> MimeBytes: ...  # means "if input is not None, output is not None"
+
+
+@overload
+def _open_as_mime_bytes(content: Literal[None]) -> Literal[None]: ...  # means "if input is None, output is None"
+
+
+def _open_as_mime_bytes(content: Optional[ContentT]) -> Optional[MimeBytes]:
+    """Open `content` as a binary file, either from a URL, a local path, raw bytes, or a PIL Image.
+
+    Do nothing if `content` is None.
+    """
+    # If content is None, yield None
+    if content is None:
+        return None
+
+    # If content is bytes, return it
+    if isinstance(content, bytes):
+        return MimeBytes(content)
+
+    # If content is raw binary data (bytearray, memoryview)
+    if isinstance(content, (bytearray, memoryview)):
+        return MimeBytes(bytes(content))
+
+    # If content is a binary file-like object
+    if hasattr(content, "read"):  # duck-typing instead of isinstance(content, BinaryIO)
+        logger.debug("Reading content from BinaryIO")
+        data = content.read()
+        mime_type = mimetypes.guess_type(str(content.name))[0] if hasattr(content, "name") else None
+        if isinstance(data, str):
+            raise TypeError("Expected binary stream (bytes), but got text stream")
+        return MimeBytes(data, mime_type=mime_type)
+
+    # If content is a string => must be either a URL or a path
+    if isinstance(content, str):
+        if content.startswith("https://") or content.startswith("http://"):
+            logger.debug(f"Downloading content from {content}")
+            response = get_session().get(content)
+            mime_type = response.headers.get("Content-Type")
+            if mime_type is None:
+                mime_type = mimetypes.guess_type(content)[0]
+            return MimeBytes(response.content, mime_type=mime_type)
+
+        content = Path(content)
+        if not content.exists():
+            raise FileNotFoundError(
+                f"File not found at {content}. If `data` is a string, it must either be a URL or a path to a local"
+                " file. To pass raw content, please encode it as bytes first."
+            )
+
+    # If content is a Path => open it
+    if isinstance(content, Path):
+        logger.debug(f"Opening content from {content}")
+        return MimeBytes(content.read_bytes(), mime_type=mimetypes.guess_type(content)[0])
+
+    # If content is a PIL Image => convert to bytes
+    if is_pillow_available():
+        from PIL import Image
+
+        if isinstance(content, Image.Image):
+            logger.debug("Converting PIL Image to bytes")
+            buffer = io.BytesIO()
+            format = content.format or "PNG"
+            content.save(buffer, format=format)
+            return MimeBytes(buffer.getvalue(), mime_type=f"image/{format.lower()}")
+
+    # If nothing matched, raise error
+    raise TypeError(
+        f"Unsupported content type: {type(content)}. "
+        "Expected one of: bytes, bytearray, BinaryIO, memoryview, Path, str (URL or file path), or PIL.Image.Image."
+    )
+
+
+def _b64_encode(content: ContentT) -> str:
+    """Encode a raw file (image, audio) into base64. Can be bytes, an opened file, a path or a URL."""
+    raw_bytes = _open_as_mime_bytes(content)
+    return base64.b64encode(raw_bytes).decode()
+
+
+def _as_url(content: ContentT, default_mime_type: str) -> str:
+    if isinstance(content, str) and content.startswith(("http://", "https://", "data:")):
+        return content
+
+    # Convert content to bytes
+    raw_bytes = _open_as_mime_bytes(content)
+
+    # Get MIME type
+    mime_type = raw_bytes.mime_type or default_mime_type
+
+    # Encode content to base64
+    encoded_data = base64.b64encode(raw_bytes).decode()
+
+    # Build data URL
+    return f"data:{mime_type};base64,{encoded_data}"
+
+
+def _b64_to_image(encoded_image: str) -> "Image":
+    """Parse a base64-encoded string into a PIL Image."""
+    Image = _import_pil_image()
+    return Image.open(io.BytesIO(base64.b64decode(encoded_image)))
+
+
+def _bytes_to_list(content: bytes) -> list:
+    """Parse bytes from a Response object into a Python list.
+
+    Expects the response body to be JSON-encoded data.
+
+    NOTE: This is exactly the same implementation as `_bytes_to_dict` and will not complain if the returned data is a
+    dictionary. The only advantage of having both is to help the user (and mypy) understand what kind of data to expect.
+    """
+    return json.loads(content.decode())
+
+
+def _bytes_to_dict(content: bytes) -> dict:
+    """Parse bytes from a Response object into a Python dictionary.
+
+    Expects the response body to be JSON-encoded data.
+
+    NOTE: This is exactly the same implementation as `_bytes_to_list` and will not complain if the returned data is a
+    list. The only advantage of having both is to help the user (and mypy) understand what kind of data to expect.
+    """
+    return json.loads(content.decode())
+
+
+def _bytes_to_image(content: bytes) -> "Image":
+    """Parse bytes from a Response object into a PIL Image.
+
+    Expects the response body to be raw bytes. To deal with b64 encoded images, use `_b64_to_image` instead.
+    """
+    Image = _import_pil_image()
+    return Image.open(io.BytesIO(content))
+
+
+def _as_dict(response: Union[bytes, dict]) -> dict:
+    return json.loads(response) if isinstance(response, bytes) else response
+
+
+## STREAMING UTILS
+
+
+def _stream_text_generation_response(
+    output_lines: Iterable[str], details: bool
+) -> Union[Iterable[str], Iterable[TextGenerationStreamOutput]]:
+    """Used in `InferenceClient.text_generation`."""
+    # Parse ServerSentEvents
+    for line in output_lines:
+        try:
+            output = _format_text_generation_stream_output(line, details)
+        except StopIteration:
+            break
+        if output is not None:
+            yield output
+
+
+async def _async_stream_text_generation_response(
+    output_lines: AsyncIterable[str], details: bool
+) -> Union[AsyncIterable[str], AsyncIterable[TextGenerationStreamOutput]]:
+    """Used in `AsyncInferenceClient.text_generation`."""
+    # Parse ServerSentEvents
+    async for line in output_lines:
+        try:
+            output = _format_text_generation_stream_output(line, details)
+        except StopIteration:
+            break
+        if output is not None:
+            yield output
+
+
+def _format_text_generation_stream_output(
+    line: str, details: bool
+) -> Optional[Union[str, TextGenerationStreamOutput]]:
+    if not line.startswith("data:"):
+        return None  # empty line
+
+    if line.strip() == "data: [DONE]":
+        raise StopIteration("[DONE] signal received.")
+
+    # Decode payload
+    payload = line.lstrip("data:").rstrip("/n")
+    json_payload = json.loads(payload)
+
+    # Either an error as being returned
+    if json_payload.get("error") is not None:
+        raise _parse_text_generation_error(json_payload["error"], json_payload.get("error_type"))
+
+    # Or parse token payload
+    output = TextGenerationStreamOutput.parse_obj_as_instance(json_payload)
+    return output.token.text if not details else output
+
+
+def _stream_chat_completion_response(
+    lines: Iterable[str],
+) -> Iterable[ChatCompletionStreamOutput]:
+    """Used in `InferenceClient.chat_completion` if model is served with TGI."""
+    for line in lines:
+        try:
+            output = _format_chat_completion_stream_output(line)
+        except StopIteration:
+            break
+        if output is not None:
+            yield output
+
+
+async def _async_stream_chat_completion_response(
+    lines: AsyncIterable[str],
+) -> AsyncIterable[ChatCompletionStreamOutput]:
+    """Used in `AsyncInferenceClient.chat_completion`."""
+    async for line in lines:
+        try:
+            output = _format_chat_completion_stream_output(line)
+        except StopIteration:
+            break
+        if output is not None:
+            yield output
+
+
+def _format_chat_completion_stream_output(
+    line: str,
+) -> Optional[ChatCompletionStreamOutput]:
+    if not line.startswith("data:"):
+        return None  # empty line
+
+    if line.strip() == "data: [DONE]":
+        raise StopIteration("[DONE] signal received.")
+
+    # Decode payload
+    json_payload = json.loads(line.lstrip("data:").strip())
+
+    # Either an error as being returned
+    if json_payload.get("error") is not None:
+        raise _parse_text_generation_error(json_payload["error"], json_payload.get("error_type"))
+
+    # Or parse token payload
+    return ChatCompletionStreamOutput.parse_obj_as_instance(json_payload)
+
+
+async def _async_yield_from(client: httpx.AsyncClient, response: httpx.Response) -> AsyncIterable[str]:
+    async for line in response.aiter_lines():
+        yield line.strip()
+
+
+# "TGI servers" are servers running with the `text-generation-inference` backend.
+# This backend is the go-to solution to run large language models at scale. However,
+# for some smaller models (e.g. "gpt2") the default `transformers` + `api-inference`
+# solution is still in use.
+#
+# Both approaches have very similar APIs, but not exactly the same. What we do first in
+# the `text_generation` method is to assume the model is served via TGI. If we realize
+# it's not the case (i.e. we receive an HTTP 400 Bad Request), we fall back to the
+# default API with a warning message. When that's the case, We remember the unsupported
+# attributes for this model in the `_UNSUPPORTED_TEXT_GENERATION_KWARGS` global variable.
+#
+# In addition, TGI servers have a built-in API route for chat-completion, which is not
+# available on the default API. We use this route to provide a more consistent behavior
+# when available.
+#
+# For more details, see https://github.com/huggingface/text-generation-inference and
+# https://huggingface.co/docs/api-inference/detailed_parameters#text-generation-task.
+
+_UNSUPPORTED_TEXT_GENERATION_KWARGS: dict[Optional[str], list[str]] = {}
+
+
+def _set_unsupported_text_generation_kwargs(model: Optional[str], unsupported_kwargs: list[str]) -> None:
+    _UNSUPPORTED_TEXT_GENERATION_KWARGS.setdefault(model, []).extend(unsupported_kwargs)
+
+
+def _get_unsupported_text_generation_kwargs(model: Optional[str]) -> list[str]:
+    return _UNSUPPORTED_TEXT_GENERATION_KWARGS.get(model, [])
+
+
+# TEXT GENERATION ERRORS
+# ----------------------
+# Text-generation errors are parsed separately to handle as much as possible the errors returned by the text generation
+# inference project (https://github.com/huggingface/text-generation-inference).
+# ----------------------
+
+
+def raise_text_generation_error(http_error: HfHubHTTPError) -> NoReturn:
+    """
+    Try to parse text-generation-inference error message and raise HTTPError in any case.
+
+    Args:
+        error (`HTTPError`):
+            The HTTPError that have been raised.
+    """
+    # Try to parse a Text Generation Inference error
+    if http_error.response is None:
+        raise http_error
+
+    try:
+        # Hacky way to retrieve payload in case of aiohttp error
+        payload = getattr(http_error, "response_error_payload", None) or http_error.response.json()
+        error = payload.get("error")
+        error_type = payload.get("error_type")
+    except Exception:  # no payload
+        raise http_error
+
+    # If error_type => more information than `hf_raise_for_status`
+    if error_type is not None:
+        exception = _parse_text_generation_error(error, error_type)
+        raise exception from http_error
+
+    # Otherwise, fallback to default error
+    raise http_error
+
+
+def _parse_text_generation_error(error: Optional[str], error_type: Optional[str]) -> TextGenerationError:
+    if error_type == "generation":
+        return GenerationError(error)  # type: ignore
+    if error_type == "incomplete_generation":
+        return IncompleteGenerationError(error)  # type: ignore
+    if error_type == "overloaded":
+        return OverloadedError(error)  # type: ignore
+    if error_type == "validation":
+        return ValidationError(error)  # type: ignore
+    return UnknownError(error)  # type: ignore

venv/lib/python3.12/site-packages/huggingface_hub/inference/_generated/types/__init__.py

@@ -0,0 +1,204 @@
+# This file is auto-generated by `utils/generate_inference_types.py`.
+# Do not modify it manually.
+#
+# ruff: noqa: F401
+
+from .audio_classification import (
+    AudioClassificationInput,
+    AudioClassificationOutputElement,
+    AudioClassificationOutputTransform,
+    AudioClassificationParameters,
+)
+from .audio_to_audio import AudioToAudioInput, AudioToAudioOutputElement
+from .automatic_speech_recognition import (
+    AutomaticSpeechRecognitionEarlyStoppingEnum,
+    AutomaticSpeechRecognitionGenerationParameters,
+    AutomaticSpeechRecognitionInput,
+    AutomaticSpeechRecognitionOutput,
+    AutomaticSpeechRecognitionOutputChunk,
+    AutomaticSpeechRecognitionParameters,
+)
+from .base import BaseInferenceType
+from .chat_completion import (
+    ChatCompletionInput,
+    ChatCompletionInputFunctionDefinition,
+    ChatCompletionInputFunctionName,
+    ChatCompletionInputGrammarType,
+    ChatCompletionInputJSONSchema,
+    ChatCompletionInputMessage,
+    ChatCompletionInputMessageChunk,
+    ChatCompletionInputMessageChunkType,
+    ChatCompletionInputResponseFormatJSONObject,
+    ChatCompletionInputResponseFormatJSONSchema,
+    ChatCompletionInputResponseFormatText,
+    ChatCompletionInputStreamOptions,
+    ChatCompletionInputTool,
+    ChatCompletionInputToolCall,
+    ChatCompletionInputToolChoiceClass,
+    ChatCompletionInputToolChoiceEnum,
+    ChatCompletionInputURL,
+    ChatCompletionOutput,
+    ChatCompletionOutputComplete,
+    ChatCompletionOutputFunctionDefinition,
+    ChatCompletionOutputLogprob,
+    ChatCompletionOutputLogprobs,
+    ChatCompletionOutputMessage,
+    ChatCompletionOutputToolCall,
+    ChatCompletionOutputTopLogprob,
+    ChatCompletionOutputUsage,
+    ChatCompletionStreamOutput,
+    ChatCompletionStreamOutputChoice,
+    ChatCompletionStreamOutputDelta,
+    ChatCompletionStreamOutputDeltaToolCall,
+    ChatCompletionStreamOutputFunction,
+    ChatCompletionStreamOutputLogprob,
+    ChatCompletionStreamOutputLogprobs,
+    ChatCompletionStreamOutputTopLogprob,
+    ChatCompletionStreamOutputUsage,
+)
+from .depth_estimation import DepthEstimationInput, DepthEstimationOutput
+from .document_question_answering import (
+    DocumentQuestionAnsweringInput,
+    DocumentQuestionAnsweringInputData,
+    DocumentQuestionAnsweringOutputElement,
+    DocumentQuestionAnsweringParameters,
+)
+from .feature_extraction import FeatureExtractionInput, FeatureExtractionInputTruncationDirection
+from .fill_mask import FillMaskInput, FillMaskOutputElement, FillMaskParameters
+from .image_classification import (
+    ImageClassificationInput,
+    ImageClassificationOutputElement,
+    ImageClassificationOutputTransform,
+    ImageClassificationParameters,
+)
+from .image_segmentation import (
+    ImageSegmentationInput,
+    ImageSegmentationOutputElement,
+    ImageSegmentationParameters,
+    ImageSegmentationSubtask,
+)
+from .image_text_to_image import (
+    ImageTextToImageInput,
+    ImageTextToImageOutput,
+    ImageTextToImageParameters,
+    ImageTextToImageTargetSize,
+)
+from .image_text_to_video import (
+    ImageTextToVideoInput,
+    ImageTextToVideoOutput,
+    ImageTextToVideoParameters,
+    ImageTextToVideoTargetSize,
+)
+from .image_to_image import ImageToImageInput, ImageToImageOutput, ImageToImageParameters, ImageToImageTargetSize
+from .image_to_text import (
+    ImageToTextEarlyStoppingEnum,
+    ImageToTextGenerationParameters,
+    ImageToTextInput,
+    ImageToTextOutput,
+    ImageToTextParameters,
+)
+from .image_to_video import ImageToVideoInput, ImageToVideoOutput, ImageToVideoParameters, ImageToVideoTargetSize
+from .object_detection import (
+    ObjectDetectionBoundingBox,
+    ObjectDetectionInput,
+    ObjectDetectionOutputElement,
+    ObjectDetectionParameters,
+)
+from .question_answering import (
+    QuestionAnsweringInput,
+    QuestionAnsweringInputData,
+    QuestionAnsweringOutputElement,
+    QuestionAnsweringParameters,
+)
+from .sentence_similarity import SentenceSimilarityInput, SentenceSimilarityInputData
+from .summarization import (
+    SummarizationInput,
+    SummarizationOutput,
+    SummarizationParameters,
+    SummarizationTruncationStrategy,
+)
+from .table_question_answering import (
+    Padding,
+    TableQuestionAnsweringInput,
+    TableQuestionAnsweringInputData,
+    TableQuestionAnsweringOutputElement,
+    TableQuestionAnsweringParameters,
+)
+from .text2text_generation import (
+    Text2TextGenerationInput,
+    Text2TextGenerationOutput,
+    Text2TextGenerationParameters,
+    Text2TextGenerationTruncationStrategy,
+)
+from .text_classification import (
+    TextClassificationInput,
+    TextClassificationOutputElement,
+    TextClassificationOutputTransform,
+    TextClassificationParameters,
+)
+from .text_generation import (
+    TextGenerationInput,
+    TextGenerationInputGenerateParameters,
+    TextGenerationInputGrammarType,
+    TextGenerationOutput,
+    TextGenerationOutputBestOfSequence,
+    TextGenerationOutputDetails,
+    TextGenerationOutputFinishReason,
+    TextGenerationOutputPrefillToken,
+    TextGenerationOutputToken,
+    TextGenerationStreamOutput,
+    TextGenerationStreamOutputStreamDetails,
+    TextGenerationStreamOutputToken,
+    TypeEnum,
+)
+from .text_to_audio import (
+    TextToAudioEarlyStoppingEnum,
+    TextToAudioGenerationParameters,
+    TextToAudioInput,
+    TextToAudioOutput,
+    TextToAudioParameters,
+)
+from .text_to_image import TextToImageInput, TextToImageOutput, TextToImageParameters
+from .text_to_speech import (
+    TextToSpeechEarlyStoppingEnum,
+    TextToSpeechGenerationParameters,
+    TextToSpeechInput,
+    TextToSpeechOutput,
+    TextToSpeechParameters,
+)
+from .text_to_video import TextToVideoInput, TextToVideoOutput, TextToVideoParameters
+from .token_classification import (
+    TokenClassificationAggregationStrategy,
+    TokenClassificationInput,
+    TokenClassificationOutputElement,
+    TokenClassificationParameters,
+)
+from .translation import TranslationInput, TranslationOutput, TranslationParameters, TranslationTruncationStrategy
+from .video_classification import (
+    VideoClassificationInput,
+    VideoClassificationOutputElement,
+    VideoClassificationOutputTransform,
+    VideoClassificationParameters,
+)
+from .visual_question_answering import (
+    VisualQuestionAnsweringInput,
+    VisualQuestionAnsweringInputData,
+    VisualQuestionAnsweringOutputElement,
+    VisualQuestionAnsweringParameters,
+)
+from .zero_shot_classification import (
+    ZeroShotClassificationInput,
+    ZeroShotClassificationOutputElement,
+    ZeroShotClassificationParameters,
+)
+from .zero_shot_image_classification import (
+    ZeroShotImageClassificationInput,
+    ZeroShotImageClassificationOutputElement,
+    ZeroShotImageClassificationParameters,
+)
+from .zero_shot_object_detection import (
+    ZeroShotObjectDetectionBoundingBox,
+    ZeroShotObjectDetectionInput,
+    ZeroShotObjectDetectionOutputElement,
+    ZeroShotObjectDetectionParameters,
+)