72cce7d5913aad64af86c29560a31d664b4ae723604106669ab386e118a0be60

lib/python3.11/site-packages/huggingface_hub/_tensorboard_logger.py

@@ -0,0 +1,168 @@
+# 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 TYPE_CHECKING, List, Optional, Union
+
+from huggingface_hub._commit_scheduler import CommitScheduler
+
+from .utils import experimental, is_tensorboard_available
+
+
+if is_tensorboard_available():
+    from tensorboardX import SummaryWriter
+
+    # TODO: clarify: should we import from torch.utils.tensorboard ?
+
+else:
+    SummaryWriter = object  # Dummy class to avoid failing at import. Will raise on instance creation.
+
+if TYPE_CHECKING:
+    from tensorboardX import SummaryWriter
+
+
+class HFSummaryWriter(SummaryWriter):
+    """
+    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).
+
+    <Tip warning={true}>
+
+    `HFSummaryWriter` is experimental. Its API is subject to change in the future without prior notice.
+
+    </Tip>
+
+    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 create a private repo or not. Defaults to False. This argument 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:
+    ```py
+    >>> from huggingface_hub import HFSummaryWriter
+
+    # Logs are automatically pushed every 15 minutes
+    >>> logger = HFSummaryWriter(repo_id="test_hf_logger", commit_every=15)
+    >>> logger.add_scalar("a", 1)
+    >>> logger.add_scalar("b", 2)
+    ...
+
+    # You can also trigger a push manually
+    >>> logger.scheduler.trigger()
+    ```
+
+    ```py
+    >>> from huggingface_hub import HFSummaryWriter
+
+    # Logs are automatically pushed every 5 minutes (default) + when exiting the context manager
+    >>> with HFSummaryWriter(repo_id="test_hf_logger") as logger:
+    ...     logger.add_scalar("a", 1)
+    ...     logger.add_scalar("b", 2)
+    ```
+    """
+
+    @experimental
+    def __new__(cls, *args, **kwargs) -> "HFSummaryWriter":
+        if not is_tensorboard_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: bool = False,
+        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
+
+    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()

lib/python3.11/site-packages/huggingface_hub/_webhooks_payload.py

@@ -0,0 +1,115 @@
+# 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 List, Literal, Optional
+
+from pydantic import BaseModel
+
+
+# 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 WebhookPayload(BaseModel):
+    event: WebhookPayloadEvent
+    repo: WebhookPayloadRepo
+    discussion: Optional[WebhookPayloadDiscussion] = None
+    comment: Optional[WebhookPayloadComment] = None
+    webhook: WebhookPayloadWebhook
+    movedTo: Optional[WebhookPayloadMovedTo] = None

lib/python3.11/site-packages/huggingface_hub/_webhooks_server.py

@@ -0,0 +1,379 @@
+# 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, Dict, Optional
+
+from .utils import experimental, is_gradio_available
+from .utils._deprecation import _deprecate_method
+
+
+if TYPE_CHECKING:
+    import gradio as gr
+
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+
+_global_app: Optional["WebhooksServer"] = None
+_is_local = os.getenv("SYSTEM") != "spaces"
+
+
+@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 `run` 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 setup your
+    WebhooksServer and deploy it on a Space.
+
+    <Tip warning={true}>
+
+    `WebhooksServer` is experimental. Its API is subject to change in the future.
+
+    </Tip>
+
+    <Tip warning={true}>
+
+    You must have `gradio` installed to use `WebhooksServer` (`pip install --upgrade gradio`).
+
+    </Tip>
+
+    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.run()
+        ```
+    """
+
+    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."
+            )
+        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.run()
+        ```
+        """
+        # 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
+        url = (ui.share_url or ui.local_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()
+
+    @_deprecate_method(version="0.23", message="Use `WebhooksServer.launch` instead.")
+    def run(self) -> None:
+        return self.launch()
+
+    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 setup your
+    server and deploy it on a Space.
+
+    <Tip warning={true}>
+
+    `webhook_endpoint` is experimental. Its API is subject to change in the future.
+
+    </Tip>
+
+    <Tip warning={true}>
+
+    You must have `gradio` installed to use `webhook_endpoint` (`pip install --upgrade gradio`).
+
+    </Tip>
+
+    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.run()
+        ```
+    """
+    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.run` to run at exit (only once)
+            atexit.register(app.run)
+
+        @wraps(app.run)
+        def _run_now():
+            # Run the app directly (without waiting atexit)
+            atexit.unregister(app.run)
+            app.run()
+
+        func.run = _run_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

lib/python3.11/site-packages/huggingface_hub/commands/__init__.py

@@ -0,0 +1,27 @@
+# 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 abc import ABC, abstractmethod
+from argparse import _SubParsersAction
+
+
+class BaseHuggingfaceCLICommand(ABC):
+    @staticmethod
+    @abstractmethod
+    def register_subcommand(parser: _SubParsersAction):
+        raise NotImplementedError()
+
+    @abstractmethod
+    def run(self):
+        raise NotImplementedError()

lib/python3.11/site-packages/huggingface_hub/commands/_cli_utils.py

@@ -0,0 +1,63 @@
+# 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 a utility for good-looking prints."""
+import os
+from typing import List, Union
+
+
+class ANSI:
+    """
+    Helper for en.wikipedia.org/wiki/ANSI_escape_code
+    """
+
+    _bold = "\u001b[1m"
+    _gray = "\u001b[90m"
+    _red = "\u001b[31m"
+    _reset = "\u001b[0m"
+
+    @classmethod
+    def bold(cls, s: str) -> str:
+        return cls._format(s, cls._bold)
+
+    @classmethod
+    def gray(cls, s: str) -> str:
+        return cls._format(s, cls._gray)
+
+    @classmethod
+    def red(cls, s: str) -> str:
+        return cls._format(s, cls._bold + cls._red)
+
+    @classmethod
+    def _format(cls, s: str, code: str) -> str:
+        if os.environ.get("NO_COLOR"):
+            # See https://no-color.org/
+            return s
+        return f"{code}{s}{cls._reset}"
+
+
+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)]
+    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:
+        lines.append(row_format.format(*row))
+    return "\n".join(lines)

lib/python3.11/site-packages/huggingface_hub/commands/delete_cache.py

@@ -0,0 +1,427 @@
+# coding=utf-8
+# Copyright 2022-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 delete some revisions from the HF cache directory.
+
+Usage:
+    huggingface-cli delete-cache
+    huggingface-cli delete-cache --disable-tui
+    huggingface-cli delete-cache --dir ~/.cache/huggingface/hub
+
+NOTE:
+    This command is based on `InquirerPy` to build the multiselect menu in the terminal.
+    This dependency has to be installed with `pip install huggingface_hub[cli]`. Since
+    we want to avoid as much as possible cross-platform issues, I chose a library that
+    is built on top of `python-prompt-toolkit` which seems to be a reference in terminal
+    GUI (actively maintained on both Unix and Windows, 7.9k stars).
+
+    For the moment, the TUI feature is in beta.
+
+    See:
+    - https://github.com/kazhala/InquirerPy
+    - https://inquirerpy.readthedocs.io/en/latest/
+    - https://github.com/prompt-toolkit/python-prompt-toolkit
+
+    Other solutions could have been:
+    - `simple_term_menu`: would be good as well for our use case but some issues suggest
+      that Windows is less supported.
+      See: https://github.com/IngoMeyer441/simple-term-menu
+    - `PyInquirer`: very similar to `InquirerPy` but older and not maintained anymore.
+      In particular, no support of Python3.10.
+      See: https://github.com/CITGuru/PyInquirer
+    - `pick` (or `pickpack`): easy to use and flexible but built on top of Python's
+      standard library `curses` that is specific to Unix (not implemented on Windows).
+      See https://github.com/wong2/pick and https://github.com/anafvana/pickpack.
+    - `inquirer`: lot of traction (700 stars) but explicitly states "experimental
+      support of Windows". Not built on top of `python-prompt-toolkit`.
+      See https://github.com/magmax/python-inquirer
+
+TODO: add support for `huggingface-cli delete-cache aaaaaa bbbbbb cccccc (...)` ?
+TODO: add "--keep-last" arg to delete revisions that are not on `main` ref
+TODO: add "--filter" arg to filter repositories by name ?
+TODO: add "--sort" arg to sort by size ?
+TODO: add "--limit" arg to limit to X repos ?
+TODO: add "-y" arg for immediate deletion ?
+See discussions in https://github.com/huggingface/huggingface_hub/issues/1025.
+"""
+import os
+from argparse import Namespace, _SubParsersAction
+from functools import wraps
+from tempfile import mkstemp
+from typing import Any, Callable, Iterable, List, Optional, Union
+
+from ..utils import CachedRepoInfo, CachedRevisionInfo, HFCacheInfo, scan_cache_dir
+from . import BaseHuggingfaceCLICommand
+from ._cli_utils import ANSI
+
+
+try:
+    from InquirerPy import inquirer
+    from InquirerPy.base.control import Choice
+    from InquirerPy.separator import Separator
+
+    _inquirer_py_available = True
+except ImportError:
+    _inquirer_py_available = False
+
+
+def require_inquirer_py(fn: Callable) -> Callable:
+    """Decorator to flag methods that require `InquirerPy`."""
+
+    # TODO: refactor this + imports in a unified pattern across codebase
+    @wraps(fn)
+    def _inner(*args, **kwargs):
+        if not _inquirer_py_available:
+            raise ImportError(
+                "The `delete-cache` command requires extra dependencies to work with"
+                " the TUI.\nPlease run `pip install huggingface_hub[cli]` to install"
+                " them.\nOtherwise, disable TUI using the `--disable-tui` flag."
+            )
+
+        return fn(*args, **kwargs)
+
+    return _inner
+
+
+# Possibility for the user to cancel deletion
+_CANCEL_DELETION_STR = "CANCEL_DELETION"
+
+
+class DeleteCacheCommand(BaseHuggingfaceCLICommand):
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        delete_cache_parser = parser.add_parser("delete-cache", help="Delete revisions from the cache directory.")
+
+        delete_cache_parser.add_argument(
+            "--dir",
+            type=str,
+            default=None,
+            help="cache directory (optional). Default to the default HuggingFace cache.",
+        )
+
+        delete_cache_parser.add_argument(
+            "--disable-tui",
+            action="store_true",
+            help=(
+                "Disable Terminal User Interface (TUI) mode. Useful if your"
+                " platform/terminal doesn't support the multiselect menu."
+            ),
+        )
+
+        delete_cache_parser.set_defaults(func=DeleteCacheCommand)
+
+    def __init__(self, args: Namespace) -> None:
+        self.cache_dir: Optional[str] = args.dir
+        self.disable_tui: bool = args.disable_tui
+
+    def run(self):
+        """Run `delete-cache` command with or without TUI."""
+        # Scan cache directory
+        hf_cache_info = scan_cache_dir(self.cache_dir)
+
+        # Manual review from the user
+        if self.disable_tui:
+            selected_hashes = _manual_review_no_tui(hf_cache_info, preselected=[])
+        else:
+            selected_hashes = _manual_review_tui(hf_cache_info, preselected=[])
+
+        # If deletion is not cancelled
+        if len(selected_hashes) > 0 and _CANCEL_DELETION_STR not in selected_hashes:
+            confirm_message = _get_expectations_str(hf_cache_info, selected_hashes) + " Confirm deletion ?"
+
+            # Confirm deletion
+            if self.disable_tui:
+                confirmed = _ask_for_confirmation_no_tui(confirm_message)
+            else:
+                confirmed = _ask_for_confirmation_tui(confirm_message)
+
+            # Deletion is confirmed
+            if confirmed:
+                strategy = hf_cache_info.delete_revisions(*selected_hashes)
+                print("Start deletion.")
+                strategy.execute()
+                print(
+                    f"Done. Deleted {len(strategy.repos)} repo(s) and"
+                    f" {len(strategy.snapshots)} revision(s) for a total of"
+                    f" {strategy.expected_freed_size_str}."
+                )
+                return
+
+        # Deletion is cancelled
+        print("Deletion is cancelled. Do nothing.")
+
+
+@require_inquirer_py
+def _manual_review_tui(hf_cache_info: HFCacheInfo, preselected: List[str]) -> List[str]:
+    """Ask the user for a manual review of the revisions to delete.
+
+    Displays a multi-select menu in the terminal (TUI).
+    """
+    # Define multiselect list
+    choices = _get_tui_choices_from_scan(repos=hf_cache_info.repos, preselected=preselected)
+    checkbox = inquirer.checkbox(
+        message="Select revisions to delete:",
+        choices=choices,  # List of revisions with some pre-selection
+        cycle=False,  # No loop between top and bottom
+        height=100,  # Large list if possible
+        # We use the instruction to display to the user the expected effect of the
+        # deletion.
+        instruction=_get_expectations_str(
+            hf_cache_info,
+            selected_hashes=[c.value for c in choices if isinstance(c, Choice) and c.enabled],
+        ),
+        # We use the long instruction to should keybindings instructions to the user
+        long_instruction="Press <space> to select, <enter> to validate and <ctrl+c> to quit without modification.",
+        # Message that is displayed once the user validates its selection.
+        transformer=lambda result: f"{len(result)} revision(s) selected.",
+    )
+
+    # Add a callback to update the information line when a revision is
+    # selected/unselected
+    def _update_expectations(_) -> None:
+        # Hacky way to dynamically set an instruction message to the checkbox when
+        # a revision hash is selected/unselected.
+        checkbox._instruction = _get_expectations_str(
+            hf_cache_info,
+            selected_hashes=[choice["value"] for choice in checkbox.content_control.choices if choice["enabled"]],
+        )
+
+    checkbox.kb_func_lookup["toggle"].append({"func": _update_expectations})
+
+    # Finally display the form to the user.
+    try:
+        return checkbox.execute()
+    except KeyboardInterrupt:
+        return []  # Quit without deletion
+
+
+@require_inquirer_py
+def _ask_for_confirmation_tui(message: str, default: bool = True) -> bool:
+    """Ask for confirmation using Inquirer."""
+    return inquirer.confirm(message, default=default).execute()
+
+
+def _get_tui_choices_from_scan(repos: Iterable[CachedRepoInfo], preselected: List[str]) -> List:
+    """Build a list of choices from the scanned repos.
+
+    Args:
+        repos (*Iterable[`CachedRepoInfo`]*):
+            List of scanned repos on which we want to delete revisions.
+        preselected (*List[`str`]*):
+            List of revision hashes that will be preselected.
+
+    Return:
+        The list of choices to pass to `inquirer.checkbox`.
+    """
+    choices: List[Union[Choice, Separator]] = []
+
+    # First choice is to cancel the deletion. If selected, nothing will be deleted,
+    # no matter the other selected items.
+    choices.append(
+        Choice(
+            _CANCEL_DELETION_STR,
+            name="None of the following (if selected, nothing will be deleted).",
+            enabled=False,
+        )
+    )
+
+    # Display a separator per repo and a Choice for each revisions of the repo
+    for repo in sorted(repos, key=_repo_sorting_order):
+        # Repo as separator
+        choices.append(
+            Separator(
+                f"\n{repo.repo_type.capitalize()} {repo.repo_id} ({repo.size_on_disk_str},"
+                f" used {repo.last_accessed_str})"
+            )
+        )
+        for revision in sorted(repo.revisions, key=_revision_sorting_order):
+            # Revision as choice
+            choices.append(
+                Choice(
+                    revision.commit_hash,
+                    name=(
+                        f"{revision.commit_hash[:8]}:"
+                        f" {', '.join(sorted(revision.refs)) or '(detached)'} #"
+                        f" modified {revision.last_modified_str}"
+                    ),
+                    enabled=revision.commit_hash in preselected,
+                )
+            )
+
+    # Return choices
+    return choices
+
+
+def _manual_review_no_tui(hf_cache_info: HFCacheInfo, preselected: List[str]) -> List[str]:
+    """Ask the user for a manual review of the revisions to delete.
+
+    Used when TUI is disabled. Manual review happens in a separate tmp file that the
+    user can manually edit.
+    """
+    # 1. Generate temporary file with delete commands.
+    fd, tmp_path = mkstemp(suffix=".txt")  # suffix to make it easier to find by editors
+    os.close(fd)
+
+    lines = []
+    for repo in sorted(hf_cache_info.repos, key=_repo_sorting_order):
+        lines.append(
+            f"\n# {repo.repo_type.capitalize()} {repo.repo_id} ({repo.size_on_disk_str},"
+            f" used {repo.last_accessed_str})"
+        )
+        for revision in sorted(repo.revisions, key=_revision_sorting_order):
+            lines.append(
+                # Deselect by prepending a '#'
+                f"{'' if revision.commit_hash in preselected else '#'}   "
+                f" {revision.commit_hash} # Refs:"
+                # Print `refs` as comment on same line
+                f" {', '.join(sorted(revision.refs)) or '(detached)'} # modified"
+                # Print `last_modified` as comment on same line
+                f" {revision.last_modified_str}"
+            )
+
+    with open(tmp_path, "w") as f:
+        f.write(_MANUAL_REVIEW_NO_TUI_INSTRUCTIONS)
+        f.write("\n".join(lines))
+
+    # 2. Prompt instructions to user.
+    instructions = f"""
+    TUI is disabled. In order to select which revisions you want to delete, please edit
+    the following file using the text editor of your choice. Instructions for manual
+    editing are located at the beginning of the file. Edit the file, save it and confirm
+    to continue.
+    File to edit: {ANSI.bold(tmp_path)}
+    """
+    print("\n".join(line.strip() for line in instructions.strip().split("\n")))
+
+    # 3. Wait for user confirmation.
+    while True:
+        selected_hashes = _read_manual_review_tmp_file(tmp_path)
+        if _ask_for_confirmation_no_tui(
+            _get_expectations_str(hf_cache_info, selected_hashes) + " Continue ?",
+            default=False,
+        ):
+            break
+
+    # 4. Return selected_hashes
+    os.remove(tmp_path)
+    return selected_hashes
+
+
+def _ask_for_confirmation_no_tui(message: str, default: bool = True) -> bool:
+    """Ask for confirmation using pure-python."""
+    YES = ("y", "yes", "1")
+    NO = ("n", "no", "0")
+    DEFAULT = ""
+    ALL = YES + NO + (DEFAULT,)
+    full_message = message + (" (Y/n) " if default else " (y/N) ")
+    while True:
+        answer = input(full_message).lower()
+        if answer == DEFAULT:
+            return default
+        if answer in YES:
+            return True
+        if answer in NO:
+            return False
+        print(f"Invalid input. Must be one of {ALL}")
+
+
+def _get_expectations_str(hf_cache_info: HFCacheInfo, selected_hashes: List[str]) -> str:
+    """Format a string to display to the user how much space would be saved.
+
+    Example:
+    ```
+    >>> _get_expectations_str(hf_cache_info, selected_hashes)
+    '7 revisions selected counting for 4.3G.'
+    ```
+    """
+    if _CANCEL_DELETION_STR in selected_hashes:
+        return "Nothing will be deleted."
+    strategy = hf_cache_info.delete_revisions(*selected_hashes)
+    return f"{len(selected_hashes)} revisions selected counting for {strategy.expected_freed_size_str}."
+
+
+def _read_manual_review_tmp_file(tmp_path: str) -> List[str]:
+    """Read the manually reviewed instruction file and return a list of revision hash.
+
+    Example:
+        ```txt
+        # This is the tmp file content
+        ###
+
+        # Commented out line
+        123456789 # revision hash
+
+        # Something else
+        #      a_newer_hash # 2 days ago
+            an_older_hash # 3 days ago
+        ```
+
+        ```py
+        >>> _read_manual_review_tmp_file(tmp_path)
+        ['123456789', 'an_older_hash']
+        ```
+    """
+    with open(tmp_path) as f:
+        content = f.read()
+
+    # Split lines
+    lines = [line.strip() for line in content.split("\n")]
+
+    # Filter commented lines
+    selected_lines = [line for line in lines if not line.startswith("#")]
+
+    # Select only before comment
+    selected_hashes = [line.split("#")[0].strip() for line in selected_lines]
+
+    # Return revision hashes
+    return [hash for hash in selected_hashes if len(hash) > 0]
+
+
+_MANUAL_REVIEW_NO_TUI_INSTRUCTIONS = f"""
+# INSTRUCTIONS
+# ------------
+# This is a temporary file created by running `huggingface-cli delete-cache` with the
+# `--disable-tui` option. It contains a set of revisions that can be deleted from your
+# local cache directory.
+#
+# Please manually review the revisions you want to delete:
+#   - Revision hashes can be commented out with '#'.
+#   - Only non-commented revisions in this file will be deleted.
+#   - Revision hashes that are removed from this file are ignored as well.
+#   - If `{_CANCEL_DELETION_STR}` line is uncommented, the all cache deletion is cancelled and
+#     no changes will be applied.
+#
+# Once you've manually reviewed this file, please confirm deletion in the terminal. This
+# file will be automatically removed once done.
+# ------------
+
+# KILL SWITCH
+# ------------
+# Un-comment following line to completely cancel the deletion process
+# {_CANCEL_DELETION_STR}
+# ------------
+
+# REVISIONS
+# ------------
+""".strip()
+
+
+def _repo_sorting_order(repo: CachedRepoInfo) -> Any:
+    # First split by Dataset/Model, then sort by last accessed (oldest first)
+    return (repo.repo_type, repo.last_accessed)
+
+
+def _revision_sorting_order(revision: CachedRevisionInfo) -> Any:
+    # Sort by last modified (oldest first)
+    return revision.last_modified

lib/python3.11/site-packages/huggingface_hub/commands/download.py

@@ -0,0 +1,214 @@
+# 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 download files from the Hub with the CLI.
+
+Usage:
+    huggingface-cli download --help
+
+    # Download file
+    huggingface-cli download gpt2 config.json
+
+    # Download entire repo
+    huggingface-cli download fffiloni/zeroscope --repo-type=space --revision=refs/pr/78
+
+    # Download repo with filters
+    huggingface-cli download gpt2 --include="*.safetensors"
+
+    # Download with token
+    huggingface-cli download Wauplin/private-model --token=hf_***
+
+    # Download quietly (no progress bar, no warnings, only the returned path)
+    huggingface-cli download gpt2 config.json --quiet
+
+    # Download to local dir
+    huggingface-cli download gpt2 --local-dir=./models/gpt2
+"""
+import warnings
+from argparse import Namespace, _SubParsersAction
+from typing import List, Literal, Optional, Union
+
+from huggingface_hub import logging
+from huggingface_hub._snapshot_download import snapshot_download
+from huggingface_hub.commands import BaseHuggingfaceCLICommand
+from huggingface_hub.constants import HF_HUB_ENABLE_HF_TRANSFER
+from huggingface_hub.file_download import hf_hub_download
+from huggingface_hub.utils import disable_progress_bars, enable_progress_bars
+
+
+logger = logging.get_logger(__name__)
+
+
+class DownloadCommand(BaseHuggingfaceCLICommand):
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        download_parser = parser.add_parser("download", help="Download files from the Hub")
+        download_parser.add_argument(
+            "repo_id", type=str, help="ID of the repo to download from (e.g. `username/repo-name`)."
+        )
+        download_parser.add_argument(
+            "filenames", type=str, nargs="*", help="Files to download (e.g. `config.json`, `data/metadata.jsonl`)."
+        )
+        download_parser.add_argument(
+            "--repo-type",
+            choices=["model", "dataset", "space"],
+            default="model",
+            help="Type of repo to download from (e.g. `dataset`).",
+        )
+        download_parser.add_argument(
+            "--revision",
+            type=str,
+            help="An optional Git revision id which can be a branch name, a tag, or a commit hash.",
+        )
+        download_parser.add_argument(
+            "--include", nargs="*", type=str, help="Glob patterns to match files to download."
+        )
+        download_parser.add_argument(
+            "--exclude", nargs="*", type=str, help="Glob patterns to exclude from files to download."
+        )
+        download_parser.add_argument(
+            "--cache-dir", type=str, help="Path to the directory where to save the downloaded files."
+        )
+        download_parser.add_argument(
+            "--local-dir",
+            type=str,
+            help=(
+                "If set, the downloaded file will be placed under this directory either as a symlink (default) or a"
+                " regular file. Check out"
+                " https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-local-folder for more"
+                " details."
+            ),
+        )
+        download_parser.add_argument(
+            "--local-dir-use-symlinks",
+            choices=["auto", "True", "False"],
+            default="auto",
+            help=(
+                "To be used with `local_dir`. If set to 'auto', the cache directory will be used and the file will be"
+                " either duplicated or symlinked to the local directory depending on its size. It set to `True`, a"
+                " symlink will be created, no matter the file size. If set to `False`, the file will either be"
+                " duplicated from cache (if already exists) or downloaded from the Hub and not cached."
+            ),
+        )
+        download_parser.add_argument(
+            "--force-download",
+            action="store_true",
+            help="If True, the files will be downloaded even if they are already cached.",
+        )
+        download_parser.add_argument(
+            "--resume-download", action="store_true", help="If True, resume a previously interrupted download."
+        )
+        download_parser.add_argument(
+            "--token", type=str, help="A User Access Token generated from https://huggingface.co/settings/tokens"
+        )
+        download_parser.add_argument(
+            "--quiet",
+            action="store_true",
+            help="If True, progress bars are disabled and only the path to the download files is printed.",
+        )
+        download_parser.set_defaults(func=DownloadCommand)
+
+    def __init__(self, args: Namespace) -> None:
+        self.token = args.token
+        self.repo_id: str = args.repo_id
+        self.filenames: List[str] = args.filenames
+        self.repo_type: str = args.repo_type
+        self.revision: Optional[str] = args.revision
+        self.include: Optional[List[str]] = args.include
+        self.exclude: Optional[List[str]] = args.exclude
+        self.cache_dir: Optional[str] = args.cache_dir
+        self.local_dir: Optional[str] = args.local_dir
+        self.force_download: bool = args.force_download
+        self.resume_download: bool = args.resume_download
+        self.quiet: bool = args.quiet
+
+        # Raise if local_dir_use_symlinks is invalid
+        self.local_dir_use_symlinks: Union[Literal["auto"], bool]
+        use_symlinks_lowercase = args.local_dir_use_symlinks.lower()
+        if use_symlinks_lowercase == "true":
+            self.local_dir_use_symlinks = True
+        elif use_symlinks_lowercase == "false":
+            self.local_dir_use_symlinks = False
+        elif use_symlinks_lowercase == "auto":
+            self.local_dir_use_symlinks = "auto"
+        else:
+            raise ValueError(
+                f"'{args.local_dir_use_symlinks}' is not a valid value for `local_dir_use_symlinks`. It must be either"
+                " 'auto', 'True' or 'False'."
+            )
+
+    def run(self) -> None:
+        if self.quiet:
+            disable_progress_bars()
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                print(self._download())  # Print path to downloaded files
+            enable_progress_bars()
+        else:
+            logging.set_verbosity_info()
+            print(self._download())  # Print path to downloaded files
+            logging.set_verbosity_warning()
+
+    def _download(self) -> str:
+        # Warn user if patterns are ignored
+        if len(self.filenames) > 0:
+            if self.include is not None and len(self.include) > 0:
+                warnings.warn("Ignoring `--include` since filenames have being explicitly set.")
+            if self.exclude is not None and len(self.exclude) > 0:
+                warnings.warn("Ignoring `--exclude` since filenames have being explicitly set.")
+
+        if not HF_HUB_ENABLE_HF_TRANSFER:
+            logger.info(
+                "Consider using `hf_transfer` for faster downloads. This solution comes with some limitations. See"
+                " https://huggingface.co/docs/huggingface_hub/hf_transfer for more details."
+            )
+
+        # Single file to download: use `hf_hub_download`
+        if len(self.filenames) == 1:
+            return hf_hub_download(
+                repo_id=self.repo_id,
+                repo_type=self.repo_type,
+                revision=self.revision,
+                filename=self.filenames[0],
+                cache_dir=self.cache_dir,
+                resume_download=self.resume_download,
+                force_download=self.force_download,
+                token=self.token,
+                local_dir=self.local_dir,
+                local_dir_use_symlinks=self.local_dir_use_symlinks,
+                library_name="huggingface-cli",
+            )
+
+        # Otherwise: use `snapshot_download` to ensure all files comes from same revision
+        elif len(self.filenames) == 0:
+            allow_patterns = self.include
+            ignore_patterns = self.exclude
+        else:
+            allow_patterns = self.filenames
+            ignore_patterns = None
+
+        return snapshot_download(
+            repo_id=self.repo_id,
+            repo_type=self.repo_type,
+            revision=self.revision,
+            allow_patterns=allow_patterns,
+            ignore_patterns=ignore_patterns,
+            resume_download=self.resume_download,
+            force_download=self.force_download,
+            cache_dir=self.cache_dir,
+            token=self.token,
+            local_dir=self.local_dir,
+            local_dir_use_symlinks=self.local_dir_use_symlinks,
+            library_name="huggingface-cli",
+        )

lib/python3.11/site-packages/huggingface_hub/commands/env.py

@@ -0,0 +1,35 @@
+# 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 command to print information about the environment.
+
+Usage:
+    huggingface-cli env
+"""
+from argparse import _SubParsersAction
+
+from ..utils import dump_environment_info
+from . import BaseHuggingfaceCLICommand
+
+
+class EnvironmentCommand(BaseHuggingfaceCLICommand):
+    def __init__(self, args):
+        self.args = args
+
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        env_parser = parser.add_parser("env", help="Print information about the environment.")
+        env_parser.set_defaults(func=EnvironmentCommand)
+
+    def run(self) -> None:
+        dump_environment_info()

lib/python3.11/site-packages/huggingface_hub/commands/huggingface_cli.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+# 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 argparse import ArgumentParser
+
+from huggingface_hub.commands.delete_cache import DeleteCacheCommand
+from huggingface_hub.commands.download import DownloadCommand
+from huggingface_hub.commands.env import EnvironmentCommand
+from huggingface_hub.commands.lfs import LfsCommands
+from huggingface_hub.commands.scan_cache import ScanCacheCommand
+from huggingface_hub.commands.upload import UploadCommand
+from huggingface_hub.commands.user import UserCommands
+
+
+def main():
+    parser = ArgumentParser("huggingface-cli", usage="huggingface-cli <command> [<args>]")
+    commands_parser = parser.add_subparsers(help="huggingface-cli command helpers")
+
+    # Register commands
+    EnvironmentCommand.register_subcommand(commands_parser)
+    UserCommands.register_subcommand(commands_parser)
+    UploadCommand.register_subcommand(commands_parser)
+    DownloadCommand.register_subcommand(commands_parser)
+    LfsCommands.register_subcommand(commands_parser)
+    ScanCacheCommand.register_subcommand(commands_parser)
+    DeleteCacheCommand.register_subcommand(commands_parser)
+
+    # Let's go
+    args = parser.parse_args()
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        exit(1)
+
+    # Run
+    service = args.func(args)
+    service.run()
+
+
+if __name__ == "__main__":
+    main()

lib/python3.11/site-packages/huggingface_hub/commands/lfs.py

@@ -0,0 +1,199 @@
+"""
+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 argparse import _SubParsersAction
+from typing import Dict, List, Optional
+
+from huggingface_hub.commands import BaseHuggingfaceCLICommand
+from huggingface_hub.lfs import LFS_MULTIPART_UPLOAD_COMMAND, SliceFileObj
+
+from ..utils import get_session, hf_raise_for_status, logging
+
+
+logger = logging.get_logger(__name__)
+
+
+class LfsCommands(BaseHuggingfaceCLICommand):
+    """
+    Implementation of a custom transfer agent for the transfer type "multipart"
+    for git-lfs. This lets users upload large files >5GB 🔥. Spec for LFS custom
+    transfer agent is:
+    https://github.com/git-lfs/git-lfs/blob/master/docs/custom-transfers.md
+
+    This introduces two commands to the CLI:
+
+    1. $ huggingface-cli lfs-enable-largefiles
+
+    This should be executed once for each model repo that contains a model file
+    >5GB. It's documented in the error message you get if you just try to git
+    push a 5GB file without having enabled it before.
+
+    2. $ huggingface-cli lfs-multipart-upload
+
+    This command is called by lfs directly and is not meant to be called by the
+    user.
+    """
+
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        enable_parser = parser.add_parser(
+            "lfs-enable-largefiles", help="Configure your repository to enable upload of files > 5GB."
+        )
+        enable_parser.add_argument("path", type=str, help="Local path to repository you want to configure.")
+        enable_parser.set_defaults(func=lambda args: LfsEnableCommand(args))
+
+        # Command will get called by git-lfs, do not call it directly.
+        upload_parser = parser.add_parser(LFS_MULTIPART_UPLOAD_COMMAND, add_help=False)
+        upload_parser.set_defaults(func=lambda args: LfsUploadCommand(args))
+
+
+class LfsEnableCommand:
+    def __init__(self, args):
+        self.args = args
+
+    def run(self):
+        local_path = os.path.abspath(self.args.path)
+        if not os.path.isdir(local_path):
+            print("This does not look like a valid git repo.")
+            exit(1)
+        subprocess.run(
+            "git config lfs.customtransfer.multipart.path huggingface-cli".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
+
+
+class LfsUploadCommand:
+    def __init__(self, args) -> None:
+        self.args = args
+
+    def run(self) -> None:
+        # 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,
+                            }
+                        )
+                        # Not precise but that's ok.
+
+            r = get_session().post(
+                completion_url,
+                json={
+                    "oid": oid,
+                    "parts": parts,
+                },
+            )
+            hf_raise_for_status(r)
+
+            write_msg({"event": "complete", "oid": oid})

lib/python3.11/site-packages/huggingface_hub/commands/scan_cache.py

@@ -0,0 +1,138 @@
+# coding=utf-8
+# Copyright 2022-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 scan the HF cache directory.
+
+Usage:
+    huggingface-cli scan-cache
+    huggingface-cli scan-cache -v
+    huggingface-cli scan-cache -vvv
+    huggingface-cli scan-cache --dir ~/.cache/huggingface/hub
+"""
+import time
+from argparse import Namespace, _SubParsersAction
+from typing import Optional
+
+from ..utils import CacheNotFound, HFCacheInfo, scan_cache_dir
+from . import BaseHuggingfaceCLICommand
+from ._cli_utils import ANSI, tabulate
+
+
+class ScanCacheCommand(BaseHuggingfaceCLICommand):
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        scan_cache_parser = parser.add_parser("scan-cache", help="Scan cache directory.")
+
+        scan_cache_parser.add_argument(
+            "--dir",
+            type=str,
+            default=None,
+            help="cache directory to scan (optional). Default to the default HuggingFace cache.",
+        )
+        scan_cache_parser.add_argument(
+            "-v",
+            "--verbose",
+            action="count",
+            default=0,
+            help="show a more verbose output",
+        )
+        scan_cache_parser.set_defaults(func=ScanCacheCommand)
+
+    def __init__(self, args: Namespace) -> None:
+        self.verbosity: int = args.verbose
+        self.cache_dir: Optional[str] = args.dir
+
+    def run(self):
+        try:
+            t0 = time.time()
+            hf_cache_info = scan_cache_dir(self.cache_dir)
+            t1 = time.time()
+        except CacheNotFound as exc:
+            cache_dir = exc.cache_dir
+            print(f"Cache directory not found: {cache_dir}")
+            return
+
+        self._print_hf_cache_info_as_table(hf_cache_info)
+
+        print(
+            f"\nDone in {round(t1-t0,1)}s. Scanned {len(hf_cache_info.repos)} repo(s)"
+            f" for a total of {ANSI.red(hf_cache_info.size_on_disk_str)}."
+        )
+        if len(hf_cache_info.warnings) > 0:
+            message = f"Got {len(hf_cache_info.warnings)} warning(s) while scanning."
+            if self.verbosity >= 3:
+                print(ANSI.gray(message))
+                for warning in hf_cache_info.warnings:
+                    print(ANSI.gray(warning))
+            else:
+                print(ANSI.gray(message + " Use -vvv to print details."))
+
+    def _print_hf_cache_info_as_table(self, hf_cache_info: HFCacheInfo) -> None:
+        if self.verbosity == 0:
+            print(
+                tabulate(
+                    rows=[
+                        [
+                            repo.repo_id,
+                            repo.repo_type,
+                            "{:>12}".format(repo.size_on_disk_str),
+                            repo.nb_files,
+                            repo.last_accessed_str,
+                            repo.last_modified_str,
+                            ", ".join(sorted(repo.refs)),
+                            str(repo.repo_path),
+                        ]
+                        for repo in sorted(hf_cache_info.repos, key=lambda repo: repo.repo_path)
+                    ],
+                    headers=[
+                        "REPO ID",
+                        "REPO TYPE",
+                        "SIZE ON DISK",
+                        "NB FILES",
+                        "LAST_ACCESSED",
+                        "LAST_MODIFIED",
+                        "REFS",
+                        "LOCAL PATH",
+                    ],
+                )
+            )
+        else:
+            print(
+                tabulate(
+                    rows=[
+                        [
+                            repo.repo_id,
+                            repo.repo_type,
+                            revision.commit_hash,
+                            "{:>12}".format(revision.size_on_disk_str),
+                            revision.nb_files,
+                            revision.last_modified_str,
+                            ", ".join(sorted(revision.refs)),
+                            str(revision.snapshot_path),
+                        ]
+                        for repo in sorted(hf_cache_info.repos, key=lambda repo: repo.repo_path)
+                        for revision in sorted(repo.revisions, key=lambda revision: revision.commit_hash)
+                    ],
+                    headers=[
+                        "REPO ID",
+                        "REPO TYPE",
+                        "REVISION",
+                        "SIZE ON DISK",
+                        "NB FILES",
+                        "LAST_MODIFIED",
+                        "REFS",
+                        "LOCAL PATH",
+                    ],
+                )
+            )

lib/python3.11/site-packages/huggingface_hub/commands/upload.py

@@ -0,0 +1,297 @@
+# 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)
+    huggingface-cli upload my-cool-model ./my-cool-model.safetensors
+
+    # Upload file (explicit)
+    huggingface-cli 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.
+    huggingface-cli upload my-cool-model
+
+    # Upload directory (explicit)
+    huggingface-cli upload my-cool-model ./models/my-cool-model .
+
+    # Upload filtered directory (example: tensorboard logs except for the last run)
+    huggingface-cli upload my-cool-model ./model/training /logs --include "*.tfevents.*" --exclude "*20230905*"
+
+    # Upload private dataset
+    huggingface-cli upload Wauplin/my-cool-dataset ./data . --repo-type=dataset --private
+
+    # Upload with token
+    huggingface-cli upload Wauplin/my-cool-model --token=hf_****
+
+    # Sync local Space with Hub (upload new files, delete removed files)
+    huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
+
+    # Schedule commits every 30 minutes
+    huggingface-cli upload Wauplin/my-cool-model --every=30
+"""
+import os
+import time
+import warnings
+from argparse import Namespace, _SubParsersAction
+from typing import List, Optional
+
+from huggingface_hub import logging
+from huggingface_hub._commit_scheduler import CommitScheduler
+from huggingface_hub.commands import BaseHuggingfaceCLICommand
+from huggingface_hub.constants import HF_HUB_ENABLE_HF_TRANSFER
+from huggingface_hub.hf_api import HfApi
+from huggingface_hub.utils import RevisionNotFoundError, disable_progress_bars, enable_progress_bars
+
+
+logger = logging.get_logger(__name__)
+
+
+class UploadCommand(BaseHuggingfaceCLICommand):
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        upload_parser = parser.add_parser("upload", help="Upload a file or a folder to a repo on the Hub")
+        upload_parser.add_argument(
+            "repo_id", type=str, help="The ID of the repo to upload to (e.g. `username/repo-name`)."
+        )
+        upload_parser.add_argument(
+            "local_path", nargs="?", help="Local path to the file or folder to upload. Defaults to current directory."
+        )
+        upload_parser.add_argument(
+            "path_in_repo",
+            nargs="?",
+            help="Path of the file or folder in the repo. Defaults to the relative path of the file or folder.",
+        )
+        upload_parser.add_argument(
+            "--repo-type",
+            choices=["model", "dataset", "space"],
+            default="model",
+            help="Type of the repo to upload to (e.g. `dataset`).",
+        )
+        upload_parser.add_argument(
+            "--revision",
+            type=str,
+            help=(
+                "An optional Git revision to push to. It can be a branch name or a PR reference. If revision does not"
+                " exist and `--create-pr` is not set, a branch will be automatically created."
+            ),
+        )
+        upload_parser.add_argument(
+            "--private",
+            action="store_true",
+            help=(
+                "Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already"
+                " exists."
+            ),
+        )
+        upload_parser.add_argument("--include", nargs="*", type=str, help="Glob patterns to match files to upload.")
+        upload_parser.add_argument(
+            "--exclude", nargs="*", type=str, help="Glob patterns to exclude from files to upload."
+        )
+        upload_parser.add_argument(
+            "--delete",
+            nargs="*",
+            type=str,
+            help="Glob patterns for file to be deleted from the repo while committing.",
+        )
+        upload_parser.add_argument(
+            "--commit-message", type=str, help="The summary / title / first line of the generated commit."
+        )
+        upload_parser.add_argument("--commit-description", type=str, help="The description of the generated commit.")
+        upload_parser.add_argument(
+            "--create-pr", action="store_true", help="Whether to upload content as a new Pull Request."
+        )
+        upload_parser.add_argument(
+            "--every",
+            type=float,
+            help="If set, a background job is scheduled to create commits every `every` minutes.",
+        )
+        upload_parser.add_argument(
+            "--token", type=str, help="A User Access Token generated from https://huggingface.co/settings/tokens"
+        )
+        upload_parser.add_argument(
+            "--quiet",
+            action="store_true",
+            help="If True, progress bars are disabled and only the path to the uploaded files is printed.",
+        )
+        upload_parser.set_defaults(func=UploadCommand)
+
+    def __init__(self, args: Namespace) -> None:
+        self.repo_id: str = args.repo_id
+        self.repo_type: Optional[str] = args.repo_type
+        self.revision: Optional[str] = args.revision
+        self.private: bool = args.private
+
+        self.include: Optional[List[str]] = args.include
+        self.exclude: Optional[List[str]] = args.exclude
+        self.delete: Optional[List[str]] = args.delete
+
+        self.commit_message: Optional[str] = args.commit_message
+        self.commit_description: Optional[str] = args.commit_description
+        self.create_pr: bool = args.create_pr
+        self.api: HfApi = HfApi(token=args.token, library_name="huggingface-cli")
+        self.quiet: bool = args.quiet  # disable warnings and progress bars
+
+        # Check `--every` is valid
+        if args.every is not None and args.every <= 0:
+            raise ValueError(f"`every` must be a positive value (got '{args.every}')")
+        self.every: Optional[float] = args.every
+
+        # Resolve `local_path` and `path_in_repo`
+        repo_name: str = args.repo_id.split("/")[-1]  # e.g. "Wauplin/my-cool-model" => "my-cool-model"
+        self.local_path: str
+        self.path_in_repo: str
+        if args.local_path is None and os.path.isfile(repo_name):
+            # Implicit case 1: user provided only a repo_id which happen to be a local file as well => upload it with same name
+            self.local_path = repo_name
+            self.path_in_repo = repo_name
+        elif args.local_path is None and os.path.isdir(repo_name):
+            # Implicit case 2: user provided only a repo_id which happen to be a local folder as well => upload it at root
+            self.local_path = repo_name
+            self.path_in_repo = "."
+        elif args.local_path is None:
+            # Implicit case 3: user provided only a repo_id that does not match a local file or folder
+            # => the user must explicitly provide a local_path => raise exception
+            raise ValueError(f"'{repo_name}' is not a local file or folder. Please set `local_path` explicitly.")
+        elif args.path_in_repo is None and os.path.isfile(args.local_path):
+            # Explicit local path to file, no path in repo => upload it at root with same name
+            self.local_path = args.local_path
+            self.path_in_repo = os.path.basename(args.local_path)
+        elif args.path_in_repo is None:
+            # Explicit local path to folder, no path in repo => upload at root
+            self.local_path = args.local_path
+            self.path_in_repo = "."
+        else:
+            # Finally, if both paths are explicit
+            self.local_path = args.local_path
+            self.path_in_repo = args.path_in_repo
+
+    def run(self) -> None:
+        if self.quiet:
+            disable_progress_bars()
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                print(self._upload())
+            enable_progress_bars()
+        else:
+            logging.set_verbosity_info()
+            print(self._upload())
+            logging.set_verbosity_warning()
+
+    def _upload(self) -> str:
+        if os.path.isfile(self.local_path):
+            if self.include is not None and len(self.include) > 0:
+                warnings.warn("Ignoring `--include` since a single file is uploaded.")
+            if self.exclude is not None and len(self.exclude) > 0:
+                warnings.warn("Ignoring `--exclude` since a single file is uploaded.")
+            if self.delete is not None and len(self.delete) > 0:
+                warnings.warn("Ignoring `--delete` since a single file is uploaded.")
+
+        if not HF_HUB_ENABLE_HF_TRANSFER:
+            logger.info(
+                "Consider using `hf_transfer` for faster uploads. This solution comes with some limitations. See"
+                " https://huggingface.co/docs/huggingface_hub/hf_transfer for more details."
+            )
+
+        # Schedule commits if `every` is set
+        if self.every is not None:
+            if os.path.isfile(self.local_path):
+                # If file => watch entire folder + use allow_patterns
+                folder_path = os.path.dirname(self.local_path)
+                path_in_repo = (
+                    self.path_in_repo[: -len(self.local_path)]  # remove filename from path_in_repo
+                    if self.path_in_repo.endswith(self.local_path)
+                    else self.path_in_repo
+                )
+                allow_patterns = [self.local_path]
+                ignore_patterns = []
+            else:
+                folder_path = self.local_path
+                path_in_repo = self.path_in_repo
+                allow_patterns = self.include or []
+                ignore_patterns = self.exclude or []
+                if self.delete is not None and len(self.delete) > 0:
+                    warnings.warn("Ignoring `--delete` when uploading with scheduled commits.")
+
+            scheduler = CommitScheduler(
+                folder_path=folder_path,
+                repo_id=self.repo_id,
+                repo_type=self.repo_type,
+                revision=self.revision,
+                allow_patterns=allow_patterns,
+                ignore_patterns=ignore_patterns,
+                path_in_repo=path_in_repo,
+                private=self.private,
+                every=self.every,
+                hf_api=self.api,
+            )
+            print(f"Scheduling commits every {self.every} minutes to {scheduler.repo_id}.")
+            try:  # Block main thread until KeyboardInterrupt
+                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(self.local_path) and not os.path.isdir(self.local_path):
+            raise FileNotFoundError(f"No such file or directory: '{self.local_path}'.")
+        repo_id = self.api.create_repo(
+            repo_id=self.repo_id,
+            repo_type=self.repo_type,
+            exist_ok=True,
+            private=self.private,
+            space_sdk="gradio" if self.repo_type == "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 `huggingface-cli repo create` for that.
+        ).repo_id
+
+        # Check if branch already exists and if not, create it
+        if self.revision is not None and not self.create_pr:
+            try:
+                self.api.repo_info(repo_id=repo_id, repo_type=self.repo_type, revision=self.revision)
+            except RevisionNotFoundError:
+                logger.info(f"Branch '{self.revision}' not found. Creating it...")
+                self.api.create_branch(repo_id=repo_id, repo_type=self.repo_type, branch=self.revision, exist_ok=True)
+                # ^ `exist_ok=True` to avoid race concurrency issues
+
+        # File-based upload
+        if os.path.isfile(self.local_path):
+            return self.api.upload_file(
+                path_or_fileobj=self.local_path,
+                path_in_repo=self.path_in_repo,
+                repo_id=repo_id,
+                repo_type=self.repo_type,
+                revision=self.revision,
+                commit_message=self.commit_message,
+                commit_description=self.commit_description,
+                create_pr=self.create_pr,
+            )
+
+        # Folder-based upload
+        else:
+            return self.api.upload_folder(
+                folder_path=self.local_path,
+                path_in_repo=self.path_in_repo,
+                repo_id=repo_id,
+                repo_type=self.repo_type,
+                revision=self.revision,
+                commit_message=self.commit_message,
+                commit_description=self.commit_description,
+                create_pr=self.create_pr,
+                allow_patterns=self.include,
+                ignore_patterns=self.exclude,
+                delete_patterns=self.delete,
+            )

lib/python3.11/site-packages/huggingface_hub/commands/user.py

@@ -0,0 +1,188 @@
+# 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.
+import subprocess
+from argparse import _SubParsersAction
+
+from requests.exceptions import HTTPError
+
+from huggingface_hub.commands import BaseHuggingfaceCLICommand
+from huggingface_hub.constants import (
+    ENDPOINT,
+    REPO_TYPES,
+    REPO_TYPES_URL_PREFIXES,
+    SPACES_SDK_TYPES,
+)
+from huggingface_hub.hf_api import HfApi
+
+from .._login import (  # noqa: F401 # for backward compatibility  # noqa: F401 # for backward compatibility
+    NOTEBOOK_LOGIN_PASSWORD_HTML,
+    NOTEBOOK_LOGIN_TOKEN_HTML_END,
+    NOTEBOOK_LOGIN_TOKEN_HTML_START,
+    login,
+    logout,
+    notebook_login,
+)
+from ..utils import get_token
+from ._cli_utils import ANSI
+
+
+class UserCommands(BaseHuggingfaceCLICommand):
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        login_parser = parser.add_parser("login", help="Log in using a token from huggingface.co/settings/tokens")
+        login_parser.add_argument(
+            "--token",
+            type=str,
+            help="Token generated from https://huggingface.co/settings/tokens",
+        )
+        login_parser.add_argument(
+            "--add-to-git-credential",
+            action="store_true",
+            help="Optional: Save token to git credential helper.",
+        )
+        login_parser.set_defaults(func=lambda args: LoginCommand(args))
+        whoami_parser = parser.add_parser("whoami", help="Find out which huggingface.co account you are logged in as.")
+        whoami_parser.set_defaults(func=lambda args: WhoamiCommand(args))
+        logout_parser = parser.add_parser("logout", help="Log out")
+        logout_parser.set_defaults(func=lambda args: LogoutCommand(args))
+
+        # new system: git-based repo system
+        repo_parser = parser.add_parser("repo", help="{create} Commands to interact with your huggingface.co repos.")
+        repo_subparsers = repo_parser.add_subparsers(help="huggingface.co repos related commands")
+        repo_create_parser = repo_subparsers.add_parser("create", help="Create a new repo on huggingface.co")
+        repo_create_parser.add_argument(
+            "name",
+            type=str,
+            help="Name for your repo. Will be namespaced under your username to build the repo id.",
+        )
+        repo_create_parser.add_argument(
+            "--type",
+            type=str,
+            help='Optional: repo_type: set to "dataset" or "space" if creating a dataset or space, default is model.',
+        )
+        repo_create_parser.add_argument("--organization", type=str, help="Optional: organization namespace.")
+        repo_create_parser.add_argument(
+            "--space_sdk",
+            type=str,
+            help='Optional: Hugging Face Spaces SDK type. Required when --type is set to "space".',
+            choices=SPACES_SDK_TYPES,
+        )
+        repo_create_parser.add_argument(
+            "-y",
+            "--yes",
+            action="store_true",
+            help="Optional: answer Yes to the prompt",
+        )
+        repo_create_parser.set_defaults(func=lambda args: RepoCreateCommand(args))
+
+
+class BaseUserCommand:
+    def __init__(self, args):
+        self.args = args
+        self._api = HfApi()
+
+
+class LoginCommand(BaseUserCommand):
+    def run(self):
+        login(token=self.args.token, add_to_git_credential=self.args.add_to_git_credential)
+
+
+class LogoutCommand(BaseUserCommand):
+    def run(self):
+        logout()
+
+
+class WhoamiCommand(BaseUserCommand):
+    def run(self):
+        token = get_token()
+        if token is None:
+            print("Not logged in")
+            exit()
+        try:
+            info = self._api.whoami(token)
+            print(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 HTTPError as e:
+            print(e)
+            print(ANSI.red(e.response.text))
+            exit(1)
+
+
+class RepoCreateCommand(BaseUserCommand):
+    def run(self):
+        token = get_token()
+        if token is None:
+            print("Not logged in")
+            exit(1)
+        try:
+            stdout = subprocess.check_output(["git", "--version"]).decode("utf-8")
+            print(ANSI.gray(stdout.strip()))
+        except FileNotFoundError:
+            print("Looks like you do not have git installed, please install.")
+
+        try:
+            stdout = subprocess.check_output(["git-lfs", "--version"]).decode("utf-8")
+            print(ANSI.gray(stdout.strip()))
+        except FileNotFoundError:
+            print(
+                ANSI.red(
+                    "Looks like you do not have git-lfs installed, please install."
+                    " You can install from https://git-lfs.github.com/."
+                    " Then run `git lfs install` (you only have to do this once)."
+                )
+            )
+        print("")
+
+        user = self._api.whoami(token)["name"]
+        namespace = self.args.organization if self.args.organization is not None else user
+
+        repo_id = f"{namespace}/{self.args.name}"
+
+        if self.args.type not in REPO_TYPES:
+            print("Invalid repo --type")
+            exit(1)
+
+        if self.args.type in REPO_TYPES_URL_PREFIXES:
+            prefixed_repo_id = REPO_TYPES_URL_PREFIXES[self.args.type] + repo_id
+        else:
+            prefixed_repo_id = repo_id
+
+        print(f"You are about to create {ANSI.bold(prefixed_repo_id)}")
+
+        if not self.args.yes:
+            choice = input("Proceed? [Y/n] ").lower()
+            if not (choice == "" or choice == "y" or choice == "yes"):
+                print("Abort")
+                exit()
+        try:
+            url = self._api.create_repo(
+                repo_id=repo_id,
+                token=token,
+                repo_type=self.args.type,
+                space_sdk=self.args.space_sdk,
+            )
+        except HTTPError as e:
+            print(e)
+            print(ANSI.red(e.response.text))
+            exit(1)
+        print("\nYour repo now lives at:")
+        print(f"  {ANSI.bold(url)}")
+        print("\nYou can clone it locally with the command below, and commit/push as usual.")
+        print(f"\n  git clone {url}")
+        print("")

lib/python3.11/site-packages/huggingface_hub/community.py

@@ -0,0 +1,354 @@
+"""
+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 List, Literal, Optional, Union
+
+from .constants import REPO_TYPE_MODEL
+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 == 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]
+
+
+@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 = dict(
+        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)

lib/python3.11/site-packages/huggingface_hub/constants.py

@@ -0,0 +1,213 @@
+import os
+import re
+import typing
+from typing import Literal, Optional, Tuple
+
+
+# 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
+HF_TRANSFER_CONCURRENCY = 100
+
+# Constants for safetensors repos
+
+SAFETENSORS_SINGLE_FILE = "model.safetensors"
+SAFETENSORS_INDEX_FILE = "model.safetensors.index.json"
+SAFETENSORS_MAX_HEADER_LENGTH = 25_000_000
+
+# 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"))
+
+ENDPOINT = os.getenv("HF_ENDPOINT") or ("https://hub-ci.huggingface.co" if _staging_mode else "https://huggingface.co")
+
+HUGGINGFACE_CO_URL_TEMPLATE = 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"
+
+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"
+
+
+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)
+
+# default cache
+default_home = os.path.join(os.path.expanduser("~"), ".cache")
+HF_HOME = os.path.expanduser(
+    os.getenv(
+        "HF_HOME",
+        os.path.join(os.getenv("XDG_CACHE_HOME", default_home), "huggingface"),
+    )
+)
+hf_cache_home = HF_HOME  # for backward compatibility. TODO: remove this in 1.0.0
+
+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.getenv("HF_HUB_CACHE", HUGGINGFACE_HUB_CACHE)
+HF_ASSETS_CACHE = 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"))
+
+# 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/
+)
+
+# In the past, token was stored in a hardcoded location
+# `_OLD_HF_TOKEN_PATH` is deprecated and will be removed "at some point".
+# See https://github.com/huggingface/huggingface_hub/issues/1232
+_OLD_HF_TOKEN_PATH = os.path.expanduser("~/.huggingface/token")
+HF_TOKEN_PATH = os.path.join(HF_HOME, "token")
+
+
+if _staging_mode:
+    # In staging mode, we use a different cache to ensure we don't mix up production and staging data or tokens
+    _staging_home = os.path.join(os.path.expanduser("~"), ".cache", "huggingface_staging")
+    HUGGINGFACE_HUB_CACHE = os.path.join(_staging_home, "hub")
+    _OLD_HF_TOKEN_PATH = os.path.join(_staging_home, "_old_token")
+    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"))
+
+# Enable fast-download using external dependency "hf_transfer"
+# See:
+# - https://pypi.org/project/hf-transfer/
+# - https://github.com/huggingface/hf_transfer (private)
+HF_HUB_ENABLE_HF_TRANSFER: bool = _is_true(os.environ.get("HF_HUB_ENABLE_HF_TRANSFER"))
+
+
+# Used if download to `local_dir` and `local_dir_use_symlinks="auto"`
+# Files smaller than 5MB are copy-pasted while bigger files are symlinked. The idea is to save disk-usage by symlinking
+# huge files (i.e. LFS files most of the time) while allowing small files to be manually edited in local folder.
+HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD: int = (
+    _as_int(os.environ.get("HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD")) or 5 * 1024 * 1024
+)
+
+# 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
+
+# List frameworks that are handled by the InferenceAPI service. Useful to scan endpoints and check which models are
+# deployed and running. Since 95% of the models are using the top 4 frameworks listed below, we scan only those by
+# default. We still keep the full list of supported frameworks in case we want to scan all of them.
+MAIN_INFERENCE_API_FRAMEWORKS = [
+    "diffusers",
+    "sentence-transformers",
+    "text-generation-inference",
+    "transformers",
+]
+
+ALL_INFERENCE_API_FRAMEWORKS = MAIN_INFERENCE_API_FRAMEWORKS + [
+    "adapter-transformers",
+    "allennlp",
+    "asteroid",
+    "bertopic",
+    "doctr",
+    "espnet",
+    "fairseq",
+    "fastai",
+    "fasttext",
+    "flair",
+    "generic",
+    "k2",
+    "keras",
+    "mindspore",
+    "nemo",
+    "open_clip",
+    "paddlenlp",
+    "peft",
+    "pyannote-audio",
+    "sklearn",
+    "spacy",
+    "span-marker",
+    "speechbrain",
+    "stanza",
+    "timm",
+]

lib/python3.11/site-packages/huggingface_hub/fastai_utils.py

@@ -0,0 +1,425 @@
+import json
+import os
+from pathlib import Path
+from pickle import DEFAULT_PROTOCOL, PicklingError
+from typing import Any, Dict, List, Optional, Union
+
+from packaging import version
+
+from huggingface_hub import snapshot_download
+from huggingface_hub.constants import CONFIG_NAME
+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
+from .utils._runtime import _PY_VERSION  # noqa: F401 # for backward compatibility...
+
+
+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.
+
+    </Tip>
+    """
+
+    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.
+
+    </Tip>
+    """
+
+    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.
+
+    </Tip>
+    """
+    _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, 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: bool = False,
+    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*, defaults to `False`):
+            Whether or not the repository created should be 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.
+
+    </Tip>
+    """
+    _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,
+        )

lib/python3.11/site-packages/huggingface_hub/file_download.py

@@ -0,0 +1,1727 @@
+import copy
+import fnmatch
+import inspect
+import io
+import json
+import os
+import re
+import shutil
+import stat
+import tempfile
+import time
+import uuid
+import warnings
+from contextlib import contextmanager
+from dataclasses import dataclass
+from functools import partial
+from pathlib import Path
+from typing import Any, BinaryIO, Dict, Generator, Literal, Optional, Tuple, Union
+from urllib.parse import quote, urlparse
+
+import requests
+from filelock import FileLock
+
+from huggingface_hub import constants
+
+from . import __version__  # noqa: F401 # for backward compatibility
+from .constants import (
+    DEFAULT_ETAG_TIMEOUT,
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_REVISION,
+    DOWNLOAD_CHUNK_SIZE,
+    ENDPOINT,
+    HF_HUB_CACHE,
+    HF_HUB_DISABLE_SYMLINKS_WARNING,
+    HF_HUB_DOWNLOAD_TIMEOUT,
+    HF_HUB_ENABLE_HF_TRANSFER,
+    HF_HUB_ETAG_TIMEOUT,
+    HF_TRANSFER_CONCURRENCY,
+    HUGGINGFACE_CO_URL_TEMPLATE,
+    HUGGINGFACE_HEADER_X_LINKED_ETAG,
+    HUGGINGFACE_HEADER_X_LINKED_SIZE,
+    HUGGINGFACE_HEADER_X_REPO_COMMIT,
+    HUGGINGFACE_HUB_CACHE,  # noqa: F401 # for backward compatibility
+    REPO_ID_SEPARATOR,
+    REPO_TYPES,
+    REPO_TYPES_URL_PREFIXES,
+)
+from .utils import (
+    EntryNotFoundError,
+    FileMetadataError,
+    GatedRepoError,
+    LocalEntryNotFoundError,
+    OfflineModeIsEnabled,
+    RepositoryNotFoundError,
+    RevisionNotFoundError,
+    SoftTemporaryDirectory,
+    build_hf_headers,
+    get_fastai_version,  # noqa: F401 # for backward compatibility
+    get_fastcore_version,  # noqa: F401 # for backward compatibility
+    get_graphviz_version,  # noqa: F401 # for backward compatibility
+    get_jinja_version,  # noqa: F401 # for backward compatibility
+    get_pydot_version,  # noqa: F401 # for backward compatibility
+    get_session,
+    get_tf_version,  # noqa: F401 # for backward compatibility
+    get_torch_version,  # noqa: F401 # for backward compatibility
+    hf_raise_for_status,
+    is_fastai_available,  # noqa: F401 # for backward compatibility
+    is_fastcore_available,  # noqa: F401 # for backward compatibility
+    is_graphviz_available,  # noqa: F401 # for backward compatibility
+    is_jinja_available,  # noqa: F401 # for backward compatibility
+    is_pydot_available,  # noqa: F401 # for backward compatibility
+    is_tf_available,  # noqa: F401 # for backward compatibility
+    is_torch_available,  # noqa: F401 # for backward compatibility
+    logging,
+    reset_sessions,
+    tqdm,
+    validate_hf_hub_args,
+)
+from .utils._deprecation import _deprecate_method
+from .utils._headers import _http_user_agent
+from .utils._runtime import _PY_VERSION  # noqa: F401 # for backward compatibility
+from .utils._typing import HTTP_METHOD_T
+from .utils.insecure_hashlib import sha256
+
+
+logger = logging.get_logger(__name__)
+
+# Regex to get filename from a "Content-Disposition" header for CDN-served files
+HEADER_FILENAME_PATTERN = re.compile(r'filename="(?P<filename>.*?)";')
+
+
+_are_symlinks_supported_in_dir: Dict[str, bool] = {}
+
+
+def are_symlinks_supported(cache_dir: Union[str, Path, None] = None) -> bool:
+    """Return whether the symlinks are supported on the machine.
+
+    Since symlinks support can change depending on the mounted disk, we need to check
+    on the precise cache folder. By default, the default HF cache directory is checked.
+
+    Args:
+        cache_dir (`str`, `Path`, *optional*):
+            Path to the folder where cached files are stored.
+
+    Returns: [bool] Whether symlinks are supported in the directory.
+    """
+    # Defaults to HF cache
+    if cache_dir is None:
+        cache_dir = HF_HUB_CACHE
+    cache_dir = str(Path(cache_dir).expanduser().resolve())  # make it unique
+
+    # Check symlink compatibility only once (per cache directory) at first time use
+    if cache_dir not in _are_symlinks_supported_in_dir:
+        _are_symlinks_supported_in_dir[cache_dir] = True
+
+        os.makedirs(cache_dir, exist_ok=True)
+        with SoftTemporaryDirectory(dir=cache_dir) as tmpdir:
+            src_path = Path(tmpdir) / "dummy_file_src"
+            src_path.touch()
+            dst_path = Path(tmpdir) / "dummy_file_dst"
+
+            # Relative source path as in `_create_symlink``
+            relative_src = os.path.relpath(src_path, start=os.path.dirname(dst_path))
+            try:
+                os.symlink(relative_src, dst_path)
+            except OSError:
+                # Likely running on Windows
+                _are_symlinks_supported_in_dir[cache_dir] = False
+
+                if not HF_HUB_DISABLE_SYMLINKS_WARNING:
+                    message = (
+                        "`huggingface_hub` cache-system uses symlinks by default to"
+                        " efficiently store duplicated files but your machine does not"
+                        f" support them in {cache_dir}. Caching files will still work"
+                        " but in a degraded version that might require more space on"
+                        " your disk. This warning can be disabled by setting the"
+                        " `HF_HUB_DISABLE_SYMLINKS_WARNING` environment variable. For"
+                        " more details, see"
+                        " https://huggingface.co/docs/huggingface_hub/how-to-cache#limitations."
+                    )
+                    if os.name == "nt":
+                        message += (
+                            "\nTo support symlinks on Windows, you either need to"
+                            " activate Developer Mode or to run Python as an"
+                            " administrator. In order to see activate developer mode,"
+                            " see this article:"
+                            " https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development"
+                        )
+                    warnings.warn(message)
+
+    return _are_symlinks_supported_in_dir[cache_dir]
+
+
+# Return value when trying to load a file from cache but the file does not exist in the distant repo.
+_CACHED_NO_EXIST = object()
+_CACHED_NO_EXIST_T = Any
+REGEX_COMMIT_HASH = re.compile(r"^[0-9a-f]{40}$")
+
+
+@dataclass(frozen=True)
+class HfFileMetadata:
+    """Data structure containing information about a file versioned on the Hub.
+
+    Returned by [`get_hf_file_metadata`] based on a URL.
+
+    Args:
+        commit_hash (`str`, *optional*):
+            The commit_hash related to the file.
+        etag (`str`, *optional*):
+            Etag of the file on the server.
+        location (`str`):
+            Location where to download the file. Can be a Hub url or not (CDN).
+        size (`size`):
+            Size of the file. In case of an LFS file, contains the size of the actual
+            LFS file, not the pointer.
+    """
+
+    commit_hash: Optional[str]
+    etag: Optional[str]
+    location: str
+    size: Optional[int]
+
+
+@validate_hf_hub_args
+def hf_hub_url(
+    repo_id: str,
+    filename: str,
+    *,
+    subfolder: Optional[str] = None,
+    repo_type: Optional[str] = None,
+    revision: Optional[str] = None,
+    endpoint: Optional[str] = None,
+) -> str:
+    """Construct the URL of a file from the given information.
+
+    The resolved address can either be a huggingface.co-hosted url, or a link to
+    Cloudfront (a Content Delivery Network, or CDN) for large files which are
+    more than a few MBs.
+
+    Args:
+        repo_id (`str`):
+            A namespace (user or an organization) name and a repo name separated
+            by a `/`.
+        filename (`str`):
+            The name of the file in the repo.
+        subfolder (`str`, *optional*):
+            An optional value corresponding to a folder inside the repo.
+        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.
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub import hf_hub_url
+
+    >>> hf_hub_url(
+    ...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
+    ... )
+    'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'
+    ```
+
+    <Tip>
+
+    Notes:
+
+        Cloudfront is replicated over the globe so downloads are way faster for
+        the end user (and it also lowers our bandwidth costs).
+
+        Cloudfront aggressively caches files by default (default TTL is 24
+        hours), however this is not an issue here because we implement a
+        git-based versioning system on huggingface.co, which means that we store
+        the files on S3/Cloudfront in a content-addressable way (i.e., the file
+        name is its hash). Using content-addressable filenames means cache can't
+        ever be stale.
+
+        In terms of client-side caching from this library, we base our caching
+        on the objects' entity tag (`ETag`), which is an identifier of a
+        specific version of a resource [1]_. An object's ETag is: its git-sha1
+        if stored in git, or its sha256 if stored in git-lfs.
+
+    </Tip>
+
+    References:
+
+    -  [1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag
+    """
+    if subfolder == "":
+        subfolder = None
+    if subfolder is not None:
+        filename = f"{subfolder}/{filename}"
+
+    if repo_type not in REPO_TYPES:
+        raise ValueError("Invalid repo type")
+
+    if repo_type in REPO_TYPES_URL_PREFIXES:
+        repo_id = REPO_TYPES_URL_PREFIXES[repo_type] + repo_id
+
+    if revision is None:
+        revision = DEFAULT_REVISION
+    url = HUGGINGFACE_CO_URL_TEMPLATE.format(
+        repo_id=repo_id, revision=quote(revision, safe=""), filename=quote(filename)
+    )
+    # Update endpoint if provided
+    if endpoint is not None and url.startswith(ENDPOINT):
+        url = endpoint + url[len(ENDPOINT) :]
+    return url
+
+
+def url_to_filename(url: str, etag: Optional[str] = None) -> str:
+    """Generate a local filename from a url.
+
+    Convert `url` into a hashed filename in a reproducible way. If `etag` is
+    specified, append its hash to the url's, delimited by a period. If the url
+    ends with .h5 (Keras HDF5 weights) adds '.h5' to the name so that TF 2.0 can
+    identify it as a HDF5 file (see
+    https://github.com/tensorflow/tensorflow/blob/00fad90125b18b80fe054de1055770cfb8fe4ba3/tensorflow/python/keras/engine/network.py#L1380)
+
+    Args:
+        url (`str`):
+            The address to the file.
+        etag (`str`, *optional*):
+            The ETag of the file.
+
+    Returns:
+        The generated filename.
+    """
+    url_bytes = url.encode("utf-8")
+    filename = sha256(url_bytes).hexdigest()
+
+    if etag:
+        etag_bytes = etag.encode("utf-8")
+        filename += "." + sha256(etag_bytes).hexdigest()
+
+    if url.endswith(".h5"):
+        filename += ".h5"
+
+    return filename
+
+
+def filename_to_url(
+    filename,
+    cache_dir: Optional[str] = None,
+    legacy_cache_layout: bool = False,
+) -> Tuple[str, str]:
+    """
+    Return the url and etag (which may be `None`) stored for `filename`. Raise
+    `EnvironmentError` if `filename` or its stored metadata do not exist.
+
+    Args:
+        filename (`str`):
+            The name of the file
+        cache_dir (`str`, *optional*):
+            The cache directory to use instead of the default one.
+        legacy_cache_layout (`bool`, *optional*, defaults to `False`):
+            If `True`, uses the legacy file cache layout i.e. just call `hf_hub_url`
+            then `cached_download`. This is deprecated as the new cache layout is
+            more powerful.
+    """
+    if not legacy_cache_layout:
+        warnings.warn(
+            "`filename_to_url` uses the legacy way cache file layout",
+            FutureWarning,
+        )
+
+    if cache_dir is None:
+        cache_dir = HF_HUB_CACHE
+    if isinstance(cache_dir, Path):
+        cache_dir = str(cache_dir)
+
+    cache_path = os.path.join(cache_dir, filename)
+    if not os.path.exists(cache_path):
+        raise EnvironmentError(f"file {cache_path} not found")
+
+    meta_path = cache_path + ".json"
+    if not os.path.exists(meta_path):
+        raise EnvironmentError(f"file {meta_path} not found")
+
+    with open(meta_path, encoding="utf-8") as meta_file:
+        metadata = json.load(meta_file)
+    url = metadata["url"]
+    etag = metadata["etag"]
+
+    return url, etag
+
+
+@_deprecate_method(version="0.22.0", message="Use `huggingface_hub.utils.build_hf_headers` instead.")
+def http_user_agent(
+    *,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    user_agent: Union[Dict, str, None] = None,
+) -> str:
+    """Deprecated in favor of [`build_hf_headers`]."""
+    return _http_user_agent(
+        library_name=library_name,
+        library_version=library_version,
+        user_agent=user_agent,
+    )
+
+
+def _request_wrapper(
+    method: HTTP_METHOD_T, url: str, *, follow_relative_redirects: bool = False, **params
+) -> requests.Response:
+    """Wrapper around requests methods to follow relative redirects if `follow_relative_redirects=True` even when
+    `allow_redirection=False`.
+
+    Args:
+        method (`str`):
+            HTTP method, such as 'GET' or 'HEAD'.
+        url (`str`):
+            The URL of the resource to fetch.
+        follow_relative_redirects (`bool`, *optional*, defaults to `False`)
+            If True, relative redirection (redirection to the same site) will be resolved even when `allow_redirection`
+            kwarg is set to False. Useful when we want to follow a redirection to a renamed repository without
+            following redirection to a CDN.
+        **params (`dict`, *optional*):
+            Params to pass to `requests.request`.
+    """
+    # Recursively follow relative redirects
+    if follow_relative_redirects:
+        response = _request_wrapper(
+            method=method,
+            url=url,
+            follow_relative_redirects=False,
+            **params,
+        )
+
+        # If redirection, we redirect only relative paths.
+        # This is useful in case of a renamed repository.
+        if 300 <= response.status_code <= 399:
+            parsed_target = urlparse(response.headers["Location"])
+            if parsed_target.netloc == "":
+                # This means it is a relative 'location' headers, as allowed by RFC 7231.
+                # (e.g. '/path/to/resource' instead of 'http://domain.tld/path/to/resource')
+                # We want to follow this relative redirect !
+                #
+                # Highly inspired by `resolve_redirects` from requests library.
+                # See https://github.com/psf/requests/blob/main/requests/sessions.py#L159
+                next_url = urlparse(url)._replace(path=parsed_target.path).geturl()
+                return _request_wrapper(method=method, url=next_url, follow_relative_redirects=True, **params)
+        return response
+
+    # Perform request and return if status_code is not in the retry list.
+    response = get_session().request(method=method, url=url, **params)
+    hf_raise_for_status(response)
+    return response
+
+
+def http_get(
+    url: str,
+    temp_file: BinaryIO,
+    *,
+    proxies=None,
+    resume_size: float = 0,
+    headers: Optional[Dict[str, str]] = None,
+    expected_size: Optional[int] = None,
+    _nb_retries: int = 5,
+):
+    """
+    Download a remote file. Do not gobble up errors, and will return errors tailored to the Hugging Face Hub.
+
+    If ConnectionError (SSLError) or ReadTimeout happen while streaming data from the server, it is most likely a
+    transient error (network outage?). We log a warning message and try to resume the download a few times before
+    giving up. The method gives up after 5 attempts if no new data has being received from the server.
+    """
+    hf_transfer = None
+    if HF_HUB_ENABLE_HF_TRANSFER:
+        if resume_size != 0:
+            warnings.warn("'hf_transfer' does not support `resume_size`: falling back to regular download method")
+        elif proxies is not None:
+            warnings.warn("'hf_transfer' does not support `proxies`: falling back to regular download method")
+        else:
+            try:
+                import hf_transfer  # type: ignore[no-redef]
+            except ImportError:
+                raise ValueError(
+                    "Fast download using 'hf_transfer' is enabled"
+                    " (HF_HUB_ENABLE_HF_TRANSFER=1) but 'hf_transfer' package is not"
+                    " available in your environment. Try `pip install hf_transfer`."
+                )
+
+    initial_headers = headers
+    headers = copy.deepcopy(headers) or {}
+    if resume_size > 0:
+        headers["Range"] = "bytes=%d-" % (resume_size,)
+
+    r = _request_wrapper(
+        method="GET", url=url, stream=True, proxies=proxies, headers=headers, timeout=HF_HUB_DOWNLOAD_TIMEOUT
+    )
+    hf_raise_for_status(r)
+    content_length = r.headers.get("Content-Length")
+
+    # NOTE: 'total' is the total number of bytes to download, not the number of bytes in the file.
+    #       If the file is compressed, the number of bytes in the saved file will be higher than 'total'.
+    total = resume_size + int(content_length) if content_length is not None else None
+
+    displayed_name = url
+    content_disposition = r.headers.get("Content-Disposition")
+    if content_disposition is not None:
+        match = HEADER_FILENAME_PATTERN.search(content_disposition)
+        if match is not None:
+            # Means file is on CDN
+            displayed_name = match.groupdict()["filename"]
+
+    # Truncate filename if too long to display
+    if len(displayed_name) > 40:
+        displayed_name = f"(…){displayed_name[-40:]}"
+
+    consistency_error_message = (
+        f"Consistency check failed: file should be of size {expected_size} but has size"
+        f" {{actual_size}} ({displayed_name}).\nWe are sorry for the inconvenience. Please retry download and"
+        " pass `force_download=True, resume_download=False` as argument.\nIf the issue persists, please let us"
+        " know by opening an issue on https://github.com/huggingface/huggingface_hub."
+    )
+
+    # Stream file to buffer
+    with tqdm(
+        unit="B",
+        unit_scale=True,
+        total=total,
+        initial=resume_size,
+        desc=displayed_name,
+        disable=bool(logger.getEffectiveLevel() == logging.NOTSET),
+    ) as progress:
+        if hf_transfer and total is not None and total > 5 * DOWNLOAD_CHUNK_SIZE:
+            supports_callback = "callback" in inspect.signature(hf_transfer.download).parameters
+            if not supports_callback:
+                warnings.warn(
+                    "You are using an outdated version of `hf_transfer`. "
+                    "Consider upgrading to latest version to enable progress bars "
+                    "using `pip install -U hf_transfer`."
+                )
+            try:
+                hf_transfer.download(
+                    url=url,
+                    filename=temp_file.name,
+                    max_files=HF_TRANSFER_CONCURRENCY,
+                    chunk_size=DOWNLOAD_CHUNK_SIZE,
+                    headers=headers,
+                    parallel_failures=3,
+                    max_retries=5,
+                    **({"callback": progress.update} if supports_callback else {}),
+                )
+            except Exception as e:
+                raise RuntimeError(
+                    "An error occurred while downloading using `hf_transfer`. Consider"
+                    " disabling HF_HUB_ENABLE_HF_TRANSFER for better error handling."
+                ) from e
+            if not supports_callback:
+                progress.update(total)
+            if expected_size is not None and expected_size != os.path.getsize(temp_file.name):
+                raise EnvironmentError(
+                    consistency_error_message.format(
+                        actual_size=os.path.getsize(temp_file.name),
+                    )
+                )
+            return
+        new_resume_size = resume_size
+        try:
+            for chunk in r.iter_content(chunk_size=DOWNLOAD_CHUNK_SIZE):
+                if chunk:  # filter out keep-alive new chunks
+                    progress.update(len(chunk))
+                    temp_file.write(chunk)
+                    new_resume_size += len(chunk)
+                    # Some data has been downloaded from the server so we reset the number of retries.
+                    _nb_retries = 5
+        except (requests.ConnectionError, requests.ReadTimeout) as e:
+            # If ConnectionError (SSLError) or ReadTimeout happen while streaming data from the server, it is most likely
+            # a transient error (network outage?). We log a warning message and try to resume the download a few times
+            # before giving up. Tre retry mechanism is basic but should be enough in most cases.
+            if _nb_retries <= 0:
+                logger.warning("Error while downloading from %s: %s\nMax retries exceeded.", url, str(e))
+                raise
+            logger.warning("Error while downloading from %s: %s\nTrying to resume download...", url, str(e))
+            time.sleep(1)
+            reset_sessions()  # In case of SSLError it's best to reset the shared requests.Session objects
+            return http_get(
+                url=url,
+                temp_file=temp_file,
+                proxies=proxies,
+                resume_size=new_resume_size,
+                headers=initial_headers,
+                expected_size=expected_size,
+                _nb_retries=_nb_retries - 1,
+            )
+
+        if expected_size is not None and expected_size != temp_file.tell():
+            raise EnvironmentError(
+                consistency_error_message.format(
+                    actual_size=temp_file.tell(),
+                )
+            )
+
+
+@validate_hf_hub_args
+def cached_download(
+    url: str,
+    *,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    cache_dir: Union[str, Path, None] = None,
+    user_agent: Union[Dict, str, None] = None,
+    force_download: bool = False,
+    force_filename: Optional[str] = None,
+    proxies: Optional[Dict] = None,
+    etag_timeout: float = DEFAULT_ETAG_TIMEOUT,
+    resume_download: bool = False,
+    token: Union[bool, str, None] = None,
+    local_files_only: bool = False,
+    legacy_cache_layout: bool = False,
+) -> str:
+    """
+    Download from a given URL and cache it if it's not already present in the
+    local cache.
+
+    Given a URL, this function looks for the corresponding file in the local
+    cache. If it's not there, download it. Then return the path to the cached
+    file.
+
+    Will raise errors tailored to the Hugging Face Hub.
+
+    Args:
+        url (`str`):
+            The path to the file to be downloaded.
+        library_name (`str`, *optional*):
+            The name of the library to which the object corresponds.
+        library_version (`str`, *optional*):
+            The version of the library.
+        cache_dir (`str`, `Path`, *optional*):
+            Path to the folder where cached files are stored.
+        user_agent (`dict`, `str`, *optional*):
+            The user-agent info in the form of a dictionary or a string.
+        force_download (`bool`, *optional*, defaults to `False`):
+            Whether the file should be downloaded even if it already exists in
+            the local cache.
+        force_filename (`str`, *optional*):
+            Use this name instead of a generated file name.
+        proxies (`dict`, *optional*):
+            Dictionary mapping protocol to the URL of the proxy passed to
+            `requests.request`.
+        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 `requests.request`.
+        resume_download (`bool`, *optional*, defaults to `False`):
+            If `True`, resume a previously interrupted download.
+        token (`bool`, `str`, *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.
+        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.
+        legacy_cache_layout (`bool`, *optional*, defaults to `False`):
+            Set this parameter to `True` to mention that you'd like to continue
+            the old cache layout. Putting this to `True` manually will not raise
+            any warning when using `cached_download`. We recommend using
+            `hf_hub_download` to take advantage of the new cache.
+
+    Returns:
+        Local path (string) of file or if networking is off, last version of
+        file cached on disk.
+
+    <Tip>
+
+    Raises the following errors:
+
+        - [`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
+        - [`~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.
+        - [`~utils.EntryNotFoundError`]
+          If the file to download cannot be found.
+        - [`~utils.LocalEntryNotFoundError`]
+          If network is disabled or unavailable and file is not found in cache.
+
+    </Tip>
+    """
+    if HF_HUB_ETAG_TIMEOUT != DEFAULT_ETAG_TIMEOUT:
+        # Respect environment variable above user value
+        etag_timeout = HF_HUB_ETAG_TIMEOUT
+
+    if not legacy_cache_layout:
+        warnings.warn(
+            "'cached_download' is the legacy way to download files from the HF hub, please consider upgrading to"
+            " 'hf_hub_download'",
+            FutureWarning,
+        )
+
+    if cache_dir is None:
+        cache_dir = HF_HUB_CACHE
+    if isinstance(cache_dir, Path):
+        cache_dir = str(cache_dir)
+
+    os.makedirs(cache_dir, exist_ok=True)
+
+    headers = build_hf_headers(
+        token=token,
+        library_name=library_name,
+        library_version=library_version,
+        user_agent=user_agent,
+    )
+
+    url_to_download = url
+    etag = None
+    expected_size = None
+    if not local_files_only:
+        try:
+            # Temporary header: we want the full (decompressed) content size returned to be able to check the
+            # downloaded file size
+            headers["Accept-Encoding"] = "identity"
+            r = _request_wrapper(
+                method="HEAD",
+                url=url,
+                headers=headers,
+                allow_redirects=False,
+                follow_relative_redirects=True,
+                proxies=proxies,
+                timeout=etag_timeout,
+            )
+            headers.pop("Accept-Encoding", None)
+            hf_raise_for_status(r)
+            etag = r.headers.get(HUGGINGFACE_HEADER_X_LINKED_ETAG) or r.headers.get("ETag")
+            # We favor a custom header indicating the etag of the linked resource, and
+            # we fallback to the regular etag header.
+            # If we don't have any of those, raise an error.
+            if etag is None:
+                raise FileMetadataError(
+                    "Distant resource does not have an ETag, we won't be able to reliably ensure reproducibility."
+                )
+            # We get the expected size of the file, to check the download went well.
+            expected_size = _int_or_none(r.headers.get("Content-Length"))
+            # In case of a redirect, save an extra redirect on the request.get call,
+            # and ensure we download the exact atomic version even if it changed
+            # between the HEAD and the GET (unlikely, but hey).
+            # Useful for lfs blobs that are stored on a CDN.
+            if 300 <= r.status_code <= 399:
+                url_to_download = r.headers["Location"]
+                headers.pop("authorization", None)
+                expected_size = None  # redirected -> can't know the expected size
+        except (requests.exceptions.SSLError, requests.exceptions.ProxyError):
+            # Actually raise for those subclasses of ConnectionError
+            raise
+        except (
+            requests.exceptions.ConnectionError,
+            requests.exceptions.Timeout,
+            OfflineModeIsEnabled,
+        ):
+            # Otherwise, our Internet connection is down.
+            # etag is None
+            pass
+
+    filename = force_filename if force_filename is not None else url_to_filename(url, etag)
+
+    # get cache path to put the file
+    cache_path = os.path.join(cache_dir, filename)
+
+    # etag is None == we don't have a connection or we passed local_files_only.
+    # try to get the last downloaded one
+    if etag is None:
+        if os.path.exists(cache_path) and not force_download:
+            return cache_path
+        else:
+            matching_files = [
+                file
+                for file in fnmatch.filter(os.listdir(cache_dir), filename.split(".")[0] + ".*")
+                if not file.endswith(".json") and not file.endswith(".lock")
+            ]
+            if len(matching_files) > 0 and not force_download and force_filename is None:
+                return os.path.join(cache_dir, matching_files[-1])
+            else:
+                # If files cannot be found and local_files_only=True,
+                # the models might've been found if local_files_only=False
+                # Notify the user about that
+                if local_files_only:
+                    raise LocalEntryNotFoundError(
+                        "Cannot find the requested files in the cached path and"
+                        " outgoing traffic has been disabled. To enable model look-ups"
+                        " and downloads online, set 'local_files_only' to False."
+                    )
+                else:
+                    raise LocalEntryNotFoundError(
+                        "Connection error, and we cannot find the requested files in"
+                        " the cached path. Please try again or make sure your Internet"
+                        " connection is on."
+                    )
+
+    # From now on, etag is not None.
+    if os.path.exists(cache_path) and not force_download:
+        return cache_path
+
+    # Prevent parallel downloads of the same file with a lock.
+    lock_path = cache_path + ".lock"
+
+    # Some Windows versions do not allow for paths longer than 255 characters.
+    # In this case, we must specify it is an extended path by using the "\\?\" prefix.
+    if os.name == "nt" and len(os.path.abspath(lock_path)) > 255:
+        lock_path = "\\\\?\\" + os.path.abspath(lock_path)
+
+    if os.name == "nt" and len(os.path.abspath(cache_path)) > 255:
+        cache_path = "\\\\?\\" + os.path.abspath(cache_path)
+
+    with FileLock(lock_path):
+        # If the download just completed while the lock was activated.
+        if os.path.exists(cache_path) and not force_download:
+            # Even if returning early like here, the lock will be released.
+            return cache_path
+
+        if resume_download:
+            incomplete_path = cache_path + ".incomplete"
+
+            @contextmanager
+            def _resumable_file_manager() -> Generator[io.BufferedWriter, None, None]:
+                with open(incomplete_path, "ab") as f:
+                    yield f
+
+            temp_file_manager = _resumable_file_manager
+            if os.path.exists(incomplete_path):
+                resume_size = os.stat(incomplete_path).st_size
+            else:
+                resume_size = 0
+        else:
+            temp_file_manager = partial(  # type: ignore
+                tempfile.NamedTemporaryFile, mode="wb", dir=cache_dir, delete=False
+            )
+            resume_size = 0
+
+        # Download to temporary file, then copy to cache dir once finished.
+        # Otherwise you get corrupt cache entries if the download gets interrupted.
+        with temp_file_manager() as temp_file:
+            logger.info("downloading %s to %s", url, temp_file.name)
+
+            http_get(
+                url_to_download,
+                temp_file,
+                proxies=proxies,
+                resume_size=resume_size,
+                headers=headers,
+                expected_size=expected_size,
+            )
+
+        logger.info("storing %s in cache at %s", url, cache_path)
+        _chmod_and_replace(temp_file.name, cache_path)
+
+        if force_filename is None:
+            logger.info("creating metadata file for %s", cache_path)
+            meta = {"url": url, "etag": etag}
+            meta_path = cache_path + ".json"
+            with open(meta_path, "w") as meta_file:
+                json.dump(meta, meta_file)
+
+    return cache_path
+
+
+def _normalize_etag(etag: Optional[str]) -> Optional[str]:
+    """Normalize ETag HTTP header, so it can be used to create nice filepaths.
+
+    The HTTP spec allows two forms of ETag:
+      ETag: W/"<etag_value>"
+      ETag: "<etag_value>"
+
+    For now, we only expect the second form from the server, but we want to be future-proof so we support both. For
+    more context, see `TestNormalizeEtag` tests and https://github.com/huggingface/huggingface_hub/pull/1428.
+
+    Args:
+        etag (`str`, *optional*): HTTP header
+
+    Returns:
+        `str` or `None`: string that can be used as a nice directory name.
+        Returns `None` if input is None.
+    """
+    if etag is None:
+        return None
+    return etag.lstrip("W/").strip('"')
+
+
+def _create_relative_symlink(src: str, dst: str, new_blob: bool = False) -> None:
+    """Alias method used in `transformers` conversion script."""
+    return _create_symlink(src=src, dst=dst, new_blob=new_blob)
+
+
+def _create_symlink(src: str, dst: str, new_blob: bool = False) -> None:
+    """Create a symbolic link named dst pointing to src.
+
+    By default, it will try to create a symlink using a relative path. Relative paths have 2 advantages:
+    - If the cache_folder is moved (example: back-up on a shared drive), relative paths within the cache folder will
+      not brake.
+    - Relative paths seems to be better handled on Windows. Issue was reported 3 times in less than a week when
+      changing from relative to absolute paths. See https://github.com/huggingface/huggingface_hub/issues/1398,
+      https://github.com/huggingface/diffusers/issues/2729 and https://github.com/huggingface/transformers/pull/22228.
+      NOTE: The issue with absolute paths doesn't happen on admin mode.
+    When creating a symlink from the cache to a local folder, it is possible that a relative path cannot be created.
+    This happens when paths are not on the same volume. In that case, we use absolute paths.
+
+
+    The result layout looks something like
+        └── [ 128]  snapshots
+            ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
+            │   ├── [  52]  README.md -> ../../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
+            │   └── [  76]  pytorch_model.bin -> ../../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
+
+    If symlinks cannot be created on this platform (most likely to be Windows), the workaround is to avoid symlinks by
+    having the actual file in `dst`. If it is a new file (`new_blob=True`), we move it to `dst`. If it is not a new file
+    (`new_blob=False`), we don't know if the blob file is already referenced elsewhere. To avoid breaking existing
+    cache, the file is duplicated on the disk.
+
+    In case symlinks are not supported, a warning message is displayed to the user once when loading `huggingface_hub`.
+    The warning message can be disable with the `DISABLE_SYMLINKS_WARNING` environment variable.
+    """
+    try:
+        os.remove(dst)
+    except OSError:
+        pass
+
+    abs_src = os.path.abspath(os.path.expanduser(src))
+    abs_dst = os.path.abspath(os.path.expanduser(dst))
+    abs_dst_folder = os.path.dirname(abs_dst)
+
+    # Use relative_dst in priority
+    try:
+        relative_src = os.path.relpath(abs_src, abs_dst_folder)
+    except ValueError:
+        # Raised on Windows if src and dst are not on the same volume. This is the case when creating a symlink to a
+        # local_dir instead of within the cache directory.
+        # See https://docs.python.org/3/library/os.path.html#os.path.relpath
+        relative_src = None
+
+    try:
+        commonpath = os.path.commonpath([abs_src, abs_dst])
+        _support_symlinks = are_symlinks_supported(commonpath)
+    except ValueError:
+        # Raised if src and dst are not on the same volume. Symlinks will still work on Linux/Macos.
+        # See https://docs.python.org/3/library/os.path.html#os.path.commonpath
+        _support_symlinks = os.name != "nt"
+    except PermissionError:
+        # Permission error means src and dst are not in the same volume (e.g. destination path has been provided
+        # by the user via `local_dir`. Let's test symlink support there)
+        _support_symlinks = are_symlinks_supported(abs_dst_folder)
+
+    # Symlinks are supported => let's create a symlink.
+    if _support_symlinks:
+        src_rel_or_abs = relative_src or abs_src
+        logger.debug(f"Creating pointer from {src_rel_or_abs} to {abs_dst}")
+        try:
+            os.symlink(src_rel_or_abs, abs_dst)
+            return
+        except FileExistsError:
+            if os.path.islink(abs_dst) and os.path.realpath(abs_dst) == os.path.realpath(abs_src):
+                # `abs_dst` already exists and is a symlink to the `abs_src` blob. It is most likely that the file has
+                # been cached twice concurrently (exactly between `os.remove` and `os.symlink`). Do nothing.
+                return
+            else:
+                # Very unlikely to happen. Means a file `dst` has been created exactly between `os.remove` and
+                # `os.symlink` and is not a symlink to the `abs_src` blob file. Raise exception.
+                raise
+        except PermissionError:
+            # Permission error means src and dst are not in the same volume (e.g. download to local dir) and symlink
+            # is supported on both volumes but not between them. Let's just make a hard copy in that case.
+            pass
+
+    # Symlinks are not supported => let's move or copy the file.
+    if new_blob:
+        logger.info(f"Symlink not supported. Moving file from {abs_src} to {abs_dst}")
+        shutil.move(abs_src, abs_dst)
+    else:
+        logger.info(f"Symlink not supported. Copying file from {abs_src} to {abs_dst}")
+        shutil.copyfile(abs_src, abs_dst)
+
+
+def _cache_commit_hash_for_specific_revision(storage_folder: str, revision: str, commit_hash: str) -> None:
+    """Cache reference between a revision (tag, branch or truncated commit hash) and the corresponding commit hash.
+
+    Does nothing if `revision` is already a proper `commit_hash` or reference is already cached.
+    """
+    if revision != commit_hash:
+        ref_path = Path(storage_folder) / "refs" / revision
+        ref_path.parent.mkdir(parents=True, exist_ok=True)
+        if not ref_path.exists() or commit_hash != ref_path.read_text():
+            # Update ref only if has been updated. Could cause useless error in case
+            # repo is already cached and user doesn't have write access to cache folder.
+            # See https://github.com/huggingface/huggingface_hub/issues/1216.
+            ref_path.write_text(commit_hash)
+
+
+@validate_hf_hub_args
+def repo_folder_name(*, repo_id: str, repo_type: str) -> str:
+    """Return a serialized version of a hf.co repo name and type, safe for disk storage
+    as a single non-nested folder.
+
+    Example: models--julien-c--EsperBERTo-small
+    """
+    # remove all `/` occurrences to correctly convert repo to directory name
+    parts = [f"{repo_type}s", *repo_id.split("/")]
+    return REPO_ID_SEPARATOR.join(parts)
+
+
+def _check_disk_space(expected_size: int, target_dir: Union[str, Path]) -> None:
+    """Check disk usage and log a warning if there is not enough disk space to download the file.
+
+    Args:
+        expected_size (`int`):
+            The expected size of the file in bytes.
+        target_dir (`str`):
+            The directory where the file will be stored after downloading.
+    """
+
+    target_dir = Path(target_dir)  # format as `Path`
+    for path in [target_dir] + list(target_dir.parents):  # first check target_dir, then each parents one by one
+        try:
+            target_dir_free = shutil.disk_usage(path).free
+            if target_dir_free < expected_size:
+                warnings.warn(
+                    "Not enough free disk space to download the file. "
+                    f"The expected file size is: {expected_size / 1e6:.2f} MB. "
+                    f"The target location {target_dir} only has {target_dir_free / 1e6:.2f} MB free disk space."
+                )
+            return
+        except OSError:  # raise on anything: file does not exist or space disk cannot be checked
+            pass
+
+
+@validate_hf_hub_args
+def hf_hub_download(
+    repo_id: str,
+    filename: str,
+    *,
+    subfolder: Optional[str] = None,
+    repo_type: Optional[str] = None,
+    revision: Optional[str] = None,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    cache_dir: Union[str, Path, None] = None,
+    local_dir: Union[str, Path, None] = None,
+    local_dir_use_symlinks: Union[bool, Literal["auto"]] = "auto",
+    user_agent: Union[Dict, str, None] = None,
+    force_download: bool = False,
+    force_filename: Optional[str] = None,
+    proxies: Optional[Dict] = None,
+    etag_timeout: float = DEFAULT_ETAG_TIMEOUT,
+    resume_download: bool = False,
+    token: Union[bool, str, None] = None,
+    local_files_only: bool = False,
+    legacy_cache_layout: bool = False,
+    endpoint: Optional[str] = None,
+) -> str:
+    """Download a given file if it's not already present in the local cache.
+
+    The new cache file layout looks like this:
+    - The cache directory contains one subfolder per repo_id (namespaced by repo type)
+    - inside each repo folder:
+        - refs is a list of the latest known revision => commit_hash pairs
+        - blobs contains the actual file blobs (identified by their git-sha or sha256, depending on
+          whether they're LFS files or not)
+        - snapshots contains one subfolder per commit, each "commit" contains the subset of the files
+          that have been resolved at that particular commit. Each filename is a symlink to the blob
+          at that particular commit.
+
+    If `local_dir` is provided, the file structure from the repo will be replicated in this location. You can configure
+    how you want to move those files:
+      - If `local_dir_use_symlinks="auto"` (default), files are downloaded and stored in the cache directory as blob
+        files. Small files (<5MB) are duplicated in `local_dir` while a symlink is created for bigger files. The goal
+        is to be able to manually edit and save small files without corrupting the cache while saving disk space for
+        binary files. The 5MB threshold can be configured with the `HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`
+        environment variable.
+      - If `local_dir_use_symlinks=True`, files are downloaded, stored in the cache directory and symlinked in `local_dir`.
+        This is optimal in term of disk usage but files must not be manually edited.
+      - If `local_dir_use_symlinks=False` and the blob files exist in the cache directory, they are duplicated in the
+        local dir. This means disk usage is not optimized.
+      - Finally, if `local_dir_use_symlinks=False` and the blob files do not exist in the cache directory, then the
+        files are downloaded and directly placed under `local_dir`. This means if you need to download them again later,
+        they will be re-downloaded entirely.
+
+    ```
+    [  96]  .
+    └── [ 160]  models--julien-c--EsperBERTo-small
+        ├── [ 160]  blobs
+        │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
+        │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
+        │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
+        ├── [  96]  refs
+        │   └── [  40]  main
+        └── [ 128]  snapshots
+            ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
+            │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
+            │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
+            └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
+                ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
+                └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
+    ```
+
+    Args:
+        repo_id (`str`):
+            A user or an organization name and a repo name separated by a `/`.
+        filename (`str`):
+            The name of the file in the repo.
+        subfolder (`str`, *optional*):
+            An optional value corresponding to a folder inside the model repo.
+        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.
+        library_name (`str`, *optional*):
+            The name of the library to which the object corresponds.
+        library_version (`str`, *optional*):
+            The version of the library.
+        cache_dir (`str`, `Path`, *optional*):
+            Path to the folder where cached files are stored.
+        local_dir (`str` or `Path`, *optional*):
+            If provided, the downloaded file will be placed under this directory, either as a symlink (default) or
+            a regular file (see description for more details).
+        local_dir_use_symlinks (`"auto"` or `bool`, defaults to `"auto"`):
+            To be used with `local_dir`. If set to "auto", the cache directory will be used and the file will be either
+            duplicated or symlinked to the local directory depending on its size. It set to `True`, a symlink will be
+            created, no matter the file size. If set to `False`, the file will either be duplicated from cache (if
+            already exists) or downloaded from the Hub and not cached. See description for more details.
+        user_agent (`dict`, `str`, *optional*):
+            The user-agent info in the form of a dictionary or a string.
+        force_download (`bool`, *optional*, defaults to `False`):
+            Whether the file should be downloaded even if it already exists in
+            the local cache.
+        proxies (`dict`, *optional*):
+            Dictionary mapping protocol to the URL of the proxy passed to
+            `requests.request`.
+        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 `requests.request`.
+        resume_download (`bool`, *optional*, defaults to `False`):
+            If `True`, resume a previously interrupted download.
+        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.
+        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.
+        legacy_cache_layout (`bool`, *optional*, defaults to `False`):
+            If `True`, uses the legacy file cache layout i.e. just call [`hf_hub_url`]
+            then `cached_download`. This is deprecated as the new cache layout is
+            more powerful.
+
+    Returns:
+        Local path (string) of file or if networking is off, last version of
+        file cached on disk.
+
+    <Tip>
+
+    Raises the following errors:
+
+        - [`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
+        - [`~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.
+        - [`~utils.EntryNotFoundError`]
+          If the file to download cannot be found.
+        - [`~utils.LocalEntryNotFoundError`]
+          If network is disabled or unavailable and file is not found in cache.
+
+    </Tip>
+    """
+    if HF_HUB_ETAG_TIMEOUT != DEFAULT_ETAG_TIMEOUT:
+        # Respect environment variable above user value
+        etag_timeout = HF_HUB_ETAG_TIMEOUT
+
+    if force_filename is not None:
+        warnings.warn(
+            "The `force_filename` parameter is deprecated as a new caching system, "
+            "which keeps the filenames as they are on the Hub, is now in place.",
+            FutureWarning,
+        )
+        legacy_cache_layout = True
+
+    if legacy_cache_layout:
+        url = hf_hub_url(
+            repo_id,
+            filename,
+            subfolder=subfolder,
+            repo_type=repo_type,
+            revision=revision,
+            endpoint=endpoint,
+        )
+
+        return cached_download(
+            url,
+            library_name=library_name,
+            library_version=library_version,
+            cache_dir=cache_dir,
+            user_agent=user_agent,
+            force_download=force_download,
+            force_filename=force_filename,
+            proxies=proxies,
+            etag_timeout=etag_timeout,
+            resume_download=resume_download,
+            token=token,
+            local_files_only=local_files_only,
+            legacy_cache_layout=legacy_cache_layout,
+        )
+
+    if cache_dir is None:
+        cache_dir = HF_HUB_CACHE
+    if revision is None:
+        revision = DEFAULT_REVISION
+    if isinstance(cache_dir, Path):
+        cache_dir = str(cache_dir)
+    if isinstance(local_dir, Path):
+        local_dir = str(local_dir)
+    locks_dir = os.path.join(cache_dir, ".locks")
+
+    if subfolder == "":
+        subfolder = None
+    if subfolder is not None:
+        # This is used to create a URL, and not a local path, hence the forward slash.
+        filename = f"{subfolder}/{filename}"
+
+    if repo_type is None:
+        repo_type = "model"
+    if repo_type not in REPO_TYPES:
+        raise ValueError(f"Invalid repo type: {repo_type}. Accepted repo types are: {str(REPO_TYPES)}")
+
+    storage_folder = os.path.join(cache_dir, repo_folder_name(repo_id=repo_id, repo_type=repo_type))
+    os.makedirs(storage_folder, exist_ok=True)
+
+    # cross platform transcription of filename, to be used as a local file path.
+    relative_filename = os.path.join(*filename.split("/"))
+    if os.name == "nt":
+        if relative_filename.startswith("..\\") or "\\..\\" in relative_filename:
+            raise ValueError(
+                f"Invalid filename: cannot handle filename '{relative_filename}' on Windows. Please ask the repository"
+                " owner to rename this file."
+            )
+
+    # if user provides a commit_hash and they already have the file on disk,
+    # shortcut everything.
+    if REGEX_COMMIT_HASH.match(revision):
+        pointer_path = _get_pointer_path(storage_folder, revision, relative_filename)
+        if os.path.exists(pointer_path):
+            if local_dir is not None:
+                return _to_local_dir(pointer_path, local_dir, relative_filename, use_symlinks=local_dir_use_symlinks)
+            return pointer_path
+
+    url = hf_hub_url(repo_id, filename, repo_type=repo_type, revision=revision, endpoint=endpoint)
+
+    headers = build_hf_headers(
+        token=token,
+        library_name=library_name,
+        library_version=library_version,
+        user_agent=user_agent,
+    )
+
+    url_to_download = url
+    etag = None
+    commit_hash = None
+    expected_size = None
+    head_call_error: Optional[Exception] = None
+    if not local_files_only:
+        try:
+            try:
+                metadata = get_hf_file_metadata(
+                    url=url,
+                    token=token,
+                    proxies=proxies,
+                    timeout=etag_timeout,
+                    library_name=library_name,
+                    library_version=library_version,
+                    user_agent=user_agent,
+                )
+            except EntryNotFoundError as http_error:
+                # Cache the non-existence of the file and raise
+                commit_hash = http_error.response.headers.get(HUGGINGFACE_HEADER_X_REPO_COMMIT)
+                if commit_hash is not None and not legacy_cache_layout:
+                    no_exist_file_path = Path(storage_folder) / ".no_exist" / commit_hash / relative_filename
+                    no_exist_file_path.parent.mkdir(parents=True, exist_ok=True)
+                    no_exist_file_path.touch()
+                    _cache_commit_hash_for_specific_revision(storage_folder, revision, commit_hash)
+                raise
+
+            # Commit hash must exist
+            commit_hash = metadata.commit_hash
+            if commit_hash is None:
+                raise FileMetadataError(
+                    "Distant resource does not seem to be on huggingface.co. It is possible that a configuration issue"
+                    " prevents you from downloading resources from https://huggingface.co. Please check your firewall"
+                    " and proxy settings and make sure your SSL certificates are updated."
+                )
+
+            # Etag must exist
+            etag = metadata.etag
+            # We favor a custom header indicating the etag of the linked resource, and
+            # we fallback to the regular etag header.
+            # If we don't have any of those, raise an error.
+            if etag is None:
+                raise FileMetadataError(
+                    "Distant resource does not have an ETag, we won't be able to reliably ensure reproducibility."
+                )
+
+            # Expected (uncompressed) size
+            expected_size = metadata.size
+
+            # In case of a redirect, save an extra redirect on the request.get call,
+            # and ensure we download the exact atomic version even if it changed
+            # between the HEAD and the GET (unlikely, but hey).
+            # Useful for lfs blobs that are stored on a CDN.
+            if metadata.location != url:
+                url_to_download = metadata.location
+                # Remove authorization header when downloading a LFS blob
+                headers.pop("authorization", None)
+        except (requests.exceptions.SSLError, requests.exceptions.ProxyError):
+            # Actually raise for those subclasses of ConnectionError
+            raise
+        except (
+            requests.exceptions.ConnectionError,
+            requests.exceptions.Timeout,
+            OfflineModeIsEnabled,
+        ) as error:
+            # Otherwise, our Internet connection is down.
+            # etag is None
+            head_call_error = error
+            pass
+        except (RevisionNotFoundError, EntryNotFoundError):
+            # The repo was found but the revision or entry doesn't exist on the Hub (never existed or got deleted)
+            raise
+        except requests.HTTPError 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)
+            head_call_error = error
+            pass
+        except FileMetadataError as error:
+            # Multiple reasons for a FileMetadataError:
+            # - Wrong network configuration (proxy, firewall, SSL certificates)
+            # - Inconsistency on the Hub
+            # => 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)
+            head_call_error = error
+            pass
+
+    # etag can be None for several reasons:
+    # 1. we passed local_files_only.
+    # 2. we don't have a connection
+    # 3. Hub is down (HTTP 500 or 504)
+    # 4. repo is not found -for example private or gated- and invalid/missing token sent
+    # 5. Hub is blocked by a firewall or proxy is not set correctly.
+    # => Try to get the last downloaded one from the specified revision.
+    #
+    # If the specified revision is a commit hash, look inside "snapshots".
+    # If the specified revision is a branch or tag, look inside "refs".
+    if etag is None:
+        # In those cases, we cannot force download.
+        if force_download:
+            raise ValueError(
+                "We have no connection or you passed local_files_only, so force_download is not an accepted option."
+            )
+
+        # Try to get "commit_hash" from "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.isfile(ref_path):
+                with open(ref_path) as f:
+                    commit_hash = f.read()
+
+        # Return pointer file if exists
+        if commit_hash is not None:
+            pointer_path = _get_pointer_path(storage_folder, commit_hash, relative_filename)
+            if os.path.exists(pointer_path):
+                if local_dir is not None:
+                    return _to_local_dir(
+                        pointer_path, local_dir, relative_filename, use_symlinks=local_dir_use_symlinks
+                    )
+                return pointer_path
+
+        # If we couldn't find an appropriate file on disk, raise an error.
+        # If files cannot be found and local_files_only=True,
+        # the models might've been found if local_files_only=False
+        # Notify the user about that
+        if local_files_only:
+            raise 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."
+            )
+        elif isinstance(head_call_error, RepositoryNotFoundError) or isinstance(head_call_error, GatedRepoError):
+            # Repo not found => let's raise the actual error
+            raise head_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 file on the Hub and we cannot find the requested files"
+                " in the local cache. Please check your connection and try again or make sure your Internet connection"
+                " is on."
+            ) from head_call_error
+
+    # From now on, etag and commit_hash are not None.
+    assert etag is not None, "etag must have been retrieved from server"
+    assert commit_hash is not None, "commit_hash must have been retrieved from server"
+    blob_path = os.path.join(storage_folder, "blobs", etag)
+    pointer_path = _get_pointer_path(storage_folder, commit_hash, relative_filename)
+
+    os.makedirs(os.path.dirname(blob_path), exist_ok=True)
+    os.makedirs(os.path.dirname(pointer_path), exist_ok=True)
+    # 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.
+    _cache_commit_hash_for_specific_revision(storage_folder, revision, commit_hash)
+
+    if os.path.exists(pointer_path) and not force_download:
+        if local_dir is not None:
+            return _to_local_dir(pointer_path, local_dir, relative_filename, use_symlinks=local_dir_use_symlinks)
+        return pointer_path
+
+    if os.path.exists(blob_path) and not force_download:
+        # we have the blob already, but not the pointer
+        if local_dir is not None:  # to local dir
+            return _to_local_dir(blob_path, local_dir, relative_filename, use_symlinks=local_dir_use_symlinks)
+        else:  # or in snapshot cache
+            _create_symlink(blob_path, pointer_path, new_blob=False)
+            return pointer_path
+
+    # Prevent parallel downloads of the same file with a lock.
+    # etag could be duplicated across repos,
+    lock_path = os.path.join(locks_dir, repo_folder_name(repo_id=repo_id, repo_type=repo_type), f"{etag}.lock")
+
+    # Some Windows versions do not allow for paths longer than 255 characters.
+    # In this case, we must specify it is an extended path by using the "\\?\" prefix.
+    if os.name == "nt" and len(os.path.abspath(lock_path)) > 255:
+        lock_path = "\\\\?\\" + os.path.abspath(lock_path)
+
+    if os.name == "nt" and len(os.path.abspath(blob_path)) > 255:
+        blob_path = "\\\\?\\" + os.path.abspath(blob_path)
+
+    Path(lock_path).parent.mkdir(parents=True, exist_ok=True)
+    with FileLock(lock_path):
+        # If the download just completed while the lock was activated.
+        if os.path.exists(pointer_path) and not force_download:
+            # Even if returning early like here, the lock will be released.
+            if local_dir is not None:
+                return _to_local_dir(pointer_path, local_dir, relative_filename, use_symlinks=local_dir_use_symlinks)
+            return pointer_path
+
+        if resume_download:
+            incomplete_path = blob_path + ".incomplete"
+
+            @contextmanager
+            def _resumable_file_manager() -> Generator[io.BufferedWriter, None, None]:
+                with open(incomplete_path, "ab") as f:
+                    yield f
+
+            temp_file_manager = _resumable_file_manager
+            if os.path.exists(incomplete_path):
+                resume_size = os.stat(incomplete_path).st_size
+            else:
+                resume_size = 0
+        else:
+            temp_file_manager = partial(  # type: ignore
+                tempfile.NamedTemporaryFile, mode="wb", dir=cache_dir, delete=False
+            )
+            resume_size = 0
+
+        # Download to temporary file, then copy to cache dir once finished.
+        # Otherwise you get corrupt cache entries if the download gets interrupted.
+        with temp_file_manager() as temp_file:
+            logger.info("downloading %s to %s", url, temp_file.name)
+
+            if expected_size is not None:  # might be None if HTTP header not set correctly
+                # Check tmp path
+                _check_disk_space(expected_size, os.path.dirname(temp_file.name))
+
+                # Check destination
+                _check_disk_space(expected_size, os.path.dirname(blob_path))
+                if local_dir is not None:
+                    _check_disk_space(expected_size, local_dir)
+
+            http_get(
+                url_to_download,
+                temp_file,
+                proxies=proxies,
+                resume_size=resume_size,
+                headers=headers,
+                expected_size=expected_size,
+            )
+
+        if local_dir is None:
+            logger.debug(f"Storing {url} in cache at {blob_path}")
+            _chmod_and_replace(temp_file.name, blob_path)
+            _create_symlink(blob_path, pointer_path, new_blob=True)
+        else:
+            local_dir_filepath = os.path.join(local_dir, relative_filename)
+            os.makedirs(os.path.dirname(local_dir_filepath), exist_ok=True)
+
+            # If "auto" (default) copy-paste small files to ease manual editing but symlink big files to save disk
+            # In both cases, blob file is cached.
+            is_big_file = os.stat(temp_file.name).st_size > constants.HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD
+            if local_dir_use_symlinks is True or (local_dir_use_symlinks == "auto" and is_big_file):
+                logger.debug(f"Storing {url} in cache at {blob_path}")
+                _chmod_and_replace(temp_file.name, blob_path)
+                logger.debug("Create symlink to local dir")
+                _create_symlink(blob_path, local_dir_filepath, new_blob=False)
+            elif local_dir_use_symlinks == "auto" and not is_big_file:
+                logger.debug(f"Storing {url} in cache at {blob_path}")
+                _chmod_and_replace(temp_file.name, blob_path)
+                logger.debug("Duplicate in local dir (small file and use_symlink set to 'auto')")
+                shutil.copyfile(blob_path, local_dir_filepath)
+            else:
+                logger.debug(f"Storing {url} in local_dir at {local_dir_filepath} (not cached).")
+                _chmod_and_replace(temp_file.name, local_dir_filepath)
+            pointer_path = local_dir_filepath  # for return value
+
+    return pointer_path
+
+
+@validate_hf_hub_args
+def try_to_load_from_cache(
+    repo_id: str,
+    filename: str,
+    cache_dir: Union[str, Path, None] = None,
+    revision: Optional[str] = None,
+    repo_type: Optional[str] = None,
+) -> Union[str, _CACHED_NO_EXIST_T, None]:
+    """
+    Explores the cache to return the latest cached file for a given revision if found.
+
+    This function will not raise any exception if the file in not cached.
+
+    Args:
+        cache_dir (`str` or `os.PathLike`):
+            The folder where the cached files lie.
+        repo_id (`str`):
+            The ID of the repo on huggingface.co.
+        filename (`str`):
+            The filename to look for inside `repo_id`.
+        revision (`str`, *optional*):
+            The specific model version to use. Will default to `"main"` if it's not provided and no `commit_hash` is
+            provided either.
+        repo_type (`str`, *optional*):
+            The type of the repository. Will default to `"model"`.
+
+    Returns:
+        `Optional[str]` or `_CACHED_NO_EXIST`:
+            Will return `None` if the file was not cached. Otherwise:
+            - The exact path to the cached file if it's found in the cache
+            - A special value `_CACHED_NO_EXIST` if the file does not exist at the given commit hash and this fact was
+              cached.
+
+    Example:
+
+    ```python
+    from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST
+
+    filepath = try_to_load_from_cache()
+    if isinstance(filepath, str):
+        # file exists and is cached
+        ...
+    elif filepath is _CACHED_NO_EXIST:
+        # non-existence of file is cached
+        ...
+    else:
+        # file is not cached
+        ...
+    ```
+    """
+    if revision is None:
+        revision = "main"
+    if repo_type is None:
+        repo_type = "model"
+    if repo_type not in REPO_TYPES:
+        raise ValueError(f"Invalid repo type: {repo_type}. Accepted repo types are: {str(REPO_TYPES)}")
+    if cache_dir is None:
+        cache_dir = HF_HUB_CACHE
+
+    object_id = repo_id.replace("/", "--")
+    repo_cache = os.path.join(cache_dir, f"{repo_type}s--{object_id}")
+    if not os.path.isdir(repo_cache):
+        # No cache for this model
+        return None
+
+    refs_dir = os.path.join(repo_cache, "refs")
+    snapshots_dir = os.path.join(repo_cache, "snapshots")
+    no_exist_dir = os.path.join(repo_cache, ".no_exist")
+
+    # Resolve refs (for instance to convert main to the associated commit sha)
+    if os.path.isdir(refs_dir):
+        revision_file = os.path.join(refs_dir, revision)
+        if os.path.isfile(revision_file):
+            with open(revision_file) as f:
+                revision = f.read()
+
+    # Check if file is cached as "no_exist"
+    if os.path.isfile(os.path.join(no_exist_dir, revision, filename)):
+        return _CACHED_NO_EXIST
+
+    # Check if revision folder exists
+    if not os.path.exists(snapshots_dir):
+        return None
+    cached_shas = os.listdir(snapshots_dir)
+    if revision not in cached_shas:
+        # No cache for this revision and we won't try to return a random revision
+        return None
+
+    # Check if file exists in cache
+    cached_file = os.path.join(snapshots_dir, revision, filename)
+    return cached_file if os.path.isfile(cached_file) else None
+
+
+@validate_hf_hub_args
+def get_hf_file_metadata(
+    url: str,
+    token: Union[bool, str, None] = None,
+    proxies: Optional[Dict] = None,
+    timeout: Optional[float] = DEFAULT_REQUEST_TIMEOUT,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    user_agent: Union[Dict, str, None] = None,
+) -> HfFileMetadata:
+    """Fetch metadata of a file versioned on the Hub for a given url.
+
+    Args:
+        url (`str`):
+            File url, for example returned by [`hf_hub_url`].
+        token (`str` or `bool`, *optional*):
+            A token to be used for the download.
+                - If `True`, the token is read from the HuggingFace config
+                  folder.
+                - If `False` or `None`, no token is provided.
+                - If a string, it's used as the authentication token.
+        proxies (`dict`, *optional*):
+            Dictionary mapping protocol to the URL of the proxy passed to
+            `requests.request`.
+        timeout (`float`, *optional*, defaults to 10):
+            How many seconds to wait for the server to send metadata before giving up.
+        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 (`dict`, `str`, *optional*):
+            The user-agent info in the form of a dictionary or a string.
+
+    Returns:
+        A [`HfFileMetadata`] object containing metadata such as location, etag, size and
+        commit_hash.
+    """
+    headers = build_hf_headers(
+        token=token, library_name=library_name, library_version=library_version, user_agent=user_agent
+    )
+    headers["Accept-Encoding"] = "identity"  # prevent any compression => we want to know the real size of the file
+
+    # Retrieve metadata
+    r = _request_wrapper(
+        method="HEAD",
+        url=url,
+        headers=headers,
+        allow_redirects=False,
+        follow_relative_redirects=True,
+        proxies=proxies,
+        timeout=timeout,
+    )
+    hf_raise_for_status(r)
+
+    # Return
+    return HfFileMetadata(
+        commit_hash=r.headers.get(HUGGINGFACE_HEADER_X_REPO_COMMIT),
+        # We favor a custom header indicating the etag of the linked resource, and
+        # we fallback to the regular etag header.
+        etag=_normalize_etag(r.headers.get(HUGGINGFACE_HEADER_X_LINKED_ETAG) or r.headers.get("ETag")),
+        # Either from response headers (if redirected) or defaults to request url
+        # Do not use directly `url`, as `_request_wrapper` might have followed relative
+        # redirects.
+        location=r.headers.get("Location") or r.request.url,  # type: ignore
+        size=_int_or_none(r.headers.get(HUGGINGFACE_HEADER_X_LINKED_SIZE) or r.headers.get("Content-Length")),
+    )
+
+
+def _int_or_none(value: Optional[str]) -> Optional[int]:
+    try:
+        return int(value)  # type: ignore
+    except (TypeError, ValueError):
+        return None
+
+
+def _chmod_and_replace(src: str, dst: str) -> None:
+    """Set correct permission before moving a blob from tmp directory to cache dir.
+
+    Do not take into account the `umask` from the process as there is no convenient way
+    to get it that is thread-safe.
+
+    See:
+    - About umask: https://docs.python.org/3/library/os.html#os.umask
+    - Thread-safety: https://stackoverflow.com/a/70343066
+    - About solution: https://github.com/huggingface/huggingface_hub/pull/1220#issuecomment-1326211591
+    - Fix issue: https://github.com/huggingface/huggingface_hub/issues/1141
+    - Fix issue: https://github.com/huggingface/huggingface_hub/issues/1215
+    """
+    # Get umask by creating a temporary file in the cached repo folder.
+    tmp_file = Path(dst).parent.parent / f"tmp_{uuid.uuid4()}"
+    try:
+        tmp_file.touch()
+        cache_dir_mode = Path(tmp_file).stat().st_mode
+        os.chmod(src, stat.S_IMODE(cache_dir_mode))
+    finally:
+        tmp_file.unlink()
+
+    shutil.move(src, dst)
+
+
+def _get_pointer_path(storage_folder: str, revision: str, relative_filename: str) -> str:
+    # Using `os.path.abspath` instead of `Path.resolve()` to avoid resolving symlinks
+    snapshot_path = os.path.join(storage_folder, "snapshots")
+    pointer_path = os.path.join(snapshot_path, revision, relative_filename)
+    if Path(os.path.abspath(snapshot_path)) not in Path(os.path.abspath(pointer_path)).parents:
+        raise ValueError(
+            "Invalid pointer path: cannot create pointer path in snapshot folder if"
+            f" `storage_folder='{storage_folder}'`, `revision='{revision}'` and"
+            f" `relative_filename='{relative_filename}'`."
+        )
+    return pointer_path
+
+
+def _to_local_dir(
+    path: str, local_dir: str, relative_filename: str, use_symlinks: Union[bool, Literal["auto"]]
+) -> str:
+    """Place a file in a local dir (different than cache_dir).
+
+    Either symlink to blob file in cache or duplicate file depending on `use_symlinks` and file size.
+    """
+    # Using `os.path.abspath` instead of `Path.resolve()` to avoid resolving symlinks
+    local_dir_filepath = os.path.join(local_dir, relative_filename)
+    if Path(os.path.abspath(local_dir)) not in Path(os.path.abspath(local_dir_filepath)).parents:
+        raise ValueError(
+            f"Cannot copy file '{relative_filename}' to local dir '{local_dir}': file would not be in the local"
+            " directory."
+        )
+
+    os.makedirs(os.path.dirname(local_dir_filepath), exist_ok=True)
+    real_blob_path = os.path.realpath(path)
+
+    # If "auto" (default) copy-paste small files to ease manual editing but symlink big files to save disk
+    if use_symlinks == "auto":
+        use_symlinks = os.stat(real_blob_path).st_size > constants.HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD
+
+    if use_symlinks:
+        _create_symlink(real_blob_path, local_dir_filepath, new_blob=False)
+    else:
+        shutil.copyfile(real_blob_path, local_dir_filepath)
+    return local_dir_filepath

lib/python3.11/site-packages/huggingface_hub/hf_file_system.py

@@ -0,0 +1,670 @@
+import copy
+import os
+import re
+import tempfile
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime
+from itertools import chain
+from typing import Any, Dict, List, NoReturn, Optional, Tuple, Union
+from urllib.parse import quote, unquote
+
+import fsspec
+
+from ._commit_api import CommitOperationCopy, CommitOperationDelete
+from .constants import DEFAULT_REVISION, ENDPOINT, REPO_TYPE_MODEL, REPO_TYPES_MAPPING, REPO_TYPES_URL_PREFIXES
+from .file_download import hf_hub_url
+from .hf_api import HfApi, LastCommitInfo, RepoFile
+from .utils import (
+    EntryNotFoundError,
+    HFValidationError,
+    RepositoryNotFoundError,
+    RevisionNotFoundError,
+    hf_raise_for_status,
+    http_backoff,
+)
+
+
+# Regex used to match special revisions with "/" in them (see #1710)
+SPECIAL_REFS_REVISION_REGEX = re.compile(
+    r"""
+    (^refs\/convert\/\w+)     # `refs/convert/parquet` revisions
+    |
+    (^refs\/pr\/\d+)          # PR revisions
+    """,
+    re.VERBOSE,
+)
+
+
+@dataclass
+class HfFileSystemResolvedPath:
+    """Data structure containing information about a resolved Hugging Face file system path."""
+
+    repo_type: str
+    repo_id: str
+    revision: str
+    path_in_repo: str
+    # The part placed after '@' in the initial path. It can be a quoted or unquoted refs revision.
+    # Used to reconstruct the unresolved path to return to the user.
+    _raw_revision: Optional[str] = field(default=None, repr=False)
+
+    def unresolve(self) -> str:
+        repo_path = REPO_TYPES_URL_PREFIXES.get(self.repo_type, "") + self.repo_id
+        if self._raw_revision:
+            return f"{repo_path}@{self._raw_revision}/{self.path_in_repo}".rstrip("/")
+        elif self.revision != DEFAULT_REVISION:
+            return f"{repo_path}@{safe_revision(self.revision)}/{self.path_in_repo}".rstrip("/")
+        else:
+            return f"{repo_path}/{self.path_in_repo}".rstrip("/")
+
+
+class HfFileSystem(fsspec.AbstractFileSystem):
+    """
+    Access a remote Hugging Face Hub repository as if were a local file system.
+
+    Args:
+        token (`str`, *optional*):
+            Authentication token, obtained with [`HfApi.login`] method. Will default to the stored token.
+
+    Usage:
+
+    ```python
+    >>> from huggingface_hub import HfFileSystem
+
+    >>> fs = HfFileSystem()
+
+    >>> # List files
+    >>> fs.glob("my-username/my-model/*.bin")
+    ['my-username/my-model/pytorch_model.bin']
+    >>> fs.ls("datasets/my-username/my-dataset", detail=False)
+    ['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']
+
+    >>> # Read/write files
+    >>> with fs.open("my-username/my-model/pytorch_model.bin") as f:
+    ...     data = f.read()
+    >>> with fs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
+    ...     f.write(data)
+    ```
+    """
+
+    root_marker = ""
+    protocol = "hf"
+
+    def __init__(
+        self,
+        *args,
+        endpoint: Optional[str] = None,
+        token: Optional[str] = None,
+        **storage_options,
+    ):
+        super().__init__(*args, **storage_options)
+        self.endpoint = endpoint or ENDPOINT
+        self.token = token
+        self._api = HfApi(endpoint=endpoint, token=token)
+        # Maps (repo_type, repo_id, revision) to a 2-tuple with:
+        #  * the 1st element indicating whether the repositoy and the revision exist
+        #  * the 2nd element being the exception raised if the repository or revision doesn't exist
+        self._repo_and_revision_exists_cache: Dict[
+            Tuple[str, str, Optional[str]], Tuple[bool, Optional[Exception]]
+        ] = {}
+
+    def _repo_and_revision_exist(
+        self, repo_type: str, repo_id: str, revision: Optional[str]
+    ) -> Tuple[bool, Optional[Exception]]:
+        if (repo_type, repo_id, revision) not in self._repo_and_revision_exists_cache:
+            try:
+                self._api.repo_info(repo_id, revision=revision, repo_type=repo_type)
+            except (RepositoryNotFoundError, HFValidationError) as e:
+                self._repo_and_revision_exists_cache[(repo_type, repo_id, revision)] = False, e
+                self._repo_and_revision_exists_cache[(repo_type, repo_id, None)] = False, e
+            except RevisionNotFoundError as e:
+                self._repo_and_revision_exists_cache[(repo_type, repo_id, revision)] = False, e
+                self._repo_and_revision_exists_cache[(repo_type, repo_id, None)] = True, None
+            else:
+                self._repo_and_revision_exists_cache[(repo_type, repo_id, revision)] = True, None
+                self._repo_and_revision_exists_cache[(repo_type, repo_id, None)] = True, None
+        return self._repo_and_revision_exists_cache[(repo_type, repo_id, revision)]
+
+    def resolve_path(self, path: str, revision: Optional[str] = None) -> HfFileSystemResolvedPath:
+        def _align_revision_in_path_with_revision(
+            revision_in_path: Optional[str], revision: Optional[str]
+        ) -> Optional[str]:
+            if revision is not None:
+                if revision_in_path is not None and revision_in_path != revision:
+                    raise ValueError(
+                        f'Revision specified in path ("{revision_in_path}") and in `revision` argument ("{revision}")'
+                        " are not the same."
+                    )
+            else:
+                revision = revision_in_path
+            return revision
+
+        path = self._strip_protocol(path)
+        if not path:
+            # can't list repositories at root
+            raise NotImplementedError("Access to repositories lists is not implemented.")
+        elif path.split("/")[0] + "/" in REPO_TYPES_URL_PREFIXES.values():
+            if "/" not in path:
+                # can't list repositories at the repository type level
+                raise NotImplementedError("Access to repositories lists is not implemented.")
+            repo_type, path = path.split("/", 1)
+            repo_type = REPO_TYPES_MAPPING[repo_type]
+        else:
+            repo_type = REPO_TYPE_MODEL
+        if path.count("/") > 0:
+            if "@" in path:
+                repo_id, revision_in_path = path.split("@", 1)
+                if "/" in revision_in_path:
+                    match = SPECIAL_REFS_REVISION_REGEX.search(revision_in_path)
+                    if match is not None and revision in (None, match.group()):
+                        # Handle `refs/convert/parquet` and PR revisions separately
+                        path_in_repo = SPECIAL_REFS_REVISION_REGEX.sub("", revision_in_path).lstrip("/")
+                        revision_in_path = match.group()
+                    else:
+                        revision_in_path, path_in_repo = revision_in_path.split("/", 1)
+                else:
+                    path_in_repo = ""
+                revision = _align_revision_in_path_with_revision(unquote(revision_in_path), revision)
+                repo_and_revision_exist, err = self._repo_and_revision_exist(repo_type, repo_id, revision)
+                if not repo_and_revision_exist:
+                    _raise_file_not_found(path, err)
+            else:
+                revision_in_path = None
+                repo_id_with_namespace = "/".join(path.split("/")[:2])
+                path_in_repo_with_namespace = "/".join(path.split("/")[2:])
+                repo_id_without_namespace = path.split("/")[0]
+                path_in_repo_without_namespace = "/".join(path.split("/")[1:])
+                repo_id = repo_id_with_namespace
+                path_in_repo = path_in_repo_with_namespace
+                repo_and_revision_exist, err = self._repo_and_revision_exist(repo_type, repo_id, revision)
+                if not repo_and_revision_exist:
+                    if isinstance(err, (RepositoryNotFoundError, HFValidationError)):
+                        repo_id = repo_id_without_namespace
+                        path_in_repo = path_in_repo_without_namespace
+                        repo_and_revision_exist, _ = self._repo_and_revision_exist(repo_type, repo_id, revision)
+                        if not repo_and_revision_exist:
+                            _raise_file_not_found(path, err)
+                    else:
+                        _raise_file_not_found(path, err)
+        else:
+            repo_id = path
+            path_in_repo = ""
+            if "@" in path:
+                repo_id, revision_in_path = path.split("@", 1)
+                revision = _align_revision_in_path_with_revision(unquote(revision_in_path), revision)
+            else:
+                revision_in_path = None
+            repo_and_revision_exist, _ = self._repo_and_revision_exist(repo_type, repo_id, revision)
+            if not repo_and_revision_exist:
+                raise NotImplementedError("Access to repositories lists is not implemented.")
+
+        revision = revision if revision is not None else DEFAULT_REVISION
+        return HfFileSystemResolvedPath(repo_type, repo_id, revision, path_in_repo, _raw_revision=revision_in_path)
+
+    def invalidate_cache(self, path: Optional[str] = None) -> None:
+        if not path:
+            self.dircache.clear()
+            self._repo_and_revision_exists_cache.clear()
+        else:
+            path = self.resolve_path(path).unresolve()
+            while path:
+                self.dircache.pop(path, None)
+                path = self._parent(path)
+
+    def _open(
+        self,
+        path: str,
+        mode: str = "rb",
+        revision: Optional[str] = None,
+        **kwargs,
+    ) -> "HfFileSystemFile":
+        if "a" in mode:
+            raise NotImplementedError("Appending to remote files is not yet supported.")
+        return HfFileSystemFile(self, path, mode=mode, revision=revision, **kwargs)
+
+    def _rm(self, path: str, revision: Optional[str] = None, **kwargs) -> None:
+        resolved_path = self.resolve_path(path, revision=revision)
+        self._api.delete_file(
+            path_in_repo=resolved_path.path_in_repo,
+            repo_id=resolved_path.repo_id,
+            token=self.token,
+            repo_type=resolved_path.repo_type,
+            revision=resolved_path.revision,
+            commit_message=kwargs.get("commit_message"),
+            commit_description=kwargs.get("commit_description"),
+        )
+        self.invalidate_cache(path=resolved_path.unresolve())
+
+    def rm(
+        self,
+        path: str,
+        recursive: bool = False,
+        maxdepth: Optional[int] = None,
+        revision: Optional[str] = None,
+        **kwargs,
+    ) -> None:
+        resolved_path = self.resolve_path(path, revision=revision)
+        root_path = REPO_TYPES_URL_PREFIXES.get(resolved_path.repo_type, "") + resolved_path.repo_id
+        paths = self.expand_path(path, recursive=recursive, maxdepth=maxdepth, revision=revision)
+        paths_in_repo = [path[len(root_path) + 1 :] for path in paths if not self.isdir(path)]
+        operations = [CommitOperationDelete(path_in_repo=path_in_repo) for path_in_repo in paths_in_repo]
+        commit_message = f"Delete {path} "
+        commit_message += "recursively " if recursive else ""
+        commit_message += f"up to depth {maxdepth} " if maxdepth is not None else ""
+        # TODO: use `commit_description` to list all the deleted paths?
+        self._api.create_commit(
+            repo_id=resolved_path.repo_id,
+            repo_type=resolved_path.repo_type,
+            token=self.token,
+            operations=operations,
+            revision=resolved_path.revision,
+            commit_message=kwargs.get("commit_message", commit_message),
+            commit_description=kwargs.get("commit_description"),
+        )
+        self.invalidate_cache(path=resolved_path.unresolve())
+
+    def ls(
+        self, path: str, detail: bool = True, refresh: bool = False, revision: Optional[str] = None, **kwargs
+    ) -> List[Union[str, Dict[str, Any]]]:
+        """List the contents of a directory."""
+        resolved_path = self.resolve_path(path, revision=revision)
+        path = resolved_path.unresolve()
+        kwargs = {"expand_info": detail, **kwargs}
+        try:
+            out = self._ls_tree(path, refresh=refresh, revision=revision, **kwargs)
+        except EntryNotFoundError:
+            # Path could be a file
+            if not resolved_path.path_in_repo:
+                _raise_file_not_found(path, None)
+            out = self._ls_tree(self._parent(path), refresh=refresh, revision=revision, **kwargs)
+            out = [o for o in out if o["name"] == path]
+            if len(out) == 0:
+                _raise_file_not_found(path, None)
+        return out if detail else [o["name"] for o in out]
+
+    def _ls_tree(
+        self,
+        path: str,
+        recursive: bool = False,
+        refresh: bool = False,
+        revision: Optional[str] = None,
+        expand_info: bool = True,
+    ):
+        resolved_path = self.resolve_path(path, revision=revision)
+        path = resolved_path.unresolve()
+        root_path = HfFileSystemResolvedPath(
+            resolved_path.repo_type,
+            resolved_path.repo_id,
+            resolved_path.revision,
+            path_in_repo="",
+            _raw_revision=resolved_path._raw_revision,
+        ).unresolve()
+
+        out = []
+        if path in self.dircache and not refresh:
+            cached_path_infos = self.dircache[path]
+            out.extend(cached_path_infos)
+            dirs_not_in_dircache = []
+            if recursive:
+                # Use BFS to traverse the cache and build the "recursive "output
+                # (The Hub uses a so-called "tree first" strategy for the tree endpoint but we sort the output to follow the spec so the result is (eventually) the same)
+                dirs_to_visit = deque(
+                    [path_info for path_info in cached_path_infos if path_info["type"] == "directory"]
+                )
+                while dirs_to_visit:
+                    dir_info = dirs_to_visit.popleft()
+                    if dir_info["name"] not in self.dircache:
+                        dirs_not_in_dircache.append(dir_info["name"])
+                    else:
+                        cached_path_infos = self.dircache[dir_info["name"]]
+                        out.extend(cached_path_infos)
+                        dirs_to_visit.extend(
+                            [path_info for path_info in cached_path_infos if path_info["type"] == "directory"]
+                        )
+
+            dirs_not_expanded = []
+            if expand_info:
+                # Check if there are directories with non-expanded entries
+                dirs_not_expanded = [self._parent(o["name"]) for o in out if o["last_commit"] is None]
+
+            if (recursive and dirs_not_in_dircache) or (expand_info and dirs_not_expanded):
+                # If the dircache is incomplete, find the common path of the missing and non-expanded entries
+                # and extend the output with the result of `_ls_tree(common_path, recursive=True)`
+                common_prefix = os.path.commonprefix(dirs_not_in_dircache + dirs_not_expanded)
+                # Get the parent directory if the common prefix itself is not a directory
+                common_path = (
+                    common_prefix.rstrip("/")
+                    if common_prefix.endswith("/")
+                    or common_prefix == root_path
+                    or common_prefix in chain(dirs_not_in_dircache, dirs_not_expanded)
+                    else self._parent(common_prefix)
+                )
+                out = [o for o in out if not o["name"].startswith(common_path + "/")]
+                for cached_path in self.dircache:
+                    if cached_path.startswith(common_path + "/"):
+                        self.dircache.pop(cached_path, None)
+                self.dircache.pop(common_path, None)
+                out.extend(
+                    self._ls_tree(
+                        common_path,
+                        recursive=recursive,
+                        refresh=True,
+                        revision=revision,
+                        expand_info=expand_info,
+                    )
+                )
+        else:
+            tree = self._api.list_repo_tree(
+                resolved_path.repo_id,
+                resolved_path.path_in_repo,
+                recursive=recursive,
+                expand=expand_info,
+                revision=resolved_path.revision,
+                repo_type=resolved_path.repo_type,
+            )
+            for path_info in tree:
+                if isinstance(path_info, RepoFile):
+                    cache_path_info = {
+                        "name": root_path + "/" + path_info.path,
+                        "size": path_info.size,
+                        "type": "file",
+                        "blob_id": path_info.blob_id,
+                        "lfs": path_info.lfs,
+                        "last_commit": path_info.last_commit,
+                        "security": path_info.security,
+                    }
+                else:
+                    cache_path_info = {
+                        "name": root_path + "/" + path_info.path,
+                        "size": 0,
+                        "type": "directory",
+                        "tree_id": path_info.tree_id,
+                        "last_commit": path_info.last_commit,
+                    }
+                parent_path = self._parent(cache_path_info["name"])
+                self.dircache.setdefault(parent_path, []).append(cache_path_info)
+                out.append(cache_path_info)
+        return copy.deepcopy(out)  # copy to not let users modify the dircache
+
+    def glob(self, path, **kwargs):
+        # Set expand_info=False by default to get a x10 speed boost
+        kwargs = {"expand_info": kwargs.get("detail", False), **kwargs}
+        path = self.resolve_path(path, revision=kwargs.get("revision")).unresolve()
+        return super().glob(path, **kwargs)
+
+    def find(
+        self,
+        path: str,
+        maxdepth: Optional[int] = None,
+        withdirs: bool = False,
+        detail: bool = False,
+        refresh: bool = False,
+        revision: Optional[str] = None,
+        **kwargs,
+    ) -> Union[List[str], Dict[str, Dict[str, Any]]]:
+        if maxdepth:
+            return super().find(
+                path, maxdepth=maxdepth, withdirs=withdirs, detail=detail, refresh=refresh, revision=revision, **kwargs
+            )
+        resolved_path = self.resolve_path(path, revision=revision)
+        path = resolved_path.unresolve()
+        kwargs = {"expand_info": detail, **kwargs}
+        try:
+            out = self._ls_tree(path, recursive=True, refresh=refresh, revision=resolved_path.revision, **kwargs)
+        except EntryNotFoundError:
+            # Path could be a file
+            if self.info(path, revision=revision, **kwargs)["type"] == "file":
+                out = {path: {}}
+            else:
+                out = {}
+        else:
+            if not withdirs:
+                out = [o for o in out if o["type"] != "directory"]
+            else:
+                # If `withdirs=True`, include the directory itself to be consistent with the spec
+                path_info = self.info(path, revision=resolved_path.revision, **kwargs)
+                out = [path_info] + out if path_info["type"] == "directory" else out
+            out = {o["name"]: o for o in out}
+        names = sorted(out)
+        if not detail:
+            return names
+        else:
+            return {name: out[name] for name in names}
+
+    def cp_file(self, path1: str, path2: str, revision: Optional[str] = None, **kwargs) -> None:
+        resolved_path1 = self.resolve_path(path1, revision=revision)
+        resolved_path2 = self.resolve_path(path2, revision=revision)
+
+        same_repo = (
+            resolved_path1.repo_type == resolved_path2.repo_type and resolved_path1.repo_id == resolved_path2.repo_id
+        )
+
+        if same_repo and self.info(path1, revision=resolved_path1.revision)["lfs"] is not None:
+            commit_message = f"Copy {path1} to {path2}"
+            self._api.create_commit(
+                repo_id=resolved_path1.repo_id,
+                repo_type=resolved_path1.repo_type,
+                revision=resolved_path2.revision,
+                commit_message=kwargs.get("commit_message", commit_message),
+                commit_description=kwargs.get("commit_description", ""),
+                operations=[
+                    CommitOperationCopy(
+                        src_path_in_repo=resolved_path1.path_in_repo,
+                        path_in_repo=resolved_path2.path_in_repo,
+                        src_revision=resolved_path1.revision,
+                    )
+                ],
+            )
+        else:
+            with self.open(path1, "rb", revision=resolved_path1.revision) as f:
+                content = f.read()
+            commit_message = f"Copy {path1} to {path2}"
+            self._api.upload_file(
+                path_or_fileobj=content,
+                path_in_repo=resolved_path2.path_in_repo,
+                repo_id=resolved_path2.repo_id,
+                token=self.token,
+                repo_type=resolved_path2.repo_type,
+                revision=resolved_path2.revision,
+                commit_message=kwargs.get("commit_message", commit_message),
+                commit_description=kwargs.get("commit_description"),
+            )
+        self.invalidate_cache(path=resolved_path1.unresolve())
+        self.invalidate_cache(path=resolved_path2.unresolve())
+
+    def modified(self, path: str, **kwargs) -> datetime:
+        info = self.info(path, **kwargs)
+        return info["last_commit"]["date"]
+
+    def info(self, path: str, refresh: bool = False, revision: Optional[str] = None, **kwargs) -> Dict[str, Any]:
+        resolved_path = self.resolve_path(path, revision=revision)
+        path = resolved_path.unresolve()
+        expand_info = kwargs.get(
+            "expand_info", True
+        )  # don't expose it as a parameter in the public API to follow the spec
+        if not resolved_path.path_in_repo:
+            # Path is the root directory
+            out = {
+                "name": path,
+                "size": 0,
+                "type": "directory",
+            }
+            if expand_info:
+                last_commit = self._api.list_repo_commits(
+                    resolved_path.repo_id, repo_type=resolved_path.repo_type, revision=resolved_path.revision
+                )[-1]
+                out = {
+                    **out,
+                    "tree_id": None,  # TODO: tree_id of the root directory?
+                    "last_commit": LastCommitInfo(
+                        oid=last_commit.commit_id, title=last_commit.title, date=last_commit.created_at
+                    ),
+                }
+        else:
+            out = None
+            parent_path = self._parent(path)
+            if parent_path in self.dircache:
+                # Check if the path is in the cache
+                out1 = [o for o in self.dircache[parent_path] if o["name"] == path]
+                if not out1:
+                    _raise_file_not_found(path, None)
+                out = out1[0]
+            if refresh or out is None or (expand_info and out and out["last_commit"] is None):
+                paths_info = self._api.get_paths_info(
+                    resolved_path.repo_id,
+                    resolved_path.path_in_repo,
+                    expand=expand_info,
+                    revision=resolved_path.revision,
+                    repo_type=resolved_path.repo_type,
+                )
+                if not paths_info:
+                    _raise_file_not_found(path, None)
+                path_info = paths_info[0]
+                root_path = HfFileSystemResolvedPath(
+                    resolved_path.repo_type,
+                    resolved_path.repo_id,
+                    resolved_path.revision,
+                    path_in_repo="",
+                    _raw_revision=resolved_path._raw_revision,
+                ).unresolve()
+                if isinstance(path_info, RepoFile):
+                    out = {
+                        "name": root_path + "/" + path_info.path,
+                        "size": path_info.size,
+                        "type": "file",
+                        "blob_id": path_info.blob_id,
+                        "lfs": path_info.lfs,
+                        "last_commit": path_info.last_commit,
+                        "security": path_info.security,
+                    }
+                else:
+                    out = {
+                        "name": root_path + "/" + path_info.path,
+                        "size": 0,
+                        "type": "directory",
+                        "tree_id": path_info.tree_id,
+                        "last_commit": path_info.last_commit,
+                    }
+                if not expand_info:
+                    out = {k: out[k] for k in ["name", "size", "type"]}
+        assert out is not None
+        return copy.deepcopy(out)  # copy to not let users modify the dircache
+
+    def exists(self, path, **kwargs):
+        """Is there a file at the given path"""
+        try:
+            self.info(path, expand_info=False, **kwargs)
+            return True
+        except:  # noqa: E722
+            # any exception allowed bar FileNotFoundError?
+            return False
+
+    def isdir(self, path):
+        """Is this entry directory-like?"""
+        try:
+            return self.info(path, expand_info=False)["type"] == "directory"
+        except OSError:
+            return False
+
+    def isfile(self, path):
+        """Is this entry file-like?"""
+        try:
+            return self.info(path, expand_info=False)["type"] == "file"
+        except:  # noqa: E722
+            return False
+
+    @property
+    def transaction(self):
+        """A context within which files are committed together upon exit
+
+        Requires the file class to implement `.commit()` and `.discard()`
+        for the normal and exception cases.
+        """
+        # Taken from https://github.com/fsspec/filesystem_spec/blob/3fbb6fee33b46cccb015607630843dea049d3243/fsspec/spec.py#L231
+        # See https://github.com/huggingface/huggingface_hub/issues/1733
+        raise NotImplementedError("Transactional commits are not supported.")
+
+    def start_transaction(self):
+        """Begin write transaction for deferring files, non-context version"""
+        # Taken from https://github.com/fsspec/filesystem_spec/blob/3fbb6fee33b46cccb015607630843dea049d3243/fsspec/spec.py#L241
+        # See https://github.com/huggingface/huggingface_hub/issues/1733
+        raise NotImplementedError("Transactional commits are not supported.")
+
+
+class HfFileSystemFile(fsspec.spec.AbstractBufferedFile):
+    def __init__(self, fs: HfFileSystem, path: str, revision: Optional[str] = None, **kwargs):
+        super().__init__(fs, path, **kwargs)
+        self.fs: HfFileSystem
+
+        try:
+            self.resolved_path = fs.resolve_path(path, revision=revision)
+        except FileNotFoundError as e:
+            if "w" in kwargs.get("mode", ""):
+                raise FileNotFoundError(
+                    f"{e}.\nMake sure the repository and revision exist before writing data."
+                ) from e
+
+    def __del__(self):
+        if not hasattr(self, "resolved_path"):
+            # Means that the constructor failed. Nothing to do.
+            return
+        return super().__del__()
+
+    def _fetch_range(self, start: int, end: int) -> bytes:
+        headers = {
+            "range": f"bytes={start}-{end - 1}",
+            **self.fs._api._build_hf_headers(),
+        }
+        url = hf_hub_url(
+            repo_id=self.resolved_path.repo_id,
+            revision=self.resolved_path.revision,
+            filename=self.resolved_path.path_in_repo,
+            repo_type=self.resolved_path.repo_type,
+            endpoint=self.fs.endpoint,
+        )
+        r = http_backoff("GET", url, headers=headers)
+        hf_raise_for_status(r)
+        return r.content
+
+    def _initiate_upload(self) -> None:
+        self.temp_file = tempfile.NamedTemporaryFile(prefix="hffs-", delete=False)
+
+    def _upload_chunk(self, final: bool = False) -> None:
+        self.buffer.seek(0)
+        block = self.buffer.read()
+        self.temp_file.write(block)
+        if final:
+            self.temp_file.close()
+            self.fs._api.upload_file(
+                path_or_fileobj=self.temp_file.name,
+                path_in_repo=self.resolved_path.path_in_repo,
+                repo_id=self.resolved_path.repo_id,
+                token=self.fs.token,
+                repo_type=self.resolved_path.repo_type,
+                revision=self.resolved_path.revision,
+                commit_message=self.kwargs.get("commit_message"),
+                commit_description=self.kwargs.get("commit_description"),
+            )
+            os.remove(self.temp_file.name)
+            self.fs.invalidate_cache(
+                path=self.resolved_path.unresolve(),
+            )
+
+
+def safe_revision(revision: str) -> str:
+    return revision if SPECIAL_REFS_REVISION_REGEX.match(revision) else safe_quote(revision)
+
+
+def safe_quote(s: str) -> str:
+    return quote(s, safe="")
+
+
+def _raise_file_not_found(path: str, err: Optional[Exception]) -> NoReturn:
+    msg = path
+    if isinstance(err, RepositoryNotFoundError):
+        msg = f"{path} (repository not found)"
+    elif isinstance(err, RevisionNotFoundError):
+        msg = f"{path} (revision not found)"
+    elif isinstance(err, HFValidationError):
+        msg = f"{path} (invalid repository id)"
+    raise FileNotFoundError(msg) from err

lib/python3.11/site-packages/huggingface_hub/hub_mixin.py

@@ -0,0 +1,368 @@
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Type, TypeVar, Union
+
+from .constants import CONFIG_NAME, PYTORCH_WEIGHTS_NAME
+from .file_download import hf_hub_download, is_torch_available
+from .hf_api import HfApi
+from .utils import HfHubHTTPError, SoftTemporaryDirectory, logging, validate_hf_hub_args
+
+
+if is_torch_available():
+    import torch  # type: ignore
+
+logger = logging.get_logger(__name__)
+
+# Generic variable that is either ModelHubMixin or a subclass thereof
+T = TypeVar("T", bound="ModelHubMixin")
+
+
+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.
+    """
+
+    def save_pretrained(
+        self,
+        save_directory: Union[str, Path],
+        *,
+        config: Optional[dict] = None,
+        repo_id: Optional[str] = None,
+        push_to_hub: bool = False,
+        **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`, *optional*):
+                Model configuration specified as a key/value dictionary.
+            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.
+            kwargs:
+                Additional key word arguments passed along to the [`~ModelHubMixin.push_to_hub`] method.
+        """
+        save_directory = Path(save_directory)
+        save_directory.mkdir(parents=True, exist_ok=True)
+
+        # saving model weights/files
+        self._save_pretrained(save_directory)
+
+        # saving config
+        if isinstance(config, dict):
+            (save_directory / CONFIG_NAME).write_text(json.dumps(config))
+
+        if push_to_hub:
+            kwargs = 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, **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,
+        resume_download: bool = False,
+        proxies: Optional[Dict] = None,
+        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.
+            resume_download (`bool`, *optional*, defaults to `False`):
+                Whether to delete incompletely received files. Will attempt to resume the download if such a file exists.
+            proxies (`Dict[str, str]`, *optional*):
+                A dictionary of proxy servers to use by protocol or endpoint, e.g., `{'http': 'foo.bar:3128',
+                'http://hostname': 'foo.bar:4012'}`. The proxies are used on every request.
+            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 `huggingface-cli 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 = pretrained_model_name_or_path
+        config_file: Optional[str] = None
+        if os.path.isdir(model_id):
+            if CONFIG_NAME in os.listdir(model_id):
+                config_file = os.path.join(model_id, CONFIG_NAME)
+            else:
+                logger.warning(f"{CONFIG_NAME} not found in {Path(model_id).resolve()}")
+        elif isinstance(model_id, str):
+            try:
+                config_file = hf_hub_download(
+                    repo_id=str(model_id),
+                    filename=CONFIG_NAME,
+                    revision=revision,
+                    cache_dir=cache_dir,
+                    force_download=force_download,
+                    proxies=proxies,
+                    resume_download=resume_download,
+                    token=token,
+                    local_files_only=local_files_only,
+                )
+            except HfHubHTTPError:
+                logger.info(f"{CONFIG_NAME} not found in HuggingFace Hub.")
+
+        if config_file is not None:
+            with open(config_file, "r", encoding="utf-8") as f:
+                config = json.load(f)
+            model_kwargs.update({"config": config})
+
+        return cls._from_pretrained(
+            model_id=str(model_id),
+            revision=revision,
+            cache_dir=cache_dir,
+            force_download=force_download,
+            proxies=proxies,
+            resume_download=resume_download,
+            local_files_only=local_files_only,
+            token=token,
+            **model_kwargs,
+        )
+
+    @classmethod
+    def _from_pretrained(
+        cls: Type[T],
+        *,
+        model_id: str,
+        revision: Optional[str],
+        cache_dir: Optional[Union[str, Path]],
+        force_download: bool,
+        proxies: Optional[Dict],
+        resume_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.
+            resume_download (`bool`, *optional*, defaults to `False`):
+                Whether to delete incompletely received files. Will attempt to resume the download if such a file exists.
+            proxies (`Dict[str, str]`, *optional*):
+                A dictionary of proxy servers to use by protocol or endpoint (e.g., `{'http': 'foo.bar:3128',
+                'http://hostname': 'foo.bar:4012'}`).
+            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 `huggingface-cli 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[dict] = None,
+        commit_message: str = "Push model using huggingface_hub.",
+        private: bool = False,
+        api_endpoint: Optional[str] = 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,
+    ) -> 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`, *optional*):
+                Configuration object to be saved alongside the model weights.
+            commit_message (`str`, *optional*):
+                Message to commit while pushing.
+            private (`bool`, *optional*, defaults to `False`):
+                Whether the repository created should be private.
+            api_endpoint (`str`, *optional*):
+                The API endpoint to use when pushing the model to the hub.
+            token (`str`, *optional*):
+                The token to use as HTTP bearer authorization for remote files. By default, it will use the token
+                cached when running `huggingface-cli 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.
+
+        Returns:
+            The url of the commit of your model in the given repository.
+        """
+        api = HfApi(endpoint=api_endpoint, 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)
+            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,
+            )
+
+
+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()`.
+
+    Example:
+
+    ```python
+    >>> import torch
+    >>> import torch.nn as nn
+    >>> from huggingface_hub import PyTorchModelHubMixin
+
+
+    >>> class MyModel(nn.Module, PyTorchModelHubMixin):
+    ...     def __init__(self):
+    ...         super().__init__()
+    ...         self.param = nn.Parameter(torch.rand(3, 4))
+    ...         self.linear = nn.Linear(4, 5)
+
+    ...     def forward(self, x):
+    ...         return self.linear(x + self.param)
+    >>> model = MyModel()
+
+    # 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")
+    ```
+    """
+
+    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
+        torch.save(model_to_save.state_dict(), save_directory / PYTORCH_WEIGHTS_NAME)
+
+    @classmethod
+    def _from_pretrained(
+        cls,
+        *,
+        model_id: str,
+        revision: Optional[str],
+        cache_dir: Optional[Union[str, Path]],
+        force_download: bool,
+        proxies: Optional[Dict],
+        resume_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."""
+        if os.path.isdir(model_id):
+            print("Loading weights from local directory")
+            model_file = os.path.join(model_id, PYTORCH_WEIGHTS_NAME)
+        else:
+            model_file = hf_hub_download(
+                repo_id=model_id,
+                filename=PYTORCH_WEIGHTS_NAME,
+                revision=revision,
+                cache_dir=cache_dir,
+                force_download=force_download,
+                proxies=proxies,
+                resume_download=resume_download,
+                token=token,
+                local_files_only=local_files_only,
+            )
+        model = cls(**model_kwargs)
+
+        state_dict = torch.load(model_file, map_location=torch.device(map_location))
+        model.load_state_dict(state_dict, strict=strict)  # type: ignore
+        model.eval()  # type: ignore
+
+        return model

lib/python3.11/site-packages/huggingface_hub/inference/_client.py

@@ -0,0 +1,1990 @@
+# 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.
+#
+# Related resources:
+#    https://huggingface.co/tasks
+#    https://huggingface.co/docs/huggingface.js/inference/README
+#    https://github.com/huggingface/huggingface.js/tree/main/packages/inference/src
+#    https://github.com/huggingface/text-generation-inference/tree/main/clients/python
+#    https://github.com/huggingface/text-generation-inference/blob/main/clients/python/text_generation/client.py
+#    https://huggingface.slack.com/archives/C03E4DQ9LAJ/p1680169099087869
+#    https://github.com/huggingface/unity-api#tasks
+#
+# Some TODO:
+# - validate inputs/options/parameters? with Pydantic for instance? or only optionally?
+# - add all tasks
+#
+# NOTE: the philosophy of this client is "let's make it as easy as possible to use it, even if less optimized". Some
+# examples of how it translates:
+# - Timeout / Server unavailable is handled by the client in a single "timeout" parameter.
+# - Files can be provided as bytes, file paths, or URLs and the client will try to "guess" the type.
+# - Images are parsed as PIL.Image for easier manipulation.
+# - Provides a "recommended model" for each task => suboptimal but user-wise quicker to get a first script running.
+# - Only the main parameters are publicly exposed. Power users can always read the docs for more options.
+import logging
+import time
+import warnings
+from dataclasses import asdict
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Literal,
+    Optional,
+    Union,
+    overload,
+)
+
+from requests import HTTPError
+from requests.structures import CaseInsensitiveDict
+
+from huggingface_hub.constants import ALL_INFERENCE_API_FRAMEWORKS, INFERENCE_ENDPOINT, MAIN_INFERENCE_API_FRAMEWORKS
+from huggingface_hub.inference._common import (
+    TASKS_EXPECTING_IMAGES,
+    ContentT,
+    InferenceTimeoutError,
+    ModelStatus,
+    _b64_encode,
+    _b64_to_image,
+    _bytes_to_dict,
+    _bytes_to_image,
+    _bytes_to_list,
+    _fetch_recommended_models,
+    _import_numpy,
+    _is_tgi_server,
+    _open_as_binary,
+    _set_as_non_tgi,
+    _stream_text_generation_response,
+)
+from huggingface_hub.inference._text_generation import (
+    TextGenerationParameters,
+    TextGenerationRequest,
+    TextGenerationResponse,
+    TextGenerationStreamResponse,
+    raise_text_generation_error,
+)
+from huggingface_hub.inference._types import (
+    ClassificationOutput,
+    ConversationalOutput,
+    FillMaskOutput,
+    ImageSegmentationOutput,
+    ObjectDetectionOutput,
+    QuestionAnsweringOutput,
+    TableQuestionAnsweringOutput,
+    TokenClassificationOutput,
+)
+from huggingface_hub.utils import (
+    BadRequestError,
+    build_hf_headers,
+    get_session,
+    hf_raise_for_status,
+)
+
+
+if TYPE_CHECKING:
+    import numpy as np
+    from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+class InferenceClient:
+    """
+    Initialize a new Inference Client.
+
+    [`InferenceClient`] aims to provide a unified experience to perform inference. The client can be used
+    seamlessly with either the (free) Inference API or self-hosted Inference Endpoints.
+
+    Args:
+        model (`str`, `optional`):
+            The model to run inference with. Can be a model id hosted on the Hugging Face Hub, e.g. `bigcode/starcoder`
+            or a URL to a deployed Inference Endpoint. Defaults to None, in which case a recommended model is
+            automatically selected for the task.
+        token (`str`, *optional*):
+            Hugging Face token. Will default to the locally saved token. Pass `token=False` if you don't want to send
+            your token to the server.
+        timeout (`float`, `optional`):
+            The maximum number of seconds to wait for a response from the server. Loading a new model in Inference
+            API can take up to several minutes. Defaults to None, meaning it will loop until the server is available.
+        headers (`Dict[str, str]`, `optional`):
+            Additional headers to send to the server. By default only the authorization and user-agent headers are sent.
+            Values in this dictionary will override the default values.
+        cookies (`Dict[str, str]`, `optional`):
+            Additional cookies to send to the server.
+    """
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        token: Union[str, bool, None] = None,
+        timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+        cookies: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.model: Optional[str] = model
+        self.headers = CaseInsensitiveDict(build_hf_headers(token=token))  # contains 'authorization' + 'user-agent'
+        if headers is not None:
+            self.headers.update(headers)
+        self.cookies = cookies
+        self.timeout = timeout
+
+    def __repr__(self):
+        return f"<InferenceClient(model='{self.model if self.model else ''}', timeout={self.timeout})>"
+
+    @overload
+    def post(  # type: ignore[misc]
+        self,
+        *,
+        json: Optional[Union[str, Dict, List]] = None,
+        data: Optional[ContentT] = None,
+        model: Optional[str] = None,
+        task: Optional[str] = None,
+        stream: Literal[False] = ...,
+    ) -> bytes:
+        pass
+
+    @overload
+    def post(
+        self,
+        *,
+        json: Optional[Union[str, Dict, List]] = None,
+        data: Optional[ContentT] = None,
+        model: Optional[str] = None,
+        task: Optional[str] = None,
+        stream: Literal[True] = ...,
+    ) -> Iterable[bytes]:
+        pass
+
+    def post(
+        self,
+        *,
+        json: Optional[Union[str, Dict, List]] = None,
+        data: Optional[ContentT] = None,
+        model: Optional[str] = None,
+        task: Optional[str] = None,
+        stream: bool = False,
+    ) -> Union[bytes, Iterable[bytes]]:
+        """
+        Make a POST request to the inference server.
+
+        Args:
+            json (`Union[str, Dict, List]`, *optional*):
+                The JSON data to send in the request body, specific to each task. Defaults to None.
+            data (`Union[str, Path, bytes, BinaryIO]`, *optional*):
+                The content to send in the request body, specific to each task.
+                It can be raw bytes, a pointer to an opened file, a local file path,
+                or a URL to an online resource (image, audio file,...). If both `json` and `data` are passed,
+                `data` will take precedence. At least `json` or `data` must be provided. Defaults to None.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. Will override the model defined at the instance level. Defaults to None.
+            task (`str`, *optional*):
+                The task to perform on the inference. All available tasks can be found
+                [here](https://huggingface.co/tasks). Used only to default to a recommended model if `model` is not
+                provided. At least `model` or `task` must be provided. Defaults to None.
+            stream (`bool`, *optional*):
+                Whether to iterate over streaming APIs.
+
+        Returns:
+            bytes: The raw bytes returned by the server.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+        """
+        url = self._resolve_url(model, task)
+
+        if data is not None and json is not None:
+            warnings.warn("Ignoring `json` as `data` is passed as binary.")
+
+        # Set Accept header if relevant
+        headers = self.headers.copy()
+        if task in TASKS_EXPECTING_IMAGES and "Accept" not in headers:
+            headers["Accept"] = "image/png"
+
+        t0 = time.time()
+        timeout = self.timeout
+        while True:
+            with _open_as_binary(data) as data_as_binary:
+                try:
+                    response = get_session().post(
+                        url,
+                        json=json,
+                        data=data_as_binary,
+                        headers=headers,
+                        cookies=self.cookies,
+                        timeout=self.timeout,
+                        stream=stream,
+                    )
+                except TimeoutError as error:
+                    # Convert any `TimeoutError` to a `InferenceTimeoutError`
+                    raise InferenceTimeoutError(f"Inference call timed out: {url}") from error  # type: ignore
+
+            try:
+                hf_raise_for_status(response)
+                return response.iter_lines() if stream else response.content
+            except HTTPError as error:
+                if error.response.status_code == 422 and task is not None:
+                    error.args = (
+                        f"{error.args[0]}\nMake sure '{task}' task is supported by the model.",
+                    ) + error.args[1:]
+                if error.response.status_code == 503:
+                    # If Model is unavailable, either raise a TimeoutError...
+                    if timeout is not None and time.time() - t0 > timeout:
+                        raise InferenceTimeoutError(
+                            f"Model not loaded on the server: {url}. Please retry with a higher timeout (current:"
+                            f" {self.timeout}).",
+                            request=error.request,
+                            response=error.response,
+                        ) from error
+                    # ...or wait 1s and retry
+                    logger.info(f"Waiting for model to be loaded on the server: {error}")
+                    time.sleep(1)
+                    if timeout is not None:
+                        timeout = max(self.timeout - (time.time() - t0), 1)  # type: ignore
+                    continue
+                raise
+
+    def audio_classification(
+        self,
+        audio: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ClassificationOutput]:
+        """
+        Perform audio classification on the provided audio content.
+
+        Args:
+            audio (Union[str, Path, bytes, BinaryIO]):
+                The audio content to classify. It can be raw audio bytes, a local audio file, or a URL pointing to an
+                audio file.
+            model (`str`, *optional*):
+                The model to use for audio classification. Can be a model ID hosted on the Hugging Face Hub
+                or a URL to a deployed Inference Endpoint. If not provided, the default recommended model for
+                audio classification will be used.
+
+        Returns:
+            `List[Dict]`: The classification output containing the predicted label and its confidence.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.audio_classification("audio.flac")
+        [{'score': 0.4976358711719513, 'label': 'hap'}, {'score': 0.3677836060523987, 'label': 'neu'},...]
+        ```
+        """
+        response = self.post(data=audio, model=model, task="audio-classification")
+        return _bytes_to_list(response)
+
+    def automatic_speech_recognition(
+        self,
+        audio: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> str:
+        """
+        Perform automatic speech recognition (ASR or audio-to-text) on the given audio content.
+
+        Args:
+            audio (Union[str, Path, bytes, BinaryIO]):
+                The content to transcribe. It can be raw audio bytes, local audio file, or a URL to an audio file.
+            model (`str`, *optional*):
+                The model to use for ASR. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. If not provided, the default recommended model for ASR will be used.
+
+        Returns:
+            str: The transcribed text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.automatic_speech_recognition("hello_world.flac")
+        "hello world"
+        ```
+        """
+        response = self.post(data=audio, model=model, task="automatic-speech-recognition")
+        return _bytes_to_dict(response)["text"]
+
+    def conversational(
+        self,
+        text: str,
+        generated_responses: Optional[List[str]] = None,
+        past_user_inputs: Optional[List[str]] = None,
+        *,
+        parameters: Optional[Dict[str, Any]] = None,
+        model: Optional[str] = None,
+    ) -> ConversationalOutput:
+        """
+        Generate conversational responses based on the given input text (i.e. chat with the API).
+
+        Args:
+            text (`str`):
+                The last input from the user in the conversation.
+            generated_responses (`List[str]`, *optional*):
+                A list of strings corresponding to the earlier replies from the model. Defaults to None.
+            past_user_inputs (`List[str]`, *optional*):
+                A list of strings corresponding to the earlier replies from the user. Should be the same length as
+                `generated_responses`. Defaults to None.
+            parameters (`Dict[str, Any]`, *optional*):
+                Additional parameters for the conversational task. Defaults to None. For more details about the available
+                parameters, please refer to [this page](https://huggingface.co/docs/api-inference/detailed_parameters#conversational-task)
+            model (`str`, *optional*):
+                The model to use for the conversational task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended conversational model will be used.
+                Defaults to None.
+
+        Returns:
+            `Dict`: The generated conversational output.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> output = client.conversational("Hi, who are you?")
+        >>> output
+        {'generated_text': 'I am the one who knocks.', 'conversation': {'generated_responses': ['I am the one who knocks.'], 'past_user_inputs': ['Hi, who are you?']}, 'warnings': ['Setting `pad_token_id` to `eos_token_id`:50256 for open-end generation.']}
+        >>> client.conversational(
+        ...     "Wow, that's scary!",
+        ...     generated_responses=output["conversation"]["generated_responses"],
+        ...     past_user_inputs=output["conversation"]["past_user_inputs"],
+        ... )
+        ```
+        """
+        payload: Dict[str, Any] = {"inputs": {"text": text}}
+        if generated_responses is not None:
+            payload["inputs"]["generated_responses"] = generated_responses
+        if past_user_inputs is not None:
+            payload["inputs"]["past_user_inputs"] = past_user_inputs
+        if parameters is not None:
+            payload["parameters"] = parameters
+        response = self.post(json=payload, model=model, task="conversational")
+        return _bytes_to_dict(response)  # type: ignore
+
+    def visual_question_answering(
+        self,
+        image: ContentT,
+        question: str,
+        *,
+        model: Optional[str] = None,
+    ) -> List[str]:
+        """
+        Answering open-ended questions based on an image.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image for the context. It can be raw bytes, an image file, or a URL to an online image.
+            question (`str`):
+                Question to be answered.
+            model (`str`, *optional*):
+                The model to use for the visual question answering task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended visual question answering model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label and associated probability.
+
+        Raises:
+            `InferenceTimeoutError`:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.visual_question_answering(
+        ...     image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg",
+        ...     question="What is the animal doing?"
+        ... )
+        [{'score': 0.778609573841095, 'answer': 'laying down'},{'score': 0.6957435607910156, 'answer': 'sitting'}, ...]
+        ```
+        """
+        payload: Dict[str, Any] = {"question": question, "image": _b64_encode(image)}
+        response = self.post(json=payload, model=model, task="visual-question-answering")
+        return _bytes_to_list(response)
+
+    def document_question_answering(
+        self,
+        image: ContentT,
+        question: str,
+        *,
+        model: Optional[str] = None,
+    ) -> List[QuestionAnsweringOutput]:
+        """
+        Answer questions on document images.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image for the context. It can be raw bytes, an image file, or a URL to an online image.
+            question (`str`):
+                Question to be answered.
+            model (`str`, *optional*):
+                The model to use for the document question answering task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended document question answering model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label, associated probability, word ids, and page number.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?")
+        [{'score': 0.42515629529953003, 'answer': 'us-001', 'start': 16, 'end': 16}]
+        ```
+        """
+        payload: Dict[str, Any] = {"question": question, "image": _b64_encode(image)}
+        response = self.post(json=payload, model=model, task="document-question-answering")
+        return _bytes_to_list(response)
+
+    def feature_extraction(self, text: str, *, model: Optional[str] = None) -> "np.ndarray":
+        """
+        Generate embeddings for a given text.
+
+        Args:
+            text (`str`):
+                The text to embed.
+            model (`str`, *optional*):
+                The model to use for the conversational task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended conversational model will be used.
+                Defaults to None.
+
+        Returns:
+            `np.ndarray`: The embedding representing the input text as a float32 numpy array.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.feature_extraction("Hi, who are you?")
+        array([[ 2.424802  ,  2.93384   ,  1.1750331 , ...,  1.240499, -0.13776633, -0.7889173 ],
+        [-0.42943227, -0.6364878 , -1.693462  , ...,  0.41978157, -2.4336355 ,  0.6162071 ],
+        ...,
+        [ 0.28552425, -0.928395  , -1.2077185 , ...,  0.76810825, -2.1069427 ,  0.6236161 ]], dtype=float32)
+        ```
+        """
+        response = self.post(json={"inputs": text}, model=model, task="feature-extraction")
+        np = _import_numpy()
+        return np.array(_bytes_to_dict(response), dtype="float32")
+
+    def fill_mask(self, text: str, *, model: Optional[str] = None) -> List[FillMaskOutput]:
+        """
+        Fill in a hole with a missing word (token to be precise).
+
+        Args:
+            text (`str`):
+                a string to be filled from, must contain the [MASK] token (check model card for exact name of the mask).
+            model (`str`, *optional*):
+                The model to use for the fill mask task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended fill mask model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of fill mask output dictionaries containing the predicted label, associated
+            probability, token reference, and completed text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.fill_mask("The goal of life is <mask>.")
+        [{'score': 0.06897063553333282,
+        'token': 11098,
+        'token_str': ' happiness',
+        'sequence': 'The goal of life is happiness.'},
+        {'score': 0.06554922461509705,
+        'token': 45075,
+        'token_str': ' immortality',
+        'sequence': 'The goal of life is immortality.'}]
+        ```
+        """
+        response = self.post(json={"inputs": text}, model=model, task="fill-mask")
+        return _bytes_to_list(response)
+
+    def image_classification(
+        self,
+        image: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ClassificationOutput]:
+        """
+        Perform image classification on the given image using the specified model.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The image to classify. It can be raw bytes, an image file, or a URL to an online image.
+            model (`str`, *optional*):
+                The model to use for image classification. Can be a model ID hosted on the Hugging Face Hub or a URL to a
+                deployed Inference Endpoint. If not provided, the default recommended model for image classification will be used.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label and associated probability.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
+        [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...]
+        ```
+        """
+        response = self.post(data=image, model=model, task="image-classification")
+        return _bytes_to_list(response)
+
+    def image_segmentation(
+        self,
+        image: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ImageSegmentationOutput]:
+        """
+        Perform image segmentation on the given image using the specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The image to segment. It can be raw bytes, an image file, or a URL to an online image.
+            model (`str`, *optional*):
+                The model to use for image segmentation. Can be a model ID hosted on the Hugging Face Hub or a URL to a
+                deployed Inference Endpoint. If not provided, the default recommended model for image segmentation will be used.
+
+        Returns:
+            `List[Dict]`: A list of dictionaries containing the segmented masks and associated attributes.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.image_segmentation("cat.jpg"):
+        [{'score': 0.989008, 'label': 'LABEL_184', 'mask': <PIL.PngImagePlugin.PngImageFile image mode=L size=400x300 at 0x7FDD2B129CC0>}, ...]
+        ```
+        """
+
+        # Segment
+        response = self.post(data=image, model=model, task="image-segmentation")
+        output = _bytes_to_dict(response)
+
+        # Parse masks as PIL Image
+        if not isinstance(output, list):
+            raise ValueError(f"Server output must be a list. Got {type(output)}: {str(output)[:200]}...")
+        for item in output:
+            item["mask"] = _b64_to_image(item["mask"])
+        return output
+
+    def image_to_image(
+        self,
+        image: ContentT,
+        prompt: Optional[str] = None,
+        *,
+        negative_prompt: Optional[str] = None,
+        height: Optional[int] = None,
+        width: Optional[int] = None,
+        num_inference_steps: Optional[int] = None,
+        guidance_scale: Optional[float] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> "Image":
+        """
+        Perform image-to-image translation using a specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image for translation. It can be raw bytes, an image file, or a URL to an online image.
+            prompt (`str`, *optional*):
+                The text prompt to guide the image generation.
+            negative_prompt (`str`, *optional*):
+                A negative prompt to guide the translation process.
+            height (`int`, *optional*):
+                The height in pixels of the generated image.
+            width (`int`, *optional*):
+                The width in pixels of the generated image.
+            num_inference_steps (`int`, *optional*):
+                The number of denoising steps. More denoising steps usually lead to a higher quality image at the
+                expense of slower inference.
+            guidance_scale (`float`, *optional*):
+                Higher guidance scale encourages to generate images that are closely linked to the text `prompt`,
+                usually at the expense of lower image quality.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `Image`: The translated image.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> image = client.image_to_image("cat.jpg", prompt="turn the cat into a tiger")
+        >>> image.save("tiger.jpg")
+        ```
+        """
+        parameters = {
+            "prompt": prompt,
+            "negative_prompt": negative_prompt,
+            "height": height,
+            "width": width,
+            "num_inference_steps": num_inference_steps,
+            "guidance_scale": guidance_scale,
+            **kwargs,
+        }
+        if all(parameter is None for parameter in parameters.values()):
+            # Either only an image to send => send as raw bytes
+            data = image
+            payload: Optional[Dict[str, Any]] = None
+        else:
+            # Or an image + some parameters => use base64 encoding
+            data = None
+            payload = {"inputs": _b64_encode(image)}
+            for key, value in parameters.items():
+                if value is not None:
+                    payload.setdefault("parameters", {})[key] = value
+
+        response = self.post(json=payload, data=data, model=model, task="image-to-image")
+        return _bytes_to_image(response)
+
+    def image_to_text(self, image: ContentT, *, model: Optional[str] = None) -> str:
+        """
+        Takes an input image and return text.
+
+        Models can have very different outputs depending on your use case (image captioning, optical character recognition
+        (OCR), Pix2Struct, etc). Please have a look to the model card to learn more about a model's specificities.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image to caption. It can be raw bytes, an image file, or a URL to an online image..
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `str`: The generated text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.image_to_text("cat.jpg")
+        'a cat standing in a grassy field '
+        >>> client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
+        'a dog laying on the grass next to a flower pot '
+        ```
+        """
+        response = self.post(data=image, model=model, task="image-to-text")
+        return _bytes_to_dict(response)[0]["generated_text"]
+
+    def list_deployed_models(
+        self, frameworks: Union[None, str, Literal["all"], List[str]] = None
+    ) -> Dict[str, List[str]]:
+        """
+        List models currently deployed on the Inference API service.
+
+        This helper checks deployed models framework by framework. By default, it will check the 4 main frameworks that
+        are supported and account for 95% of the hosted models. However, if you want a complete list of models you can
+        specify `frameworks="all"` as input. Alternatively, if you know before-hand which framework you are interested
+        in, you can also restrict to search to this one (e.g. `frameworks="text-generation-inference"`). The more
+        frameworks are checked, the more time it will take.
+
+        <Tip>
+
+        This endpoint is mostly useful for discoverability. If you already know which model you want to use and want to
+        check its availability, you can directly use [`~InferenceClient.get_model_status`].
+
+        </Tip>
+
+        Args:
+            frameworks (`Literal["all"]` or `List[str]` or `str`, *optional*):
+                The frameworks to filter on. By default only a subset of the available frameworks are tested. If set to
+                "all", all available frameworks will be tested. It is also possible to provide a single framework or a
+                custom set of frameworks to check.
+
+        Returns:
+            `Dict[str, List[str]]`: A dictionary mapping task names to a sorted list of model IDs.
+
+        Example:
+        ```python
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+
+        # Discover zero-shot-classification models currently deployed
+        >>> models = client.list_deployed_models()
+        >>> models["zero-shot-classification"]
+        ['Narsil/deberta-large-mnli-zero-cls', 'facebook/bart-large-mnli', ...]
+
+        # List from only 1 framework
+        >>> client.list_deployed_models("text-generation-inference")
+        {'text-generation': ['bigcode/starcoder', 'meta-llama/Llama-2-70b-chat-hf', ...], ...}
+        ```
+        """
+        # Resolve which frameworks to check
+        if frameworks is None:
+            frameworks = MAIN_INFERENCE_API_FRAMEWORKS
+        elif frameworks == "all":
+            frameworks = ALL_INFERENCE_API_FRAMEWORKS
+        elif isinstance(frameworks, str):
+            frameworks = [frameworks]
+        frameworks = list(set(frameworks))
+
+        # Fetch them iteratively
+        models_by_task: Dict[str, List[str]] = {}
+
+        def _unpack_response(framework: str, items: List[Dict]) -> None:
+            for model in items:
+                if framework == "sentence-transformers":
+                    # Model running with the `sentence-transformers` framework can work with both tasks even if not
+                    # branded as such in the API response
+                    models_by_task.setdefault("feature-extraction", []).append(model["model_id"])
+                    models_by_task.setdefault("sentence-similarity", []).append(model["model_id"])
+                else:
+                    models_by_task.setdefault(model["task"], []).append(model["model_id"])
+
+        for framework in frameworks:
+            response = get_session().get(f"{INFERENCE_ENDPOINT}/framework/{framework}", headers=self.headers)
+            hf_raise_for_status(response)
+            _unpack_response(framework, response.json())
+
+        # Sort alphabetically for discoverability and return
+        for task, models in models_by_task.items():
+            models_by_task[task] = sorted(set(models), key=lambda x: x.lower())
+        return models_by_task
+
+    def object_detection(
+        self,
+        image: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ObjectDetectionOutput]:
+        """
+        Perform object detection on the given image using the specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The image to detect objects on. It can be raw bytes, an image file, or a URL to an online image.
+            model (`str`, *optional*):
+                The model to use for object detection. Can be a model ID hosted on the Hugging Face Hub or a URL to a
+                deployed Inference Endpoint. If not provided, the default recommended model for object detection (DETR) will be used.
+
+        Returns:
+            `List[ObjectDetectionOutput]`: A list of dictionaries containing the bounding boxes and associated attributes.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+            `ValueError`:
+                If the request output is not a List.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.object_detection("people.jpg"):
+        [{"score":0.9486683011054993,"label":"person","box":{"xmin":59,"ymin":39,"xmax":420,"ymax":510}}, ... ]
+        ```
+        """
+        # detect objects
+        response = self.post(data=image, model=model, task="object-detection")
+        output = _bytes_to_dict(response)
+        if not isinstance(output, list):
+            raise ValueError(f"Server output must be a list. Got {type(output)}: {str(output)[:200]}...")
+        return output
+
+    def question_answering(
+        self, question: str, context: str, *, model: Optional[str] = None
+    ) -> QuestionAnsweringOutput:
+        """
+        Retrieve the answer to a question from a given text.
+
+        Args:
+            question (`str`):
+                Question to be answered.
+            context (`str`):
+                The context of the question.
+            model (`str`):
+                The model to use for the question answering task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint.
+
+        Returns:
+            `Dict`: a dictionary of question answering output containing the score, start index, end index, and answer.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.question_answering(question="What's my name?", context="My name is Clara and I live in Berkeley.")
+        {'score': 0.9326562285423279, 'start': 11, 'end': 16, 'answer': 'Clara'}
+        ```
+        """
+
+        payload: Dict[str, Any] = {"question": question, "context": context}
+        response = self.post(
+            json=payload,
+            model=model,
+            task="question-answering",
+        )
+        return _bytes_to_dict(response)  # type: ignore
+
+    def sentence_similarity(
+        self, sentence: str, other_sentences: List[str], *, model: Optional[str] = None
+    ) -> List[float]:
+        """
+        Compute the semantic similarity between a sentence and a list of other sentences by comparing their embeddings.
+
+        Args:
+            sentence (`str`):
+                The main sentence to compare to others.
+            other_sentences (`List[str]`):
+                The list of sentences to compare to.
+            model (`str`, *optional*):
+                The model to use for the conversational task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended conversational model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[float]`: The embedding representing the input text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.sentence_similarity(
+        ...     "Machine learning is so easy.",
+        ...     other_sentences=[
+        ...         "Deep learning is so straightforward.",
+        ...         "This is so difficult, like rocket science.",
+        ...         "I can't believe how much I struggled with this.",
+        ...     ],
+        ... )
+        [0.7785726189613342, 0.45876261591911316, 0.2906220555305481]
+        ```
+        """
+        response = self.post(
+            json={"inputs": {"source_sentence": sentence, "sentences": other_sentences}},
+            model=model,
+            task="sentence-similarity",
+        )
+        return _bytes_to_list(response)
+
+    def summarization(
+        self,
+        text: str,
+        *,
+        parameters: Optional[Dict[str, Any]] = None,
+        model: Optional[str] = None,
+    ) -> str:
+        """
+        Generate a summary of a given text using a specified model.
+
+        Args:
+            text (`str`):
+                The input text to summarize.
+            parameters (`Dict[str, Any]`, *optional*):
+                Additional parameters for summarization. Check out this [page](https://huggingface.co/docs/api-inference/detailed_parameters#summarization-task)
+                for more details.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `str`: The generated summary text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.summarization("The Eiffel tower...")
+        'The Eiffel tower is one of the most famous landmarks in the world....'
+        ```
+        """
+        payload: Dict[str, Any] = {"inputs": text}
+        if parameters is not None:
+            payload["parameters"] = parameters
+        response = self.post(json=payload, model=model, task="summarization")
+        return _bytes_to_dict(response)[0]["summary_text"]
+
+    def table_question_answering(
+        self, table: Dict[str, Any], query: str, *, model: Optional[str] = None
+    ) -> TableQuestionAnsweringOutput:
+        """
+        Retrieve the answer to a question from information given in a table.
+
+        Args:
+            table (`str`):
+                A table of data represented as a dict of lists where entries are headers and the lists are all the
+                values, all lists must have the same size.
+            query (`str`):
+                The query in plain text that you want to ask the table.
+            model (`str`):
+                The model to use for the table-question-answering task. Can be a model ID hosted on the Hugging Face
+                Hub or a URL to a deployed Inference Endpoint.
+
+        Returns:
+            `Dict`: a dictionary of table question answering output containing the answer, coordinates, cells and the aggregator used.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> query = "How many stars does the transformers repository have?"
+        >>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]}
+        >>> client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq")
+        {'answer': 'AVERAGE > 36542', 'coordinates': [[0, 1]], 'cells': ['36542'], 'aggregator': 'AVERAGE'}
+        ```
+        """
+        response = self.post(
+            json={
+                "query": query,
+                "table": table,
+            },
+            model=model,
+            task="table-question-answering",
+        )
+        return _bytes_to_dict(response)  # type: ignore
+
+    def tabular_classification(self, table: Dict[str, Any], *, model: str) -> List[str]:
+        """
+        Classifying a target category (a group) based on a set of attributes.
+
+        Args:
+            table (`Dict[str, Any]`):
+                Set of attributes to classify.
+            model (`str`):
+                The model to use for the tabular-classification task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint.
+
+        Returns:
+            `List`: a list of labels, one per row in the initial table.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> table = {
+        ...     "fixed_acidity": ["7.4", "7.8", "10.3"],
+        ...     "volatile_acidity": ["0.7", "0.88", "0.32"],
+        ...     "citric_acid": ["0", "0", "0.45"],
+        ...     "residual_sugar": ["1.9", "2.6", "6.4"],
+        ...     "chlorides": ["0.076", "0.098", "0.073"],
+        ...     "free_sulfur_dioxide": ["11", "25", "5"],
+        ...     "total_sulfur_dioxide": ["34", "67", "13"],
+        ...     "density": ["0.9978", "0.9968", "0.9976"],
+        ...     "pH": ["3.51", "3.2", "3.23"],
+        ...     "sulphates": ["0.56", "0.68", "0.82"],
+        ...     "alcohol": ["9.4", "9.8", "12.6"],
+        ... }
+        >>> client.tabular_classification(table=table, model="julien-c/wine-quality")
+        ["5", "5", "5"]
+        ```
+        """
+        response = self.post(json={"table": table}, model=model, task="tabular-classification")
+        return _bytes_to_list(response)
+
+    def tabular_regression(self, table: Dict[str, Any], *, model: str) -> List[float]:
+        """
+        Predicting a numerical target value given a set of attributes/features in a table.
+
+        Args:
+            table (`Dict[str, Any]`):
+                Set of attributes stored in a table. The attributes used to predict the target can be both numerical and categorical.
+            model (`str`):
+                The model to use for the tabular-regression task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint.
+
+        Returns:
+            `List`: a list of predicted numerical target values.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> table = {
+        ...     "Height": ["11.52", "12.48", "12.3778"],
+        ...     "Length1": ["23.2", "24", "23.9"],
+        ...     "Length2": ["25.4", "26.3", "26.5"],
+        ...     "Length3": ["30", "31.2", "31.1"],
+        ...     "Species": ["Bream", "Bream", "Bream"],
+        ...     "Width": ["4.02", "4.3056", "4.6961"],
+        ... }
+        >>> client.tabular_regression(table, model="scikit-learn/Fish-Weight")
+        [110, 120, 130]
+        ```
+        """
+        response = self.post(json={"table": table}, model=model, task="tabular-regression")
+        return _bytes_to_list(response)
+
+    def text_classification(self, text: str, *, model: Optional[str] = None) -> List[ClassificationOutput]:
+        """
+        Perform text classification (e.g. sentiment-analysis) on the given text.
+
+        Args:
+            text (`str`):
+                A string to be classified.
+            model (`str`, *optional*):
+                The model to use for the text classification task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended text classification model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label and associated probability.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.text_classification("I like you")
+        [{'label': 'POSITIVE', 'score': 0.9998695850372314}, {'label': 'NEGATIVE', 'score': 0.0001304351753788069}]
+        ```
+        """
+        response = self.post(json={"inputs": text}, model=model, task="text-classification")
+        return _bytes_to_list(response)[0]
+
+    @overload
+    def text_generation(  # type: ignore
+        self,
+        prompt: str,
+        *,
+        details: Literal[False] = ...,
+        stream: Literal[False] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> str:
+        ...
+
+    @overload
+    def text_generation(  # type: ignore
+        self,
+        prompt: str,
+        *,
+        details: Literal[True] = ...,
+        stream: Literal[False] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> TextGenerationResponse:
+        ...
+
+    @overload
+    def text_generation(  # type: ignore
+        self,
+        prompt: str,
+        *,
+        details: Literal[False] = ...,
+        stream: Literal[True] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> Iterable[str]:
+        ...
+
+    @overload
+    def text_generation(
+        self,
+        prompt: str,
+        *,
+        details: Literal[True] = ...,
+        stream: Literal[True] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> Iterable[TextGenerationStreamResponse]:
+        ...
+
+    def text_generation(
+        self,
+        prompt: str,
+        *,
+        details: bool = False,
+        stream: bool = False,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+        decoder_input_details: bool = False,
+    ) -> Union[str, TextGenerationResponse, Iterable[str], Iterable[TextGenerationStreamResponse]]:
+        """
+        Given a prompt, generate the following text.
+
+        It is recommended to have Pydantic installed in order to get inputs validated. This is preferable as it allow
+        early failures.
+
+        API endpoint is supposed to run with the `text-generation-inference` backend (TGI). 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. This method is compatible with both approaches but some parameters are only available for
+        `text-generation-inference`. If some parameters are ignored, a warning message is triggered but the process
+        continues correctly.
+
+        To learn more about the TGI project, please refer to https://github.com/huggingface/text-generation-inference.
+
+        Args:
+            prompt (`str`):
+                Input text.
+            details (`bool`, *optional*):
+                By default, text_generation returns a string. Pass `details=True` if you want a detailed output (tokens,
+                probabilities, seed, finish reason, etc.). Only available for models running on with the
+                `text-generation-inference` backend.
+            stream (`bool`, *optional*):
+                By default, text_generation returns the full generated text. Pass `stream=True` if you want a stream of
+                tokens to be returned. Only available for models running on with the `text-generation-inference`
+                backend.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+            do_sample (`bool`):
+                Activate logits sampling
+            max_new_tokens (`int`):
+                Maximum number of generated tokens
+            best_of (`int`):
+                Generate best_of sequences and return the one if the highest token logprobs
+            repetition_penalty (`float`):
+                The parameter for repetition penalty. 1.0 means no penalty. See [this
+                paper](https://arxiv.org/pdf/1909.05858.pdf) for more details.
+            return_full_text (`bool`):
+                Whether to prepend the prompt to the generated text
+            seed (`int`):
+                Random sampling seed
+            stop_sequences (`List[str]`):
+                Stop generating tokens if a member of `stop_sequences` is generated
+            temperature (`float`):
+                The value used to module the logits distribution.
+            top_k (`int`):
+                The number of highest probability vocabulary tokens to keep for top-k-filtering.
+            top_p (`float`):
+                If set to < 1, only the smallest set of most probable tokens with probabilities that add up to `top_p` or
+                higher are kept for generation.
+            truncate (`int`):
+                Truncate inputs tokens to the given size
+            typical_p (`float`):
+                Typical Decoding mass
+                See [Typical Decoding for Natural Language Generation](https://arxiv.org/abs/2202.00666) for more information
+            watermark (`bool`):
+                Watermarking with [A Watermark for Large Language Models](https://arxiv.org/abs/2301.10226)
+            decoder_input_details (`bool`):
+                Return the decoder input token logprobs and ids. You must set `details=True` as well for it to be taken
+                into account. Defaults to `False`.
+
+        Returns:
+            `Union[str, TextGenerationResponse, Iterable[str], Iterable[TextGenerationStreamResponse]]`:
+            Generated text returned from the server:
+            - if `stream=False` and `details=False`, the generated text is returned as a `str` (default)
+            - if `stream=True` and `details=False`, the generated text is returned token by token as a `Iterable[str]`
+            - if `stream=False` and `details=True`, the generated text is returned with more details as a [`~huggingface_hub.inference._text_generation.TextGenerationResponse`]
+            - if `details=True` and `stream=True`, the generated text is returned token by token as a iterable of [`~huggingface_hub.inference._text_generation.TextGenerationStreamResponse`]
+
+        Raises:
+            `ValidationError`:
+                If input values are not valid. No HTTP call is made to the server.
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+
+        # Case 1: generate text
+        >>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12)
+        '100% open source and built to be easy to use.'
+
+        # Case 2: iterate over the generated tokens. Useful for large generation.
+        >>> for token in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True):
+        ...     print(token)
+        100
+        %
+        open
+        source
+        and
+        built
+        to
+        be
+        easy
+        to
+        use
+        .
+
+        # Case 3: get more details about the generation process.
+        >>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True)
+        TextGenerationResponse(
+            generated_text='100% open source and built to be easy to use.',
+            details=Details(
+                finish_reason=<FinishReason.Length: 'length'>,
+                generated_tokens=12,
+                seed=None,
+                prefill=[
+                    InputToken(id=487, text='The', logprob=None),
+                    InputToken(id=53789, text=' hugging', logprob=-13.171875),
+                    (...)
+                    InputToken(id=204, text=' ', logprob=-7.0390625)
+                ],
+                tokens=[
+                    Token(id=1425, text='100', logprob=-1.0175781, special=False),
+                    Token(id=16, text='%', logprob=-0.0463562, special=False),
+                    (...)
+                    Token(id=25, text='.', logprob=-0.5703125, special=False)
+                ],
+                best_of_sequences=None
+            )
+        )
+
+        # Case 4: iterate over the generated tokens with more details.
+        # Last object is more complete, containing the full generated text and the finish reason.
+        >>> for details in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True):
+        ...     print(details)
+        ...
+        TextGenerationStreamResponse(token=Token(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(
+            id=25,
+            text='.',
+            logprob=-0.5703125,
+            special=False),
+            generated_text='100% open source and built to be easy to use.',
+            details=StreamDetails(finish_reason=<FinishReason.Length: 'length'>, generated_tokens=12, seed=None)
+        )
+        ```
+        """
+        # NOTE: Text-generation integration is taken from the text-generation-inference project. It has more features
+        # like input/output validation (if Pydantic is installed). See `_text_generation.py` header for more details.
+
+        if decoder_input_details and not details:
+            warnings.warn(
+                "`decoder_input_details=True` has been passed to the server but `details=False` is set meaning that"
+                " the output from the server will be truncated."
+            )
+            decoder_input_details = False
+
+        # Validate parameters
+        parameters = TextGenerationParameters(
+            best_of=best_of,
+            details=details,
+            do_sample=do_sample,
+            max_new_tokens=max_new_tokens,
+            repetition_penalty=repetition_penalty,
+            return_full_text=return_full_text,
+            seed=seed,
+            stop=stop_sequences if stop_sequences is not None else [],
+            temperature=temperature,
+            top_k=top_k,
+            top_p=top_p,
+            truncate=truncate,
+            typical_p=typical_p,
+            watermark=watermark,
+            decoder_input_details=decoder_input_details,
+        )
+        request = TextGenerationRequest(inputs=prompt, stream=stream, parameters=parameters)
+        payload = asdict(request)
+
+        # Remove some parameters if not a TGI server
+        if not _is_tgi_server(model):
+            ignored_parameters = []
+            for key in "watermark", "stop", "details", "decoder_input_details":
+                if payload["parameters"][key] is not None:
+                    ignored_parameters.append(key)
+                del payload["parameters"][key]
+            if len(ignored_parameters) > 0:
+                warnings.warn(
+                    "API endpoint/model for text-generation is not served via TGI. Ignoring parameters"
+                    f" {ignored_parameters}.",
+                    UserWarning,
+                )
+            if details:
+                warnings.warn(
+                    "API endpoint/model for text-generation is not served via TGI. Parameter `details=True` will"
+                    " be ignored meaning only the generated text will be returned.",
+                    UserWarning,
+                )
+                details = False
+            if stream:
+                raise ValueError(
+                    "API endpoint/model for text-generation is not served via TGI. Cannot return output as a stream."
+                    " Please pass `stream=False` as input."
+                )
+
+        # Handle errors separately for more precise error messages
+        try:
+            bytes_output = self.post(json=payload, model=model, task="text-generation", stream=stream)  # type: ignore
+        except HTTPError as e:
+            if isinstance(e, BadRequestError) and "The following `model_kwargs` are not used by the model" in str(e):
+                _set_as_non_tgi(model)
+                return self.text_generation(  # type: ignore
+                    prompt=prompt,
+                    details=details,
+                    stream=stream,
+                    model=model,
+                    do_sample=do_sample,
+                    max_new_tokens=max_new_tokens,
+                    best_of=best_of,
+                    repetition_penalty=repetition_penalty,
+                    return_full_text=return_full_text,
+                    seed=seed,
+                    stop_sequences=stop_sequences,
+                    temperature=temperature,
+                    top_k=top_k,
+                    top_p=top_p,
+                    truncate=truncate,
+                    typical_p=typical_p,
+                    watermark=watermark,
+                    decoder_input_details=decoder_input_details,
+                )
+            raise_text_generation_error(e)
+
+        # Parse output
+        if stream:
+            return _stream_text_generation_response(bytes_output, details)  # type: ignore
+
+        data = _bytes_to_dict(bytes_output)[0]
+        return TextGenerationResponse(**data) if details else data["generated_text"]
+
+    def text_to_image(
+        self,
+        prompt: str,
+        *,
+        negative_prompt: Optional[str] = None,
+        height: Optional[float] = None,
+        width: Optional[float] = None,
+        num_inference_steps: Optional[float] = None,
+        guidance_scale: Optional[float] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> "Image":
+        """
+        Generate an image based on a given text using a specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            prompt (`str`):
+                The prompt to generate an image from.
+            negative_prompt (`str`, *optional*):
+                An optional negative prompt for the image generation.
+            height (`float`, *optional*):
+                The height in pixels of the image to generate.
+            width (`float`, *optional*):
+                The width in pixels of the image to generate.
+            num_inference_steps (`int`, *optional*):
+                The number of denoising steps. More denoising steps usually lead to a higher quality image at the
+                expense of slower inference.
+            guidance_scale (`float`, *optional*):
+                Higher guidance scale encourages to generate images that are closely linked to the text `prompt`,
+                usually at the expense of lower image quality.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `Image`: The generated image.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+
+        >>> image = client.text_to_image("An astronaut riding a horse on the moon.")
+        >>> image.save("astronaut.png")
+
+        >>> image = client.text_to_image(
+        ...     "An astronaut riding a horse on the moon.",
+        ...     negative_prompt="low resolution, blurry",
+        ...     model="stabilityai/stable-diffusion-2-1",
+        ... )
+        >>> image.save("better_astronaut.png")
+        ```
+        """
+        payload = {"inputs": prompt}
+        parameters = {
+            "negative_prompt": negative_prompt,
+            "height": height,
+            "width": width,
+            "num_inference_steps": num_inference_steps,
+            "guidance_scale": guidance_scale,
+            **kwargs,
+        }
+        for key, value in parameters.items():
+            if value is not None:
+                payload.setdefault("parameters", {})[key] = value  # type: ignore
+        response = self.post(json=payload, model=model, task="text-to-image")
+        return _bytes_to_image(response)
+
+    def text_to_speech(self, text: str, *, model: Optional[str] = None) -> bytes:
+        """
+        Synthesize an audio of a voice pronouncing a given text.
+
+        Args:
+            text (`str`):
+                The text to synthesize.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `bytes`: The generated audio.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from pathlib import Path
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+
+        >>> audio = client.text_to_speech("Hello world")
+        >>> Path("hello_world.flac").write_bytes(audio)
+        ```
+        """
+        return self.post(json={"inputs": text}, model=model, task="text-to-speech")
+
+    def token_classification(self, text: str, *, model: Optional[str] = None) -> List[TokenClassificationOutput]:
+        """
+        Perform token classification on the given text.
+        Usually used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text.
+
+        Args:
+            text (`str`):
+                A string to be classified.
+            model (`str`, *optional*):
+                The model to use for the token classification task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended token classification model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: List of token classification outputs containing the entity group, confidence score, word, start and end index.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
+        [{'entity_group': 'PER',
+        'score': 0.9971321225166321,
+        'word': 'Sarah Jessica Parker',
+        'start': 11,
+        'end': 31},
+        {'entity_group': 'PER',
+        'score': 0.9773476123809814,
+        'word': 'Jessica',
+        'start': 52,
+        'end': 59}]
+        ```
+        """
+        payload: Dict[str, Any] = {"inputs": text}
+        response = self.post(
+            json=payload,
+            model=model,
+            task="token-classification",
+        )
+        return _bytes_to_list(response)
+
+    def translation(
+        self, text: str, *, model: Optional[str] = None, src_lang: Optional[str] = None, tgt_lang: Optional[str] = None
+    ) -> str:
+        """
+        Convert text from one language to another.
+
+        Check out https://huggingface.co/tasks/translation for more information on how to choose the best model for
+        your specific use case. Source and target languages usually depend on the model.
+        However, it is possible to specify source and target languages for certain models. If you are working with one of these models,
+        you can use `src_lang` and `tgt_lang` arguments to pass the relevant information.
+        You can find this information in the model card.
+
+        Args:
+            text (`str`):
+                A string to be translated.
+            model (`str`, *optional*):
+                The model to use for the translation task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended translation model will be used.
+                Defaults to None.
+            src_lang (`str`, *optional*):
+                Source language of the translation task, i.e. input language. Cannot be passed without `tgt_lang`.
+            tgt_lang (`str`, *optional*):
+                Target language of the translation task, i.e. output language. Cannot be passed without `src_lang`.
+
+        Returns:
+            `str`: The generated translated text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+            `ValueError`:
+                If only one of the `src_lang` and `tgt_lang` arguments are provided.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.translation("My name is Wolfgang and I live in Berlin")
+        'Mein Name ist Wolfgang und ich lebe in Berlin.'
+        >>> client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr")
+        "Je m'appelle Wolfgang et je vis à Berlin."
+        ```
+
+        Specifying languages:
+        ```py
+        >>> client.translation("My name is Sarah Jessica Parker but you can call me Jessica", model="facebook/mbart-large-50-many-to-many-mmt", src_lang="en_XX", tgt_lang="fr_XX")
+        "Mon nom est Sarah Jessica Parker mais vous pouvez m\'appeler Jessica"
+        ```
+        """
+        # Throw error if only one of `src_lang` and `tgt_lang` was given
+        if src_lang is not None and tgt_lang is None:
+            raise ValueError("You cannot specify `src_lang` without specifying `tgt_lang`.")
+
+        if src_lang is None and tgt_lang is not None:
+            raise ValueError("You cannot specify `tgt_lang` without specifying `src_lang`.")
+
+        # If both `src_lang` and `tgt_lang` are given, pass them to the request body
+        payload: Dict = {"inputs": text}
+        if src_lang and tgt_lang:
+            payload["parameters"] = {"src_lang": src_lang, "tgt_lang": tgt_lang}
+        response = self.post(json=payload, model=model, task="translation")
+        return _bytes_to_dict(response)[0]["translation_text"]
+
+    def zero_shot_classification(
+        self, text: str, labels: List[str], *, multi_label: bool = False, model: Optional[str] = None
+    ) -> List[ClassificationOutput]:
+        """
+        Provide as input a text and a set of candidate labels to classify the input text.
+
+        Args:
+            text (`str`):
+                The input text to classify.
+            labels (`List[str]`):
+                List of string possible labels. There must be at least 2 labels.
+            multi_label (`bool`):
+                Boolean that is set to True if classes can overlap.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `List[Dict]`: List of classification outputs containing the predicted labels and their confidence.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> text = (
+        ...     "A new model offers an explanation for how the Galilean satellites formed around the solar system's"
+        ...     "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling"
+        ...     " mysteries when he went for a run up a hill in Nice, France."
+        ... )
+        >>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"]
+        >>> client.zero_shot_classification(text, labels)
+        [
+            {"label": "scientific discovery", "score": 0.7961668968200684},
+            {"label": "space & cosmos", "score": 0.18570658564567566},
+            {"label": "microbiology", "score": 0.00730885099619627},
+            {"label": "archeology", "score": 0.006258360575884581},
+            {"label": "robots", "score": 0.004559356719255447},
+        ]
+        >>> client.zero_shot_classification(text, labels, multi_label=True)
+        [
+            {"label": "scientific discovery", "score": 0.9829297661781311},
+            {"label": "space & cosmos", "score": 0.755190908908844},
+            {"label": "microbiology", "score": 0.0005462635890580714},
+            {"label": "archeology", "score": 0.00047131875180639327},
+            {"label": "robots", "score": 0.00030448526376858354},
+        ]
+        ```
+        """
+        # Raise ValueError if input is less than 2 labels
+        if len(labels) < 2:
+            raise ValueError("You must specify at least 2 classes to compare.")
+
+        response = self.post(
+            json={
+                "inputs": text,
+                "parameters": {
+                    "candidate_labels": ",".join(labels),
+                    "multi_label": multi_label,
+                },
+            },
+            model=model,
+            task="zero-shot-classification",
+        )
+        output = _bytes_to_dict(response)
+        return [{"label": label, "score": score} for label, score in zip(output["labels"], output["scores"])]
+
+    def zero_shot_image_classification(
+        self, image: ContentT, labels: List[str], *, model: Optional[str] = None
+    ) -> List[ClassificationOutput]:
+        """
+        Provide input image and text labels to predict text labels for the image.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image to caption. It can be raw bytes, an image file, or a URL to an online image.
+            labels (`List[str]`):
+                List of string possible labels. There must be at least 2 labels.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `List[Dict]`: List of classification outputs containing the predicted labels and their confidence.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `HTTPError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+
+        >>> client.zero_shot_image_classification(
+        ...     "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg",
+        ...     labels=["dog", "cat", "horse"],
+        ... )
+        [{"label": "dog", "score": 0.956}, ...]
+        ```
+        """
+        # Raise ValueError if input is less than 2 labels
+        if len(labels) < 2:
+            raise ValueError("You must specify at least 2 classes to compare.")
+
+        response = self.post(
+            json={"image": _b64_encode(image), "parameters": {"candidate_labels": ",".join(labels)}},
+            model=model,
+            task="zero-shot-image-classification",
+        )
+        return _bytes_to_list(response)
+
+    def _resolve_url(self, model: Optional[str] = None, task: Optional[str] = None) -> str:
+        model = model or self.model
+
+        # If model is already a URL, ignore `task` and return directly
+        if model is not None and (model.startswith("http://") or model.startswith("https://")):
+            return model
+
+        # # If no model but task is set => fetch the recommended one for this task
+        if model is None:
+            if task is None:
+                raise ValueError(
+                    "You must specify at least a model (repo_id or URL) or a task, either when instantiating"
+                    " `InferenceClient` or when making a request."
+                )
+            model = self.get_recommended_model(task)
+            logger.info(
+                f"Using recommended model {model} for task {task}. Note that it is"
+                f" encouraged to explicitly set `model='{model}'` as the recommended"
+                " models list might get updated without prior notice."
+            )
+
+        # Compute InferenceAPI url
+        return (
+            # Feature-extraction and sentence-similarity are the only cases where we handle models with several tasks.
+            f"{INFERENCE_ENDPOINT}/pipeline/{task}/{model}"
+            if task in ("feature-extraction", "sentence-similarity")
+            # Otherwise, we use the default endpoint
+            else f"{INFERENCE_ENDPOINT}/models/{model}"
+        )
+
+    @staticmethod
+    def get_recommended_model(task: str) -> str:
+        """
+        Get the model Hugging Face recommends for the input task.
+
+        Args:
+            task (`str`):
+                The Hugging Face task to get which model Hugging Face recommends.
+                All available tasks can be found [here](https://huggingface.co/tasks).
+
+        Returns:
+            `str`: Name of the model recommended for the input task.
+
+        Raises:
+            `ValueError`: If Hugging Face has no recommendation for the input task.
+        """
+        model = _fetch_recommended_models().get(task)
+        if model is None:
+            raise ValueError(
+                f"Task {task} has no recommended model. Please specify a model"
+                " explicitly. Visit https://huggingface.co/tasks for more info."
+            )
+        return model
+
+    def get_model_status(self, model: Optional[str] = None) -> ModelStatus:
+        """
+        Get the status of a model hosted on the Inference API.
+
+        <Tip>
+
+        This endpoint is mostly useful when you already know which model you want to use and want to check its
+        availability. If you want to discover already deployed models, you should rather use [`~InferenceClient.list_deployed_models`].
+
+        </Tip>
+
+        Args:
+            model (`str`, *optional*):
+                Identifier of the model for witch the status gonna be checked. If model is not provided,
+                the model associated with this instance of [`InferenceClient`] will be used. Only InferenceAPI service can be checked so the
+                identifier cannot be a URL.
+
+
+        Returns:
+            [`ModelStatus`]: An instance of ModelStatus dataclass, containing information,
+                         about the state of the model: load, state, compute type and framework.
+
+        Example:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.get_model_status("bigcode/starcoder")
+        ModelStatus(loaded=True, state='Loaded', compute_type='gpu', framework='text-generation-inference')
+        ```
+        """
+        model = model or self.model
+        if model is None:
+            raise ValueError("Model id not provided.")
+        if model.startswith("https://"):
+            raise NotImplementedError("Model status is only available for Inference API endpoints.")
+        url = f"{INFERENCE_ENDPOINT}/status/{model}"
+
+        response = get_session().get(url, headers=self.headers)
+        hf_raise_for_status(response)
+        response_data = response.json()
+
+        if "error" in response_data:
+            raise ValueError(response_data["error"])
+
+        return ModelStatus(
+            loaded=response_data["loaded"],
+            state=response_data["state"],
+            compute_type=response_data["compute_type"],
+            framework=response_data["framework"],
+        )

lib/python3.11/site-packages/huggingface_hub/inference/_common.py

@@ -0,0 +1,327 @@
+# 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
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncIterable,
+    BinaryIO,
+    ContextManager,
+    Dict,
+    Generator,
+    Iterable,
+    List,
+    Literal,
+    Optional,
+    Set,
+    Union,
+    overload,
+)
+
+from requests import HTTPError
+
+from ..constants import ENDPOINT
+from ..utils import (
+    build_hf_headers,
+    get_session,
+    hf_raise_for_status,
+    is_aiohttp_available,
+    is_numpy_available,
+    is_pillow_available,
+)
+from ._text_generation import TextGenerationStreamResponse, _parse_text_generation_error
+
+
+if TYPE_CHECKING:
+    from aiohttp import ClientResponse, ClientSession
+    from PIL import Image
+
+# TYPES
+UrlT = str
+PathT = Union[str, Path]
+BinaryT = Union[bytes, BinaryIO]
+ContentT = Union[BinaryT, PathT, UrlT]
+
+# Use to set a Accept: image/png header
+TASKS_EXPECTING_IMAGES = {"text-to-image", "image-to-image"}
+
+logger = logging.getLogger(__name__)
+
+
+# Add dataclass for ModelStatus. We use this dataclass in get_model_status function.
+@dataclass
+class ModelStatus:
+    """
+    This Dataclass represents the the model status in the Hugging Face Inference API.
+
+    Args:
+        loaded (`bool`):
+            If the model is currently loaded into Hugging Face's InferenceAPI. Models
+            are loaded on-demand, leading to the user's first request taking longer.
+            If a model is loaded, you can be assured that it is in a healthy state.
+        state (`str`):
+            The current state of the model. This can be 'Loaded', 'Loadable', 'TooBig'.
+            If a model's state is 'Loadable', it's not too big and has a supported
+            backend. Loadable models are automatically loaded when the user first
+            requests inference on the endpoint. This means it is transparent for the
+            user to load a model, except that the first call takes longer to complete.
+        compute_type (`str`):
+            The type of compute resource the model is using or will use, such as 'gpu' or 'cpu'.
+        framework (`str`):
+            The name of the framework that the model was built with, such as 'transformers'
+            or 'text-generation-inference'.
+    """
+
+    loaded: bool
+    state: str
+    compute_type: str
+    framework: str
+
+
+class InferenceTimeoutError(HTTPError, TimeoutError):
+    """Error raised when a model is unavailable or the request times out."""
+
+
+## IMPORT UTILS
+
+
+def _import_aiohttp():
+    # Make sure `aiohttp` is installed on the machine.
+    if not is_aiohttp_available():
+        raise ImportError("Please install aiohttp to use `AsyncInferenceClient` (`pip install aiohttp`).")
+    import aiohttp
+
+    return aiohttp
+
+
+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
+
+
+## RECOMMENDED MODELS
+
+# Will be globally fetched only once (see '_fetch_recommended_models')
+_RECOMMENDED_MODELS: Optional[Dict[str, Optional[str]]] = None
+
+
+def _fetch_recommended_models() -> Dict[str, Optional[str]]:
+    global _RECOMMENDED_MODELS
+    if _RECOMMENDED_MODELS is None:
+        response = get_session().get(f"{ENDPOINT}/api/tasks", headers=build_hf_headers())
+        hf_raise_for_status(response)
+        _RECOMMENDED_MODELS = {
+            task: _first_or_none(details["widgetModels"]) for task, details in response.json().items()
+        }
+    return _RECOMMENDED_MODELS
+
+
+def _first_or_none(items: List[Any]) -> Optional[Any]:
+    try:
+        return items[0] or None
+    except IndexError:
+        return None
+
+
+## ENCODING / DECODING UTILS
+
+
+@overload
+def _open_as_binary(content: ContentT) -> ContextManager[BinaryT]:
+    ...  # means "if input is not None, output is not None"
+
+
+@overload
+def _open_as_binary(content: Literal[None]) -> ContextManager[Literal[None]]:
+    ...  # means "if input is None, output is None"
+
+
+@contextmanager  # type: ignore
+def _open_as_binary(content: Optional[ContentT]) -> Generator[Optional[BinaryT], None, None]:
+    """Open `content` as a binary file, either from a URL, a local path, or raw bytes.
+
+    Do nothing if `content` is None,
+
+    TODO: handle a PIL.Image as input
+    TODO: handle base64 as input
+    """
+    # 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}")
+            yield get_session().get(content).content  # TODO: retrieve as stream and pipe to post request ?
+            return
+        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}")
+        with content.open("rb") as f:
+            yield f
+    else:
+        # Otherwise: already a file-like object or None
+        yield content
+
+
+def _b64_encode(content: ContentT) -> str:
+    """Encode a raw file (image, audio) into base64. Can be byes, an opened file, a path or a URL."""
+    with _open_as_binary(content) as data:
+        data_as_bytes = data if isinstance(data, bytes) else data.read()
+        return base64.b64encode(data_as_bytes).decode()
+
+
+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))
+
+
+## STREAMING UTILS
+
+
+def _stream_text_generation_response(
+    bytes_output_as_lines: Iterable[bytes], details: bool
+) -> Union[Iterable[str], Iterable[TextGenerationStreamResponse]]:
+    # Parse ServerSentEvents
+    for byte_payload in bytes_output_as_lines:
+        # Skip line
+        if byte_payload == b"\n":
+            continue
+
+        payload = byte_payload.decode("utf-8")
+
+        # Event data
+        if payload.startswith("data:"):
+            # Decode payload
+            json_payload = json.loads(payload.lstrip("data:").rstrip("/n"))
+            # 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 = TextGenerationStreamResponse(**json_payload)
+            yield output.token.text if not details else output
+
+
+async def _async_stream_text_generation_response(
+    bytes_output_as_lines: AsyncIterable[bytes], details: bool
+) -> Union[AsyncIterable[str], AsyncIterable[TextGenerationStreamResponse]]:
+    # Parse ServerSentEvents
+    async for byte_payload in bytes_output_as_lines:
+        # Skip line
+        if byte_payload == b"\n":
+            continue
+
+        payload = byte_payload.decode("utf-8")
+
+        # Event data
+        if payload.startswith("data:"):
+            # Decode payload
+            json_payload = json.loads(payload.lstrip("data:").rstrip("/n"))
+            # 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 = TextGenerationStreamResponse(**json_payload)
+            yield output.token.text if not details else output
+
+
+async def _async_yield_from(client: "ClientSession", response: "ClientResponse") -> AsyncIterable[bytes]:
+    async for byte_payload in response.content:
+        yield byte_payload
+    await client.close()
+
+
+# "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 fallback to the
+# default API with a warning message. We remember for each model if it's a TGI server
+# or not using `_NON_TGI_SERVERS` global variable.
+#
+# For more details, see https://github.com/huggingface/text-generation-inference and
+# https://huggingface.co/docs/api-inference/detailed_parameters#text-generation-task.
+
+_NON_TGI_SERVERS: Set[Optional[str]] = set()
+
+
+def _set_as_non_tgi(model: Optional[str]) -> None:
+    _NON_TGI_SERVERS.add(model)
+
+
+def _is_tgi_server(model: Optional[str]) -> bool:
+    return model not in _NON_TGI_SERVERS

lib/python3.11/site-packages/huggingface_hub/inference/_generated/_async_client.py

@@ -0,0 +1,2020 @@
+# 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.
+#
+# WARNING
+# This entire file has been adapted from the sync-client code in `src/huggingface_hub/inference/_client.py`.
+# Any change in InferenceClient will be automatically reflected in AsyncInferenceClient.
+# To re-generate the code, run `make style` or `python ./utils/generate_async_inference_client.py --update`.
+# WARNING
+import asyncio
+import logging
+import time
+import warnings
+from dataclasses import asdict
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncIterable,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Union,
+    overload,
+)
+
+from requests.structures import CaseInsensitiveDict
+
+from huggingface_hub.constants import ALL_INFERENCE_API_FRAMEWORKS, INFERENCE_ENDPOINT, MAIN_INFERENCE_API_FRAMEWORKS
+from huggingface_hub.inference._common import (
+    TASKS_EXPECTING_IMAGES,
+    ContentT,
+    InferenceTimeoutError,
+    ModelStatus,
+    _async_stream_text_generation_response,
+    _b64_encode,
+    _b64_to_image,
+    _bytes_to_dict,
+    _bytes_to_image,
+    _bytes_to_list,
+    _fetch_recommended_models,
+    _import_numpy,
+    _is_tgi_server,
+    _open_as_binary,
+    _set_as_non_tgi,
+)
+from huggingface_hub.inference._text_generation import (
+    TextGenerationParameters,
+    TextGenerationRequest,
+    TextGenerationResponse,
+    TextGenerationStreamResponse,
+    raise_text_generation_error,
+)
+from huggingface_hub.inference._types import (
+    ClassificationOutput,
+    ConversationalOutput,
+    FillMaskOutput,
+    ImageSegmentationOutput,
+    ObjectDetectionOutput,
+    QuestionAnsweringOutput,
+    TableQuestionAnsweringOutput,
+    TokenClassificationOutput,
+)
+from huggingface_hub.utils import (
+    build_hf_headers,
+)
+
+from .._common import _async_yield_from, _import_aiohttp
+
+
+if TYPE_CHECKING:
+    import numpy as np
+    from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncInferenceClient:
+    """
+    Initialize a new Inference Client.
+
+    [`InferenceClient`] aims to provide a unified experience to perform inference. The client can be used
+    seamlessly with either the (free) Inference API or self-hosted Inference Endpoints.
+
+    Args:
+        model (`str`, `optional`):
+            The model to run inference with. Can be a model id hosted on the Hugging Face Hub, e.g. `bigcode/starcoder`
+            or a URL to a deployed Inference Endpoint. Defaults to None, in which case a recommended model is
+            automatically selected for the task.
+        token (`str`, *optional*):
+            Hugging Face token. Will default to the locally saved token. Pass `token=False` if you don't want to send
+            your token to the server.
+        timeout (`float`, `optional`):
+            The maximum number of seconds to wait for a response from the server. Loading a new model in Inference
+            API can take up to several minutes. Defaults to None, meaning it will loop until the server is available.
+        headers (`Dict[str, str]`, `optional`):
+            Additional headers to send to the server. By default only the authorization and user-agent headers are sent.
+            Values in this dictionary will override the default values.
+        cookies (`Dict[str, str]`, `optional`):
+            Additional cookies to send to the server.
+    """
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        token: Union[str, bool, None] = None,
+        timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+        cookies: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.model: Optional[str] = model
+        self.headers = CaseInsensitiveDict(build_hf_headers(token=token))  # contains 'authorization' + 'user-agent'
+        if headers is not None:
+            self.headers.update(headers)
+        self.cookies = cookies
+        self.timeout = timeout
+
+    def __repr__(self):
+        return f"<InferenceClient(model='{self.model if self.model else ''}', timeout={self.timeout})>"
+
+    @overload
+    async def post(  # type: ignore[misc]
+        self,
+        *,
+        json: Optional[Union[str, Dict, List]] = None,
+        data: Optional[ContentT] = None,
+        model: Optional[str] = None,
+        task: Optional[str] = None,
+        stream: Literal[False] = ...,
+    ) -> bytes:
+        pass
+
+    @overload
+    async def post(
+        self,
+        *,
+        json: Optional[Union[str, Dict, List]] = None,
+        data: Optional[ContentT] = None,
+        model: Optional[str] = None,
+        task: Optional[str] = None,
+        stream: Literal[True] = ...,
+    ) -> AsyncIterable[bytes]:
+        pass
+
+    async def post(
+        self,
+        *,
+        json: Optional[Union[str, Dict, List]] = None,
+        data: Optional[ContentT] = None,
+        model: Optional[str] = None,
+        task: Optional[str] = None,
+        stream: bool = False,
+    ) -> Union[bytes, AsyncIterable[bytes]]:
+        """
+        Make a POST request to the inference server.
+
+        Args:
+            json (`Union[str, Dict, List]`, *optional*):
+                The JSON data to send in the request body, specific to each task. Defaults to None.
+            data (`Union[str, Path, bytes, BinaryIO]`, *optional*):
+                The content to send in the request body, specific to each task.
+                It can be raw bytes, a pointer to an opened file, a local file path,
+                or a URL to an online resource (image, audio file,...). If both `json` and `data` are passed,
+                `data` will take precedence. At least `json` or `data` must be provided. Defaults to None.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. Will override the model defined at the instance level. Defaults to None.
+            task (`str`, *optional*):
+                The task to perform on the inference. All available tasks can be found
+                [here](https://huggingface.co/tasks). Used only to default to a recommended model if `model` is not
+                provided. At least `model` or `task` must be provided. Defaults to None.
+            stream (`bool`, *optional*):
+                Whether to iterate over streaming APIs.
+
+        Returns:
+            bytes: The raw bytes returned by the server.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+        """
+
+        aiohttp = _import_aiohttp()
+
+        url = self._resolve_url(model, task)
+
+        if data is not None and json is not None:
+            warnings.warn("Ignoring `json` as `data` is passed as binary.")
+
+        # Set Accept header if relevant
+        headers = self.headers.copy()
+        if task in TASKS_EXPECTING_IMAGES and "Accept" not in headers:
+            headers["Accept"] = "image/png"
+
+        t0 = time.time()
+        timeout = self.timeout
+        while True:
+            with _open_as_binary(data) as data_as_binary:
+                # Do not use context manager as we don't want to close the connection immediately when returning
+                # a stream
+                client = aiohttp.ClientSession(
+                    headers=headers, cookies=self.cookies, timeout=aiohttp.ClientTimeout(self.timeout)
+                )
+
+                try:
+                    response = await client.post(url, json=json, data=data_as_binary)
+                    response_error_payload = None
+                    if response.status != 200:
+                        try:
+                            response_error_payload = await response.json()  # get payload before connection closed
+                        except Exception:
+                            pass
+                    response.raise_for_status()
+                    if stream:
+                        return _async_yield_from(client, response)
+                    else:
+                        content = await response.read()
+                        await client.close()
+                        return content
+                except asyncio.TimeoutError as error:
+                    await client.close()
+                    # Convert any `TimeoutError` to a `InferenceTimeoutError`
+                    raise InferenceTimeoutError(f"Inference call timed out: {url}") from error  # type: ignore
+                except aiohttp.ClientResponseError as error:
+                    error.response_error_payload = response_error_payload
+                    await client.close()
+                    if response.status == 422 and task is not None:
+                        error.message += f". Make sure '{task}' task is supported by the model."
+                    if response.status == 503:
+                        # If Model is unavailable, either raise a TimeoutError...
+                        if timeout is not None and time.time() - t0 > timeout:
+                            raise InferenceTimeoutError(
+                                f"Model not loaded on the server: {url}. Please retry with a higher timeout"
+                                f" (current: {self.timeout}).",
+                                request=error.request,
+                                response=error.response,
+                            ) from error
+                        # ...or wait 1s and retry
+                        logger.info(f"Waiting for model to be loaded on the server: {error}")
+                        time.sleep(1)
+                        if timeout is not None:
+                            timeout = max(self.timeout - (time.time() - t0), 1)  # type: ignore
+                        continue
+                    raise error
+
+    async def audio_classification(
+        self,
+        audio: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ClassificationOutput]:
+        """
+        Perform audio classification on the provided audio content.
+
+        Args:
+            audio (Union[str, Path, bytes, BinaryIO]):
+                The audio content to classify. It can be raw audio bytes, a local audio file, or a URL pointing to an
+                audio file.
+            model (`str`, *optional*):
+                The model to use for audio classification. Can be a model ID hosted on the Hugging Face Hub
+                or a URL to a deployed Inference Endpoint. If not provided, the default recommended model for
+                audio classification will be used.
+
+        Returns:
+            `List[Dict]`: The classification output containing the predicted label and its confidence.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.audio_classification("audio.flac")
+        [{'score': 0.4976358711719513, 'label': 'hap'}, {'score': 0.3677836060523987, 'label': 'neu'},...]
+        ```
+        """
+        response = await self.post(data=audio, model=model, task="audio-classification")
+        return _bytes_to_list(response)
+
+    async def automatic_speech_recognition(
+        self,
+        audio: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> str:
+        """
+        Perform automatic speech recognition (ASR or audio-to-text) on the given audio content.
+
+        Args:
+            audio (Union[str, Path, bytes, BinaryIO]):
+                The content to transcribe. It can be raw audio bytes, local audio file, or a URL to an audio file.
+            model (`str`, *optional*):
+                The model to use for ASR. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. If not provided, the default recommended model for ASR will be used.
+
+        Returns:
+            str: The transcribed text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.automatic_speech_recognition("hello_world.flac")
+        "hello world"
+        ```
+        """
+        response = await self.post(data=audio, model=model, task="automatic-speech-recognition")
+        return _bytes_to_dict(response)["text"]
+
+    async def conversational(
+        self,
+        text: str,
+        generated_responses: Optional[List[str]] = None,
+        past_user_inputs: Optional[List[str]] = None,
+        *,
+        parameters: Optional[Dict[str, Any]] = None,
+        model: Optional[str] = None,
+    ) -> ConversationalOutput:
+        """
+        Generate conversational responses based on the given input text (i.e. chat with the API).
+
+        Args:
+            text (`str`):
+                The last input from the user in the conversation.
+            generated_responses (`List[str]`, *optional*):
+                A list of strings corresponding to the earlier replies from the model. Defaults to None.
+            past_user_inputs (`List[str]`, *optional*):
+                A list of strings corresponding to the earlier replies from the user. Should be the same length as
+                `generated_responses`. Defaults to None.
+            parameters (`Dict[str, Any]`, *optional*):
+                Additional parameters for the conversational task. Defaults to None. For more details about the available
+                parameters, please refer to [this page](https://huggingface.co/docs/api-inference/detailed_parameters#conversational-task)
+            model (`str`, *optional*):
+                The model to use for the conversational task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended conversational model will be used.
+                Defaults to None.
+
+        Returns:
+            `Dict`: The generated conversational output.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> output = await client.conversational("Hi, who are you?")
+        >>> output
+        {'generated_text': 'I am the one who knocks.', 'conversation': {'generated_responses': ['I am the one who knocks.'], 'past_user_inputs': ['Hi, who are you?']}, 'warnings': ['Setting `pad_token_id` to `eos_token_id`:50256 async for open-end generation.']}
+        >>> await client.conversational(
+        ...     "Wow, that's scary!",
+        ...     generated_responses=output["conversation"]["generated_responses"],
+        ...     past_user_inputs=output["conversation"]["past_user_inputs"],
+        ... )
+        ```
+        """
+        payload: Dict[str, Any] = {"inputs": {"text": text}}
+        if generated_responses is not None:
+            payload["inputs"]["generated_responses"] = generated_responses
+        if past_user_inputs is not None:
+            payload["inputs"]["past_user_inputs"] = past_user_inputs
+        if parameters is not None:
+            payload["parameters"] = parameters
+        response = await self.post(json=payload, model=model, task="conversational")
+        return _bytes_to_dict(response)  # type: ignore
+
+    async def visual_question_answering(
+        self,
+        image: ContentT,
+        question: str,
+        *,
+        model: Optional[str] = None,
+    ) -> List[str]:
+        """
+        Answering open-ended questions based on an image.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image for the context. It can be raw bytes, an image file, or a URL to an online image.
+            question (`str`):
+                Question to be answered.
+            model (`str`, *optional*):
+                The model to use for the visual question answering task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended visual question answering model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label and associated probability.
+
+        Raises:
+            `InferenceTimeoutError`:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.visual_question_answering(
+        ...     image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg",
+        ...     question="What is the animal doing?"
+        ... )
+        [{'score': 0.778609573841095, 'answer': 'laying down'},{'score': 0.6957435607910156, 'answer': 'sitting'}, ...]
+        ```
+        """
+        payload: Dict[str, Any] = {"question": question, "image": _b64_encode(image)}
+        response = await self.post(json=payload, model=model, task="visual-question-answering")
+        return _bytes_to_list(response)
+
+    async def document_question_answering(
+        self,
+        image: ContentT,
+        question: str,
+        *,
+        model: Optional[str] = None,
+    ) -> List[QuestionAnsweringOutput]:
+        """
+        Answer questions on document images.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image for the context. It can be raw bytes, an image file, or a URL to an online image.
+            question (`str`):
+                Question to be answered.
+            model (`str`, *optional*):
+                The model to use for the document question answering task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended document question answering model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label, associated probability, word ids, and page number.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?")
+        [{'score': 0.42515629529953003, 'answer': 'us-001', 'start': 16, 'end': 16}]
+        ```
+        """
+        payload: Dict[str, Any] = {"question": question, "image": _b64_encode(image)}
+        response = await self.post(json=payload, model=model, task="document-question-answering")
+        return _bytes_to_list(response)
+
+    async def feature_extraction(self, text: str, *, model: Optional[str] = None) -> "np.ndarray":
+        """
+        Generate embeddings for a given text.
+
+        Args:
+            text (`str`):
+                The text to embed.
+            model (`str`, *optional*):
+                The model to use for the conversational task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended conversational model will be used.
+                Defaults to None.
+
+        Returns:
+            `np.ndarray`: The embedding representing the input text as a float32 numpy array.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.feature_extraction("Hi, who are you?")
+        array([[ 2.424802  ,  2.93384   ,  1.1750331 , ...,  1.240499, -0.13776633, -0.7889173 ],
+        [-0.42943227, -0.6364878 , -1.693462  , ...,  0.41978157, -2.4336355 ,  0.6162071 ],
+        ...,
+        [ 0.28552425, -0.928395  , -1.2077185 , ...,  0.76810825, -2.1069427 ,  0.6236161 ]], dtype=float32)
+        ```
+        """
+        response = await self.post(json={"inputs": text}, model=model, task="feature-extraction")
+        np = _import_numpy()
+        return np.array(_bytes_to_dict(response), dtype="float32")
+
+    async def fill_mask(self, text: str, *, model: Optional[str] = None) -> List[FillMaskOutput]:
+        """
+        Fill in a hole with a missing word (token to be precise).
+
+        Args:
+            text (`str`):
+                a string to be filled from, must contain the [MASK] token (check model card for exact name of the mask).
+            model (`str`, *optional*):
+                The model to use for the fill mask task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended fill mask model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of fill mask output dictionaries containing the predicted label, associated
+            probability, token reference, and completed text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.fill_mask("The goal of life is <mask>.")
+        [{'score': 0.06897063553333282,
+        'token': 11098,
+        'token_str': ' happiness',
+        'sequence': 'The goal of life is happiness.'},
+        {'score': 0.06554922461509705,
+        'token': 45075,
+        'token_str': ' immortality',
+        'sequence': 'The goal of life is immortality.'}]
+        ```
+        """
+        response = await self.post(json={"inputs": text}, model=model, task="fill-mask")
+        return _bytes_to_list(response)
+
+    async def image_classification(
+        self,
+        image: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ClassificationOutput]:
+        """
+        Perform image classification on the given image using the specified model.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The image to classify. It can be raw bytes, an image file, or a URL to an online image.
+            model (`str`, *optional*):
+                The model to use for image classification. Can be a model ID hosted on the Hugging Face Hub or a URL to a
+                deployed Inference Endpoint. If not provided, the default recommended model for image classification will be used.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label and associated probability.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
+        [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...]
+        ```
+        """
+        response = await self.post(data=image, model=model, task="image-classification")
+        return _bytes_to_list(response)
+
+    async def image_segmentation(
+        self,
+        image: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ImageSegmentationOutput]:
+        """
+        Perform image segmentation on the given image using the specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The image to segment. It can be raw bytes, an image file, or a URL to an online image.
+            model (`str`, *optional*):
+                The model to use for image segmentation. Can be a model ID hosted on the Hugging Face Hub or a URL to a
+                deployed Inference Endpoint. If not provided, the default recommended model for image segmentation will be used.
+
+        Returns:
+            `List[Dict]`: A list of dictionaries containing the segmented masks and associated attributes.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.image_segmentation("cat.jpg"):
+        [{'score': 0.989008, 'label': 'LABEL_184', 'mask': <PIL.PngImagePlugin.PngImageFile image mode=L size=400x300 at 0x7FDD2B129CC0>}, ...]
+        ```
+        """
+
+        # Segment
+        response = await self.post(data=image, model=model, task="image-segmentation")
+        output = _bytes_to_dict(response)
+
+        # Parse masks as PIL Image
+        if not isinstance(output, list):
+            raise ValueError(f"Server output must be a list. Got {type(output)}: {str(output)[:200]}...")
+        for item in output:
+            item["mask"] = _b64_to_image(item["mask"])
+        return output
+
+    async def image_to_image(
+        self,
+        image: ContentT,
+        prompt: Optional[str] = None,
+        *,
+        negative_prompt: Optional[str] = None,
+        height: Optional[int] = None,
+        width: Optional[int] = None,
+        num_inference_steps: Optional[int] = None,
+        guidance_scale: Optional[float] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> "Image":
+        """
+        Perform image-to-image translation using a specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image for translation. It can be raw bytes, an image file, or a URL to an online image.
+            prompt (`str`, *optional*):
+                The text prompt to guide the image generation.
+            negative_prompt (`str`, *optional*):
+                A negative prompt to guide the translation process.
+            height (`int`, *optional*):
+                The height in pixels of the generated image.
+            width (`int`, *optional*):
+                The width in pixels of the generated image.
+            num_inference_steps (`int`, *optional*):
+                The number of denoising steps. More denoising steps usually lead to a higher quality image at the
+                expense of slower inference.
+            guidance_scale (`float`, *optional*):
+                Higher guidance scale encourages to generate images that are closely linked to the text `prompt`,
+                usually at the expense of lower image quality.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `Image`: The translated image.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> image = await client.image_to_image("cat.jpg", prompt="turn the cat into a tiger")
+        >>> image.save("tiger.jpg")
+        ```
+        """
+        parameters = {
+            "prompt": prompt,
+            "negative_prompt": negative_prompt,
+            "height": height,
+            "width": width,
+            "num_inference_steps": num_inference_steps,
+            "guidance_scale": guidance_scale,
+            **kwargs,
+        }
+        if all(parameter is None for parameter in parameters.values()):
+            # Either only an image to send => send as raw bytes
+            data = image
+            payload: Optional[Dict[str, Any]] = None
+        else:
+            # Or an image + some parameters => use base64 encoding
+            data = None
+            payload = {"inputs": _b64_encode(image)}
+            for key, value in parameters.items():
+                if value is not None:
+                    payload.setdefault("parameters", {})[key] = value
+
+        response = await self.post(json=payload, data=data, model=model, task="image-to-image")
+        return _bytes_to_image(response)
+
+    async def image_to_text(self, image: ContentT, *, model: Optional[str] = None) -> str:
+        """
+        Takes an input image and return text.
+
+        Models can have very different outputs depending on your use case (image captioning, optical character recognition
+        (OCR), Pix2Struct, etc). Please have a look to the model card to learn more about a model's specificities.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image to caption. It can be raw bytes, an image file, or a URL to an online image..
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `str`: The generated text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.image_to_text("cat.jpg")
+        'a cat standing in a grassy field '
+        >>> await client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
+        'a dog laying on the grass next to a flower pot '
+        ```
+        """
+        response = await self.post(data=image, model=model, task="image-to-text")
+        return _bytes_to_dict(response)[0]["generated_text"]
+
+    async def list_deployed_models(
+        self, frameworks: Union[None, str, Literal["all"], List[str]] = None
+    ) -> Dict[str, List[str]]:
+        """
+        List models currently deployed on the Inference API service.
+
+        This helper checks deployed models framework by framework. By default, it will check the 4 main frameworks that
+        are supported and account for 95% of the hosted models. However, if you want a complete list of models you can
+        specify `frameworks="all"` as input. Alternatively, if you know before-hand which framework you are interested
+        in, you can also restrict to search to this one (e.g. `frameworks="text-generation-inference"`). The more
+        frameworks are checked, the more time it will take.
+
+        <Tip>
+
+        This endpoint is mostly useful for discoverability. If you already know which model you want to use and want to
+        check its availability, you can directly use [`~InferenceClient.get_model_status`].
+
+        </Tip>
+
+        Args:
+            frameworks (`Literal["all"]` or `List[str]` or `str`, *optional*):
+                The frameworks to filter on. By default only a subset of the available frameworks are tested. If set to
+                "all", all available frameworks will be tested. It is also possible to provide a single framework or a
+                custom set of frameworks to check.
+
+        Returns:
+            `Dict[str, List[str]]`: A dictionary mapping task names to a sorted list of model IDs.
+
+        Example:
+        ```py
+        # Must be run in an async contextthon
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+
+        # Discover zero-shot-classification models currently deployed
+        >>> models = await client.list_deployed_models()
+        >>> models["zero-shot-classification"]
+        ['Narsil/deberta-large-mnli-zero-cls', 'facebook/bart-large-mnli', ...]
+
+        # List from only 1 framework
+        >>> await client.list_deployed_models("text-generation-inference")
+        {'text-generation': ['bigcode/starcoder', 'meta-llama/Llama-2-70b-chat-hf', ...], ...}
+        ```
+        """
+        # Resolve which frameworks to check
+        if frameworks is None:
+            frameworks = MAIN_INFERENCE_API_FRAMEWORKS
+        elif frameworks == "all":
+            frameworks = ALL_INFERENCE_API_FRAMEWORKS
+        elif isinstance(frameworks, str):
+            frameworks = [frameworks]
+        frameworks = list(set(frameworks))
+
+        # Fetch them iteratively
+        models_by_task: Dict[str, List[str]] = {}
+
+        def _unpack_response(framework: str, items: List[Dict]) -> None:
+            for model in items:
+                if framework == "sentence-transformers":
+                    # Model running with the `sentence-transformers` framework can work with both tasks even if not
+                    # branded as such in the API response
+                    models_by_task.setdefault("feature-extraction", []).append(model["model_id"])
+                    models_by_task.setdefault("sentence-similarity", []).append(model["model_id"])
+                else:
+                    models_by_task.setdefault(model["task"], []).append(model["model_id"])
+
+        async def _fetch_framework(framework: str) -> None:
+            async with _import_aiohttp().ClientSession(headers=self.headers) as client:
+                response = await client.get(f"{INFERENCE_ENDPOINT}/framework/{framework}")
+                response.raise_for_status()
+                _unpack_response(framework, await response.json())
+
+        import asyncio
+
+        await asyncio.gather(*[_fetch_framework(framework) for framework in frameworks])
+
+        # Sort alphabetically for discoverability and return
+        for task, models in models_by_task.items():
+            models_by_task[task] = sorted(set(models), key=lambda x: x.lower())
+        return models_by_task
+
+    async def object_detection(
+        self,
+        image: ContentT,
+        *,
+        model: Optional[str] = None,
+    ) -> List[ObjectDetectionOutput]:
+        """
+        Perform object detection on the given image using the specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The image to detect objects on. It can be raw bytes, an image file, or a URL to an online image.
+            model (`str`, *optional*):
+                The model to use for object detection. Can be a model ID hosted on the Hugging Face Hub or a URL to a
+                deployed Inference Endpoint. If not provided, the default recommended model for object detection (DETR) will be used.
+
+        Returns:
+            `List[ObjectDetectionOutput]`: A list of dictionaries containing the bounding boxes and associated attributes.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+            `ValueError`:
+                If the request output is not a List.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.object_detection("people.jpg"):
+        [{"score":0.9486683011054993,"label":"person","box":{"xmin":59,"ymin":39,"xmax":420,"ymax":510}}, ... ]
+        ```
+        """
+        # detect objects
+        response = await self.post(data=image, model=model, task="object-detection")
+        output = _bytes_to_dict(response)
+        if not isinstance(output, list):
+            raise ValueError(f"Server output must be a list. Got {type(output)}: {str(output)[:200]}...")
+        return output
+
+    async def question_answering(
+        self, question: str, context: str, *, model: Optional[str] = None
+    ) -> QuestionAnsweringOutput:
+        """
+        Retrieve the answer to a question from a given text.
+
+        Args:
+            question (`str`):
+                Question to be answered.
+            context (`str`):
+                The context of the question.
+            model (`str`):
+                The model to use for the question answering task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint.
+
+        Returns:
+            `Dict`: a dictionary of question answering output containing the score, start index, end index, and answer.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.question_answering(question="What's my name?", context="My name is Clara and I live in Berkeley.")
+        {'score': 0.9326562285423279, 'start': 11, 'end': 16, 'answer': 'Clara'}
+        ```
+        """
+
+        payload: Dict[str, Any] = {"question": question, "context": context}
+        response = await self.post(
+            json=payload,
+            model=model,
+            task="question-answering",
+        )
+        return _bytes_to_dict(response)  # type: ignore
+
+    async def sentence_similarity(
+        self, sentence: str, other_sentences: List[str], *, model: Optional[str] = None
+    ) -> List[float]:
+        """
+        Compute the semantic similarity between a sentence and a list of other sentences by comparing their embeddings.
+
+        Args:
+            sentence (`str`):
+                The main sentence to compare to others.
+            other_sentences (`List[str]`):
+                The list of sentences to compare to.
+            model (`str`, *optional*):
+                The model to use for the conversational task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended conversational model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[float]`: The embedding representing the input text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.sentence_similarity(
+        ...     "Machine learning is so easy.",
+        ...     other_sentences=[
+        ...         "Deep learning is so straightforward.",
+        ...         "This is so difficult, like rocket science.",
+        ...         "I can't believe how much I struggled with this.",
+        ...     ],
+        ... )
+        [0.7785726189613342, 0.45876261591911316, 0.2906220555305481]
+        ```
+        """
+        response = await self.post(
+            json={"inputs": {"source_sentence": sentence, "sentences": other_sentences}},
+            model=model,
+            task="sentence-similarity",
+        )
+        return _bytes_to_list(response)
+
+    async def summarization(
+        self,
+        text: str,
+        *,
+        parameters: Optional[Dict[str, Any]] = None,
+        model: Optional[str] = None,
+    ) -> str:
+        """
+        Generate a summary of a given text using a specified model.
+
+        Args:
+            text (`str`):
+                The input text to summarize.
+            parameters (`Dict[str, Any]`, *optional*):
+                Additional parameters for summarization. Check out this [page](https://huggingface.co/docs/api-inference/detailed_parameters#summarization-task)
+                for more details.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `str`: The generated summary text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.summarization("The Eiffel tower...")
+        'The Eiffel tower is one of the most famous landmarks in the world....'
+        ```
+        """
+        payload: Dict[str, Any] = {"inputs": text}
+        if parameters is not None:
+            payload["parameters"] = parameters
+        response = await self.post(json=payload, model=model, task="summarization")
+        return _bytes_to_dict(response)[0]["summary_text"]
+
+    async def table_question_answering(
+        self, table: Dict[str, Any], query: str, *, model: Optional[str] = None
+    ) -> TableQuestionAnsweringOutput:
+        """
+        Retrieve the answer to a question from information given in a table.
+
+        Args:
+            table (`str`):
+                A table of data represented as a dict of lists where entries are headers and the lists are all the
+                values, all lists must have the same size.
+            query (`str`):
+                The query in plain text that you want to ask the table.
+            model (`str`):
+                The model to use for the table-question-answering task. Can be a model ID hosted on the Hugging Face
+                Hub or a URL to a deployed Inference Endpoint.
+
+        Returns:
+            `Dict`: a dictionary of table question answering output containing the answer, coordinates, cells and the aggregator used.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> query = "How many stars does the transformers repository have?"
+        >>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]}
+        >>> await client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq")
+        {'answer': 'AVERAGE > 36542', 'coordinates': [[0, 1]], 'cells': ['36542'], 'aggregator': 'AVERAGE'}
+        ```
+        """
+        response = await self.post(
+            json={
+                "query": query,
+                "table": table,
+            },
+            model=model,
+            task="table-question-answering",
+        )
+        return _bytes_to_dict(response)  # type: ignore
+
+    async def tabular_classification(self, table: Dict[str, Any], *, model: str) -> List[str]:
+        """
+        Classifying a target category (a group) based on a set of attributes.
+
+        Args:
+            table (`Dict[str, Any]`):
+                Set of attributes to classify.
+            model (`str`):
+                The model to use for the tabular-classification task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint.
+
+        Returns:
+            `List`: a list of labels, one per row in the initial table.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> table = {
+        ...     "fixed_acidity": ["7.4", "7.8", "10.3"],
+        ...     "volatile_acidity": ["0.7", "0.88", "0.32"],
+        ...     "citric_acid": ["0", "0", "0.45"],
+        ...     "residual_sugar": ["1.9", "2.6", "6.4"],
+        ...     "chlorides": ["0.076", "0.098", "0.073"],
+        ...     "free_sulfur_dioxide": ["11", "25", "5"],
+        ...     "total_sulfur_dioxide": ["34", "67", "13"],
+        ...     "density": ["0.9978", "0.9968", "0.9976"],
+        ...     "pH": ["3.51", "3.2", "3.23"],
+        ...     "sulphates": ["0.56", "0.68", "0.82"],
+        ...     "alcohol": ["9.4", "9.8", "12.6"],
+        ... }
+        >>> await client.tabular_classification(table=table, model="julien-c/wine-quality")
+        ["5", "5", "5"]
+        ```
+        """
+        response = await self.post(json={"table": table}, model=model, task="tabular-classification")
+        return _bytes_to_list(response)
+
+    async def tabular_regression(self, table: Dict[str, Any], *, model: str) -> List[float]:
+        """
+        Predicting a numerical target value given a set of attributes/features in a table.
+
+        Args:
+            table (`Dict[str, Any]`):
+                Set of attributes stored in a table. The attributes used to predict the target can be both numerical and categorical.
+            model (`str`):
+                The model to use for the tabular-regression task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint.
+
+        Returns:
+            `List`: a list of predicted numerical target values.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> table = {
+        ...     "Height": ["11.52", "12.48", "12.3778"],
+        ...     "Length1": ["23.2", "24", "23.9"],
+        ...     "Length2": ["25.4", "26.3", "26.5"],
+        ...     "Length3": ["30", "31.2", "31.1"],
+        ...     "Species": ["Bream", "Bream", "Bream"],
+        ...     "Width": ["4.02", "4.3056", "4.6961"],
+        ... }
+        >>> await client.tabular_regression(table, model="scikit-learn/Fish-Weight")
+        [110, 120, 130]
+        ```
+        """
+        response = await self.post(json={"table": table}, model=model, task="tabular-regression")
+        return _bytes_to_list(response)
+
+    async def text_classification(self, text: str, *, model: Optional[str] = None) -> List[ClassificationOutput]:
+        """
+        Perform text classification (e.g. sentiment-analysis) on the given text.
+
+        Args:
+            text (`str`):
+                A string to be classified.
+            model (`str`, *optional*):
+                The model to use for the text classification task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended text classification model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: a list of dictionaries containing the predicted label and associated probability.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.text_classification("I like you")
+        [{'label': 'POSITIVE', 'score': 0.9998695850372314}, {'label': 'NEGATIVE', 'score': 0.0001304351753788069}]
+        ```
+        """
+        response = await self.post(json={"inputs": text}, model=model, task="text-classification")
+        return _bytes_to_list(response)[0]
+
+    @overload
+    async def text_generation(  # type: ignore
+        self,
+        prompt: str,
+        *,
+        details: Literal[False] = ...,
+        stream: Literal[False] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> str:
+        ...
+
+    @overload
+    async def text_generation(  # type: ignore
+        self,
+        prompt: str,
+        *,
+        details: Literal[True] = ...,
+        stream: Literal[False] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> TextGenerationResponse:
+        ...
+
+    @overload
+    async def text_generation(  # type: ignore
+        self,
+        prompt: str,
+        *,
+        details: Literal[False] = ...,
+        stream: Literal[True] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> AsyncIterable[str]:
+        ...
+
+    @overload
+    async def text_generation(
+        self,
+        prompt: str,
+        *,
+        details: Literal[True] = ...,
+        stream: Literal[True] = ...,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+    ) -> AsyncIterable[TextGenerationStreamResponse]:
+        ...
+
+    async def text_generation(
+        self,
+        prompt: str,
+        *,
+        details: bool = False,
+        stream: bool = False,
+        model: Optional[str] = None,
+        do_sample: bool = False,
+        max_new_tokens: int = 20,
+        best_of: Optional[int] = None,
+        repetition_penalty: Optional[float] = None,
+        return_full_text: bool = False,
+        seed: Optional[int] = None,
+        stop_sequences: Optional[List[str]] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        truncate: Optional[int] = None,
+        typical_p: Optional[float] = None,
+        watermark: bool = False,
+        decoder_input_details: bool = False,
+    ) -> Union[str, TextGenerationResponse, AsyncIterable[str], AsyncIterable[TextGenerationStreamResponse]]:
+        """
+        Given a prompt, generate the following text.
+
+        It is recommended to have Pydantic installed in order to get inputs validated. This is preferable as it allow
+        early failures.
+
+        API endpoint is supposed to run with the `text-generation-inference` backend (TGI). 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. This method is compatible with both approaches but some parameters are only available for
+        `text-generation-inference`. If some parameters are ignored, a warning message is triggered but the process
+        continues correctly.
+
+        To learn more about the TGI project, please refer to https://github.com/huggingface/text-generation-inference.
+
+        Args:
+            prompt (`str`):
+                Input text.
+            details (`bool`, *optional*):
+                By default, text_generation returns a string. Pass `details=True` if you want a detailed output (tokens,
+                probabilities, seed, finish reason, etc.). Only available for models running on with the
+                `text-generation-inference` backend.
+            stream (`bool`, *optional*):
+                By default, text_generation returns the full generated text. Pass `stream=True` if you want a stream of
+                tokens to be returned. Only available for models running on with the `text-generation-inference`
+                backend.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+            do_sample (`bool`):
+                Activate logits sampling
+            max_new_tokens (`int`):
+                Maximum number of generated tokens
+            best_of (`int`):
+                Generate best_of sequences and return the one if the highest token logprobs
+            repetition_penalty (`float`):
+                The parameter for repetition penalty. 1.0 means no penalty. See [this
+                paper](https://arxiv.org/pdf/1909.05858.pdf) for more details.
+            return_full_text (`bool`):
+                Whether to prepend the prompt to the generated text
+            seed (`int`):
+                Random sampling seed
+            stop_sequences (`List[str]`):
+                Stop generating tokens if a member of `stop_sequences` is generated
+            temperature (`float`):
+                The value used to module the logits distribution.
+            top_k (`int`):
+                The number of highest probability vocabulary tokens to keep for top-k-filtering.
+            top_p (`float`):
+                If set to < 1, only the smallest set of most probable tokens with probabilities that add up to `top_p` or
+                higher are kept for generation.
+            truncate (`int`):
+                Truncate inputs tokens to the given size
+            typical_p (`float`):
+                Typical Decoding mass
+                See [Typical Decoding for Natural Language Generation](https://arxiv.org/abs/2202.00666) for more information
+            watermark (`bool`):
+                Watermarking with [A Watermark for Large Language Models](https://arxiv.org/abs/2301.10226)
+            decoder_input_details (`bool`):
+                Return the decoder input token logprobs and ids. You must set `details=True` as well for it to be taken
+                into account. Defaults to `False`.
+
+        Returns:
+            `Union[str, TextGenerationResponse, Iterable[str], Iterable[TextGenerationStreamResponse]]`:
+            Generated text returned from the server:
+            - if `stream=False` and `details=False`, the generated text is returned as a `str` (default)
+            - if `stream=True` and `details=False`, the generated text is returned token by token as a `Iterable[str]`
+            - if `stream=False` and `details=True`, the generated text is returned with more details as a [`~huggingface_hub.inference._text_generation.TextGenerationResponse`]
+            - if `details=True` and `stream=True`, the generated text is returned token by token as a iterable of [`~huggingface_hub.inference._text_generation.TextGenerationStreamResponse`]
+
+        Raises:
+            `ValidationError`:
+                If input values are not valid. No HTTP call is made to the server.
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+
+        # Case 1: generate text
+        >>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12)
+        '100% open source and built to be easy to use.'
+
+        # Case 2: iterate over the generated tokens. Useful async for large generation.
+        >>> async for token in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True):
+        ...     print(token)
+        100
+        %
+        open
+        source
+        and
+        built
+        to
+        be
+        easy
+        to
+        use
+        .
+
+        # Case 3: get more details about the generation process.
+        >>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True)
+        TextGenerationResponse(
+            generated_text='100% open source and built to be easy to use.',
+            details=Details(
+                finish_reason=<FinishReason.Length: 'length'>,
+                generated_tokens=12,
+                seed=None,
+                prefill=[
+                    InputToken(id=487, text='The', logprob=None),
+                    InputToken(id=53789, text=' hugging', logprob=-13.171875),
+                    (...)
+                    InputToken(id=204, text=' ', logprob=-7.0390625)
+                ],
+                tokens=[
+                    Token(id=1425, text='100', logprob=-1.0175781, special=False),
+                    Token(id=16, text='%', logprob=-0.0463562, special=False),
+                    (...)
+                    Token(id=25, text='.', logprob=-0.5703125, special=False)
+                ],
+                best_of_sequences=None
+            )
+        )
+
+        # Case 4: iterate over the generated tokens with more details.
+        # Last object is more complete, containing the full generated text and the finish reason.
+        >>> async for details in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True):
+        ...     print(details)
+        ...
+        TextGenerationStreamResponse(token=Token(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None)
+        TextGenerationStreamResponse(token=Token(
+            id=25,
+            text='.',
+            logprob=-0.5703125,
+            special=False),
+            generated_text='100% open source and built to be easy to use.',
+            details=StreamDetails(finish_reason=<FinishReason.Length: 'length'>, generated_tokens=12, seed=None)
+        )
+        ```
+        """
+        # NOTE: Text-generation integration is taken from the text-generation-inference project. It has more features
+        # like input/output validation (if Pydantic is installed). See `_text_generation.py` header for more details.
+
+        if decoder_input_details and not details:
+            warnings.warn(
+                "`decoder_input_details=True` has been passed to the server but `details=False` is set meaning that"
+                " the output from the server will be truncated."
+            )
+            decoder_input_details = False
+
+        # Validate parameters
+        parameters = TextGenerationParameters(
+            best_of=best_of,
+            details=details,
+            do_sample=do_sample,
+            max_new_tokens=max_new_tokens,
+            repetition_penalty=repetition_penalty,
+            return_full_text=return_full_text,
+            seed=seed,
+            stop=stop_sequences if stop_sequences is not None else [],
+            temperature=temperature,
+            top_k=top_k,
+            top_p=top_p,
+            truncate=truncate,
+            typical_p=typical_p,
+            watermark=watermark,
+            decoder_input_details=decoder_input_details,
+        )
+        request = TextGenerationRequest(inputs=prompt, stream=stream, parameters=parameters)
+        payload = asdict(request)
+
+        # Remove some parameters if not a TGI server
+        if not _is_tgi_server(model):
+            ignored_parameters = []
+            for key in "watermark", "stop", "details", "decoder_input_details":
+                if payload["parameters"][key] is not None:
+                    ignored_parameters.append(key)
+                del payload["parameters"][key]
+            if len(ignored_parameters) > 0:
+                warnings.warn(
+                    "API endpoint/model for text-generation is not served via TGI. Ignoring parameters"
+                    f" {ignored_parameters}.",
+                    UserWarning,
+                )
+            if details:
+                warnings.warn(
+                    "API endpoint/model for text-generation is not served via TGI. Parameter `details=True` will"
+                    " be ignored meaning only the generated text will be returned.",
+                    UserWarning,
+                )
+                details = False
+            if stream:
+                raise ValueError(
+                    "API endpoint/model for text-generation is not served via TGI. Cannot return output as a stream."
+                    " Please pass `stream=False` as input."
+                )
+
+        # Handle errors separately for more precise error messages
+        try:
+            bytes_output = await self.post(json=payload, model=model, task="text-generation", stream=stream)  # type: ignore
+        except _import_aiohttp().ClientResponseError as e:
+            error_message = getattr(e, "response_error_payload", {}).get("error", "")
+            if e.code == 400 and "The following `model_kwargs` are not used by the model" in error_message:
+                _set_as_non_tgi(model)
+                return await self.text_generation(  # type: ignore
+                    prompt=prompt,
+                    details=details,
+                    stream=stream,
+                    model=model,
+                    do_sample=do_sample,
+                    max_new_tokens=max_new_tokens,
+                    best_of=best_of,
+                    repetition_penalty=repetition_penalty,
+                    return_full_text=return_full_text,
+                    seed=seed,
+                    stop_sequences=stop_sequences,
+                    temperature=temperature,
+                    top_k=top_k,
+                    top_p=top_p,
+                    truncate=truncate,
+                    typical_p=typical_p,
+                    watermark=watermark,
+                    decoder_input_details=decoder_input_details,
+                )
+            raise_text_generation_error(e)
+
+        # Parse output
+        if stream:
+            return _async_stream_text_generation_response(bytes_output, details)  # type: ignore
+
+        data = _bytes_to_dict(bytes_output)[0]
+        return TextGenerationResponse(**data) if details else data["generated_text"]
+
+    async def text_to_image(
+        self,
+        prompt: str,
+        *,
+        negative_prompt: Optional[str] = None,
+        height: Optional[float] = None,
+        width: Optional[float] = None,
+        num_inference_steps: Optional[float] = None,
+        guidance_scale: Optional[float] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> "Image":
+        """
+        Generate an image based on a given text using a specified model.
+
+        <Tip warning={true}>
+
+        You must have `PIL` installed if you want to work with images (`pip install Pillow`).
+
+        </Tip>
+
+        Args:
+            prompt (`str`):
+                The prompt to generate an image from.
+            negative_prompt (`str`, *optional*):
+                An optional negative prompt for the image generation.
+            height (`float`, *optional*):
+                The height in pixels of the image to generate.
+            width (`float`, *optional*):
+                The width in pixels of the image to generate.
+            num_inference_steps (`int`, *optional*):
+                The number of denoising steps. More denoising steps usually lead to a higher quality image at the
+                expense of slower inference.
+            guidance_scale (`float`, *optional*):
+                Higher guidance scale encourages to generate images that are closely linked to the text `prompt`,
+                usually at the expense of lower image quality.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `Image`: The generated image.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+
+        >>> image = await client.text_to_image("An astronaut riding a horse on the moon.")
+        >>> image.save("astronaut.png")
+
+        >>> image = await client.text_to_image(
+        ...     "An astronaut riding a horse on the moon.",
+        ...     negative_prompt="low resolution, blurry",
+        ...     model="stabilityai/stable-diffusion-2-1",
+        ... )
+        >>> image.save("better_astronaut.png")
+        ```
+        """
+        payload = {"inputs": prompt}
+        parameters = {
+            "negative_prompt": negative_prompt,
+            "height": height,
+            "width": width,
+            "num_inference_steps": num_inference_steps,
+            "guidance_scale": guidance_scale,
+            **kwargs,
+        }
+        for key, value in parameters.items():
+            if value is not None:
+                payload.setdefault("parameters", {})[key] = value  # type: ignore
+        response = await self.post(json=payload, model=model, task="text-to-image")
+        return _bytes_to_image(response)
+
+    async def text_to_speech(self, text: str, *, model: Optional[str] = None) -> bytes:
+        """
+        Synthesize an audio of a voice pronouncing a given text.
+
+        Args:
+            text (`str`):
+                The text to synthesize.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `bytes`: The generated audio.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from pathlib import Path
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+
+        >>> audio = await client.text_to_speech("Hello world")
+        >>> Path("hello_world.flac").write_bytes(audio)
+        ```
+        """
+        return await self.post(json={"inputs": text}, model=model, task="text-to-speech")
+
+    async def token_classification(self, text: str, *, model: Optional[str] = None) -> List[TokenClassificationOutput]:
+        """
+        Perform token classification on the given text.
+        Usually used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text.
+
+        Args:
+            text (`str`):
+                A string to be classified.
+            model (`str`, *optional*):
+                The model to use for the token classification task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended token classification model will be used.
+                Defaults to None.
+
+        Returns:
+            `List[Dict]`: List of token classification outputs containing the entity group, confidence score, word, start and end index.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
+        [{'entity_group': 'PER',
+        'score': 0.9971321225166321,
+        'word': 'Sarah Jessica Parker',
+        'start': 11,
+        'end': 31},
+        {'entity_group': 'PER',
+        'score': 0.9773476123809814,
+        'word': 'Jessica',
+        'start': 52,
+        'end': 59}]
+        ```
+        """
+        payload: Dict[str, Any] = {"inputs": text}
+        response = await self.post(
+            json=payload,
+            model=model,
+            task="token-classification",
+        )
+        return _bytes_to_list(response)
+
+    async def translation(
+        self, text: str, *, model: Optional[str] = None, src_lang: Optional[str] = None, tgt_lang: Optional[str] = None
+    ) -> str:
+        """
+        Convert text from one language to another.
+
+        Check out https://huggingface.co/tasks/translation for more information on how to choose the best model for
+        your specific use case. Source and target languages usually depend on the model.
+        However, it is possible to specify source and target languages for certain models. If you are working with one of these models,
+        you can use `src_lang` and `tgt_lang` arguments to pass the relevant information.
+        You can find this information in the model card.
+
+        Args:
+            text (`str`):
+                A string to be translated.
+            model (`str`, *optional*):
+                The model to use for the translation task. Can be a model ID hosted on the Hugging Face Hub or a URL to
+                a deployed Inference Endpoint. If not provided, the default recommended translation model will be used.
+                Defaults to None.
+            src_lang (`str`, *optional*):
+                Source language of the translation task, i.e. input language. Cannot be passed without `tgt_lang`.
+            tgt_lang (`str`, *optional*):
+                Target language of the translation task, i.e. output language. Cannot be passed without `src_lang`.
+
+        Returns:
+            `str`: The generated translated text.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+            `ValueError`:
+                If only one of the `src_lang` and `tgt_lang` arguments are provided.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.translation("My name is Wolfgang and I live in Berlin")
+        'Mein Name ist Wolfgang und ich lebe in Berlin.'
+        >>> await client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr")
+        "Je m'appelle Wolfgang et je vis à Berlin."
+        ```
+
+        Specifying languages:
+        ```py
+        >>> client.translation("My name is Sarah Jessica Parker but you can call me Jessica", model="facebook/mbart-large-50-many-to-many-mmt", src_lang="en_XX", tgt_lang="fr_XX")
+        "Mon nom est Sarah Jessica Parker mais vous pouvez m\'appeler Jessica"
+        ```
+        """
+        # Throw error if only one of `src_lang` and `tgt_lang` was given
+        if src_lang is not None and tgt_lang is None:
+            raise ValueError("You cannot specify `src_lang` without specifying `tgt_lang`.")
+
+        if src_lang is None and tgt_lang is not None:
+            raise ValueError("You cannot specify `tgt_lang` without specifying `src_lang`.")
+
+        # If both `src_lang` and `tgt_lang` are given, pass them to the request body
+        payload: Dict = {"inputs": text}
+        if src_lang and tgt_lang:
+            payload["parameters"] = {"src_lang": src_lang, "tgt_lang": tgt_lang}
+        response = await self.post(json=payload, model=model, task="translation")
+        return _bytes_to_dict(response)[0]["translation_text"]
+
+    async def zero_shot_classification(
+        self, text: str, labels: List[str], *, multi_label: bool = False, model: Optional[str] = None
+    ) -> List[ClassificationOutput]:
+        """
+        Provide as input a text and a set of candidate labels to classify the input text.
+
+        Args:
+            text (`str`):
+                The input text to classify.
+            labels (`List[str]`):
+                List of string possible labels. There must be at least 2 labels.
+            multi_label (`bool`):
+                Boolean that is set to True if classes can overlap.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `List[Dict]`: List of classification outputs containing the predicted labels and their confidence.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> text = (
+        ...     "A new model offers an explanation async for how the Galilean satellites formed around the solar system's"
+        ...     "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling"
+        ...     " mysteries when he went async for a run up a hill in Nice, France."
+        ... )
+        >>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"]
+        >>> await client.zero_shot_classification(text, labels)
+        [
+            {"label": "scientific discovery", "score": 0.7961668968200684},
+            {"label": "space & cosmos", "score": 0.18570658564567566},
+            {"label": "microbiology", "score": 0.00730885099619627},
+            {"label": "archeology", "score": 0.006258360575884581},
+            {"label": "robots", "score": 0.004559356719255447},
+        ]
+        >>> await client.zero_shot_classification(text, labels, multi_label=True)
+        [
+            {"label": "scientific discovery", "score": 0.9829297661781311},
+            {"label": "space & cosmos", "score": 0.755190908908844},
+            {"label": "microbiology", "score": 0.0005462635890580714},
+            {"label": "archeology", "score": 0.00047131875180639327},
+            {"label": "robots", "score": 0.00030448526376858354},
+        ]
+        ```
+        """
+        # Raise ValueError if input is less than 2 labels
+        if len(labels) < 2:
+            raise ValueError("You must specify at least 2 classes to compare.")
+
+        response = await self.post(
+            json={
+                "inputs": text,
+                "parameters": {
+                    "candidate_labels": ",".join(labels),
+                    "multi_label": multi_label,
+                },
+            },
+            model=model,
+            task="zero-shot-classification",
+        )
+        output = _bytes_to_dict(response)
+        return [{"label": label, "score": score} for label, score in zip(output["labels"], output["scores"])]
+
+    async def zero_shot_image_classification(
+        self, image: ContentT, labels: List[str], *, model: Optional[str] = None
+    ) -> List[ClassificationOutput]:
+        """
+        Provide input image and text labels to predict text labels for the image.
+
+        Args:
+            image (`Union[str, Path, bytes, BinaryIO]`):
+                The input image to caption. It can be raw bytes, an image file, or a URL to an online image.
+            labels (`List[str]`):
+                List of string possible labels. There must be at least 2 labels.
+            model (`str`, *optional*):
+                The model to use for inference. Can be a model ID hosted on the Hugging Face Hub or a URL to a deployed
+                Inference Endpoint. This parameter overrides the model defined at the instance level. Defaults to None.
+
+        Returns:
+            `List[Dict]`: List of classification outputs containing the predicted labels and their confidence.
+
+        Raises:
+            [`InferenceTimeoutError`]:
+                If the model is unavailable or the request times out.
+            `aiohttp.ClientResponseError`:
+                If the request fails with an HTTP error status code other than HTTP 503.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+
+        >>> await client.zero_shot_image_classification(
+        ...     "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg",
+        ...     labels=["dog", "cat", "horse"],
+        ... )
+        [{"label": "dog", "score": 0.956}, ...]
+        ```
+        """
+        # Raise ValueError if input is less than 2 labels
+        if len(labels) < 2:
+            raise ValueError("You must specify at least 2 classes to compare.")
+
+        response = await self.post(
+            json={"image": _b64_encode(image), "parameters": {"candidate_labels": ",".join(labels)}},
+            model=model,
+            task="zero-shot-image-classification",
+        )
+        return _bytes_to_list(response)
+
+    def _resolve_url(self, model: Optional[str] = None, task: Optional[str] = None) -> str:
+        model = model or self.model
+
+        # If model is already a URL, ignore `task` and return directly
+        if model is not None and (model.startswith("http://") or model.startswith("https://")):
+            return model
+
+        # # If no model but task is set => fetch the recommended one for this task
+        if model is None:
+            if task is None:
+                raise ValueError(
+                    "You must specify at least a model (repo_id or URL) or a task, either when instantiating"
+                    " `InferenceClient` or when making a request."
+                )
+            model = self.get_recommended_model(task)
+            logger.info(
+                f"Using recommended model {model} for task {task}. Note that it is"
+                f" encouraged to explicitly set `model='{model}'` as the recommended"
+                " models list might get updated without prior notice."
+            )
+
+        # Compute InferenceAPI url
+        return (
+            # Feature-extraction and sentence-similarity are the only cases where we handle models with several tasks.
+            f"{INFERENCE_ENDPOINT}/pipeline/{task}/{model}"
+            if task in ("feature-extraction", "sentence-similarity")
+            # Otherwise, we use the default endpoint
+            else f"{INFERENCE_ENDPOINT}/models/{model}"
+        )
+
+    @staticmethod
+    def get_recommended_model(task: str) -> str:
+        """
+        Get the model Hugging Face recommends for the input task.
+
+        Args:
+            task (`str`):
+                The Hugging Face task to get which model Hugging Face recommends.
+                All available tasks can be found [here](https://huggingface.co/tasks).
+
+        Returns:
+            `str`: Name of the model recommended for the input task.
+
+        Raises:
+            `ValueError`: If Hugging Face has no recommendation for the input task.
+        """
+        model = _fetch_recommended_models().get(task)
+        if model is None:
+            raise ValueError(
+                f"Task {task} has no recommended model. Please specify a model"
+                " explicitly. Visit https://huggingface.co/tasks for more info."
+            )
+        return model
+
+    async def get_model_status(self, model: Optional[str] = None) -> ModelStatus:
+        """
+        Get the status of a model hosted on the Inference API.
+
+        <Tip>
+
+        This endpoint is mostly useful when you already know which model you want to use and want to check its
+        availability. If you want to discover already deployed models, you should rather use [`~InferenceClient.list_deployed_models`].
+
+        </Tip>
+
+        Args:
+            model (`str`, *optional*):
+                Identifier of the model for witch the status gonna be checked. If model is not provided,
+                the model associated with this instance of [`InferenceClient`] will be used. Only InferenceAPI service can be checked so the
+                identifier cannot be a URL.
+
+
+        Returns:
+            [`ModelStatus`]: An instance of ModelStatus dataclass, containing information,
+                         about the state of the model: load, state, compute type and framework.
+
+        Example:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.get_model_status("bigcode/starcoder")
+        ModelStatus(loaded=True, state='Loaded', compute_type='gpu', framework='text-generation-inference')
+        ```
+        """
+        model = model or self.model
+        if model is None:
+            raise ValueError("Model id not provided.")
+        if model.startswith("https://"):
+            raise NotImplementedError("Model status is only available for Inference API endpoints.")
+        url = f"{INFERENCE_ENDPOINT}/status/{model}"
+
+        async with _import_aiohttp().ClientSession(headers=self.headers) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+            response_data = await response.json()
+
+        if "error" in response_data:
+            raise ValueError(response_data["error"])
+
+        return ModelStatus(
+            loaded=response_data["loaded"],
+            state=response_data["state"],
+            compute_type=response_data["compute_type"],
+            framework=response_data["framework"],
+        )

lib/python3.11/site-packages/huggingface_hub/inference/_text_generation.py

@@ -0,0 +1,546 @@
+# 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.
+#
+# Original implementation taken from the `text-generation` Python client (see https://pypi.org/project/text-generation/
+# and https://github.com/huggingface/text-generation-inference/tree/main/clients/python)
+#
+# Changes compared to original implementation:
+# - use pydantic.dataclasses instead of BaseModel
+# - default to Python's dataclasses if Pydantic is not installed (same implementation but no validation)
+# - added default values for all parameters (not needed in BaseModel but dataclasses yes)
+# - integrated in `huggingface_hub.InferenceClient``
+# - added `stream: bool` and `details: bool` in the `text_generation` method instead of having different methods for each use case
+import warnings
+from dataclasses import field
+from enum import Enum
+from typing import List, NoReturn, Optional
+
+from requests import HTTPError
+
+from ..utils import is_pydantic_available
+
+
+if is_pydantic_available():
+    from pydantic import validator as pydantic_validator
+    from pydantic.dataclasses import dataclass
+
+    def validator(*args, **kwargs):
+        # Pydantic v1's `@validator` is deprecated in favor of `@field_validator`. In order to support both pydantic v1
+        # and v2 without changing the logic, we catch the warning message in pydantic v2 and ignore it. If we want to
+        # support pydantic v3 in the future, we will drop support for pydantic v1 and use `pydantic.field_validator`
+        # correctly.
+        #
+        # Related:
+        # - https://docs.pydantic.dev/latest/migration/#changes-to-validators
+        # - https://github.com/huggingface/huggingface_hub/pull/1837
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", message="Pydantic V1 style `@validator` validators are deprecated.")
+            return pydantic_validator(*args, **kwargs)
+else:
+    # No validation if Pydantic is not installed
+    from dataclasses import dataclass  # type: ignore
+
+    def validator(x):  # type: ignore
+        return lambda y: y
+
+
+@dataclass
+class TextGenerationParameters:
+    """
+    Parameters for text generation.
+
+    Args:
+        do_sample (`bool`, *optional*):
+            Activate logits sampling. Defaults to False.
+        max_new_tokens (`int`, *optional*):
+            Maximum number of generated tokens. Defaults to 20.
+        repetition_penalty (`Optional[float]`, *optional*):
+            The parameter for repetition penalty. A value of 1.0 means no penalty. See [this paper](https://arxiv.org/pdf/1909.05858.pdf)
+            for more details. Defaults to None.
+        return_full_text (`bool`, *optional*):
+            Whether to prepend the prompt to the generated text. Defaults to False.
+        stop (`List[str]`, *optional*):
+            Stop generating tokens if a member of `stop_sequences` is generated. Defaults to an empty list.
+        seed (`Optional[int]`, *optional*):
+            Random sampling seed. Defaults to None.
+        temperature (`Optional[float]`, *optional*):
+            The value used to modulate the logits distribution. Defaults to None.
+        top_k (`Optional[int]`, *optional*):
+            The number of highest probability vocabulary tokens to keep for top-k-filtering. Defaults to None.
+        top_p (`Optional[float]`, *optional*):
+            If set to a value less than 1, only the smallest set of most probable tokens with probabilities that add up
+            to `top_p` or higher are kept for generation. Defaults to None.
+        truncate (`Optional[int]`, *optional*):
+            Truncate input tokens to the given size. Defaults to None.
+        typical_p (`Optional[float]`, *optional*):
+            Typical Decoding mass. See [Typical Decoding for Natural Language Generation](https://arxiv.org/abs/2202.00666)
+            for more information. Defaults to None.
+        best_of (`Optional[int]`, *optional*):
+            Generate `best_of` sequences and return the one with the highest token logprobs. Defaults to None.
+        watermark (`bool`, *optional*):
+            Watermarking with [A Watermark for Large Language Models](https://arxiv.org/abs/2301.10226). Defaults to False.
+        details (`bool`, *optional*):
+            Get generation details. Defaults to False.
+        decoder_input_details (`bool`, *optional*):
+            Get decoder input token logprobs and ids. Defaults to False.
+    """
+
+    # Activate logits sampling
+    do_sample: bool = False
+    # Maximum number of generated tokens
+    max_new_tokens: int = 20
+    # The parameter for repetition penalty. 1.0 means no penalty.
+    # See [this paper](https://arxiv.org/pdf/1909.05858.pdf) for more details.
+    repetition_penalty: Optional[float] = None
+    # Whether to prepend the prompt to the generated text
+    return_full_text: bool = False
+    # Stop generating tokens if a member of `stop_sequences` is generated
+    stop: List[str] = field(default_factory=lambda: [])
+    # Random sampling seed
+    seed: Optional[int] = None
+    # The value used to module the logits distribution.
+    temperature: Optional[float] = None
+    # The number of highest probability vocabulary tokens to keep for top-k-filtering.
+    top_k: Optional[int] = None
+    # If set to < 1, only the smallest set of most probable tokens with probabilities that add up to `top_p` or
+    # higher are kept for generation.
+    top_p: Optional[float] = None
+    # truncate inputs tokens to the given size
+    truncate: Optional[int] = None
+    # Typical Decoding mass
+    # See [Typical Decoding for Natural Language Generation](https://arxiv.org/abs/2202.00666) for more information
+    typical_p: Optional[float] = None
+    # Generate best_of sequences and return the one if the highest token logprobs
+    best_of: Optional[int] = None
+    # Watermarking with [A Watermark for Large Language Models](https://arxiv.org/abs/2301.10226)
+    watermark: bool = False
+    # Get generation details
+    details: bool = False
+    # Get decoder input token logprobs and ids
+    decoder_input_details: bool = False
+
+    @validator("best_of")
+    def valid_best_of(cls, field_value, values):
+        if field_value is not None:
+            if field_value <= 0:
+                raise ValueError("`best_of` must be strictly positive")
+            if field_value > 1 and values["seed"] is not None:
+                raise ValueError("`seed` must not be set when `best_of` is > 1")
+            sampling = (
+                values["do_sample"]
+                | (values["temperature"] is not None)
+                | (values["top_k"] is not None)
+                | (values["top_p"] is not None)
+                | (values["typical_p"] is not None)
+            )
+            if field_value > 1 and not sampling:
+                raise ValueError("you must use sampling when `best_of` is > 1")
+
+        return field_value
+
+    @validator("repetition_penalty")
+    def valid_repetition_penalty(cls, v):
+        if v is not None and v <= 0:
+            raise ValueError("`repetition_penalty` must be strictly positive")
+        return v
+
+    @validator("seed")
+    def valid_seed(cls, v):
+        if v is not None and v < 0:
+            raise ValueError("`seed` must be positive")
+        return v
+
+    @validator("temperature")
+    def valid_temp(cls, v):
+        if v is not None and v <= 0:
+            raise ValueError("`temperature` must be strictly positive")
+        return v
+
+    @validator("top_k")
+    def valid_top_k(cls, v):
+        if v is not None and v <= 0:
+            raise ValueError("`top_k` must be strictly positive")
+        return v
+
+    @validator("top_p")
+    def valid_top_p(cls, v):
+        if v is not None and (v <= 0 or v >= 1.0):
+            raise ValueError("`top_p` must be > 0.0 and < 1.0")
+        return v
+
+    @validator("truncate")
+    def valid_truncate(cls, v):
+        if v is not None and v <= 0:
+            raise ValueError("`truncate` must be strictly positive")
+        return v
+
+    @validator("typical_p")
+    def valid_typical_p(cls, v):
+        if v is not None and (v <= 0 or v >= 1.0):
+            raise ValueError("`typical_p` must be > 0.0 and < 1.0")
+        return v
+
+
+@dataclass
+class TextGenerationRequest:
+    """
+    Request object for text generation (only for internal use).
+
+    Args:
+        inputs (`str`):
+            The prompt for text generation.
+        parameters (`Optional[TextGenerationParameters]`, *optional*):
+            Generation parameters.
+        stream (`bool`, *optional*):
+            Whether to stream output tokens. Defaults to False.
+    """
+
+    # Prompt
+    inputs: str
+    # Generation parameters
+    parameters: Optional[TextGenerationParameters] = None
+    # Whether to stream output tokens
+    stream: bool = False
+
+    @validator("inputs")
+    def valid_input(cls, v):
+        if not v:
+            raise ValueError("`inputs` cannot be empty")
+        return v
+
+    @validator("stream")
+    def valid_best_of_stream(cls, field_value, values):
+        parameters = values["parameters"]
+        if parameters is not None and parameters.best_of is not None and parameters.best_of > 1 and field_value:
+            raise ValueError("`best_of` != 1 is not supported when `stream` == True")
+        return field_value
+
+    def __post_init__(self):
+        if not is_pydantic_available():
+            # If pydantic is not installed, we need to instantiate the nested dataclasses manually
+            if self.parameters is not None and isinstance(self.parameters, dict):
+                self.parameters = TextGenerationParameters(**self.parameters)
+
+
+# Decoder input tokens
+@dataclass
+class InputToken:
+    """
+    Represents an input token.
+
+    Args:
+        id (`int`):
+            Token ID from the model tokenizer.
+        text (`str`):
+            Token text.
+        logprob (`float` or `None`):
+            Log probability of the token. Optional since the logprob of the first token cannot be computed.
+    """
+
+    # Token ID from the model tokenizer
+    id: int
+    # Token text
+    text: str
+    # Logprob
+    # Optional since the logprob of the first token cannot be computed
+    logprob: Optional[float] = None
+
+
+# Generated tokens
+@dataclass
+class Token:
+    """
+    Represents a token.
+
+    Args:
+        id (`int`):
+            Token ID from the model tokenizer.
+        text (`str`):
+            Token text.
+        logprob (`float`):
+            Log probability of the token.
+        special (`bool`):
+            Indicates whether the token is a special token. It can be used to ignore
+            tokens when concatenating.
+    """
+
+    # Token ID from the model tokenizer
+    id: int
+    # Token text
+    text: str
+    # Logprob
+    logprob: float
+    # Is the token a special token
+    # Can be used to ignore tokens when concatenating
+    special: bool
+
+
+# Generation finish reason
+class FinishReason(str, Enum):
+    # number of generated tokens == `max_new_tokens`
+    Length = "length"
+    # the model generated its end of sequence token
+    EndOfSequenceToken = "eos_token"
+    # the model generated a text included in `stop_sequences`
+    StopSequence = "stop_sequence"
+
+
+# Additional sequences when using the `best_of` parameter
+@dataclass
+class BestOfSequence:
+    """
+    Represents a best-of sequence generated during text generation.
+
+    Args:
+        generated_text (`str`):
+            The generated text.
+        finish_reason (`FinishReason`):
+            The reason for the generation to finish, represented by a `FinishReason` value.
+        generated_tokens (`int`):
+            The number of generated tokens in the sequence.
+        seed (`Optional[int]`):
+            The sampling seed if sampling was activated.
+        prefill (`List[InputToken]`):
+            The decoder input tokens. Empty if `decoder_input_details` is False. Defaults to an empty list.
+        tokens (`List[Token]`):
+            The generated tokens. Defaults to an empty list.
+    """
+
+    # Generated text
+    generated_text: str
+    # Generation finish reason
+    finish_reason: FinishReason
+    # Number of generated tokens
+    generated_tokens: int
+    # Sampling seed if sampling was activated
+    seed: Optional[int] = None
+    # Decoder input tokens, empty if decoder_input_details is False
+    prefill: List[InputToken] = field(default_factory=lambda: [])
+    # Generated tokens
+    tokens: List[Token] = field(default_factory=lambda: [])
+
+    def __post_init__(self):
+        if not is_pydantic_available():
+            # If pydantic is not installed, we need to instantiate the nested dataclasses manually
+            self.prefill = [
+                InputToken(**input_token) if isinstance(input_token, dict) else input_token
+                for input_token in self.prefill
+            ]
+            self.tokens = [Token(**token) if isinstance(token, dict) else token for token in self.tokens]
+
+
+# `generate` details
+@dataclass
+class Details:
+    """
+    Represents details of a text generation.
+
+    Args:
+        finish_reason (`FinishReason`):
+            The reason for the generation to finish, represented by a `FinishReason` value.
+        generated_tokens (`int`):
+            The number of generated tokens.
+        seed (`Optional[int]`):
+            The sampling seed if sampling was activated.
+        prefill (`List[InputToken]`, *optional*):
+            The decoder input tokens. Empty if `decoder_input_details` is False. Defaults to an empty list.
+        tokens (`List[Token]`):
+            The generated tokens. Defaults to an empty list.
+        best_of_sequences (`Optional[List[BestOfSequence]]`):
+            Additional sequences when using the `best_of` parameter.
+    """
+
+    # Generation finish reason
+    finish_reason: FinishReason
+    # Number of generated tokens
+    generated_tokens: int
+    # Sampling seed if sampling was activated
+    seed: Optional[int] = None
+    # Decoder input tokens, empty if decoder_input_details is False
+    prefill: List[InputToken] = field(default_factory=lambda: [])
+    # Generated tokens
+    tokens: List[Token] = field(default_factory=lambda: [])
+    # Additional sequences when using the `best_of` parameter
+    best_of_sequences: Optional[List[BestOfSequence]] = None
+
+    def __post_init__(self):
+        if not is_pydantic_available():
+            # If pydantic is not installed, we need to instantiate the nested dataclasses manually
+            self.prefill = [
+                InputToken(**input_token) if isinstance(input_token, dict) else input_token
+                for input_token in self.prefill
+            ]
+            self.tokens = [Token(**token) if isinstance(token, dict) else token for token in self.tokens]
+            if self.best_of_sequences is not None:
+                self.best_of_sequences = [
+                    BestOfSequence(**best_of_sequence) if isinstance(best_of_sequence, dict) else best_of_sequence
+                    for best_of_sequence in self.best_of_sequences
+                ]
+
+
+# `generate` return value
+@dataclass
+class TextGenerationResponse:
+    """
+    Represents a response for text generation.
+
+    Only returned when `details=True`, otherwise a string is returned.
+
+    Args:
+        generated_text (`str`):
+            The generated text.
+        details (`Optional[Details]`):
+            Generation details. Returned only if `details=True` is sent to the server.
+    """
+
+    # Generated text
+    generated_text: str
+    # Generation details
+    details: Optional[Details] = None
+
+    def __post_init__(self):
+        if not is_pydantic_available():
+            # If pydantic is not installed, we need to instantiate the nested dataclasses manually
+            if self.details is not None and isinstance(self.details, dict):
+                self.details = Details(**self.details)
+
+
+# `generate_stream` details
+@dataclass
+class StreamDetails:
+    """
+    Represents details of a text generation stream.
+
+    Args:
+        finish_reason (`FinishReason`):
+            The reason for the generation to finish, represented by a `FinishReason` value.
+        generated_tokens (`int`):
+            The number of generated tokens.
+        seed (`Optional[int]`):
+            The sampling seed if sampling was activated.
+    """
+
+    # Generation finish reason
+    finish_reason: FinishReason
+    # Number of generated tokens
+    generated_tokens: int
+    # Sampling seed if sampling was activated
+    seed: Optional[int] = None
+
+
+# `generate_stream` return value
+@dataclass
+class TextGenerationStreamResponse:
+    """
+    Represents a response for streaming text generation.
+
+    Only returned when `details=True` and `stream=True`.
+
+    Args:
+        token (`Token`):
+            The generated token.
+        generated_text (`Optional[str]`, *optional*):
+            The complete generated text. Only available when the generation is finished.
+        details (`Optional[StreamDetails]`, *optional*):
+            Generation details. Only available when the generation is finished.
+    """
+
+    # Generated token
+    token: Token
+    # Complete generated text
+    # Only available when the generation is finished
+    generated_text: Optional[str] = None
+    # Generation details
+    # Only available when the generation is finished
+    details: Optional[StreamDetails] = None
+
+    def __post_init__(self):
+        if not is_pydantic_available():
+            # If pydantic is not installed, we need to instantiate the nested dataclasses manually
+            if isinstance(self.token, dict):
+                self.token = Token(**self.token)
+            if self.details is not None and isinstance(self.details, dict):
+                self.details = StreamDetails(**self.details)
+
+
+# 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).
+# ----------------------
+
+
+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
+
+
+def raise_text_generation_error(http_error: HTTPError) -> 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
+
+    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

lib/python3.11/site-packages/huggingface_hub/inference/_types.py

@@ -0,0 +1,183 @@
+# 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.
+from typing import TYPE_CHECKING, List, TypedDict
+
+
+if TYPE_CHECKING:
+    from PIL import Image
+
+
+class ClassificationOutput(TypedDict):
+    """Dictionary containing the output of a [`~InferenceClient.audio_classification`] and  [`~InferenceClient.image_classification`] task.
+
+    Args:
+        label (`str`):
+            The label predicted by the model.
+        score (`float`):
+            The score of the label predicted by the model.
+    """
+
+    label: str
+    score: float
+
+
+class ConversationalOutputConversation(TypedDict):
+    """Dictionary containing the "conversation" part of a [`~InferenceClient.conversational`] task.
+
+    Args:
+        generated_responses (`List[str]`):
+            A list of the responses from the model.
+        past_user_inputs (`List[str]`):
+            A list of the inputs from the user. Must be the same length as `generated_responses`.
+    """
+
+    generated_responses: List[str]
+    past_user_inputs: List[str]
+
+
+class ConversationalOutput(TypedDict):
+    """Dictionary containing the output of a  [`~InferenceClient.conversational`] task.
+
+    Args:
+        generated_text (`str`):
+            The last response from the model.
+        conversation (`ConversationalOutputConversation`):
+            The past conversation.
+        warnings (`List[str]`):
+            A list of warnings associated with the process.
+    """
+
+    conversation: ConversationalOutputConversation
+    generated_text: str
+    warnings: List[str]
+
+
+class FillMaskOutput(TypedDict):
+    """Dictionary containing information about a [`~InferenceClient.fill_mask`] task.
+
+    Args:
+        score (`float`):
+            The probability of the token.
+        token (`int`):
+            The id of the token.
+        token_str (`str`):
+            The string representation of the token.
+        sequence (`str`):
+            The actual sequence of tokens that ran against the model (may contain special tokens).
+    """
+
+    score: float
+    token: int
+    token_str: str
+    sequence: str
+
+
+class ImageSegmentationOutput(TypedDict):
+    """Dictionary containing information about a [`~InferenceClient.image_segmentation`] task. In practice, image segmentation returns a
+    list of `ImageSegmentationOutput` with 1 item per mask.
+
+    Args:
+        label (`str`):
+            The label corresponding to the mask.
+        mask (`Image`):
+            An Image object representing the mask predicted by the model.
+        score (`float`):
+            The score associated with the label for this mask.
+    """
+
+    label: str
+    mask: "Image"
+    score: float
+
+
+class ObjectDetectionOutput(TypedDict):
+    """Dictionary containing information about a [`~InferenceClient.object_detection`] task.
+
+    Args:
+        label (`str`):
+            The label corresponding to the detected object.
+        box (`dict`):
+            A dict response of bounding box coordinates of
+            the detected object: xmin, ymin, xmax, ymax
+        score (`float`):
+            The score corresponding to the detected object.
+    """
+
+    label: str
+    box: dict
+    score: float
+
+
+class QuestionAnsweringOutput(TypedDict):
+    """Dictionary containing information about a [`~InferenceClient.question_answering`] task.
+
+    Args:
+        score (`float`):
+            A float that represents how likely that the answer is correct.
+        start (`int`):
+            The index (string wise) of the start of the answer within context.
+        end (`int`):
+            The index (string wise) of the end of the answer within context.
+        answer (`str`):
+            A string that is the answer within the text.
+    """
+
+    score: float
+    start: int
+    end: int
+    answer: str
+
+
+class TableQuestionAnsweringOutput(TypedDict):
+    """Dictionary containing information about a [`~InferenceClient.table_question_answering`] task.
+
+    Args:
+        answer (`str`):
+            The plaintext answer.
+        coordinates (`List[List[int]]`):
+            A list of coordinates of the cells referenced in the answer.
+        cells (`List[int]`):
+            A list of coordinates of the cells contents.
+        aggregator (`str`):
+            The aggregator used to get the answer.
+    """
+
+    answer: str
+    coordinates: List[List[int]]
+    cells: List[List[int]]
+    aggregator: str
+
+
+class TokenClassificationOutput(TypedDict):
+    """Dictionary containing the output of a [`~InferenceClient.token_classification`] task.
+
+    Args:
+        entity_group (`str`):
+            The type for the entity being recognized (model specific).
+        score (`float`):
+            The score of the label predicted by the model.
+        word (`str`):
+            The string that was captured.
+        start (`int`):
+            The offset stringwise where the answer is located. Useful to disambiguate if word occurs multiple times.
+        end (`int`):
+            The offset stringwise where the answer is located. Useful to disambiguate if word occurs multiple times.
+    """
+
+    entity_group: str
+    score: float
+    word: str
+    start: int
+    end: int

lib/python3.11/site-packages/huggingface_hub/inference_api.py

@@ -0,0 +1,217 @@
+import io
+from typing import Any, Dict, List, Optional, Union
+
+from .constants import INFERENCE_ENDPOINT
+from .hf_api import HfApi
+from .utils import build_hf_headers, get_session, is_pillow_available, logging, validate_hf_hub_args
+from .utils._deprecation import _deprecate_method
+
+
+logger = logging.get_logger(__name__)
+
+
+ALL_TASKS = [
+    # NLP
+    "text-classification",
+    "token-classification",
+    "table-question-answering",
+    "question-answering",
+    "zero-shot-classification",
+    "translation",
+    "summarization",
+    "conversational",
+    "feature-extraction",
+    "text-generation",
+    "text2text-generation",
+    "fill-mask",
+    "sentence-similarity",
+    # Audio
+    "text-to-speech",
+    "automatic-speech-recognition",
+    "audio-to-audio",
+    "audio-classification",
+    "voice-activity-detection",
+    # Computer vision
+    "image-classification",
+    "object-detection",
+    "image-segmentation",
+    "text-to-image",
+    "image-to-image",
+    # Others
+    "tabular-classification",
+    "tabular-regression",
+]
+
+
+class InferenceApi:
+    """Client to configure requests and make calls to the HuggingFace Inference API.
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub.inference_api import InferenceApi
+
+    >>> # Mask-fill example
+    >>> inference = InferenceApi("bert-base-uncased")
+    >>> inference(inputs="The goal of life is [MASK].")
+    [{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}]
+
+    >>> # Question Answering example
+    >>> inference = InferenceApi("deepset/roberta-base-squad2")
+    >>> inputs = {
+    ...     "question": "What's my name?",
+    ...     "context": "My name is Clara and I live in Berkeley.",
+    ... }
+    >>> inference(inputs)
+    {'score': 0.9326569437980652, 'start': 11, 'end': 16, 'answer': 'Clara'}
+
+    >>> # Zero-shot example
+    >>> inference = InferenceApi("typeform/distilbert-base-uncased-mnli")
+    >>> inputs = "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!"
+    >>> params = {"candidate_labels": ["refund", "legal", "faq"]}
+    >>> inference(inputs, params)
+    {'sequence': 'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!', 'labels': ['refund', 'faq', 'legal'], 'scores': [0.9378499388694763, 0.04914155602455139, 0.013008488342165947]}
+
+    >>> # Overriding configured task
+    >>> inference = InferenceApi("bert-base-uncased", task="feature-extraction")
+
+    >>> # Text-to-image
+    >>> inference = InferenceApi("stabilityai/stable-diffusion-2-1")
+    >>> inference("cat")
+    <PIL.PngImagePlugin.PngImageFile image (...)>
+
+    >>> # Return as raw response to parse the output yourself
+    >>> inference = InferenceApi("mio/amadeus")
+    >>> response = inference("hello world", raw_response=True)
+    >>> response.headers
+    {"Content-Type": "audio/flac", ...}
+    >>> response.content # raw bytes from server
+    b'(...)'
+    ```
+    """
+
+    @validate_hf_hub_args
+    @_deprecate_method(
+        version="1.0",
+        message=(
+            "`InferenceApi` client is deprecated in favor of the more feature-complete `InferenceClient`. Check out"
+            " this guide to learn how to convert your script to use it:"
+            " https://huggingface.co/docs/huggingface_hub/guides/inference#legacy-inferenceapi-client."
+        ),
+    )
+    def __init__(
+        self,
+        repo_id: str,
+        task: Optional[str] = None,
+        token: Optional[str] = None,
+        gpu: bool = False,
+    ):
+        """Inits headers and API call information.
+
+        Args:
+            repo_id (``str``):
+                Id of repository (e.g. `user/bert-base-uncased`).
+            task (``str``, `optional`, defaults ``None``):
+                Whether to force a task instead of using task specified in the
+                repository.
+            token (`str`, `optional`):
+                The API token to use as HTTP bearer authorization. This is not
+                the authentication token. You can find the token in
+                https://huggingface.co/settings/token. Alternatively, you can
+                find both your organizations and personal API tokens using
+                `HfApi().whoami(token)`.
+            gpu (`bool`, `optional`, defaults `False`):
+                Whether to use GPU instead of CPU for inference(requires Startup
+                plan at least).
+        """
+        self.options = {"wait_for_model": True, "use_gpu": gpu}
+        self.headers = build_hf_headers(token=token)
+
+        # Configure task
+        model_info = HfApi(token=token).model_info(repo_id=repo_id)
+        if not model_info.pipeline_tag and not task:
+            raise ValueError(
+                "Task not specified in the repository. Please add it to the model card"
+                " using pipeline_tag"
+                " (https://huggingface.co/docs#how-is-a-models-type-of-inference-api-and-widget-determined)"
+            )
+
+        if task and task != model_info.pipeline_tag:
+            if task not in ALL_TASKS:
+                raise ValueError(f"Invalid task {task}. Make sure it's valid.")
+
+            logger.warning(
+                "You're using a different task than the one specified in the"
+                " repository. Be sure to know what you're doing :)"
+            )
+            self.task = task
+        else:
+            assert model_info.pipeline_tag is not None, "Pipeline tag cannot be None"
+            self.task = model_info.pipeline_tag
+
+        self.api_url = f"{INFERENCE_ENDPOINT}/pipeline/{self.task}/{repo_id}"
+
+    def __repr__(self):
+        # Do not add headers to repr to avoid leaking token.
+        return f"InferenceAPI(api_url='{self.api_url}', task='{self.task}', options={self.options})"
+
+    def __call__(
+        self,
+        inputs: Optional[Union[str, Dict, List[str], List[List[str]]]] = None,
+        params: Optional[Dict] = None,
+        data: Optional[bytes] = None,
+        raw_response: bool = False,
+    ) -> Any:
+        """Make a call to the Inference API.
+
+        Args:
+            inputs (`str` or `Dict` or `List[str]` or `List[List[str]]`, *optional*):
+                Inputs for the prediction.
+            params (`Dict`, *optional*):
+                Additional parameters for the models. Will be sent as `parameters` in the
+                payload.
+            data (`bytes`, *optional*):
+                Bytes content of the request. In this case, leave `inputs` and `params` empty.
+            raw_response (`bool`, defaults to `False`):
+                If `True`, the raw `Response` object is returned. You can parse its content
+                as preferred. By default, the content is parsed into a more practical format
+                (json dictionary or PIL Image for example).
+        """
+        # Build payload
+        payload: Dict[str, Any] = {
+            "options": self.options,
+        }
+        if inputs:
+            payload["inputs"] = inputs
+        if params:
+            payload["parameters"] = params
+
+        # Make API call
+        response = get_session().post(self.api_url, headers=self.headers, json=payload, data=data)
+
+        # Let the user handle the response
+        if raw_response:
+            return response
+
+        # By default, parse the response for the user.
+        content_type = response.headers.get("Content-Type") or ""
+        if content_type.startswith("image"):
+            if not is_pillow_available():
+                raise ImportError(
+                    f"Task '{self.task}' returned as image but Pillow is not installed."
+                    " Please install it (`pip install Pillow`) or pass"
+                    " `raw_response=True` to get the raw `Response` object and parse"
+                    " the image by yourself."
+                )
+
+            from PIL import Image
+
+            return Image.open(io.BytesIO(response.content))
+        elif content_type == "application/json":
+            return response.json()
+        else:
+            raise NotImplementedError(
+                f"{content_type} output type is not implemented yet. You can pass"
+                " `raw_response=True` to get the raw `Response` object and parse the"
+                " output by yourself."
+            )

lib/python3.11/site-packages/huggingface_hub/keras_mixin.py

@@ -0,0 +1,480 @@
+import collections.abc as collections
+import json
+import os
+import warnings
+from pathlib import Path
+from shutil import copytree
+from typing import Any, Dict, List, Optional, Union
+
+from huggingface_hub import ModelHubMixin, snapshot_download
+from huggingface_hub.utils import (
+    get_tf_version,
+    is_graphviz_available,
+    is_pydot_available,
+    is_tf_available,
+    yaml_dump,
+)
+
+from .constants import CONFIG_NAME
+from .hf_api import HfApi
+from .utils import SoftTemporaryDirectory, logging, validate_hf_hub_args
+
+
+logger = logging.get_logger(__name__)
+
+if is_tf_available():
+    import tensorflow as tf  # type: ignore
+
+
+def _flatten_dict(dictionary, parent_key=""):
+    """Flatten a nested dictionary.
+    Reference: https://stackoverflow.com/a/6027615/10319735
+
+    Args:
+        dictionary (`dict`):
+            The nested dictionary to be flattened.
+        parent_key (`str`):
+            The parent key to be prefixed to the children keys.
+            Necessary for recursing over the nested dictionary.
+
+    Returns:
+        The flattened dictionary.
+    """
+    items = []
+    for key, value in dictionary.items():
+        new_key = f"{parent_key}.{key}" if parent_key else key
+        if isinstance(value, collections.MutableMapping):
+            items.extend(
+                _flatten_dict(
+                    value,
+                    new_key,
+                ).items()
+            )
+        else:
+            items.append((new_key, value))
+    return dict(items)
+
+
+def _create_hyperparameter_table(model):
+    """Parse hyperparameter dictionary into a markdown table."""
+    if model.optimizer is not None:
+        optimizer_params = model.optimizer.get_config()
+        # flatten the configuration
+        optimizer_params = _flatten_dict(optimizer_params)
+        optimizer_params["training_precision"] = tf.keras.mixed_precision.global_policy().name
+        table = "| Hyperparameters | Value |\n| :-- | :-- |\n"
+        for key, value in optimizer_params.items():
+            table += f"| {key} | {value} |\n"
+    else:
+        table = None
+    return table
+
+
+def _plot_network(model, save_directory):
+    tf.keras.utils.plot_model(
+        model,
+        to_file=f"{save_directory}/model.png",
+        show_shapes=False,
+        show_dtype=False,
+        show_layer_names=True,
+        rankdir="TB",
+        expand_nested=False,
+        dpi=96,
+        layer_range=None,
+    )
+
+
+def _create_model_card(
+    model,
+    repo_dir: Path,
+    plot_model: bool = True,
+    metadata: Optional[dict] = None,
+):
+    """
+    Creates a model card for the repository.
+
+    Do not overwrite an existing README.md file.
+    """
+    readme_path = repo_dir / "README.md"
+    if readme_path.exists():
+        return
+
+    hyperparameters = _create_hyperparameter_table(model)
+    if plot_model and is_graphviz_available() and is_pydot_available():
+        _plot_network(model, repo_dir)
+    if metadata is None:
+        metadata = {}
+    metadata["library_name"] = "keras"
+    model_card: str = "---\n"
+    model_card += yaml_dump(metadata, default_flow_style=False)
+    model_card += "---\n"
+    model_card += "\n## Model description\n\nMore information needed\n"
+    model_card += "\n## Intended uses & limitations\n\nMore information needed\n"
+    model_card += "\n## Training and evaluation data\n\nMore information needed\n"
+    if hyperparameters is not None:
+        model_card += "\n## Training procedure\n"
+        model_card += "\n### Training hyperparameters\n"
+        model_card += "\nThe following hyperparameters were used during training:\n\n"
+        model_card += hyperparameters
+        model_card += "\n"
+    if plot_model and os.path.exists(f"{repo_dir}/model.png"):
+        model_card += "\n ## Model Plot\n"
+        model_card += "\n<details>"
+        model_card += "\n<summary>View Model Plot</summary>\n"
+        path_to_plot = "./model.png"
+        model_card += f"\n![Model Image]({path_to_plot})\n"
+        model_card += "\n</details>"
+
+    readme_path.write_text(model_card)
+
+
+def save_pretrained_keras(
+    model,
+    save_directory: Union[str, Path],
+    config: Optional[Dict[str, Any]] = None,
+    include_optimizer: bool = False,
+    plot_model: bool = True,
+    tags: Optional[Union[list, str]] = None,
+    **model_save_kwargs,
+):
+    """
+    Saves a Keras model to save_directory in SavedModel format. Use this if
+    you're using the Functional or Sequential APIs.
+
+    Args:
+        model (`Keras.Model`):
+            The [Keras
+            model](https://www.tensorflow.org/api_docs/python/tf/keras/Model)
+            you'd like to save. The model must be compiled and built.
+        save_directory (`str` or `Path`):
+            Specify directory in which you want to save the Keras model.
+        config (`dict`, *optional*):
+            Configuration object to be saved alongside the model weights.
+        include_optimizer(`bool`, *optional*, defaults to `False`):
+            Whether or not to include optimizer in serialization.
+        plot_model (`bool`, *optional*, defaults to `True`):
+            Setting this to `True` will plot the model and put it in the model
+            card. Requires graphviz and pydot to be installed.
+        tags (Union[`str`,`list`], *optional*):
+            List of tags that are related to model or string of a single tag. See example tags
+            [here](https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1).
+        model_save_kwargs(`dict`, *optional*):
+            model_save_kwargs will be passed to
+            [`tf.keras.models.save_model()`](https://www.tensorflow.org/api_docs/python/tf/keras/models/save_model).
+    """
+    if is_tf_available():
+        import tensorflow as tf
+    else:
+        raise ImportError("Called a Tensorflow-specific function but could not import it.")
+
+    if not model.built:
+        raise ValueError("Model should be built before trying to save")
+
+    save_directory = Path(save_directory)
+    save_directory.mkdir(parents=True, exist_ok=True)
+
+    # saving config
+    if config:
+        if not isinstance(config, dict):
+            raise RuntimeError(f"Provided config to save_pretrained_keras should be a dict. Got: '{type(config)}'")
+
+        with (save_directory / CONFIG_NAME).open("w") as f:
+            json.dump(config, f)
+
+    metadata = {}
+    if isinstance(tags, list):
+        metadata["tags"] = tags
+    elif isinstance(tags, str):
+        metadata["tags"] = [tags]
+
+    task_name = model_save_kwargs.pop("task_name", None)
+    if task_name is not None:
+        warnings.warn(
+            "`task_name` input argument is deprecated. Pass `tags` instead.",
+            FutureWarning,
+        )
+        if "tags" in metadata:
+            metadata["tags"].append(task_name)
+        else:
+            metadata["tags"] = [task_name]
+
+    if model.history is not None:
+        if model.history.history != {}:
+            path = save_directory / "history.json"
+            if path.exists():
+                warnings.warn(
+                    "`history.json` file already exists, it will be overwritten by the history of this version.",
+                    UserWarning,
+                )
+            with path.open("w", encoding="utf-8") as f:
+                json.dump(model.history.history, f, indent=2, sort_keys=True)
+
+    _create_model_card(model, save_directory, plot_model, metadata)
+    tf.keras.models.save_model(model, save_directory, include_optimizer=include_optimizer, **model_save_kwargs)
+
+
+def from_pretrained_keras(*args, **kwargs) -> "KerasModelHubMixin":
+    r"""
+    Instantiate a pretrained Keras model from a pre-trained model from the Hub.
+    The model is expected to be in `SavedModel` format.
+
+    Args:
+        pretrained_model_name_or_path (`str` or `os.PathLike`):
+            Can be either:
+                - A string, the `model id` of a pretrained model hosted inside a
+                  model repo on huggingface.co. Valid model ids can be located
+                  at the root-level, like `bert-base-uncased`, or namespaced
+                  under a user or organization name, like
+                  `dbmdz/bert-base-german-cased`.
+                - You can add `revision` by appending `@` at the end of model_id
+                  simply like this: `dbmdz/bert-base-german-cased@main` Revision
+                  is the specific model version to use. It can be a branch name,
+                  a tag name, or a commit id, since we use a git-based system
+                  for storing models and other artifacts on huggingface.co, so
+                  `revision` can be any identifier allowed by git.
+                - A path to a `directory` containing model weights saved using
+                  [`~transformers.PreTrainedModel.save_pretrained`], e.g.,
+                  `./my_model_directory/`.
+                - `None` if you are both providing the configuration and state
+                  dictionary (resp. with keyword arguments `config` and
+                  `state_dict`).
+        force_download (`bool`, *optional*, defaults to `False`):
+            Whether to force the (re-)download of the model weights and
+            configuration files, overriding the cached versions if they exist.
+        resume_download (`bool`, *optional*, defaults to `False`):
+            Whether to delete incompletely received files. Will attempt to
+            resume the download if such a file exists.
+        proxies (`Dict[str, str]`, *optional*):
+            A dictionary of proxy servers to use by protocol or endpoint, e.g.,
+            `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. The
+            proxies are used on each request.
+        token (`str` or `bool`, *optional*):
+            The token to use as HTTP bearer authorization for remote files. If
+            `True`, will use the token generated when running `transformers-cli
+            login` (stored in `~/.huggingface`).
+        cache_dir (`Union[str, os.PathLike]`, *optional*):
+            Path to a directory in which a downloaded pretrained model
+            configuration should be cached if the standard cache should not be
+            used.
+        local_files_only(`bool`, *optional*, defaults to `False`):
+            Whether to only look at local files (i.e., do not try to download
+            the model).
+        model_kwargs (`Dict`, *optional*):
+            model_kwargs will be passed to the model during initialization
+
+    <Tip>
+
+    Passing `token=True` is required when you want to use a private
+    model.
+
+    </Tip>
+    """
+    return KerasModelHubMixin.from_pretrained(*args, **kwargs)
+
+
+@validate_hf_hub_args
+def push_to_hub_keras(
+    model,
+    repo_id: str,
+    *,
+    config: Optional[dict] = None,
+    commit_message: str = "Push Keras model using huggingface_hub.",
+    private: bool = False,
+    api_endpoint: Optional[str] = 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,
+    log_dir: Optional[str] = None,
+    include_optimizer: bool = False,
+    tags: Optional[Union[list, str]] = None,
+    plot_model: bool = True,
+    **model_save_kwargs,
+):
+    """
+    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:
+        model (`Keras.Model`):
+            The [Keras model](`https://www.tensorflow.org/api_docs/python/tf/keras/Model`) you'd like to push to the
+            Hub. The model must be compiled and built.
+        repo_id (`str`):
+                ID of the repository to push to (example: `"username/my-model"`).
+        commit_message (`str`, *optional*, defaults to "Add Keras model"):
+            Message to commit while pushing.
+        private (`bool`, *optional*, defaults to `False`):
+            Whether the repository created should be private.
+        api_endpoint (`str`, *optional*):
+            The API endpoint to use when pushing the model to the hub.
+        token (`str`, *optional*):
+            The token to use as HTTP bearer authorization for remote files. If
+            not set, will use the token set when logging in with
+            `huggingface-cli login` (stored in `~/.huggingface`).
+        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`.
+        config (`dict`, *optional*):
+            Configuration object to be saved alongside the model weights.
+        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.
+        log_dir (`str`, *optional*):
+            TensorBoard logging directory to be pushed. The Hub automatically
+            hosts and displays a TensorBoard instance if log files are included
+            in the repository.
+        include_optimizer (`bool`, *optional*, defaults to `False`):
+            Whether or not to include optimizer during serialization.
+        tags (Union[`list`, `str`], *optional*):
+            List of tags that are related to model or string of a single tag. See example tags
+            [here](https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1).
+        plot_model (`bool`, *optional*, defaults to `True`):
+            Setting this to `True` will plot the model and put it in the model
+            card. Requires graphviz and pydot to be installed.
+        model_save_kwargs(`dict`, *optional*):
+            model_save_kwargs will be passed to
+            [`tf.keras.models.save_model()`](https://www.tensorflow.org/api_docs/python/tf/keras/models/save_model).
+
+    Returns:
+        The url of the commit of your model in the given repository.
+    """
+    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_keras(
+            model,
+            saved_path,
+            config=config,
+            include_optimizer=include_optimizer,
+            tags=tags,
+            plot_model=plot_model,
+            **model_save_kwargs,
+        )
+
+        # If `log_dir` provided, delete remote logs and upload new ones
+        if log_dir is not None:
+            delete_patterns = (
+                []
+                if delete_patterns is None
+                else (
+                    [delete_patterns]  # convert `delete_patterns` to a list
+                    if isinstance(delete_patterns, str)
+                    else delete_patterns
+                )
+            )
+            delete_patterns.append("logs/*")
+            copytree(log_dir, saved_path / "logs")
+
+        return api.upload_folder(
+            repo_type="model",
+            repo_id=repo_id,
+            folder_path=saved_path,
+            commit_message=commit_message,
+            token=token,
+            revision=branch,
+            create_pr=create_pr,
+            allow_patterns=allow_patterns,
+            ignore_patterns=ignore_patterns,
+            delete_patterns=delete_patterns,
+        )
+
+
+class KerasModelHubMixin(ModelHubMixin):
+    """
+    Implementation of [`ModelHubMixin`] to provide model Hub upload/download
+    capabilities to Keras models.
+
+
+    ```python
+    >>> import tensorflow as tf
+    >>> from huggingface_hub import KerasModelHubMixin
+
+
+    >>> class MyModel(tf.keras.Model, KerasModelHubMixin):
+    ...     def __init__(self, **kwargs):
+    ...         super().__init__()
+    ...         self.config = kwargs.pop("config", None)
+    ...         self.dummy_inputs = ...
+    ...         self.layer = ...
+
+    ...     def call(self, *args):
+    ...         return ...
+
+
+    >>> # Initialize and compile the model as you normally would
+    >>> model = MyModel()
+    >>> model.compile(...)
+    >>> # Build the graph by training it or passing dummy inputs
+    >>> _ = model(model.dummy_inputs)
+    >>> # 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/super-cool-model")
+    ```
+    """
+
+    def _save_pretrained(self, save_directory):
+        save_pretrained_keras(self, save_directory)
+
+    @classmethod
+    def _from_pretrained(
+        cls,
+        model_id,
+        revision,
+        cache_dir,
+        force_download,
+        proxies,
+        resume_download,
+        local_files_only,
+        token,
+        **model_kwargs,
+    ):
+        """Here we just call [`from_pretrained_keras`] function so both the mixin and
+        functional APIs stay in sync.
+
+                TODO - Some args above aren't used since we are calling
+                snapshot_download instead of hf_hub_download.
+        """
+        if is_tf_available():
+            import tensorflow as tf
+        else:
+            raise ImportError("Called a TensorFlow-specific function but could not import it.")
+
+        # TODO - Figure out what to do about these config values. Config is not going to be needed to load model
+        cfg = model_kwargs.pop("config", None)
+
+        # Root is either a local filepath matching model_id or a cached snapshot
+        if not os.path.isdir(model_id):
+            storage_folder = snapshot_download(
+                repo_id=model_id,
+                revision=revision,
+                cache_dir=cache_dir,
+                library_name="keras",
+                library_version=get_tf_version(),
+            )
+        else:
+            storage_folder = model_id
+
+        model = tf.keras.models.load_model(storage_folder, **model_kwargs)
+
+        # For now, we add a new attribute, config, to store the config loaded from the hub/a local dir.
+        model.config = cfg
+
+        return model

lib/python3.11/site-packages/huggingface_hub/lfs.py

@@ -0,0 +1,522 @@
+# 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.
+"""Git LFS related type definitions and utilities"""
+import inspect
+import io
+import os
+import re
+import warnings
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from math import ceil
+from os.path import getsize
+from pathlib import Path
+from typing import TYPE_CHECKING, BinaryIO, Dict, Iterable, List, Optional, Tuple, TypedDict
+from urllib.parse import unquote
+
+from huggingface_hub.constants import ENDPOINT, HF_HUB_ENABLE_HF_TRANSFER, REPO_TYPES_URL_PREFIXES
+from huggingface_hub.utils import get_session
+
+from .utils import (
+    build_hf_headers,
+    hf_raise_for_status,
+    http_backoff,
+    logging,
+    tqdm,
+    validate_hf_hub_args,
+)
+from .utils.sha import sha256, sha_fileobj
+
+
+if TYPE_CHECKING:
+    from ._commit_api import CommitOperationAdd
+
+logger = logging.get_logger(__name__)
+
+OID_REGEX = re.compile(r"^[0-9a-f]{40}$")
+
+LFS_MULTIPART_UPLOAD_COMMAND = "lfs-multipart-upload"
+
+LFS_HEADERS = {
+    "Accept": "application/vnd.git-lfs+json",
+    "Content-Type": "application/vnd.git-lfs+json",
+}
+
+
+@dataclass
+class UploadInfo:
+    """
+    Dataclass holding required information to determine whether a blob
+    should be uploaded to the hub using the LFS protocol or the regular protocol
+
+    Args:
+        sha256 (`bytes`):
+            SHA256 hash of the blob
+        size (`int`):
+            Size in bytes of the blob
+        sample (`bytes`):
+            First 512 bytes of the blob
+    """
+
+    sha256: bytes
+    size: int
+    sample: bytes
+
+    @classmethod
+    def from_path(cls, path: str):
+        size = getsize(path)
+        with io.open(path, "rb") as file:
+            sample = file.peek(512)[:512]
+            sha = sha_fileobj(file)
+        return cls(size=size, sha256=sha, sample=sample)
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        sha = sha256(data).digest()
+        return cls(size=len(data), sample=data[:512], sha256=sha)
+
+    @classmethod
+    def from_fileobj(cls, fileobj: BinaryIO):
+        sample = fileobj.read(512)
+        fileobj.seek(0, io.SEEK_SET)
+        sha = sha_fileobj(fileobj)
+        size = fileobj.tell()
+        fileobj.seek(0, io.SEEK_SET)
+        return cls(size=size, sha256=sha, sample=sample)
+
+
+@validate_hf_hub_args
+def post_lfs_batch_info(
+    upload_infos: Iterable[UploadInfo],
+    token: Optional[str],
+    repo_type: str,
+    repo_id: str,
+    revision: Optional[str] = None,
+    endpoint: Optional[str] = None,
+) -> Tuple[List[dict], List[dict]]:
+    """
+    Requests the LFS batch endpoint to retrieve upload instructions
+
+    Learn more: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md
+
+    Args:
+        upload_infos (`Iterable` of `UploadInfo`):
+            `UploadInfo` for the files that are being uploaded, typically obtained
+            from `CommitOperationAdd.upload_info`
+        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 `/`.
+        token (`str`, *optional*):
+            An authentication token ( See https://huggingface.co/settings/tokens )
+        revision (`str`, *optional*):
+            The git revision to upload to.
+
+    Returns:
+        `LfsBatchInfo`: 2-tuple:
+            - First element is the list of upload instructions from the server
+            - Second element is an list of errors, if any
+
+    Raises:
+        `ValueError`: If an argument is invalid or the server response is malformed
+
+        `HTTPError`: If the server returned an error
+    """
+    endpoint = endpoint if endpoint is not None else ENDPOINT
+    url_prefix = ""
+    if repo_type in REPO_TYPES_URL_PREFIXES:
+        url_prefix = REPO_TYPES_URL_PREFIXES[repo_type]
+    batch_url = f"{endpoint}/{url_prefix}{repo_id}.git/info/lfs/objects/batch"
+    payload: Dict = {
+        "operation": "upload",
+        "transfers": ["basic", "multipart"],
+        "objects": [
+            {
+                "oid": upload.sha256.hex(),
+                "size": upload.size,
+            }
+            for upload in upload_infos
+        ],
+        "hash_algo": "sha256",
+    }
+    if revision is not None:
+        payload["ref"] = {"name": unquote(revision)}  # revision has been previously 'quoted'
+    headers = {**LFS_HEADERS, **build_hf_headers(token=token or True)}  # Token must be provided or retrieved
+    resp = get_session().post(batch_url, headers=headers, json=payload)
+    hf_raise_for_status(resp)
+    batch_info = resp.json()
+
+    objects = batch_info.get("objects", None)
+    if not isinstance(objects, list):
+        raise ValueError("Malformed response from server")
+
+    return (
+        [_validate_batch_actions(obj) for obj in objects if "error" not in obj],
+        [_validate_batch_error(obj) for obj in objects if "error" in obj],
+    )
+
+
+class PayloadPartT(TypedDict):
+    partNumber: int
+    etag: str
+
+
+class CompletionPayloadT(TypedDict):
+    """Payload that will be sent to the Hub when uploading multi-part."""
+
+    oid: str
+    parts: List[PayloadPartT]
+
+
+def lfs_upload(operation: "CommitOperationAdd", lfs_batch_action: Dict, token: Optional[str]) -> None:
+    """
+    Handles uploading a given object to the Hub with the LFS protocol.
+
+    Can be a No-op if the content of the file is already present on the hub large file storage.
+
+    Args:
+        operation (`CommitOperationAdd`):
+            The add operation triggering this upload.
+        lfs_batch_action (`dict`):
+            Upload instructions from the LFS batch endpoint for this object. See [`~utils.lfs.post_lfs_batch_info`] for
+            more details.
+        token (`str`, *optional*):
+            A [user access token](https://hf.co/settings/tokens) to authenticate requests against the Hub
+
+    Raises:
+        - `ValueError` if `lfs_batch_action` is improperly formatted
+        - `HTTPError` if the upload resulted in an error
+    """
+    # 0. If LFS file is already present, skip upload
+    _validate_batch_actions(lfs_batch_action)
+    actions = lfs_batch_action.get("actions")
+    if actions is None:
+        # The file was already uploaded
+        logger.debug(f"Content of file {operation.path_in_repo} is already present upstream - skipping upload")
+        return
+
+    # 1. Validate server response (check required keys in dict)
+    upload_action = lfs_batch_action["actions"]["upload"]
+    _validate_lfs_action(upload_action)
+    verify_action = lfs_batch_action["actions"].get("verify")
+    if verify_action is not None:
+        _validate_lfs_action(verify_action)
+
+    # 2. Upload file (either single part or multi-part)
+    header = upload_action.get("header", {})
+    chunk_size = header.get("chunk_size")
+    if chunk_size is not None:
+        try:
+            chunk_size = int(chunk_size)
+        except (ValueError, TypeError):
+            raise ValueError(
+                f"Malformed response from LFS batch endpoint: `chunk_size` should be an integer. Got '{chunk_size}'."
+            )
+        _upload_multi_part(operation=operation, header=header, chunk_size=chunk_size, upload_url=upload_action["href"])
+    else:
+        _upload_single_part(operation=operation, upload_url=upload_action["href"])
+
+    # 3. Verify upload went well
+    if verify_action is not None:
+        _validate_lfs_action(verify_action)
+        verify_resp = get_session().post(
+            verify_action["href"],
+            headers=build_hf_headers(token=token or True),
+            json={"oid": operation.upload_info.sha256.hex(), "size": operation.upload_info.size},
+        )
+        hf_raise_for_status(verify_resp)
+    logger.debug(f"{operation.path_in_repo}: Upload successful")
+
+
+def _validate_lfs_action(lfs_action: dict):
+    """validates response from the LFS batch endpoint"""
+    if not (
+        isinstance(lfs_action.get("href"), str)
+        and (lfs_action.get("header") is None or isinstance(lfs_action.get("header"), dict))
+    ):
+        raise ValueError("lfs_action is improperly formatted")
+    return lfs_action
+
+
+def _validate_batch_actions(lfs_batch_actions: dict):
+    """validates response from the LFS batch endpoint"""
+    if not (isinstance(lfs_batch_actions.get("oid"), str) and isinstance(lfs_batch_actions.get("size"), int)):
+        raise ValueError("lfs_batch_actions is improperly formatted")
+
+    upload_action = lfs_batch_actions.get("actions", {}).get("upload")
+    verify_action = lfs_batch_actions.get("actions", {}).get("verify")
+    if upload_action is not None:
+        _validate_lfs_action(upload_action)
+    if verify_action is not None:
+        _validate_lfs_action(verify_action)
+    return lfs_batch_actions
+
+
+def _validate_batch_error(lfs_batch_error: dict):
+    """validates response from the LFS batch endpoint"""
+    if not (isinstance(lfs_batch_error.get("oid"), str) and isinstance(lfs_batch_error.get("size"), int)):
+        raise ValueError("lfs_batch_error is improperly formatted")
+    error_info = lfs_batch_error.get("error")
+    if not (
+        isinstance(error_info, dict)
+        and isinstance(error_info.get("message"), str)
+        and isinstance(error_info.get("code"), int)
+    ):
+        raise ValueError("lfs_batch_error is improperly formatted")
+    return lfs_batch_error
+
+
+def _upload_single_part(operation: "CommitOperationAdd", upload_url: str) -> None:
+    """
+    Uploads `fileobj` as a single PUT HTTP request (basic LFS transfer protocol)
+
+    Args:
+        upload_url (`str`):
+            The URL to PUT the file to.
+        fileobj:
+            The file-like object holding the data to upload.
+
+    Returns: `requests.Response`
+
+    Raises: `requests.HTTPError` if the upload resulted in an error
+    """
+    with operation.as_file(with_tqdm=True) as fileobj:
+        # S3 might raise a transient 500 error -> let's retry if that happens
+        response = http_backoff("PUT", upload_url, data=fileobj, retry_on_status_codes=(500, 503))
+        hf_raise_for_status(response)
+
+
+def _upload_multi_part(operation: "CommitOperationAdd", header: Dict, chunk_size: int, upload_url: str) -> None:
+    """
+    Uploads file using HF multipart LFS transfer protocol.
+    """
+    # 1. Get upload URLs for each part
+    sorted_parts_urls = _get_sorted_parts_urls(header=header, upload_info=operation.upload_info, chunk_size=chunk_size)
+
+    # 2. Upload parts (either with hf_transfer or in pure Python)
+    use_hf_transfer = HF_HUB_ENABLE_HF_TRANSFER
+    if (
+        HF_HUB_ENABLE_HF_TRANSFER
+        and not isinstance(operation.path_or_fileobj, str)
+        and not isinstance(operation.path_or_fileobj, Path)
+    ):
+        warnings.warn(
+            "hf_transfer is enabled but does not support uploading from bytes or BinaryIO, falling back to regular"
+            " upload"
+        )
+        use_hf_transfer = False
+
+    response_headers = (
+        _upload_parts_hf_transfer(operation=operation, sorted_parts_urls=sorted_parts_urls, chunk_size=chunk_size)
+        if use_hf_transfer
+        else _upload_parts_iteratively(operation=operation, sorted_parts_urls=sorted_parts_urls, chunk_size=chunk_size)
+    )
+
+    # 3. Send completion request
+    completion_res = get_session().post(
+        upload_url,
+        json=_get_completion_payload(response_headers, operation.upload_info.sha256.hex()),
+        headers=LFS_HEADERS,
+    )
+    hf_raise_for_status(completion_res)
+
+
+def _get_sorted_parts_urls(header: Dict, upload_info: UploadInfo, chunk_size: int) -> List[str]:
+    sorted_part_upload_urls = [
+        upload_url
+        for _, upload_url in sorted(
+            [
+                (int(part_num, 10), upload_url)
+                for part_num, upload_url in header.items()
+                if part_num.isdigit() and len(part_num) > 0
+            ],
+            key=lambda t: t[0],
+        )
+    ]
+    num_parts = len(sorted_part_upload_urls)
+    if num_parts != ceil(upload_info.size / chunk_size):
+        raise ValueError("Invalid server response to upload large LFS file")
+    return sorted_part_upload_urls
+
+
+def _get_completion_payload(response_headers: List[Dict], oid: str) -> CompletionPayloadT:
+    parts: List[PayloadPartT] = []
+    for part_number, header in enumerate(response_headers):
+        etag = header.get("etag")
+        if etag is None or etag == "":
+            raise ValueError(f"Invalid etag (`{etag}`) returned for part {part_number + 1}")
+        parts.append(
+            {
+                "partNumber": part_number + 1,
+                "etag": etag,
+            }
+        )
+    return {"oid": oid, "parts": parts}
+
+
+def _upload_parts_iteratively(
+    operation: "CommitOperationAdd", sorted_parts_urls: List[str], chunk_size: int
+) -> List[Dict]:
+    headers = []
+    with operation.as_file(with_tqdm=True) as fileobj:
+        for part_idx, part_upload_url in enumerate(sorted_parts_urls):
+            with SliceFileObj(
+                fileobj,
+                seek_from=chunk_size * part_idx,
+                read_limit=chunk_size,
+            ) as fileobj_slice:
+                # S3 might raise a transient 500 error -> let's retry if that happens
+                part_upload_res = http_backoff(
+                    "PUT", part_upload_url, data=fileobj_slice, retry_on_status_codes=(500, 503)
+                )
+                hf_raise_for_status(part_upload_res)
+                headers.append(part_upload_res.headers)
+    return headers  # type: ignore
+
+
+def _upload_parts_hf_transfer(
+    operation: "CommitOperationAdd", sorted_parts_urls: List[str], chunk_size: int
+) -> List[Dict]:
+    # Upload file using an external Rust-based package. Upload is faster but support less features (no progress bars).
+    try:
+        from hf_transfer import multipart_upload
+    except ImportError:
+        raise ValueError(
+            "Fast uploading using 'hf_transfer' is enabled (HF_HUB_ENABLE_HF_TRANSFER=1) but 'hf_transfer' package is"
+            " not available in your environment. Try `pip install hf_transfer`."
+        )
+
+    supports_callback = "callback" in inspect.signature(multipart_upload).parameters
+    if not supports_callback:
+        warnings.warn(
+            "You are using an outdated version of `hf_transfer`. Consider upgrading to latest version to enable progress bars using `pip install -U hf_transfer`."
+        )
+
+    total = operation.upload_info.size
+    desc = operation.path_in_repo
+    if len(desc) > 40:
+        desc = f"(…){desc[-40:]}"
+    disable = bool(logger.getEffectiveLevel() == logging.NOTSET)
+
+    with tqdm(unit="B", unit_scale=True, total=total, initial=0, desc=desc, disable=disable) as progress:
+        try:
+            output = multipart_upload(
+                file_path=operation.path_or_fileobj,
+                parts_urls=sorted_parts_urls,
+                chunk_size=chunk_size,
+                max_files=128,
+                parallel_failures=127,  # could be removed
+                max_retries=5,
+                **({"callback": progress.update} if supports_callback else {}),
+            )
+        except Exception as e:
+            raise RuntimeError(
+                "An error occurred while uploading using `hf_transfer`. Consider disabling HF_HUB_ENABLE_HF_TRANSFER for"
+                " better error handling."
+            ) from e
+        if not supports_callback:
+            progress.update(total)
+        return output
+
+
+class SliceFileObj(AbstractContextManager):
+    """
+    Utility context manager to read a *slice* of a seekable file-like object as a seekable, file-like object.
+
+    This is NOT thread safe
+
+    Inspired by stackoverflow.com/a/29838711/593036
+
+    Credits to @julien-c
+
+    Args:
+        fileobj (`BinaryIO`):
+            A file-like object to slice. MUST implement `tell()` and `seek()` (and `read()` of course).
+            `fileobj` will be reset to its original position when exiting the context manager.
+        seek_from (`int`):
+            The start of the slice (offset from position 0 in bytes).
+        read_limit (`int`):
+            The maximum number of bytes to read from the slice.
+
+    Attributes:
+        previous_position (`int`):
+            The previous position
+
+    Examples:
+
+    Reading 200 bytes with an offset of 128 bytes from a file (ie bytes 128 to 327):
+    ```python
+    >>> with open("path/to/file", "rb") as file:
+    ...     with SliceFileObj(file, seek_from=128, read_limit=200) as fslice:
+    ...         fslice.read(...)
+    ```
+
+    Reading a file in chunks of 512 bytes
+    ```python
+    >>> import os
+    >>> chunk_size = 512
+    >>> file_size = os.getsize("path/to/file")
+    >>> with open("path/to/file", "rb") as file:
+    ...     for chunk_idx in range(ceil(file_size / chunk_size)):
+    ...         with SliceFileObj(file, seek_from=chunk_idx * chunk_size, read_limit=chunk_size) as fslice:
+    ...             chunk = fslice.read(...)
+
+    ```
+    """
+
+    def __init__(self, fileobj: BinaryIO, seek_from: int, read_limit: int):
+        self.fileobj = fileobj
+        self.seek_from = seek_from
+        self.read_limit = read_limit
+
+    def __enter__(self):
+        self._previous_position = self.fileobj.tell()
+        end_of_stream = self.fileobj.seek(0, os.SEEK_END)
+        self._len = min(self.read_limit, end_of_stream - self.seek_from)
+        # ^^ The actual number of bytes that can be read from the slice
+        self.fileobj.seek(self.seek_from, io.SEEK_SET)
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.fileobj.seek(self._previous_position, io.SEEK_SET)
+
+    def read(self, n: int = -1):
+        pos = self.tell()
+        if pos >= self._len:
+            return b""
+        remaining_amount = self._len - pos
+        data = self.fileobj.read(remaining_amount if n < 0 else min(n, remaining_amount))
+        return data
+
+    def tell(self) -> int:
+        return self.fileobj.tell() - self.seek_from
+
+    def seek(self, offset: int, whence: int = os.SEEK_SET) -> int:
+        start = self.seek_from
+        end = start + self._len
+        if whence in (os.SEEK_SET, os.SEEK_END):
+            offset = start + offset if whence == os.SEEK_SET else end + offset
+            offset = max(start, min(offset, end))
+            whence = os.SEEK_SET
+        elif whence == os.SEEK_CUR:
+            cur_pos = self.fileobj.tell()
+            offset = max(start - cur_pos, min(offset, end - cur_pos))
+        else:
+            raise ValueError(f"whence value {whence} is not supported")
+        return self.fileobj.seek(offset, whence) - self.seek_from
+
+    def __iter__(self):
+        yield self.read(n=4 * 1024 * 1024)

lib/python3.11/site-packages/huggingface_hub/repocard.py

@@ -0,0 +1,818 @@
+import os
+import re
+import warnings
+from pathlib import Path
+from typing import Any, Dict, Literal, Optional, Type, Union
+
+import requests
+import yaml
+
+from huggingface_hub.file_download import hf_hub_download
+from huggingface_hub.hf_api import upload_file
+from huggingface_hub.repocard_data import (
+    CardData,
+    DatasetCardData,
+    EvalResult,
+    ModelCardData,
+    SpaceCardData,
+    eval_results_to_model_index,
+    model_index_to_eval_results,
+)
+from huggingface_hub.utils import get_session, is_jinja_available, yaml_dump
+
+from .constants import REPOCARD_NAME
+from .utils import EntryNotFoundError, SoftTemporaryDirectory, validate_hf_hub_args
+
+
+TEMPLATE_MODELCARD_PATH = Path(__file__).parent / "templates" / "modelcard_template.md"
+TEMPLATE_DATASETCARD_PATH = Path(__file__).parent / "templates" / "datasetcard_template.md"
+
+# exact same regex as in the Hub server. Please keep in sync.
+# See https://github.com/huggingface/moon-landing/blob/main/server/lib/ViewMarkdown.ts#L18
+REGEX_YAML_BLOCK = re.compile(r"^(\s*---[\r\n]+)([\S\s]*?)([\r\n]+---(\r\n|\n|$))")
+
+
+class RepoCard:
+    card_data_class = CardData
+    default_template_path = TEMPLATE_MODELCARD_PATH
+    repo_type = "model"
+
+    def __init__(self, content: str, ignore_metadata_errors: bool = False):
+        """Initialize a RepoCard from string content. The content should be a
+        Markdown file with a YAML block at the beginning and a Markdown body.
+
+        Args:
+            content (`str`): The content of the Markdown file.
+
+        Example:
+            ```python
+            >>> from huggingface_hub.repocard import RepoCard
+            >>> text = '''
+            ... ---
+            ... language: en
+            ... license: mit
+            ... ---
+            ...
+            ... # My repo
+            ... '''
+            >>> card = RepoCard(text)
+            >>> card.data.to_dict()
+            {'language': 'en', 'license': 'mit'}
+            >>> card.text
+            '\\n# My repo\\n'
+
+            ```
+        <Tip>
+        Raises the following error:
+
+            - [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+              when the content of the repo card metadata is not a dictionary.
+
+        </Tip>
+        """
+
+        # Set the content of the RepoCard, as well as underlying .data and .text attributes.
+        # See the `content` property setter for more details.
+        self.ignore_metadata_errors = ignore_metadata_errors
+        self.content = content
+
+    @property
+    def content(self):
+        """The content of the RepoCard, including the YAML block and the Markdown body."""
+        line_break = _detect_line_ending(self._content) or "\n"
+        return f"---{line_break}{self.data.to_yaml(line_break=line_break)}{line_break}---{line_break}{self.text}"
+
+    @content.setter
+    def content(self, content: str):
+        """Set the content of the RepoCard."""
+        self._content = content
+
+        match = REGEX_YAML_BLOCK.search(content)
+        if match:
+            # Metadata found in the YAML block
+            yaml_block = match.group(2)
+            self.text = content[match.end() :]
+            data_dict = yaml.safe_load(yaml_block)
+
+            if data_dict is None:
+                data_dict = {}
+
+            # The YAML block's data should be a dictionary
+            if not isinstance(data_dict, dict):
+                raise ValueError("repo card metadata block should be a dict")
+        else:
+            # Model card without metadata... create empty metadata
+            warnings.warn("Repo card metadata block was not found. Setting CardData to empty.")
+            data_dict = {}
+            self.text = content
+
+        self.data = self.card_data_class(**data_dict, ignore_metadata_errors=self.ignore_metadata_errors)
+
+    def __str__(self):
+        return self.content
+
+    def save(self, filepath: Union[Path, str]):
+        r"""Save a RepoCard to a file.
+
+        Args:
+            filepath (`Union[Path, str]`): Filepath to the markdown file to save.
+
+        Example:
+            ```python
+            >>> from huggingface_hub.repocard import RepoCard
+            >>> card = RepoCard("---\nlanguage: en\n---\n# This is a test repo card")
+            >>> card.save("/tmp/test.md")
+
+            ```
+        """
+        filepath = Path(filepath)
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+        # Preserve newlines as in the existing file.
+        with open(filepath, mode="w", newline="", encoding="utf-8") as f:
+            f.write(str(self))
+
+    @classmethod
+    def load(
+        cls,
+        repo_id_or_path: Union[str, Path],
+        repo_type: Optional[str] = None,
+        token: Optional[str] = None,
+        ignore_metadata_errors: bool = False,
+    ):
+        """Initialize a RepoCard from a Hugging Face Hub repo's README.md or a local filepath.
+
+        Args:
+            repo_id_or_path (`Union[str, Path]`):
+                The repo ID associated with a Hugging Face Hub repo or a local filepath.
+            repo_type (`str`, *optional*):
+                The type of Hugging Face repo to push to. Defaults to None, which will use use "model". Other options
+                are "dataset" and "space". Not used when loading from a local filepath. If this is called from a child
+                class, the default value will be the child class's `repo_type`.
+            token (`str`, *optional*):
+                Authentication token, obtained with `huggingface_hub.HfApi.login` method. Will default to the stored token.
+            ignore_metadata_errors (`str`):
+                If True, errors while parsing the metadata section will be ignored. Some information might be lost during
+                the process. Use it at your own risk.
+
+        Returns:
+            [`huggingface_hub.repocard.RepoCard`]: The RepoCard (or subclass) initialized from the repo's
+                README.md file or filepath.
+
+        Example:
+            ```python
+            >>> from huggingface_hub.repocard import RepoCard
+            >>> card = RepoCard.load("nateraw/food")
+            >>> assert card.data.tags == ["generated_from_trainer", "image-classification", "pytorch"]
+
+            ```
+        """
+
+        if Path(repo_id_or_path).exists():
+            card_path = Path(repo_id_or_path)
+        elif isinstance(repo_id_or_path, str):
+            card_path = Path(
+                hf_hub_download(
+                    repo_id_or_path,
+                    REPOCARD_NAME,
+                    repo_type=repo_type or cls.repo_type,
+                    token=token,
+                )
+            )
+        else:
+            raise ValueError(f"Cannot load RepoCard: path not found on disk ({repo_id_or_path}).")
+
+        # Preserve newlines in the existing file.
+        with card_path.open(mode="r", newline="", encoding="utf-8") as f:
+            return cls(f.read(), ignore_metadata_errors=ignore_metadata_errors)
+
+    def validate(self, repo_type: Optional[str] = None):
+        """Validates card against Hugging Face Hub's card validation logic.
+        Using this function requires access to the internet, so it is only called
+        internally by [`huggingface_hub.repocard.RepoCard.push_to_hub`].
+
+        Args:
+            repo_type (`str`, *optional*, defaults to "model"):
+                The type of Hugging Face repo to push to. Options are "model", "dataset", and "space".
+                If this function is called from a child class, the default will be the child class's `repo_type`.
+
+        <Tip>
+        Raises the following errors:
+
+            - [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+              if the card fails validation checks.
+            - [`HTTPError`](https://requests.readthedocs.io/en/latest/api/#requests.HTTPError)
+              if the request to the Hub API fails for any other reason.
+
+        </Tip>
+        """
+
+        # If repo type is provided, otherwise, use the repo type of the card.
+        repo_type = repo_type or self.repo_type
+
+        body = {
+            "repoType": repo_type,
+            "content": str(self),
+        }
+        headers = {"Accept": "text/plain"}
+
+        try:
+            r = get_session().post("https://huggingface.co/api/validate-yaml", body, headers=headers)
+            r.raise_for_status()
+        except requests.exceptions.HTTPError as exc:
+            if r.status_code == 400:
+                raise ValueError(r.text)
+            else:
+                raise exc
+
+    def push_to_hub(
+        self,
+        repo_id: str,
+        token: Optional[str] = None,
+        repo_type: Optional[str] = None,
+        commit_message: Optional[str] = None,
+        commit_description: Optional[str] = None,
+        revision: Optional[str] = None,
+        create_pr: Optional[bool] = None,
+        parent_commit: Optional[str] = None,
+    ):
+        """Push a RepoCard to a Hugging Face Hub repo.
+
+        Args:
+            repo_id (`str`):
+                The repo ID of the Hugging Face Hub repo to push to. Example: "nateraw/food".
+            token (`str`, *optional*):
+                Authentication token, obtained with `huggingface_hub.HfApi.login` method. Will default to
+                the stored token.
+            repo_type (`str`, *optional*, defaults to "model"):
+                The type of Hugging Face repo to push to. Options are "model", "dataset", and "space". If this
+                function is called by a child class, it will default to the child class's `repo_type`.
+            commit_message (`str`, *optional*):
+                The summary / title / first line of the generated commit.
+            commit_description (`str`, *optional*)
+                The description of the generated commit.
+            revision (`str`, *optional*):
+                The git revision to commit from. Defaults to the head of the `"main"` branch.
+            create_pr (`bool`, *optional*):
+                Whether or not to create a Pull Request with this commit. Defaults to `False`.
+            parent_commit (`str`, *optional*):
+                The OID / SHA of the parent commit, as a hexadecimal string. Shorthands (7 first characters) are also supported.
+                If specified and `create_pr` is `False`, the commit will fail if `revision` does not point to `parent_commit`.
+                If specified and `create_pr` is `True`, the pull request will be created from `parent_commit`.
+                Specifying `parent_commit` ensures the repo has not changed before committing the changes, and can be
+                especially useful if the repo is updated / committed to concurrently.
+        Returns:
+            `str`: URL of the commit which updated the card metadata.
+        """
+
+        # If repo type is provided, otherwise, use the repo type of the card.
+        repo_type = repo_type or self.repo_type
+
+        # Validate card before pushing to hub
+        self.validate(repo_type=repo_type)
+
+        with SoftTemporaryDirectory() as tmpdir:
+            tmp_path = Path(tmpdir) / REPOCARD_NAME
+            tmp_path.write_text(str(self))
+            url = upload_file(
+                path_or_fileobj=str(tmp_path),
+                path_in_repo=REPOCARD_NAME,
+                repo_id=repo_id,
+                token=token,
+                repo_type=repo_type,
+                commit_message=commit_message,
+                commit_description=commit_description,
+                create_pr=create_pr,
+                revision=revision,
+                parent_commit=parent_commit,
+            )
+        return url
+
+    @classmethod
+    def from_template(
+        cls,
+        card_data: CardData,
+        template_path: Optional[str] = None,
+        **template_kwargs,
+    ):
+        """Initialize a RepoCard from a template. By default, it uses the default template.
+
+        Templates are Jinja2 templates that can be customized by passing keyword arguments.
+
+        Args:
+            card_data (`huggingface_hub.CardData`):
+                A huggingface_hub.CardData instance containing the metadata you want to include in the YAML
+                header of the repo card on the Hugging Face Hub.
+            template_path (`str`, *optional*):
+                A path to a markdown file with optional Jinja template variables that can be filled
+                in with `template_kwargs`. Defaults to the default template.
+
+        Returns:
+            [`huggingface_hub.repocard.RepoCard`]: A RepoCard instance with the specified card data and content from the
+            template.
+        """
+        if is_jinja_available():
+            import jinja2
+        else:
+            raise ImportError(
+                "Using RepoCard.from_template requires Jinja2 to be installed. Please"
+                " install it with `pip install Jinja2`."
+            )
+
+        kwargs = card_data.to_dict().copy()
+        kwargs.update(template_kwargs)  # Template_kwargs have priority
+        template = jinja2.Template(Path(template_path or cls.default_template_path).read_text())
+        content = template.render(card_data=card_data.to_yaml(), **kwargs)
+        return cls(content)
+
+
+class ModelCard(RepoCard):
+    card_data_class = ModelCardData
+    default_template_path = TEMPLATE_MODELCARD_PATH
+    repo_type = "model"
+
+    @classmethod
+    def from_template(  # type: ignore # violates Liskov property but easier to use
+        cls,
+        card_data: ModelCardData,
+        template_path: Optional[str] = None,
+        **template_kwargs,
+    ):
+        """Initialize a ModelCard from a template. By default, it uses the default template, which can be found here:
+        https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md
+
+        Templates are Jinja2 templates that can be customized by passing keyword arguments.
+
+        Args:
+            card_data (`huggingface_hub.ModelCardData`):
+                A huggingface_hub.ModelCardData instance containing the metadata you want to include in the YAML
+                header of the model card on the Hugging Face Hub.
+            template_path (`str`, *optional*):
+                A path to a markdown file with optional Jinja template variables that can be filled
+                in with `template_kwargs`. Defaults to the default template.
+
+        Returns:
+            [`huggingface_hub.ModelCard`]: A ModelCard instance with the specified card data and content from the
+            template.
+
+        Example:
+            ```python
+            >>> from huggingface_hub import ModelCard, ModelCardData, EvalResult
+
+            >>> # Using the Default Template
+            >>> card_data = ModelCardData(
+            ...     language='en',
+            ...     license='mit',
+            ...     library_name='timm',
+            ...     tags=['image-classification', 'resnet'],
+            ...     datasets=['beans'],
+            ...     metrics=['accuracy'],
+            ... )
+            >>> card = ModelCard.from_template(
+            ...     card_data,
+            ...     model_description='This model does x + y...'
+            ... )
+
+            >>> # Including Evaluation Results
+            >>> card_data = ModelCardData(
+            ...     language='en',
+            ...     tags=['image-classification', 'resnet'],
+            ...     eval_results=[
+            ...         EvalResult(
+            ...             task_type='image-classification',
+            ...             dataset_type='beans',
+            ...             dataset_name='Beans',
+            ...             metric_type='accuracy',
+            ...             metric_value=0.9,
+            ...         ),
+            ...     ],
+            ...     model_name='my-cool-model',
+            ... )
+            >>> card = ModelCard.from_template(card_data)
+
+            >>> # Using a Custom Template
+            >>> card_data = ModelCardData(
+            ...     language='en',
+            ...     tags=['image-classification', 'resnet']
+            ... )
+            >>> card = ModelCard.from_template(
+            ...     card_data=card_data,
+            ...     template_path='./src/huggingface_hub/templates/modelcard_template.md',
+            ...     custom_template_var='custom value',  # will be replaced in template if it exists
+            ... )
+
+            ```
+        """
+        return super().from_template(card_data, template_path, **template_kwargs)
+
+
+class DatasetCard(RepoCard):
+    card_data_class = DatasetCardData
+    default_template_path = TEMPLATE_DATASETCARD_PATH
+    repo_type = "dataset"
+
+    @classmethod
+    def from_template(  # type: ignore # violates Liskov property but easier to use
+        cls,
+        card_data: DatasetCardData,
+        template_path: Optional[str] = None,
+        **template_kwargs,
+    ):
+        """Initialize a DatasetCard from a template. By default, it uses the default template, which can be found here:
+        https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/datasetcard_template.md
+
+        Templates are Jinja2 templates that can be customized by passing keyword arguments.
+
+        Args:
+            card_data (`huggingface_hub.DatasetCardData`):
+                A huggingface_hub.DatasetCardData instance containing the metadata you want to include in the YAML
+                header of the dataset card on the Hugging Face Hub.
+            template_path (`str`, *optional*):
+                A path to a markdown file with optional Jinja template variables that can be filled
+                in with `template_kwargs`. Defaults to the default template.
+
+        Returns:
+            [`huggingface_hub.DatasetCard`]: A DatasetCard instance with the specified card data and content from the
+            template.
+
+        Example:
+            ```python
+            >>> from huggingface_hub import DatasetCard, DatasetCardData
+
+            >>> # Using the Default Template
+            >>> card_data = DatasetCardData(
+            ...     language='en',
+            ...     license='mit',
+            ...     annotations_creators='crowdsourced',
+            ...     task_categories=['text-classification'],
+            ...     task_ids=['sentiment-classification', 'text-scoring'],
+            ...     multilinguality='monolingual',
+            ...     pretty_name='My Text Classification Dataset',
+            ... )
+            >>> card = DatasetCard.from_template(
+            ...     card_data,
+            ...     pretty_name=card_data.pretty_name,
+            ... )
+
+            >>> # Using a Custom Template
+            >>> card_data = DatasetCardData(
+            ...     language='en',
+            ...     license='mit',
+            ... )
+            >>> card = DatasetCard.from_template(
+            ...     card_data=card_data,
+            ...     template_path='./src/huggingface_hub/templates/datasetcard_template.md',
+            ...     custom_template_var='custom value',  # will be replaced in template if it exists
+            ... )
+
+            ```
+        """
+        return super().from_template(card_data, template_path, **template_kwargs)
+
+
+class SpaceCard(RepoCard):
+    card_data_class = SpaceCardData
+    default_template_path = TEMPLATE_MODELCARD_PATH
+    repo_type = "space"
+
+
+def _detect_line_ending(content: str) -> Literal["\r", "\n", "\r\n", None]:  # noqa: F722
+    """Detect the line ending of a string. Used by RepoCard to avoid making huge diff on newlines.
+
+    Uses same implementation as in Hub server, keep it in sync.
+
+    Returns:
+        str: The detected line ending of the string.
+    """
+    cr = content.count("\r")
+    lf = content.count("\n")
+    crlf = content.count("\r\n")
+    if cr + lf == 0:
+        return None
+    if crlf == cr and crlf == lf:
+        return "\r\n"
+    if cr > lf:
+        return "\r"
+    else:
+        return "\n"
+
+
+def metadata_load(local_path: Union[str, Path]) -> Optional[Dict]:
+    content = Path(local_path).read_text()
+    match = REGEX_YAML_BLOCK.search(content)
+    if match:
+        yaml_block = match.group(2)
+        data = yaml.safe_load(yaml_block)
+        if data is None or isinstance(data, dict):
+            return data
+        raise ValueError("repo card metadata block should be a dict")
+    else:
+        return None
+
+
+def metadata_save(local_path: Union[str, Path], data: Dict) -> None:
+    """
+    Save the metadata dict in the upper YAML part Trying to preserve newlines as
+    in the existing file. Docs about open() with newline="" parameter:
+    https://docs.python.org/3/library/functions.html?highlight=open#open Does
+    not work with "^M" linebreaks, which are replaced by \n
+    """
+    line_break = "\n"
+    content = ""
+    # try to detect existing newline character
+    if os.path.exists(local_path):
+        with open(local_path, "r", newline="", encoding="utf8") as readme:
+            content = readme.read()
+            if isinstance(readme.newlines, tuple):
+                line_break = readme.newlines[0]
+            elif isinstance(readme.newlines, str):
+                line_break = readme.newlines
+
+    # creates a new file if it not
+    with open(local_path, "w", newline="", encoding="utf8") as readme:
+        data_yaml = yaml_dump(data, sort_keys=False, line_break=line_break)
+        # sort_keys: keep dict order
+        match = REGEX_YAML_BLOCK.search(content)
+        if match:
+            output = content[: match.start()] + f"---{line_break}{data_yaml}---{line_break}" + content[match.end() :]
+        else:
+            output = f"---{line_break}{data_yaml}---{line_break}{content}"
+
+        readme.write(output)
+        readme.close()
+
+
+def metadata_eval_result(
+    *,
+    model_pretty_name: str,
+    task_pretty_name: str,
+    task_id: str,
+    metrics_pretty_name: str,
+    metrics_id: str,
+    metrics_value: Any,
+    dataset_pretty_name: str,
+    dataset_id: str,
+    metrics_config: Optional[str] = None,
+    metrics_verified: bool = False,
+    dataset_config: Optional[str] = None,
+    dataset_split: Optional[str] = None,
+    dataset_revision: Optional[str] = None,
+    metrics_verification_token: Optional[str] = None,
+) -> Dict:
+    """
+    Creates a metadata dict with the result from a model evaluated on a dataset.
+
+    Args:
+        model_pretty_name (`str`):
+            The name of the model in natural language.
+        task_pretty_name (`str`):
+            The name of a task in natural language.
+        task_id (`str`):
+            Example: automatic-speech-recognition. A task id.
+        metrics_pretty_name (`str`):
+            A name for the metric in natural language. Example: Test WER.
+        metrics_id (`str`):
+            Example: wer. A metric id from https://hf.co/metrics.
+        metrics_value (`Any`):
+            The value from the metric. Example: 20.0 or "20.0 ± 1.2".
+        dataset_pretty_name (`str`):
+            The name of the dataset in natural language.
+        dataset_id (`str`):
+            Example: common_voice. A dataset id from https://hf.co/datasets.
+        metrics_config (`str`, *optional*):
+            The name of the metric configuration used in `load_metric()`.
+            Example: bleurt-large-512 in `load_metric("bleurt", "bleurt-large-512")`.
+        metrics_verified (`bool`, *optional*, defaults to `False`):
+            Indicates whether the metrics originate from Hugging Face's [evaluation service](https://huggingface.co/spaces/autoevaluate/model-evaluator) or not. Automatically computed by Hugging Face, do not set.
+        dataset_config (`str`, *optional*):
+            Example: fr. The name of the dataset configuration used in `load_dataset()`.
+        dataset_split (`str`, *optional*):
+            Example: test. The name of the dataset split used in `load_dataset()`.
+        dataset_revision (`str`, *optional*):
+            Example: 5503434ddd753f426f4b38109466949a1217c2bb. The name of the dataset dataset revision
+            used in `load_dataset()`.
+        metrics_verification_token (`bool`, *optional*):
+            A JSON Web Token that is used to verify whether the metrics originate from Hugging Face's [evaluation service](https://huggingface.co/spaces/autoevaluate/model-evaluator) or not.
+
+    Returns:
+        `dict`: a metadata dict with the result from a model evaluated on a dataset.
+
+    Example:
+        ```python
+        >>> from huggingface_hub import metadata_eval_result
+        >>> results = metadata_eval_result(
+        ...         model_pretty_name="RoBERTa fine-tuned on ReactionGIF",
+        ...         task_pretty_name="Text Classification",
+        ...         task_id="text-classification",
+        ...         metrics_pretty_name="Accuracy",
+        ...         metrics_id="accuracy",
+        ...         metrics_value=0.2662102282047272,
+        ...         dataset_pretty_name="ReactionJPEG",
+        ...         dataset_id="julien-c/reactionjpeg",
+        ...         dataset_config="default",
+        ...         dataset_split="test",
+        ... )
+        >>> results == {
+        ...     'model-index': [
+        ...         {
+        ...             'name': 'RoBERTa fine-tuned on ReactionGIF',
+        ...             'results': [
+        ...                 {
+        ...                     'task': {
+        ...                         'type': 'text-classification',
+        ...                         'name': 'Text Classification'
+        ...                     },
+        ...                     'dataset': {
+        ...                         'name': 'ReactionJPEG',
+        ...                         'type': 'julien-c/reactionjpeg',
+        ...                         'config': 'default',
+        ...                         'split': 'test'
+        ...                     },
+        ...                     'metrics': [
+        ...                         {
+        ...                             'type': 'accuracy',
+        ...                             'value': 0.2662102282047272,
+        ...                             'name': 'Accuracy',
+        ...                             'verified': False
+        ...                         }
+        ...                     ]
+        ...                 }
+        ...             ]
+        ...         }
+        ...     ]
+        ... }
+        True
+
+        ```
+    """
+
+    return {
+        "model-index": eval_results_to_model_index(
+            model_name=model_pretty_name,
+            eval_results=[
+                EvalResult(
+                    task_name=task_pretty_name,
+                    task_type=task_id,
+                    metric_name=metrics_pretty_name,
+                    metric_type=metrics_id,
+                    metric_value=metrics_value,
+                    dataset_name=dataset_pretty_name,
+                    dataset_type=dataset_id,
+                    metric_config=metrics_config,
+                    verified=metrics_verified,
+                    verify_token=metrics_verification_token,
+                    dataset_config=dataset_config,
+                    dataset_split=dataset_split,
+                    dataset_revision=dataset_revision,
+                )
+            ],
+        )
+    }
+
+
+@validate_hf_hub_args
+def metadata_update(
+    repo_id: str,
+    metadata: Dict,
+    *,
+    repo_type: Optional[str] = None,
+    overwrite: bool = False,
+    token: Optional[str] = None,
+    commit_message: Optional[str] = None,
+    commit_description: Optional[str] = None,
+    revision: Optional[str] = None,
+    create_pr: bool = False,
+    parent_commit: Optional[str] = None,
+) -> str:
+    """
+    Updates the metadata in the README.md of a repository on the Hugging Face Hub.
+    If the README.md file doesn't exist yet, a new one is created with metadata and an
+    the default ModelCard or DatasetCard template. For `space` repo, an error is thrown
+    as a Space cannot exist without a `README.md` file.
+
+    Args:
+        repo_id (`str`):
+            The name of the repository.
+        metadata (`dict`):
+            A dictionary containing the metadata to be updated.
+        repo_type (`str`, *optional*):
+            Set to `"dataset"` or `"space"` if updating to a dataset or space,
+            `None` or `"model"` if updating to a model. Default is `None`.
+        overwrite (`bool`, *optional*, defaults to `False`):
+            If set to `True` an existing field can be overwritten, otherwise
+            attempting to overwrite an existing field will cause an error.
+        token (`str`, *optional*):
+            The Hugging Face authentication token.
+        commit_message (`str`, *optional*):
+            The summary / title / first line of the generated commit. Defaults to
+            `f"Update metadata with huggingface_hub"`
+        commit_description (`str` *optional*)
+            The description of the generated commit
+        revision (`str`, *optional*):
+            The git revision to commit from. Defaults to the head of the
+            `"main"` branch.
+        create_pr (`boolean`, *optional*):
+            Whether or not to create a Pull Request from `revision` with that commit.
+            Defaults to `False`.
+        parent_commit (`str`, *optional*):
+            The OID / SHA of the parent commit, as a hexadecimal string. Shorthands (7 first characters) are also supported.
+            If specified and `create_pr` is `False`, the commit will fail if `revision` does not point to `parent_commit`.
+            If specified and `create_pr` is `True`, the pull request will be created from `parent_commit`.
+            Specifying `parent_commit` ensures the repo has not changed before committing the changes, and can be
+            especially useful if the repo is updated / committed to concurrently.
+    Returns:
+        `str`: URL of the commit which updated the card metadata.
+
+    Example:
+        ```python
+        >>> from huggingface_hub import metadata_update
+        >>> metadata = {'model-index': [{'name': 'RoBERTa fine-tuned on ReactionGIF',
+        ...             'results': [{'dataset': {'name': 'ReactionGIF',
+        ...                                      'type': 'julien-c/reactiongif'},
+        ...                           'metrics': [{'name': 'Recall',
+        ...                                        'type': 'recall',
+        ...                                        'value': 0.7762102282047272}],
+        ...                          'task': {'name': 'Text Classification',
+        ...                                   'type': 'text-classification'}}]}]}
+        >>> url = metadata_update("hf-internal-testing/reactiongif-roberta-card", metadata)
+
+        ```
+    """
+    commit_message = commit_message if commit_message is not None else "Update metadata with huggingface_hub"
+
+    # Card class given repo_type
+    card_class: Type[RepoCard]
+    if repo_type is None or repo_type == "model":
+        card_class = ModelCard
+    elif repo_type == "dataset":
+        card_class = DatasetCard
+    elif repo_type == "space":
+        card_class = RepoCard
+    else:
+        raise ValueError(f"Unknown repo_type: {repo_type}")
+
+    # Either load repo_card from the Hub or create an empty one.
+    # NOTE: Will not create the repo if it doesn't exist.
+    try:
+        card = card_class.load(repo_id, token=token, repo_type=repo_type)
+    except EntryNotFoundError:
+        if repo_type == "space":
+            raise ValueError("Cannot update metadata on a Space that doesn't contain a `README.md` file.")
+
+        # Initialize a ModelCard or DatasetCard from default template and no data.
+        card = card_class.from_template(CardData())
+
+    for key, value in metadata.items():
+        if key == "model-index":
+            # if the new metadata doesn't include a name, either use existing one or repo name
+            if "name" not in value[0]:
+                value[0]["name"] = getattr(card, "model_name", repo_id)
+            model_name, new_results = model_index_to_eval_results(value)
+            if card.data.eval_results is None:
+                card.data.eval_results = new_results
+                card.data.model_name = model_name
+            else:
+                existing_results = card.data.eval_results
+
+                # Iterate over new results
+                #   Iterate over existing results
+                #       If both results describe the same metric but value is different:
+                #           If overwrite=True: overwrite the metric value
+                #           Else: raise ValueError
+                #       Else: append new result to existing ones.
+                for new_result in new_results:
+                    result_found = False
+                    for existing_result in existing_results:
+                        if new_result.is_equal_except_value(existing_result):
+                            if new_result != existing_result and not overwrite:
+                                raise ValueError(
+                                    "You passed a new value for the existing metric"
+                                    f" 'name: {new_result.metric_name}, type: "
+                                    f"{new_result.metric_type}'. Set `overwrite=True`"
+                                    " to overwrite existing metrics."
+                                )
+                            result_found = True
+                            existing_result.metric_value = new_result.metric_value
+                            if existing_result.verified is True:
+                                existing_result.verify_token = new_result.verify_token
+                    if not result_found:
+                        card.data.eval_results.append(new_result)
+        else:
+            # Any metadata that is not a result metric
+            if card.data.get(key) is not None and not overwrite and card.data.get(key) != value:
+                raise ValueError(
+                    f"You passed a new value for the existing meta data field '{key}'."
+                    " Set `overwrite=True` to overwrite existing metadata."
+                )
+            else:
+                card.data[key] = value
+
+    return card.push_to_hub(
+        repo_id,
+        token=token,
+        repo_type=repo_type,
+        commit_message=commit_message,
+        commit_description=commit_description,
+        create_pr=create_pr,
+        revision=revision,
+        parent_commit=parent_commit,
+    )

lib/python3.11/site-packages/huggingface_hub/repocard_data.py

@@ -0,0 +1,711 @@
+import copy
+import warnings
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from huggingface_hub.utils import yaml_dump
+
+
+@dataclass
+class EvalResult:
+    """
+    Flattened representation of individual evaluation results found in model-index of Model Cards.
+
+    For more information on the model-index spec, see https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1.
+
+    Args:
+        task_type (`str`):
+            The task identifier. Example: "image-classification".
+        dataset_type (`str`):
+            The dataset identifier. Example: "common_voice". Use dataset id from https://hf.co/datasets.
+        dataset_name (`str`):
+            A pretty name for the dataset. Example: "Common Voice (French)".
+        metric_type (`str`):
+            The metric identifier. Example: "wer". Use metric id from https://hf.co/metrics.
+        metric_value (`Any`):
+            The metric value. Example: 0.9 or "20.0 ± 1.2".
+        task_name (`str`, *optional*):
+            A pretty name for the task. Example: "Speech Recognition".
+        dataset_config (`str`, *optional*):
+            The name of the dataset configuration used in `load_dataset()`.
+            Example: fr in `load_dataset("common_voice", "fr")`. See the `datasets` docs for more info:
+            https://hf.co/docs/datasets/package_reference/loading_methods#datasets.load_dataset.name
+        dataset_split (`str`, *optional*):
+            The split used in `load_dataset()`. Example: "test".
+        dataset_revision (`str`, *optional*):
+            The revision (AKA Git Sha) of the dataset used in `load_dataset()`.
+            Example: 5503434ddd753f426f4b38109466949a1217c2bb
+        dataset_args (`Dict[str, Any]`, *optional*):
+            The arguments passed during `Metric.compute()`. Example for `bleu`: `{"max_order": 4}`
+        metric_name (`str`, *optional*):
+            A pretty name for the metric. Example: "Test WER".
+        metric_config (`str`, *optional*):
+            The name of the metric configuration used in `load_metric()`.
+            Example: bleurt-large-512 in `load_metric("bleurt", "bleurt-large-512")`.
+            See the `datasets` docs for more info: https://huggingface.co/docs/datasets/v2.1.0/en/loading#load-configurations
+        metric_args (`Dict[str, Any]`, *optional*):
+            The arguments passed during `Metric.compute()`. Example for `bleu`: max_order: 4
+        verified (`bool`, *optional*):
+            Indicates whether the metrics originate from Hugging Face's [evaluation service](https://huggingface.co/spaces/autoevaluate/model-evaluator) or not. Automatically computed by Hugging Face, do not set.
+        verify_token (`str`, *optional*):
+            A JSON Web Token that is used to verify whether the metrics originate from Hugging Face's [evaluation service](https://huggingface.co/spaces/autoevaluate/model-evaluator) or not.
+        source_name (`str`, *optional*):
+            The name of the source of the evaluation result. Example: "Open LLM Leaderboard".
+        source_url (`str`, *optional*):
+            The URL of the source of the evaluation result. Example: "https://huggingface.co/spaces/HuggingFaceH4/open_llm_leaderboard".
+    """
+
+    # Required
+
+    # The task identifier
+    # Example: automatic-speech-recognition
+    task_type: str
+
+    # The dataset identifier
+    # Example: common_voice. Use dataset id from https://hf.co/datasets
+    dataset_type: str
+
+    # A pretty name for the dataset.
+    # Example: Common Voice (French)
+    dataset_name: str
+
+    # The metric identifier
+    # Example: wer. Use metric id from https://hf.co/metrics
+    metric_type: str
+
+    # Value of the metric.
+    # Example: 20.0 or "20.0 ± 1.2"
+    metric_value: Any
+
+    # Optional
+
+    # A pretty name for the task.
+    # Example: Speech Recognition
+    task_name: Optional[str] = None
+
+    # The name of the dataset configuration used in `load_dataset()`.
+    # Example: fr in `load_dataset("common_voice", "fr")`.
+    # See the `datasets` docs for more info:
+    # https://huggingface.co/docs/datasets/package_reference/loading_methods#datasets.load_dataset.name
+    dataset_config: Optional[str] = None
+
+    # The split used in `load_dataset()`.
+    # Example: test
+    dataset_split: Optional[str] = None
+
+    # The revision (AKA Git Sha) of the dataset used in `load_dataset()`.
+    # Example: 5503434ddd753f426f4b38109466949a1217c2bb
+    dataset_revision: Optional[str] = None
+
+    # The arguments passed during `Metric.compute()`.
+    # Example for `bleu`: max_order: 4
+    dataset_args: Optional[Dict[str, Any]] = None
+
+    # A pretty name for the metric.
+    # Example: Test WER
+    metric_name: Optional[str] = None
+
+    # The name of the metric configuration used in `load_metric()`.
+    # Example: bleurt-large-512 in `load_metric("bleurt", "bleurt-large-512")`.
+    # See the `datasets` docs for more info: https://huggingface.co/docs/datasets/v2.1.0/en/loading#load-configurations
+    metric_config: Optional[str] = None
+
+    # The arguments passed during `Metric.compute()`.
+    # Example for `bleu`: max_order: 4
+    metric_args: Optional[Dict[str, Any]] = None
+
+    # Indicates whether the metrics originate from Hugging Face's [evaluation service](https://huggingface.co/spaces/autoevaluate/model-evaluator) or not. Automatically computed by Hugging Face, do not set.
+    verified: Optional[bool] = None
+
+    # A JSON Web Token that is used to verify whether the metrics originate from Hugging Face's [evaluation service](https://huggingface.co/spaces/autoevaluate/model-evaluator) or not.
+    verify_token: Optional[str] = None
+
+    # The name of the source of the evaluation result.
+    # Example: Open LLM Leaderboard
+    source_name: Optional[str] = None
+
+    # The URL of the source of the evaluation result.
+    # Example: https://huggingface.co/spaces/HuggingFaceH4/open_llm_leaderboard
+    source_url: Optional[str] = None
+
+    @property
+    def unique_identifier(self) -> tuple:
+        """Returns a tuple that uniquely identifies this evaluation."""
+        return (
+            self.task_type,
+            self.dataset_type,
+            self.dataset_config,
+            self.dataset_split,
+            self.dataset_revision,
+        )
+
+    def is_equal_except_value(self, other: "EvalResult") -> bool:
+        """
+        Return True if `self` and `other` describe exactly the same metric but with a
+        different value.
+        """
+        for key, _ in self.__dict__.items():
+            if key == "metric_value":
+                continue
+            # For metrics computed by Hugging Face's evaluation service, `verify_token` is derived from `metric_value`,
+            # so we exclude it here in the comparison.
+            if key != "verify_token" and getattr(self, key) != getattr(other, key):
+                return False
+        return True
+
+    def __post_init__(self) -> None:
+        if self.source_name is not None and self.source_url is None:
+            raise ValueError("If `source_name` is provided, `source_url` must also be provided.")
+
+
+@dataclass
+class CardData:
+    """Structure containing metadata from a RepoCard.
+
+    [`CardData`] is the parent class of [`ModelCardData`] and [`DatasetCardData`].
+
+    Metadata can be exported as a dictionary or YAML. Export can be customized to alter the representation of the data
+    (example: flatten evaluation results). `CardData` behaves as a dictionary (can get, pop, set values) but do not
+    inherit from `dict` to allow this export step.
+    """
+
+    def __init__(self, ignore_metadata_errors: bool = False, **kwargs):
+        self.__dict__.update(kwargs)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts CardData to a dict.
+
+        Returns:
+            `dict`: CardData represented as a dictionary ready to be dumped to a YAML
+            block for inclusion in a README.md file.
+        """
+
+        data_dict = copy.deepcopy(self.__dict__)
+        self._to_dict(data_dict)
+        return _remove_none(data_dict)
+
+    def _to_dict(self, data_dict):
+        """Use this method in child classes to alter the dict representation of the data. Alter the dict in-place.
+
+        Args:
+            data_dict (`dict`): The raw dict representation of the card data.
+        """
+        pass
+
+    def to_yaml(self, line_break=None) -> str:
+        """Dumps CardData to a YAML block for inclusion in a README.md file.
+
+        Args:
+            line_break (str, *optional*):
+                The line break to use when dumping to yaml.
+
+        Returns:
+            `str`: CardData represented as a YAML block.
+        """
+        return yaml_dump(self.to_dict(), sort_keys=False, line_break=line_break).strip()
+
+    def __repr__(self):
+        return repr(self.__dict__)
+
+    def __str__(self):
+        return self.to_yaml()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get value for a given metadata key."""
+        return self.__dict__.get(key, default)
+
+    def pop(self, key: str, default: Any = None) -> Any:
+        """Pop value for a given metadata key."""
+        return self.__dict__.pop(key, default)
+
+    def __getitem__(self, key: str) -> Any:
+        """Get value for a given metadata key."""
+        return self.__dict__[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set value for a given metadata key."""
+        self.__dict__[key] = value
+
+    def __contains__(self, key: str) -> bool:
+        """Check if a given metadata key is set."""
+        return key in self.__dict__
+
+    def __len__(self) -> int:
+        """Return the number of metadata keys set."""
+        return len(self.__dict__)
+
+
+class ModelCardData(CardData):
+    """Model Card Metadata that is used by Hugging Face Hub when included at the top of your README.md
+
+    Args:
+        language (`Union[str, List[str]]`, *optional*):
+            Language of model's training data or metadata. It must be an ISO 639-1, 639-2 or
+            639-3 code (two/three letters), or a special value like "code", "multilingual". Defaults to `None`.
+        license (`str`, *optional*):
+            License of this model. Example: apache-2.0 or any license from
+            https://huggingface.co/docs/hub/repositories-licenses. Defaults to None.
+        library_name (`str`, *optional*):
+            Name of library used by this model. Example: keras or any library from
+            https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries.ts.
+            Defaults to None.
+        tags (`List[str]`, *optional*):
+            List of tags to add to your model that can be used when filtering on the Hugging
+            Face Hub. Defaults to None.
+        datasets (`List[str]`, *optional*):
+            List of datasets that were used to train this model. Should be a dataset ID
+            found on https://hf.co/datasets. Defaults to None.
+        metrics (`List[str]`, *optional*):
+            List of metrics used to evaluate this model. Should be a metric name that can be found
+            at https://hf.co/metrics. Example: 'accuracy'. Defaults to None.
+        eval_results (`Union[List[EvalResult], EvalResult]`, *optional*):
+            List of `huggingface_hub.EvalResult` that define evaluation results of the model. If provided,
+            `model_name` is used to as a name on PapersWithCode's leaderboards. Defaults to `None`.
+        model_name (`str`, *optional*):
+            A name for this model. It is used along with
+            `eval_results` to construct the `model-index` within the card's metadata. The name
+            you supply here is what will be used on PapersWithCode's leaderboards. If None is provided
+            then the repo name is used as a default. Defaults to None.
+        ignore_metadata_errors (`str`):
+            If True, errors while parsing the metadata section will be ignored. Some information might be lost during
+            the process. Use it at your own risk.
+        kwargs (`dict`, *optional*):
+            Additional metadata that will be added to the model card. Defaults to None.
+
+    Example:
+        ```python
+        >>> from huggingface_hub import ModelCardData
+        >>> card_data = ModelCardData(
+        ...     language="en",
+        ...     license="mit",
+        ...     library_name="timm",
+        ...     tags=['image-classification', 'resnet'],
+        ... )
+        >>> card_data.to_dict()
+        {'language': 'en', 'license': 'mit', 'library_name': 'timm', 'tags': ['image-classification', 'resnet']}
+
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        language: Optional[Union[str, List[str]]] = None,
+        license: Optional[str] = None,
+        library_name: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        datasets: Optional[List[str]] = None,
+        metrics: Optional[List[str]] = None,
+        eval_results: Optional[List[EvalResult]] = None,
+        model_name: Optional[str] = None,
+        ignore_metadata_errors: bool = False,
+        **kwargs,
+    ):
+        self.language = language
+        self.license = license
+        self.library_name = library_name
+        self.tags = tags
+        self.datasets = datasets
+        self.metrics = metrics
+        self.eval_results = eval_results
+        self.model_name = model_name
+
+        model_index = kwargs.pop("model-index", None)
+        if model_index:
+            try:
+                model_name, eval_results = model_index_to_eval_results(model_index)
+                self.model_name = model_name
+                self.eval_results = eval_results
+            except (KeyError, TypeError) as error:
+                if ignore_metadata_errors:
+                    warnings.warn("Invalid model-index. Not loading eval results into CardData.")
+                else:
+                    raise ValueError(
+                        f"Invalid `model_index` in metadata cannot be parsed: {error.__class__} {error}. Pass"
+                        " `ignore_metadata_errors=True` to ignore this error while loading a Model Card. Warning:"
+                        " some information will be lost. Use it at your own risk."
+                    )
+
+        super().__init__(**kwargs)
+
+        if self.eval_results:
+            if type(self.eval_results) == EvalResult:
+                self.eval_results = [self.eval_results]
+            if self.model_name is None:
+                raise ValueError("Passing `eval_results` requires `model_name` to be set.")
+
+    def _to_dict(self, data_dict):
+        """Format the internal data dict. In this case, we convert eval results to a valid model index"""
+        if self.eval_results is not None:
+            data_dict["model-index"] = eval_results_to_model_index(self.model_name, self.eval_results)
+            del data_dict["eval_results"], data_dict["model_name"]
+
+
+class DatasetCardData(CardData):
+    """Dataset Card Metadata that is used by Hugging Face Hub when included at the top of your README.md
+
+    Args:
+        language (`List[str]`, *optional*):
+            Language of dataset's data or metadata. It must be an ISO 639-1, 639-2 or
+            639-3 code (two/three letters), or a special value like "code", "multilingual".
+        license (`Union[str, List[str]]`, *optional*):
+            License(s) of this dataset. Example: apache-2.0 or any license from
+            https://huggingface.co/docs/hub/repositories-licenses.
+        annotations_creators (`Union[str, List[str]]`, *optional*):
+            How the annotations for the dataset were created.
+            Options are: 'found', 'crowdsourced', 'expert-generated', 'machine-generated', 'no-annotation', 'other'.
+        language_creators (`Union[str, List[str]]`, *optional*):
+            How the text-based data in the dataset was created.
+            Options are: 'found', 'crowdsourced', 'expert-generated', 'machine-generated', 'other'
+        multilinguality (`Union[str, List[str]]`, *optional*):
+            Whether the dataset is multilingual.
+            Options are: 'monolingual', 'multilingual', 'translation', 'other'.
+        size_categories (`Union[str, List[str]]`, *optional*):
+            The number of examples in the dataset. Options are: 'n<1K', '1K<n<10K', '10K<n<100K',
+            '100K<n<1M', '1M<n<10M', '10M<n<100M', '100M<n<1B', '1B<n<10B', '10B<n<100B', '100B<n<1T', 'n>1T', and 'other'.
+        source_datasets (`List[str]]`, *optional*):
+            Indicates whether the dataset is an original dataset or extended from another existing dataset.
+            Options are: 'original' and 'extended'.
+        task_categories (`Union[str, List[str]]`, *optional*):
+            What categories of task does the dataset support?
+        task_ids (`Union[str, List[str]]`, *optional*):
+            What specific tasks does the dataset support?
+        paperswithcode_id (`str`, *optional*):
+            ID of the dataset on PapersWithCode.
+        pretty_name (`str`, *optional*):
+            A more human-readable name for the dataset. (ex. "Cats vs. Dogs")
+        train_eval_index (`Dict`, *optional*):
+            A dictionary that describes the necessary spec for doing evaluation on the Hub.
+            If not provided, it will be gathered from the 'train-eval-index' key of the kwargs.
+        config_names (`Union[str, List[str]]`, *optional*):
+            A list of the available dataset configs for the dataset.
+    """
+
+    def __init__(
+        self,
+        *,
+        language: Optional[Union[str, List[str]]] = None,
+        license: Optional[Union[str, List[str]]] = None,
+        annotations_creators: Optional[Union[str, List[str]]] = None,
+        language_creators: Optional[Union[str, List[str]]] = None,
+        multilinguality: Optional[Union[str, List[str]]] = None,
+        size_categories: Optional[Union[str, List[str]]] = None,
+        source_datasets: Optional[List[str]] = None,
+        task_categories: Optional[Union[str, List[str]]] = None,
+        task_ids: Optional[Union[str, List[str]]] = None,
+        paperswithcode_id: Optional[str] = None,
+        pretty_name: Optional[str] = None,
+        train_eval_index: Optional[Dict] = None,
+        config_names: Optional[Union[str, List[str]]] = None,
+        ignore_metadata_errors: bool = False,
+        **kwargs,
+    ):
+        self.annotations_creators = annotations_creators
+        self.language_creators = language_creators
+        self.language = language
+        self.license = license
+        self.multilinguality = multilinguality
+        self.size_categories = size_categories
+        self.source_datasets = source_datasets
+        self.task_categories = task_categories
+        self.task_ids = task_ids
+        self.paperswithcode_id = paperswithcode_id
+        self.pretty_name = pretty_name
+        self.config_names = config_names
+
+        # TODO - maybe handle this similarly to EvalResult?
+        self.train_eval_index = train_eval_index or kwargs.pop("train-eval-index", None)
+        super().__init__(**kwargs)
+
+    def _to_dict(self, data_dict):
+        data_dict["train-eval-index"] = data_dict.pop("train_eval_index")
+
+
+class SpaceCardData(CardData):
+    """Space Card Metadata that is used by Hugging Face Hub when included at the top of your README.md
+
+    To get an exhaustive reference of Spaces configuration, please visit https://huggingface.co/docs/hub/spaces-config-reference#spaces-configuration-reference.
+
+    Args:
+        title (`str`, *optional*)
+            Title of the Space.
+        sdk (`str`, *optional*)
+            SDK of the Space (one of `gradio`, `streamlit`, `docker`, or `static`).
+        sdk_version (`str`, *optional*)
+            Version of the used SDK (if Gradio/Streamlit sdk).
+        python_version (`str`, *optional*)
+            Python version used in the Space (if Gradio/Streamlit sdk).
+        app_file (`str`, *optional*)
+            Path to your main application file (which contains either gradio or streamlit Python code, or static html code).
+            Path is relative to the root of the repository.
+        app_port (`str`, *optional*)
+            Port on which your application is running. Used only if sdk is `docker`.
+        license (`str`, *optional*)
+            License of this model. Example: apache-2.0 or any license from
+            https://huggingface.co/docs/hub/repositories-licenses.
+        duplicated_from (`str`, *optional*)
+            ID of the original Space if this is a duplicated Space.
+        models (List[`str`], *optional*)
+            List of models related to this Space. Should be a dataset ID found on https://hf.co/models.
+        datasets (`List[str]`, *optional*)
+            List of datasets related to this Space. Should be a dataset ID found on https://hf.co/datasets.
+        tags (`List[str]`, *optional*)
+            List of tags to add to your Space that can be used when filtering on the Hub.
+        ignore_metadata_errors (`str`):
+            If True, errors while parsing the metadata section will be ignored. Some information might be lost during
+            the process. Use it at your own risk.
+        kwargs (`dict`, *optional*):
+            Additional metadata that will be added to the space card.
+
+    Example:
+        ```python
+        >>> from huggingface_hub import SpaceCardData
+        >>> card_data = SpaceCardData(
+        ...     title="Dreambooth Training",
+        ...     license="mit",
+        ...     sdk="gradio",
+        ...     duplicated_from="multimodalart/dreambooth-training"
+        ... )
+        >>> card_data.to_dict()
+        {'title': 'Dreambooth Training', 'sdk': 'gradio', 'license': 'mit', 'duplicated_from': 'multimodalart/dreambooth-training'}
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        title: Optional[str] = None,
+        sdk: Optional[str] = None,
+        sdk_version: Optional[str] = None,
+        python_version: Optional[str] = None,
+        app_file: Optional[str] = None,
+        app_port: Optional[int] = None,
+        license: Optional[str] = None,
+        duplicated_from: Optional[str] = None,
+        models: Optional[List[str]] = None,
+        datasets: Optional[List[str]] = None,
+        tags: Optional[List[str]] = None,
+        ignore_metadata_errors: bool = False,
+        **kwargs,
+    ):
+        self.title = title
+        self.sdk = sdk
+        self.sdk_version = sdk_version
+        self.python_version = python_version
+        self.app_file = app_file
+        self.app_port = app_port
+        self.license = license
+        self.duplicated_from = duplicated_from
+        self.models = models
+        self.datasets = datasets
+        self.tags = tags
+        super().__init__(**kwargs)
+
+
+def model_index_to_eval_results(model_index: List[Dict[str, Any]]) -> Tuple[str, List[EvalResult]]:
+    """Takes in a model index and returns the model name and a list of `huggingface_hub.EvalResult` objects.
+
+    A detailed spec of the model index can be found here:
+    https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1
+
+    Args:
+        model_index (`List[Dict[str, Any]]`):
+            A model index data structure, likely coming from a README.md file on the
+            Hugging Face Hub.
+
+    Returns:
+        model_name (`str`):
+            The name of the model as found in the model index. This is used as the
+            identifier for the model on leaderboards like PapersWithCode.
+        eval_results (`List[EvalResult]`):
+            A list of `huggingface_hub.EvalResult` objects containing the metrics
+            reported in the provided model_index.
+
+    Example:
+        ```python
+        >>> from huggingface_hub.repocard_data import model_index_to_eval_results
+        >>> # Define a minimal model index
+        >>> model_index = [
+        ...     {
+        ...         "name": "my-cool-model",
+        ...         "results": [
+        ...             {
+        ...                 "task": {
+        ...                     "type": "image-classification"
+        ...                 },
+        ...                 "dataset": {
+        ...                     "type": "beans",
+        ...                     "name": "Beans"
+        ...                 },
+        ...                 "metrics": [
+        ...                     {
+        ...                         "type": "accuracy",
+        ...                         "value": 0.9
+        ...                     }
+        ...                 ]
+        ...             }
+        ...         ]
+        ...     }
+        ... ]
+        >>> model_name, eval_results = model_index_to_eval_results(model_index)
+        >>> model_name
+        'my-cool-model'
+        >>> eval_results[0].task_type
+        'image-classification'
+        >>> eval_results[0].metric_type
+        'accuracy'
+
+        ```
+    """
+
+    eval_results = []
+    for elem in model_index:
+        name = elem["name"]
+        results = elem["results"]
+        for result in results:
+            task_type = result["task"]["type"]
+            task_name = result["task"].get("name")
+            dataset_type = result["dataset"]["type"]
+            dataset_name = result["dataset"]["name"]
+            dataset_config = result["dataset"].get("config")
+            dataset_split = result["dataset"].get("split")
+            dataset_revision = result["dataset"].get("revision")
+            dataset_args = result["dataset"].get("args")
+            source_name = result.get("source", {}).get("name")
+            source_url = result.get("source", {}).get("url")
+
+            for metric in result["metrics"]:
+                metric_type = metric["type"]
+                metric_value = metric["value"]
+                metric_name = metric.get("name")
+                metric_args = metric.get("args")
+                metric_config = metric.get("config")
+                verified = metric.get("verified")
+                verify_token = metric.get("verifyToken")
+
+                eval_result = EvalResult(
+                    task_type=task_type,  # Required
+                    dataset_type=dataset_type,  # Required
+                    dataset_name=dataset_name,  # Required
+                    metric_type=metric_type,  # Required
+                    metric_value=metric_value,  # Required
+                    task_name=task_name,
+                    dataset_config=dataset_config,
+                    dataset_split=dataset_split,
+                    dataset_revision=dataset_revision,
+                    dataset_args=dataset_args,
+                    metric_name=metric_name,
+                    metric_args=metric_args,
+                    metric_config=metric_config,
+                    verified=verified,
+                    verify_token=verify_token,
+                    source_name=source_name,
+                    source_url=source_url,
+                )
+                eval_results.append(eval_result)
+    return name, eval_results
+
+
+def _remove_none(obj):
+    """
+    Recursively remove `None` values from a dict. Borrowed from: https://stackoverflow.com/a/20558778
+    """
+    if isinstance(obj, (list, tuple, set)):
+        return type(obj)(_remove_none(x) for x in obj if x is not None)
+    elif isinstance(obj, dict):
+        return type(obj)((_remove_none(k), _remove_none(v)) for k, v in obj.items() if k is not None and v is not None)
+    else:
+        return obj
+
+
+def eval_results_to_model_index(model_name: str, eval_results: List[EvalResult]) -> List[Dict[str, Any]]:
+    """Takes in given model name and list of `huggingface_hub.EvalResult` and returns a
+    valid model-index that will be compatible with the format expected by the
+    Hugging Face Hub.
+
+    Args:
+        model_name (`str`):
+            Name of the model (ex. "my-cool-model"). This is used as the identifier
+            for the model on leaderboards like PapersWithCode.
+        eval_results (`List[EvalResult]`):
+            List of `huggingface_hub.EvalResult` objects containing the metrics to be
+            reported in the model-index.
+
+    Returns:
+        model_index (`List[Dict[str, Any]]`): The eval_results converted to a model-index.
+
+    Example:
+        ```python
+        >>> from huggingface_hub.repocard_data import eval_results_to_model_index, EvalResult
+        >>> # Define minimal eval_results
+        >>> eval_results = [
+        ...     EvalResult(
+        ...         task_type="image-classification",  # Required
+        ...         dataset_type="beans",  # Required
+        ...         dataset_name="Beans",  # Required
+        ...         metric_type="accuracy",  # Required
+        ...         metric_value=0.9,  # Required
+        ...     )
+        ... ]
+        >>> eval_results_to_model_index("my-cool-model", eval_results)
+        [{'name': 'my-cool-model', 'results': [{'task': {'type': 'image-classification'}, 'dataset': {'name': 'Beans', 'type': 'beans'}, 'metrics': [{'type': 'accuracy', 'value': 0.9}]}]}]
+
+        ```
+    """
+
+    # Metrics are reported on a unique task-and-dataset basis.
+    # Here, we make a map of those pairs and the associated EvalResults.
+    task_and_ds_types_map: Dict[Any, List[EvalResult]] = defaultdict(list)
+    for eval_result in eval_results:
+        task_and_ds_types_map[eval_result.unique_identifier].append(eval_result)
+
+    # Use the map from above to generate the model index data.
+    model_index_data = []
+    for results in task_and_ds_types_map.values():
+        # All items from `results` share same metadata
+        sample_result = results[0]
+        data = {
+            "task": {
+                "type": sample_result.task_type,
+                "name": sample_result.task_name,
+            },
+            "dataset": {
+                "name": sample_result.dataset_name,
+                "type": sample_result.dataset_type,
+                "config": sample_result.dataset_config,
+                "split": sample_result.dataset_split,
+                "revision": sample_result.dataset_revision,
+                "args": sample_result.dataset_args,
+            },
+            "metrics": [
+                {
+                    "type": result.metric_type,
+                    "value": result.metric_value,
+                    "name": result.metric_name,
+                    "config": result.metric_config,
+                    "args": result.metric_args,
+                    "verified": result.verified,
+                    "verifyToken": result.verify_token,
+                }
+                for result in results
+            ],
+        }
+        if sample_result.source_url is not None:
+            source = {
+                "url": sample_result.source_url,
+            }
+            if sample_result.source_name is not None:
+                source["name"] = sample_result.source_name
+            data["source"] = source
+        model_index_data.append(data)
+
+    # TODO - Check if there cases where this list is longer than one?
+    # Finally, the model index itself is list of dicts.
+    model_index = [
+        {
+            "name": model_name,
+            "results": model_index_data,
+        }
+    ]
+    return _remove_none(model_index)

lib/python3.11/site-packages/huggingface_hub/repository.py

@@ -0,0 +1,1476 @@
+import atexit
+import os
+import re
+import subprocess
+import threading
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Callable, Dict, Iterator, List, Optional, Tuple, TypedDict, Union
+from urllib.parse import urlparse
+
+from huggingface_hub.constants import REPO_TYPES_URL_PREFIXES, REPOCARD_NAME
+from huggingface_hub.repocard import metadata_load, metadata_save
+
+from .hf_api import HfApi, repo_type_and_id_from_hf_id
+from .lfs import LFS_MULTIPART_UPLOAD_COMMAND
+from .utils import (
+    SoftTemporaryDirectory,
+    get_token,
+    logging,
+    run_subprocess,
+    tqdm,
+    validate_hf_hub_args,
+)
+from .utils._deprecation import _deprecate_method
+
+
+logger = logging.get_logger(__name__)
+
+
+class CommandInProgress:
+    """
+    Utility to follow commands launched asynchronously.
+    """
+
+    def __init__(
+        self,
+        title: str,
+        is_done_method: Callable,
+        status_method: Callable,
+        process: subprocess.Popen,
+        post_method: Optional[Callable] = None,
+    ):
+        self.title = title
+        self._is_done = is_done_method
+        self._status = status_method
+        self._process = process
+        self._stderr = ""
+        self._stdout = ""
+        self._post_method = post_method
+
+    @property
+    def is_done(self) -> bool:
+        """
+        Whether the process is done.
+        """
+        result = self._is_done()
+
+        if result and self._post_method is not None:
+            self._post_method()
+            self._post_method = None
+
+        return result
+
+    @property
+    def status(self) -> int:
+        """
+        The exit code/status of the current action. Will return `0` if the
+        command has completed successfully, and a number between 1 and 255 if
+        the process errored-out.
+
+        Will return -1 if the command is still ongoing.
+        """
+        return self._status()
+
+    @property
+    def failed(self) -> bool:
+        """
+        Whether the process errored-out.
+        """
+        return self.status > 0
+
+    @property
+    def stderr(self) -> str:
+        """
+        The current output message on the standard error.
+        """
+        if self._process.stderr is not None:
+            self._stderr += self._process.stderr.read()
+        return self._stderr
+
+    @property
+    def stdout(self) -> str:
+        """
+        The current output message on the standard output.
+        """
+        if self._process.stdout is not None:
+            self._stdout += self._process.stdout.read()
+        return self._stdout
+
+    def __repr__(self):
+        status = self.status
+
+        if status == -1:
+            status = "running"
+
+        return (
+            f"[{self.title} command, status code: {status},"
+            f" {'in progress.' if not self.is_done else 'finished.'} PID:"
+            f" {self._process.pid}]"
+        )
+
+
+def is_git_repo(folder: Union[str, Path]) -> bool:
+    """
+    Check if the folder is the root or part of a git repository
+
+    Args:
+        folder (`str`):
+            The folder in which to run the command.
+
+    Returns:
+        `bool`: `True` if the repository is part of a repository, `False`
+        otherwise.
+    """
+    folder_exists = os.path.exists(os.path.join(folder, ".git"))
+    git_branch = subprocess.run("git branch".split(), cwd=folder, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    return folder_exists and git_branch.returncode == 0
+
+
+def is_local_clone(folder: Union[str, Path], remote_url: str) -> bool:
+    """
+    Check if the folder is a local clone of the remote_url
+
+    Args:
+        folder (`str` or `Path`):
+            The folder in which to run the command.
+        remote_url (`str`):
+            The url of a git repository.
+
+    Returns:
+        `bool`: `True` if the repository is a local clone of the remote
+        repository specified, `False` otherwise.
+    """
+    if not is_git_repo(folder):
+        return False
+
+    remotes = run_subprocess("git remote -v", folder).stdout
+
+    # Remove token for the test with remotes.
+    remote_url = re.sub(r"https://.*@", "https://", remote_url)
+    remotes = [re.sub(r"https://.*@", "https://", remote) for remote in remotes.split()]
+    return remote_url in remotes
+
+
+def is_tracked_with_lfs(filename: Union[str, Path]) -> bool:
+    """
+    Check if the file passed is tracked with git-lfs.
+
+    Args:
+        filename (`str` or `Path`):
+            The filename to check.
+
+    Returns:
+        `bool`: `True` if the file passed is tracked with git-lfs, `False`
+        otherwise.
+    """
+    folder = Path(filename).parent
+    filename = Path(filename).name
+
+    try:
+        p = run_subprocess("git check-attr -a".split() + [filename], folder)
+        attributes = p.stdout.strip()
+    except subprocess.CalledProcessError as exc:
+        if not is_git_repo(folder):
+            return False
+        else:
+            raise OSError(exc.stderr)
+
+    if len(attributes) == 0:
+        return False
+
+    found_lfs_tag = {"diff": False, "merge": False, "filter": False}
+
+    for attribute in attributes.split("\n"):
+        for tag in found_lfs_tag.keys():
+            if tag in attribute and "lfs" in attribute:
+                found_lfs_tag[tag] = True
+
+    return all(found_lfs_tag.values())
+
+
+def is_git_ignored(filename: Union[str, Path]) -> bool:
+    """
+    Check if file is git-ignored. Supports nested .gitignore files.
+
+    Args:
+        filename (`str` or `Path`):
+            The filename to check.
+
+    Returns:
+        `bool`: `True` if the file passed is ignored by `git`, `False`
+        otherwise.
+    """
+    folder = Path(filename).parent
+    filename = Path(filename).name
+
+    try:
+        p = run_subprocess("git check-ignore".split() + [filename], folder, check=False)
+        # Will return exit code 1 if not gitignored
+        is_ignored = not bool(p.returncode)
+    except subprocess.CalledProcessError as exc:
+        raise OSError(exc.stderr)
+
+    return is_ignored
+
+
+def is_binary_file(filename: Union[str, Path]) -> bool:
+    """
+    Check if file is a binary file.
+
+    Args:
+        filename (`str` or `Path`):
+            The filename to check.
+
+    Returns:
+        `bool`: `True` if the file passed is a binary file, `False` otherwise.
+    """
+    try:
+        with open(filename, "rb") as f:
+            content = f.read(10 * (1024**2))  # Read a maximum of 10MB
+
+        # Code sample taken from the following stack overflow thread
+        # https://stackoverflow.com/questions/898669/how-can-i-detect-if-a-file-is-binary-non-text-in-python/7392391#7392391
+        text_chars = bytearray({7, 8, 9, 10, 12, 13, 27} | set(range(0x20, 0x100)) - {0x7F})
+        return bool(content.translate(None, text_chars))
+    except UnicodeDecodeError:
+        return True
+
+
+def files_to_be_staged(pattern: str = ".", folder: Union[str, Path, None] = None) -> List[str]:
+    """
+    Returns a list of filenames that are to be staged.
+
+    Args:
+        pattern (`str` or `Path`):
+            The pattern of filenames to check. Put `.` to get all files.
+        folder (`str` or `Path`):
+            The folder in which to run the command.
+
+    Returns:
+        `List[str]`: List of files that are to be staged.
+    """
+    try:
+        p = run_subprocess("git ls-files --exclude-standard -mo".split() + [pattern], folder)
+        if len(p.stdout.strip()):
+            files = p.stdout.strip().split("\n")
+        else:
+            files = []
+    except subprocess.CalledProcessError as exc:
+        raise EnvironmentError(exc.stderr)
+
+    return files
+
+
+def is_tracked_upstream(folder: Union[str, Path]) -> bool:
+    """
+    Check if the current checked-out branch is tracked upstream.
+
+    Args:
+        folder (`str` or `Path`):
+            The folder in which to run the command.
+
+    Returns:
+        `bool`: `True` if the current checked-out branch is tracked upstream,
+        `False` otherwise.
+    """
+    try:
+        run_subprocess("git rev-parse --symbolic-full-name --abbrev-ref @{u}", folder)
+        return True
+    except subprocess.CalledProcessError as exc:
+        if "HEAD" in exc.stderr:
+            raise OSError("No branch checked out")
+
+        return False
+
+
+def commits_to_push(folder: Union[str, Path], upstream: Optional[str] = None) -> int:
+    """
+        Check the number of commits that would be pushed upstream
+
+        Args:
+            folder (`str` or `Path`):
+                The folder in which to run the command.
+            upstream (`str`, *optional*):
+    The name of the upstream repository with which the comparison should be
+    made.
+
+        Returns:
+            `int`: Number of commits that would be pushed upstream were a `git
+            push` to proceed.
+    """
+    try:
+        result = run_subprocess(f"git cherry -v {upstream or ''}", folder)
+        return len(result.stdout.split("\n")) - 1
+    except subprocess.CalledProcessError as exc:
+        raise EnvironmentError(exc.stderr)
+
+
+class PbarT(TypedDict):
+    # Used to store an opened progress bar in `_lfs_log_progress`
+    bar: tqdm
+    past_bytes: int
+
+
+@contextmanager
+def _lfs_log_progress():
+    """
+    This is a context manager that will log the Git LFS progress of cleaning,
+    smudging, pulling and pushing.
+    """
+
+    if logger.getEffectiveLevel() >= logging.ERROR:
+        try:
+            yield
+        except Exception:
+            pass
+        return
+
+    def output_progress(stopping_event: threading.Event):
+        """
+        To be launched as a separate thread with an event meaning it should stop
+        the tail.
+        """
+        # Key is tuple(state, filename), value is a dict(tqdm bar and a previous value)
+        pbars: Dict[Tuple[str, str], PbarT] = {}
+
+        def close_pbars():
+            for pbar in pbars.values():
+                pbar["bar"].update(pbar["bar"].total - pbar["past_bytes"])
+                pbar["bar"].refresh()
+                pbar["bar"].close()
+
+        def tail_file(filename) -> Iterator[str]:
+            """
+            Creates a generator to be iterated through, which will return each
+            line one by one. Will stop tailing the file if the stopping_event is
+            set.
+            """
+            with open(filename, "r") as file:
+                current_line = ""
+                while True:
+                    if stopping_event.is_set():
+                        close_pbars()
+                        break
+
+                    line_bit = file.readline()
+                    if line_bit is not None and not len(line_bit.strip()) == 0:
+                        current_line += line_bit
+                        if current_line.endswith("\n"):
+                            yield current_line
+                            current_line = ""
+                    else:
+                        time.sleep(1)
+
+        # If the file isn't created yet, wait for a few seconds before trying again.
+        # Can be interrupted with the stopping_event.
+        while not os.path.exists(os.environ["GIT_LFS_PROGRESS"]):
+            if stopping_event.is_set():
+                close_pbars()
+                return
+
+            time.sleep(2)
+
+        for line in tail_file(os.environ["GIT_LFS_PROGRESS"]):
+            try:
+                state, file_progress, byte_progress, filename = line.split()
+            except ValueError as error:
+                # Try/except to ease debugging. See https://github.com/huggingface/huggingface_hub/issues/1373.
+                raise ValueError(f"Cannot unpack LFS progress line:\n{line}") from error
+            description = f"{state.capitalize()} file {filename}"
+
+            current_bytes, total_bytes = byte_progress.split("/")
+            current_bytes_int = int(current_bytes)
+            total_bytes_int = int(total_bytes)
+
+            pbar = pbars.get((state, filename))
+            if pbar is None:
+                # Initialize progress bar
+                pbars[(state, filename)] = {
+                    "bar": tqdm(
+                        desc=description,
+                        initial=current_bytes_int,
+                        total=total_bytes_int,
+                        unit="B",
+                        unit_scale=True,
+                        unit_divisor=1024,
+                    ),
+                    "past_bytes": int(current_bytes),
+                }
+            else:
+                # Update progress bar
+                pbar["bar"].update(current_bytes_int - pbar["past_bytes"])
+                pbar["past_bytes"] = current_bytes_int
+
+    current_lfs_progress_value = os.environ.get("GIT_LFS_PROGRESS", "")
+
+    with SoftTemporaryDirectory() as tmpdir:
+        os.environ["GIT_LFS_PROGRESS"] = os.path.join(tmpdir, "lfs_progress")
+        logger.debug(f"Following progress in {os.environ['GIT_LFS_PROGRESS']}")
+
+        exit_event = threading.Event()
+        x = threading.Thread(target=output_progress, args=(exit_event,), daemon=True)
+        x.start()
+
+        try:
+            yield
+        finally:
+            exit_event.set()
+            x.join()
+
+            os.environ["GIT_LFS_PROGRESS"] = current_lfs_progress_value
+
+
+class Repository:
+    """
+    Helper class to wrap the git and git-lfs commands.
+
+    The aim is to facilitate interacting with huggingface.co hosted model or
+    dataset repos, though not a lot here (if any) is actually specific to
+    huggingface.co.
+
+    <Tip warning={true}>
+
+    [`Repository`] is deprecated in favor of the http-based alternatives implemented in
+    [`HfApi`]. Given its large adoption in legacy code, the complete removal of
+    [`Repository`] will only happen in release `v1.0`. For more details, please read
+    https://huggingface.co/docs/huggingface_hub/concepts/git_vs_http.
+
+    </Tip>
+    """
+
+    command_queue: List[CommandInProgress]
+
+    @validate_hf_hub_args
+    @_deprecate_method(
+        version="1.0",
+        message=(
+            "Please prefer the http-based alternatives instead. Given its large adoption in legacy code, the complete"
+            " removal is only planned on next major release.\nFor more details, please read"
+            " https://huggingface.co/docs/huggingface_hub/concepts/git_vs_http."
+        ),
+    )
+    def __init__(
+        self,
+        local_dir: Union[str, Path],
+        clone_from: Optional[str] = None,
+        repo_type: Optional[str] = None,
+        token: Union[bool, str] = True,
+        git_user: Optional[str] = None,
+        git_email: Optional[str] = None,
+        revision: Optional[str] = None,
+        skip_lfs_files: bool = False,
+        client: Optional[HfApi] = None,
+    ):
+        """
+        Instantiate a local clone of a git repo.
+
+        If `clone_from` is set, the repo will be cloned from an existing remote repository.
+        If the remote repo does not exist, a `EnvironmentError` exception will be thrown.
+        Please create the remote repo first using [`create_repo`].
+
+        `Repository` uses the local git credentials by default. If explicitly set, the `token`
+        or the `git_user`/`git_email` pair will be used instead.
+
+        Args:
+            local_dir (`str` or `Path`):
+                path (e.g. `'my_trained_model/'`) to the local directory, where
+                the `Repository` will be initialized.
+            clone_from (`str`, *optional*):
+                Either a repository url or `repo_id`.
+                Example:
+                - `"https://huggingface.co/philschmid/playground-tests"`
+                - `"philschmid/playground-tests"`
+            repo_type (`str`, *optional*):
+                To set when cloning a repo from a repo_id. Default is model.
+            token (`bool` or `str`, *optional*):
+                A valid authentication token (see https://huggingface.co/settings/token).
+                If `None` or `True` and machine is logged in (through `huggingface-cli login`
+                or [`~huggingface_hub.login`]), token will be retrieved from the cache.
+                If `False`, token is not sent in the request header.
+            git_user (`str`, *optional*):
+                will override the `git config user.name` for committing and
+                pushing files to the hub.
+            git_email (`str`, *optional*):
+                will override the `git config user.email` for committing and
+                pushing files to the hub.
+            revision (`str`, *optional*):
+                Revision to checkout after initializing the repository. If the
+                revision doesn't exist, a branch will be created with that
+                revision name from the default branch's current HEAD.
+            skip_lfs_files (`bool`, *optional*, defaults to `False`):
+                whether to skip git-LFS files or not.
+            client (`HfApi`, *optional*):
+                Instance of [`HfApi`] to use when calling the HF Hub API. A new
+                instance will be created if this is left to `None`.
+
+        Raises:
+            - [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+              if the remote repository set in `clone_from` does not exist.
+        """
+        if isinstance(local_dir, Path):
+            local_dir = str(local_dir)
+        os.makedirs(local_dir, exist_ok=True)
+        self.local_dir = os.path.join(os.getcwd(), local_dir)
+        self._repo_type = repo_type
+        self.command_queue = []
+        self.skip_lfs_files = skip_lfs_files
+        self.client = client if client is not None else HfApi()
+
+        self.check_git_versions()
+
+        if isinstance(token, str):
+            self.huggingface_token: Optional[str] = token
+        elif token is False:
+            self.huggingface_token = None
+        else:
+            # if `True` -> explicit use of the cached token
+            # if `None` -> implicit use of the cached token
+            self.huggingface_token = get_token()
+
+        if clone_from is not None:
+            self.clone_from(repo_url=clone_from)
+        else:
+            if is_git_repo(self.local_dir):
+                logger.debug("[Repository] is a valid git repo")
+            else:
+                raise ValueError("If not specifying `clone_from`, you need to pass Repository a valid git clone.")
+
+        if self.huggingface_token is not None and (git_email is None or git_user is None):
+            user = self.client.whoami(self.huggingface_token)
+
+            if git_email is None:
+                git_email = user["email"]
+
+            if git_user is None:
+                git_user = user["fullname"]
+
+        if git_user is not None or git_email is not None:
+            self.git_config_username_and_email(git_user, git_email)
+
+        self.lfs_enable_largefiles()
+        self.git_credential_helper_store()
+
+        if revision is not None:
+            self.git_checkout(revision, create_branch_ok=True)
+
+        # This ensures that all commands exit before exiting the Python runtime.
+        # This will ensure all pushes register on the hub, even if other errors happen in subsequent operations.
+        atexit.register(self.wait_for_commands)
+
+    @property
+    def current_branch(self) -> str:
+        """
+        Returns the current checked out branch.
+
+        Returns:
+            `str`: Current checked out branch.
+        """
+        try:
+            result = run_subprocess("git rev-parse --abbrev-ref HEAD", self.local_dir).stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+        return result
+
+    def check_git_versions(self):
+        """
+        Checks that `git` and `git-lfs` can be run.
+
+        Raises:
+            - [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+              if `git` or `git-lfs` are not installed.
+        """
+        try:
+            git_version = run_subprocess("git --version", self.local_dir).stdout.strip()
+        except FileNotFoundError:
+            raise EnvironmentError("Looks like you do not have git installed, please install.")
+
+        try:
+            lfs_version = run_subprocess("git-lfs --version", self.local_dir).stdout.strip()
+        except FileNotFoundError:
+            raise EnvironmentError(
+                "Looks like you do not have git-lfs installed, please install."
+                " You can install from https://git-lfs.github.com/."
+                " Then run `git lfs install` (you only have to do this once)."
+            )
+        logger.info(git_version + "\n" + lfs_version)
+
+    @validate_hf_hub_args
+    def clone_from(self, repo_url: str, token: Union[bool, str, None] = None):
+        """
+        Clone from a remote. If the folder already exists, will try to clone the
+        repository within it.
+
+        If this folder is a git repository with linked history, will try to
+        update the repository.
+
+        Args:
+            repo_url (`str`):
+                The URL from which to clone the repository
+            token (`Union[str, bool]`, *optional*):
+                Whether to use the authentication token. It can be:
+                 - a string which is the token itself
+                 - `False`, which would not use the authentication token
+                 - `True`, which would fetch the authentication token from the
+                   local folder and use it (you should be logged in for this to
+                   work).
+                - `None`, which would retrieve the value of
+                  `self.huggingface_token`.
+
+        <Tip>
+
+        Raises the following error:
+
+            - [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+              if an organization token (starts with "api_org") is passed. Use must use
+              your own personal access token (see https://hf.co/settings/tokens).
+
+            - [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+              if you are trying to clone the repository in a non-empty folder, or if the
+              `git` operations raise errors.
+
+        </Tip>
+        """
+        token = (
+            token  # str -> use it
+            if isinstance(token, str)
+            else (
+                None  # `False` -> explicit no token
+                if token is False
+                else self.huggingface_token  # `None` or `True` -> use default
+            )
+        )
+        if token is not None and token.startswith("api_org"):
+            raise ValueError(
+                "You must use your personal access token, not an Organization token"
+                " (see https://hf.co/settings/tokens)."
+            )
+
+        hub_url = self.client.endpoint
+        if hub_url in repo_url or ("http" not in repo_url and len(repo_url.split("/")) <= 2):
+            repo_type, namespace, repo_name = repo_type_and_id_from_hf_id(repo_url, hub_url=hub_url)
+            repo_id = f"{namespace}/{repo_name}" if namespace is not None else repo_name
+
+            if repo_type is not None:
+                self._repo_type = repo_type
+
+            repo_url = hub_url + "/"
+
+            if self._repo_type in REPO_TYPES_URL_PREFIXES:
+                repo_url += REPO_TYPES_URL_PREFIXES[self._repo_type]
+
+            if token is not None:
+                # Add token in git url when provided
+                scheme = urlparse(repo_url).scheme
+                repo_url = repo_url.replace(f"{scheme}://", f"{scheme}://user:{token}@")
+
+            repo_url += repo_id
+
+        # For error messages, it's cleaner to show the repo url without the token.
+        clean_repo_url = re.sub(r"(https?)://.*@", r"\1://", repo_url)
+        try:
+            run_subprocess("git lfs install", self.local_dir)
+
+            # checks if repository is initialized in a empty repository or in one with files
+            if len(os.listdir(self.local_dir)) == 0:
+                logger.warning(f"Cloning {clean_repo_url} into local empty directory.")
+
+                with _lfs_log_progress():
+                    env = os.environ.copy()
+
+                    if self.skip_lfs_files:
+                        env.update({"GIT_LFS_SKIP_SMUDGE": "1"})
+
+                    run_subprocess(
+                        # 'git lfs clone' is deprecated (will display a warning in the terminal)
+                        # but we still use it as it provides a nicer UX when downloading large
+                        # files (shows progress).
+                        f"{'git clone' if self.skip_lfs_files else 'git lfs clone'} {repo_url} .",
+                        self.local_dir,
+                        env=env,
+                    )
+            else:
+                # Check if the folder is the root of a git repository
+                if not is_git_repo(self.local_dir):
+                    raise EnvironmentError(
+                        "Tried to clone a repository in a non-empty folder that isn't"
+                        f" a git repository ('{self.local_dir}'). If you really want to"
+                        f" do this, do it manually:\n cd {self.local_dir} && git init"
+                        " && git remote add origin && git pull origin main\n or clone"
+                        " repo to a new folder and move your existing files there"
+                        " afterwards."
+                    )
+
+                if is_local_clone(self.local_dir, repo_url):
+                    logger.warning(
+                        f"{self.local_dir} is already a clone of {clean_repo_url}."
+                        " Make sure you pull the latest changes with"
+                        " `repo.git_pull()`."
+                    )
+                else:
+                    output = run_subprocess("git remote get-url origin", self.local_dir, check=False)
+
+                    error_msg = (
+                        f"Tried to clone {clean_repo_url} in an unrelated git"
+                        " repository.\nIf you believe this is an error, please add"
+                        f" a remote with the following URL: {clean_repo_url}."
+                    )
+                    if output.returncode == 0:
+                        clean_local_remote_url = re.sub(r"https://.*@", "https://", output.stdout)
+                        error_msg += f"\nLocal path has its origin defined as: {clean_local_remote_url}"
+                    raise EnvironmentError(error_msg)
+
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_config_username_and_email(self, git_user: Optional[str] = None, git_email: Optional[str] = None):
+        """
+        Sets git username and email (only in the current repo).
+
+        Args:
+            git_user (`str`, *optional*):
+                The username to register through `git`.
+            git_email (`str`, *optional*):
+                The email to register through `git`.
+        """
+        try:
+            if git_user is not None:
+                run_subprocess("git config user.name".split() + [git_user], self.local_dir)
+
+            if git_email is not None:
+                run_subprocess(f"git config user.email {git_email}".split(), self.local_dir)
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_credential_helper_store(self):
+        """
+        Sets the git credential helper to `store`
+        """
+        try:
+            run_subprocess("git config credential.helper store", self.local_dir)
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_head_hash(self) -> str:
+        """
+        Get commit sha on top of HEAD.
+
+        Returns:
+            `str`: The current checked out commit SHA.
+        """
+        try:
+            p = run_subprocess("git rev-parse HEAD", self.local_dir)
+            return p.stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_remote_url(self) -> str:
+        """
+        Get URL to origin remote.
+
+        Returns:
+            `str`: The URL of the `origin` remote.
+        """
+        try:
+            p = run_subprocess("git config --get remote.origin.url", self.local_dir)
+            url = p.stdout.strip()
+            # Strip basic auth info.
+            return re.sub(r"https://.*@", "https://", url)
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_head_commit_url(self) -> str:
+        """
+        Get URL to last commit on HEAD. We assume it's been pushed, and the url
+        scheme is the same one as for GitHub or HuggingFace.
+
+        Returns:
+            `str`: The URL to the current checked-out commit.
+        """
+        sha = self.git_head_hash()
+        url = self.git_remote_url()
+        if url.endswith("/"):
+            url = url[:-1]
+        return f"{url}/commit/{sha}"
+
+    def list_deleted_files(self) -> List[str]:
+        """
+        Returns a list of the files that are deleted in the working directory or
+        index.
+
+        Returns:
+            `List[str]`: A list of files that have been deleted in the working
+            directory or index.
+        """
+        try:
+            git_status = run_subprocess("git status -s", self.local_dir).stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+        if len(git_status) == 0:
+            return []
+
+        # Receives a status like the following
+        #  D .gitignore
+        #  D new_file.json
+        # AD new_file1.json
+        # ?? new_file2.json
+        # ?? new_file4.json
+
+        # Strip each line of whitespaces
+        modified_files_statuses = [status.strip() for status in git_status.split("\n")]
+
+        # Only keep files that are deleted using the D prefix
+        deleted_files_statuses = [status for status in modified_files_statuses if "D" in status.split()[0]]
+
+        # Remove the D prefix and strip to keep only the relevant filename
+        deleted_files = [status.split()[-1].strip() for status in deleted_files_statuses]
+
+        return deleted_files
+
+    def lfs_track(self, patterns: Union[str, List[str]], filename: bool = False):
+        """
+        Tell git-lfs to track files according to a pattern.
+
+        Setting the `filename` argument to `True` will treat the arguments as
+        literal filenames, not as patterns. Any special glob characters in the
+        filename will be escaped when writing to the `.gitattributes` file.
+
+        Args:
+            patterns (`Union[str, List[str]]`):
+                The pattern, or list of patterns, to track with git-lfs.
+            filename (`bool`, *optional*, defaults to `False`):
+                Whether to use the patterns as literal filenames.
+        """
+        if isinstance(patterns, str):
+            patterns = [patterns]
+        try:
+            for pattern in patterns:
+                run_subprocess(
+                    f"git lfs track {'--filename' if filename else ''} {pattern}",
+                    self.local_dir,
+                )
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def lfs_untrack(self, patterns: Union[str, List[str]]):
+        """
+        Tell git-lfs to untrack those files.
+
+        Args:
+            patterns (`Union[str, List[str]]`):
+                The pattern, or list of patterns, to untrack with git-lfs.
+        """
+        if isinstance(patterns, str):
+            patterns = [patterns]
+        try:
+            for pattern in patterns:
+                run_subprocess("git lfs untrack".split() + [pattern], self.local_dir)
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def lfs_enable_largefiles(self):
+        """
+        HF-specific. This enables upload support of files >5GB.
+        """
+        try:
+            lfs_config = "git config lfs.customtransfer.multipart"
+            run_subprocess(f"{lfs_config}.path huggingface-cli", self.local_dir)
+            run_subprocess(
+                f"{lfs_config}.args {LFS_MULTIPART_UPLOAD_COMMAND}",
+                self.local_dir,
+            )
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def auto_track_binary_files(self, pattern: str = ".") -> List[str]:
+        """
+        Automatically track binary files with git-lfs.
+
+        Args:
+            pattern (`str`, *optional*, defaults to "."):
+                The pattern with which to track files that are binary.
+
+        Returns:
+            `List[str]`: List of filenames that are now tracked due to being
+            binary files
+        """
+        files_to_be_tracked_with_lfs = []
+
+        deleted_files = self.list_deleted_files()
+
+        for filename in files_to_be_staged(pattern, folder=self.local_dir):
+            if filename in deleted_files:
+                continue
+
+            path_to_file = os.path.join(os.getcwd(), self.local_dir, filename)
+
+            if not (is_tracked_with_lfs(path_to_file) or is_git_ignored(path_to_file)):
+                size_in_mb = os.path.getsize(path_to_file) / (1024 * 1024)
+
+                if size_in_mb >= 10:
+                    logger.warning(
+                        "Parsing a large file to check if binary or not. Tracking large"
+                        " files using `repository.auto_track_large_files` is"
+                        " recommended so as to not load the full file in memory."
+                    )
+
+                is_binary = is_binary_file(path_to_file)
+
+                if is_binary:
+                    self.lfs_track(filename)
+                    files_to_be_tracked_with_lfs.append(filename)
+
+        # Cleanup the .gitattributes if files were deleted
+        self.lfs_untrack(deleted_files)
+
+        return files_to_be_tracked_with_lfs
+
+    def auto_track_large_files(self, pattern: str = ".") -> List[str]:
+        """
+        Automatically track large files (files that weigh more than 10MBs) with
+        git-lfs.
+
+        Args:
+            pattern (`str`, *optional*, defaults to "."):
+                The pattern with which to track files that are above 10MBs.
+
+        Returns:
+            `List[str]`: List of filenames that are now tracked due to their
+            size.
+        """
+        files_to_be_tracked_with_lfs = []
+
+        deleted_files = self.list_deleted_files()
+
+        for filename in files_to_be_staged(pattern, folder=self.local_dir):
+            if filename in deleted_files:
+                continue
+
+            path_to_file = os.path.join(os.getcwd(), self.local_dir, filename)
+            size_in_mb = os.path.getsize(path_to_file) / (1024 * 1024)
+
+            if size_in_mb >= 10 and not is_tracked_with_lfs(path_to_file) and not is_git_ignored(path_to_file):
+                self.lfs_track(filename)
+                files_to_be_tracked_with_lfs.append(filename)
+
+        # Cleanup the .gitattributes if files were deleted
+        self.lfs_untrack(deleted_files)
+
+        return files_to_be_tracked_with_lfs
+
+    def lfs_prune(self, recent=False):
+        """
+        git lfs prune
+
+        Args:
+            recent (`bool`, *optional*, defaults to `False`):
+                Whether to prune files even if they were referenced by recent
+                commits. See the following
+                [link](https://github.com/git-lfs/git-lfs/blob/f3d43f0428a84fc4f1e5405b76b5a73ec2437e65/docs/man/git-lfs-prune.1.ronn#recent-files)
+                for more information.
+        """
+        try:
+            with _lfs_log_progress():
+                result = run_subprocess(f"git lfs prune {'--recent' if recent else ''}", self.local_dir)
+                logger.info(result.stdout)
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_pull(self, rebase: bool = False, lfs: bool = False):
+        """
+        git pull
+
+        Args:
+            rebase (`bool`, *optional*, defaults to `False`):
+                Whether to rebase the current branch on top of the upstream
+                branch after fetching.
+            lfs (`bool`, *optional*, defaults to `False`):
+                Whether to fetch the LFS files too. This option only changes the
+                behavior when a repository was cloned without fetching the LFS
+                files; calling `repo.git_pull(lfs=True)` will then fetch the LFS
+                file from the remote repository.
+        """
+        command = "git pull" if not lfs else "git lfs pull"
+        if rebase:
+            command += " --rebase"
+        try:
+            with _lfs_log_progress():
+                result = run_subprocess(command, self.local_dir)
+                logger.info(result.stdout)
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_add(self, pattern: str = ".", auto_lfs_track: bool = False):
+        """
+        git add
+
+        Setting the `auto_lfs_track` parameter to `True` will automatically
+        track files that are larger than 10MB with `git-lfs`.
+
+        Args:
+            pattern (`str`, *optional*, defaults to "."):
+                The pattern with which to add files to staging.
+            auto_lfs_track (`bool`, *optional*, defaults to `False`):
+                Whether to automatically track large and binary files with
+                git-lfs. Any file over 10MB in size, or in binary format, will
+                be automatically tracked.
+        """
+        if auto_lfs_track:
+            # Track files according to their size (>=10MB)
+            tracked_files = self.auto_track_large_files(pattern)
+
+            # Read the remaining files and track them if they're binary
+            tracked_files.extend(self.auto_track_binary_files(pattern))
+
+            if tracked_files:
+                logger.warning(
+                    f"Adding files tracked by Git LFS: {tracked_files}. This may take a"
+                    " bit of time if the files are large."
+                )
+
+        try:
+            result = run_subprocess("git add -v".split() + [pattern], self.local_dir)
+            logger.info(f"Adding to index:\n{result.stdout}\n")
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+    def git_commit(self, commit_message: str = "commit files to HF hub"):
+        """
+        git commit
+
+        Args:
+            commit_message (`str`, *optional*, defaults to "commit files to HF hub"):
+                The message attributed to the commit.
+        """
+        try:
+            result = run_subprocess("git commit -v -m".split() + [commit_message], self.local_dir)
+            logger.info(f"Committed:\n{result.stdout}\n")
+        except subprocess.CalledProcessError as exc:
+            if len(exc.stderr) > 0:
+                raise EnvironmentError(exc.stderr)
+            else:
+                raise EnvironmentError(exc.stdout)
+
+    def git_push(
+        self,
+        upstream: Optional[str] = None,
+        blocking: bool = True,
+        auto_lfs_prune: bool = False,
+    ) -> Union[str, Tuple[str, CommandInProgress]]:
+        """
+        git push
+
+        If used without setting `blocking`, will return url to commit on remote
+        repo. If used with `blocking=True`, will return a tuple containing the
+        url to commit and the command object to follow for information about the
+        process.
+
+        Args:
+            upstream (`str`, *optional*):
+                Upstream to which this should push. If not specified, will push
+                to the lastly defined upstream or to the default one (`origin
+                main`).
+            blocking (`bool`, *optional*, defaults to `True`):
+                Whether the function should return only when the push has
+                finished. Setting this to `False` will return an
+                `CommandInProgress` object which has an `is_done` property. This
+                property will be set to `True` when the push is finished.
+            auto_lfs_prune (`bool`, *optional*, defaults to `False`):
+                Whether to automatically prune files once they have been pushed
+                to the remote.
+        """
+        command = "git push"
+
+        if upstream:
+            command += f" --set-upstream {upstream}"
+
+        number_of_commits = commits_to_push(self.local_dir, upstream)
+
+        if number_of_commits > 1:
+            logger.warning(f"Several commits ({number_of_commits}) will be pushed upstream.")
+            if blocking:
+                logger.warning("The progress bars may be unreliable.")
+
+        try:
+            with _lfs_log_progress():
+                process = subprocess.Popen(
+                    command.split(),
+                    stderr=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    encoding="utf-8",
+                    cwd=self.local_dir,
+                )
+
+                if blocking:
+                    stdout, stderr = process.communicate()
+                    return_code = process.poll()
+                    process.kill()
+
+                    if len(stderr):
+                        logger.warning(stderr)
+
+                    if return_code:
+                        raise subprocess.CalledProcessError(return_code, process.args, output=stdout, stderr=stderr)
+
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+        if not blocking:
+
+            def status_method():
+                status = process.poll()
+                if status is None:
+                    return -1
+                else:
+                    return status
+
+            command_in_progress = CommandInProgress(
+                "push",
+                is_done_method=lambda: process.poll() is not None,
+                status_method=status_method,
+                process=process,
+                post_method=self.lfs_prune if auto_lfs_prune else None,
+            )
+
+            self.command_queue.append(command_in_progress)
+
+            return self.git_head_commit_url(), command_in_progress
+
+        if auto_lfs_prune:
+            self.lfs_prune()
+
+        return self.git_head_commit_url()
+
+    def git_checkout(self, revision: str, create_branch_ok: bool = False):
+        """
+        git checkout a given revision
+
+        Specifying `create_branch_ok` to `True` will create the branch to the
+        given revision if that revision doesn't exist.
+
+        Args:
+            revision (`str`):
+                The revision to checkout.
+            create_branch_ok (`str`, *optional*, defaults to `False`):
+                Whether creating a branch named with the `revision` passed at
+                the current checked-out reference if `revision` isn't an
+                existing revision is allowed.
+        """
+        try:
+            result = run_subprocess(f"git checkout {revision}", self.local_dir)
+            logger.warning(f"Checked out {revision} from {self.current_branch}.")
+            logger.warning(result.stdout)
+        except subprocess.CalledProcessError as exc:
+            if not create_branch_ok:
+                raise EnvironmentError(exc.stderr)
+            else:
+                try:
+                    result = run_subprocess(f"git checkout -b {revision}", self.local_dir)
+                    logger.warning(
+                        f"Revision `{revision}` does not exist. Created and checked out branch `{revision}`."
+                    )
+                    logger.warning(result.stdout)
+                except subprocess.CalledProcessError as exc:
+                    raise EnvironmentError(exc.stderr)
+
+    def tag_exists(self, tag_name: str, remote: Optional[str] = None) -> bool:
+        """
+        Check if a tag exists or not.
+
+        Args:
+            tag_name (`str`):
+                The name of the tag to check.
+            remote (`str`, *optional*):
+                Whether to check if the tag exists on a remote. This parameter
+                should be the identifier of the remote.
+
+        Returns:
+            `bool`: Whether the tag exists.
+        """
+        if remote:
+            try:
+                result = run_subprocess(f"git ls-remote origin refs/tags/{tag_name}", self.local_dir).stdout.strip()
+            except subprocess.CalledProcessError as exc:
+                raise EnvironmentError(exc.stderr)
+
+            return len(result) != 0
+        else:
+            try:
+                git_tags = run_subprocess("git tag", self.local_dir).stdout.strip()
+            except subprocess.CalledProcessError as exc:
+                raise EnvironmentError(exc.stderr)
+
+            git_tags = git_tags.split("\n")
+            return tag_name in git_tags
+
+    def delete_tag(self, tag_name: str, remote: Optional[str] = None) -> bool:
+        """
+        Delete a tag, both local and remote, if it exists
+
+        Args:
+            tag_name (`str`):
+                The tag name to delete.
+            remote (`str`, *optional*):
+                The remote on which to delete the tag.
+
+        Returns:
+             `bool`: `True` if deleted, `False` if the tag didn't exist.
+                If remote is not passed, will just be updated locally
+        """
+        delete_locally = True
+        delete_remotely = True
+
+        if not self.tag_exists(tag_name):
+            delete_locally = False
+
+        if not self.tag_exists(tag_name, remote=remote):
+            delete_remotely = False
+
+        if delete_locally:
+            try:
+                run_subprocess(["git", "tag", "-d", tag_name], self.local_dir).stdout.strip()
+            except subprocess.CalledProcessError as exc:
+                raise EnvironmentError(exc.stderr)
+
+        if remote and delete_remotely:
+            try:
+                run_subprocess(f"git push {remote} --delete {tag_name}", self.local_dir).stdout.strip()
+            except subprocess.CalledProcessError as exc:
+                raise EnvironmentError(exc.stderr)
+
+        return True
+
+    def add_tag(self, tag_name: str, message: Optional[str] = None, remote: Optional[str] = None):
+        """
+        Add a tag at the current head and push it
+
+        If remote is None, will just be updated locally
+
+        If no message is provided, the tag will be lightweight. if a message is
+        provided, the tag will be annotated.
+
+        Args:
+            tag_name (`str`):
+                The name of the tag to be added.
+            message (`str`, *optional*):
+                The message that accompanies the tag. The tag will turn into an
+                annotated tag if a message is passed.
+            remote (`str`, *optional*):
+                The remote on which to add the tag.
+        """
+        if message:
+            tag_args = ["git", "tag", "-a", tag_name, "-m", message]
+        else:
+            tag_args = ["git", "tag", tag_name]
+
+        try:
+            run_subprocess(tag_args, self.local_dir).stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+        if remote:
+            try:
+                run_subprocess(f"git push {remote} {tag_name}", self.local_dir).stdout.strip()
+            except subprocess.CalledProcessError as exc:
+                raise EnvironmentError(exc.stderr)
+
+    def is_repo_clean(self) -> bool:
+        """
+        Return whether or not the git status is clean or not
+
+        Returns:
+            `bool`: `True` if the git status is clean, `False` otherwise.
+        """
+        try:
+            git_status = run_subprocess("git status --porcelain", self.local_dir).stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            raise EnvironmentError(exc.stderr)
+
+        return len(git_status) == 0
+
+    def push_to_hub(
+        self,
+        commit_message: str = "commit files to HF hub",
+        blocking: bool = True,
+        clean_ok: bool = True,
+        auto_lfs_prune: bool = False,
+    ) -> Union[None, str, Tuple[str, CommandInProgress]]:
+        """
+        Helper to add, commit, and push files to remote repository on the
+        HuggingFace Hub. Will automatically track large files (>10MB).
+
+        Args:
+            commit_message (`str`):
+                Message to use for the commit.
+            blocking (`bool`, *optional*, defaults to `True`):
+                Whether the function should return only when the `git push` has
+                finished.
+            clean_ok (`bool`, *optional*, defaults to `True`):
+                If True, this function will return None if the repo is
+                untouched. Default behavior is to fail because the git command
+                fails.
+            auto_lfs_prune (`bool`, *optional*, defaults to `False`):
+                Whether to automatically prune files once they have been pushed
+                to the remote.
+        """
+        if clean_ok and self.is_repo_clean():
+            logger.info("Repo currently clean. Ignoring push_to_hub")
+            return None
+        self.git_add(auto_lfs_track=True)
+        self.git_commit(commit_message)
+        return self.git_push(
+            upstream=f"origin {self.current_branch}",
+            blocking=blocking,
+            auto_lfs_prune=auto_lfs_prune,
+        )
+
+    @contextmanager
+    def commit(
+        self,
+        commit_message: str,
+        branch: Optional[str] = None,
+        track_large_files: bool = True,
+        blocking: bool = True,
+        auto_lfs_prune: bool = False,
+    ):
+        """
+        Context manager utility to handle committing to a repository. This
+        automatically tracks large files (>10Mb) with git-lfs. Set the
+        `track_large_files` argument to `False` if you wish to ignore that
+        behavior.
+
+        Args:
+            commit_message (`str`):
+                Message to use for the commit.
+            branch (`str`, *optional*):
+                The branch on which the commit will appear. This branch will be
+                checked-out before any operation.
+            track_large_files (`bool`, *optional*, defaults to `True`):
+                Whether to automatically track large files or not. Will do so by
+                default.
+            blocking (`bool`, *optional*, defaults to `True`):
+                Whether the function should return only when the `git push` has
+                finished.
+            auto_lfs_prune (`bool`, defaults to `True`):
+                Whether to automatically prune files once they have been pushed
+                to the remote.
+
+        Examples:
+
+        ```python
+        >>> with Repository(
+        ...     "text-files",
+        ...     clone_from="<user>/text-files",
+        ...     token=True,
+        >>> ).commit("My first file :)"):
+        ...     with open("file.txt", "w+") as f:
+        ...         f.write(json.dumps({"hey": 8}))
+
+        >>> import torch
+
+        >>> model = torch.nn.Transformer()
+        >>> with Repository(
+        ...     "torch-model",
+        ...     clone_from="<user>/torch-model",
+        ...     token=True,
+        >>> ).commit("My cool model :)"):
+        ...     torch.save(model.state_dict(), "model.pt")
+        ```
+
+        """
+
+        files_to_stage = files_to_be_staged(".", folder=self.local_dir)
+
+        if len(files_to_stage):
+            files_in_msg = str(files_to_stage[:5])[:-1] + ", ...]" if len(files_to_stage) > 5 else str(files_to_stage)
+            logger.error(
+                "There exists some updated files in the local repository that are not"
+                f" committed: {files_in_msg}. This may lead to errors if checking out"
+                " a branch. These files and their modifications will be added to the"
+                " current commit."
+            )
+
+        if branch is not None:
+            self.git_checkout(branch, create_branch_ok=True)
+
+        if is_tracked_upstream(self.local_dir):
+            logger.warning("Pulling changes ...")
+            self.git_pull(rebase=True)
+        else:
+            logger.warning(f"The current branch has no upstream branch. Will push to 'origin {self.current_branch}'")
+
+        current_working_directory = os.getcwd()
+        os.chdir(os.path.join(current_working_directory, self.local_dir))
+
+        try:
+            yield self
+        finally:
+            self.git_add(auto_lfs_track=track_large_files)
+
+            try:
+                self.git_commit(commit_message)
+            except OSError as e:
+                # If no changes are detected, there is nothing to commit.
+                if "nothing to commit" not in str(e):
+                    raise e
+
+            try:
+                self.git_push(
+                    upstream=f"origin {self.current_branch}",
+                    blocking=blocking,
+                    auto_lfs_prune=auto_lfs_prune,
+                )
+            except OSError as e:
+                # If no changes are detected, there is nothing to commit.
+                if "could not read Username" in str(e):
+                    raise OSError("Couldn't authenticate user for push. Did you set `token` to `True`?") from e
+                else:
+                    raise e
+
+            os.chdir(current_working_directory)
+
+    def repocard_metadata_load(self) -> Optional[Dict]:
+        filepath = os.path.join(self.local_dir, REPOCARD_NAME)
+        if os.path.isfile(filepath):
+            return metadata_load(filepath)
+        return None
+
+    def repocard_metadata_save(self, data: Dict) -> None:
+        return metadata_save(os.path.join(self.local_dir, REPOCARD_NAME), data)
+
+    @property
+    def commands_failed(self):
+        """
+        Returns the asynchronous commands that failed.
+        """
+        return [c for c in self.command_queue if c.status > 0]
+
+    @property
+    def commands_in_progress(self):
+        """
+        Returns the asynchronous commands that are currently in progress.
+        """
+        return [c for c in self.command_queue if not c.is_done]
+
+    def wait_for_commands(self):
+        """
+        Blocking method: blocks all subsequent execution until all commands have
+        been processed.
+        """
+        index = 0
+        for command_failed in self.commands_failed:
+            logger.error(f"The {command_failed.title} command with PID {command_failed._process.pid} failed.")
+            logger.error(command_failed.stderr)
+
+        while self.commands_in_progress:
+            if index % 10 == 0:
+                logger.warning(
+                    f"Waiting for the following commands to finish before shutting down: {self.commands_in_progress}."
+                )
+
+            index += 1
+
+            time.sleep(1)