huggingface-hub 0.21.4__py3-none-any.whl → 0.22.0rc0__py3-none-any.whl

huggingface_hub/inference/_generated/types/zero_shot_object_detection.py

@@ -0,0 +1,55 @@
+# Inference code generated from the JSON schema spec in @huggingface/tasks.
+#
+# See:
+#   - script: https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/scripts/inference-codegen.ts
+#   - specs:  https://github.com/huggingface/huggingface.js/tree/main/packages/tasks/src/tasks.
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .base import BaseInferenceType
+
+
+@dataclass
+class ZeroShotObjectDetectionInputData(BaseInferenceType):
+    """The input image data, with candidate labels"""
+
+    candidate_labels: List[str]
+    """The candidate labels for this image"""
+    image: Any
+    """The image data to generate bounding boxes from"""
+
+
+@dataclass
+class ZeroShotObjectDetectionInput(BaseInferenceType):
+    """Inputs for Zero Shot Object Detection inference"""
+
+    inputs: ZeroShotObjectDetectionInputData
+    """The input image data, with candidate labels"""
+    parameters: Optional[Dict[str, Any]] = None
+    """Additional inference parameters"""
+
+
+@dataclass
+class ZeroShotObjectDetectionBoundingBox(BaseInferenceType):
+    """The predicted bounding box. Coordinates are relative to the top left corner of the input
+    image.
+    """
+
+    xmax: int
+    xmin: int
+    ymax: int
+    ymin: int
+
+
+@dataclass
+class ZeroShotObjectDetectionOutputElement(BaseInferenceType):
+    """Outputs of inference for the Zero Shot Object Detection task"""
+
+    box: ZeroShotObjectDetectionBoundingBox
+    """The predicted bounding box. Coordinates are relative to the top left corner of the input
+    image.
+    """
+    label: str
+    """A candidate label"""
+    score: float
+    """The associated score / probability"""

huggingface_hub/inference/_templating.py

@@ -0,0 +1,105 @@
+from functools import lru_cache
+from typing import Callable, Dict, List, Optional, Union
+
+from ..utils import HfHubHTTPError, RepositoryNotFoundError, is_minijinja_available
+
+
+class TemplateError(Exception):
+    """Any error raised while trying to fetch or render a chat template."""
+
+
+def _import_minijinja():
+    if not is_minijinja_available():
+        raise ImportError("Cannot render template. Please install minijinja using `pip install minijinja`.")
+    import minijinja  # noqa: F401
+
+    return minijinja
+
+
+def render_chat_prompt(
+    *,
+    model_id: str,
+    messages: List[Dict[str, str]],
+    token: Union[str, bool, None] = None,
+    add_generation_prompt: bool = True,
+    **kwargs,
+) -> str:
+    """Render a chat prompt using a model's chat template.
+
+    Args:
+        model_id (`str`):
+            The model id.
+        messages (`List[Dict[str, str]]`):
+            The list of messages to render.
+        token (`str` or `bool`, *optional*):
+            Hugging Face token. Will default to the locally saved token if not provided.
+
+    Returns:
+        `str`: The rendered chat prompt.
+
+    Raises:
+        `TemplateError`: If there's any issue while fetching, compiling or rendering the chat template.
+    """
+    minijinja = _import_minijinja()
+    template = _fetch_and_compile_template(model_id=model_id, token=token)
+
+    try:
+        return template(messages=messages, add_generation_prompt=add_generation_prompt, **kwargs)
+    except minijinja.TemplateError as e:
+        raise TemplateError(f"Error while trying to render chat prompt for model '{model_id}': {e}") from e
+
+
+@lru_cache  # TODO: lru_cache for raised exceptions
+def _fetch_and_compile_template(*, model_id: str, token: Union[str, None]) -> Callable:
+    """Fetch and compile a model's chat template.
+
+    Method is cached to avoid fetching the same model's config multiple times.
+
+    Args:
+        model_id (`str`):
+            The model id.
+        token (`str` or `bool`, *optional*):
+            Hugging Face token. Will default to the locally saved token if not provided.
+
+    Returns:
+        `Callable`: A callable that takes a list of messages and returns the rendered chat prompt.
+    """
+    from huggingface_hub.hf_api import HfApi
+
+    minijinja = _import_minijinja()
+
+    # 1. fetch config from API
+    try:
+        config = HfApi(token=token).model_info(model_id).config
+    except RepositoryNotFoundError as e:
+        raise TemplateError(f"Cannot render chat template: model '{model_id}' not found.") from e
+    except HfHubHTTPError as e:
+        raise TemplateError(f"Error while trying to fetch chat template for model '{model_id}': {e}") from e
+
+    # 2. check config validity
+    if config is None:
+        raise TemplateError(f"Config not found for model '{model_id}'.")
+    tokenizer_config = config.get("tokenizer_config")
+    if tokenizer_config is None:
+        raise TemplateError(f"Tokenizer config not found for model '{model_id}'.")
+    if tokenizer_config.get("chat_template") is None:
+        raise TemplateError(f"Chat template not found in tokenizer_config for model '{model_id}'.")
+    chat_template = tokenizer_config["chat_template"]
+    if not isinstance(chat_template, str):
+        raise TemplateError(f"Chat template must be a string, not '{type(chat_template)}' (model: {model_id}).")
+
+    special_tokens: Dict[str, Optional[str]] = {}
+    for key, value in tokenizer_config.items():
+        if "token" in key:
+            if isinstance(value, str):
+                special_tokens[key] = value
+            elif isinstance(value, dict) and value.get("__type") == "AddedToken":
+                special_tokens[key] = value.get("content")
+
+    # 3. compile template and return
+    env = minijinja.Environment()
+    try:
+        env.add_template("chat_template", chat_template)
+    except minijinja.TemplateError as e:
+        raise TemplateError(f"Error while trying to compile chat template for model '{model_id}': {e}") from e
+    return lambda **kwargs: env.render_template("chat_template", **kwargs, **special_tokens)

huggingface_hub/inference/_types.py

@@ -12,42 +12,13 @@
 # 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
 
+from typing import List, TypedDict
 
-if TYPE_CHECKING:
-    from PIL import Image
 
-
-class AudioToAudioOutput(TypedDict):
-    """Dictionary containing the output of a [`~InferenceClient.audio_to_audio`] task.
-
-    Args:
-        label (`str`):
-            The label of the audio file.
-        content-type (`str`):
-            The content type of audio file.
-        blob (`bytes`):
-            The audio file in byte format.
-    """
-
-    label: str
-    content_type: str
-    blob: bytes
-
-
-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
+# Legacy types
+# Types are now generated from the JSON schema spec in @huggingface/tasks.
+# See ./src/huggingface_hub/inference/_generated/types
 
 
 class ConversationalOutputConversation(TypedDict):
@@ -79,122 +50,3 @@ class ConversationalOutput(TypedDict):
     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

huggingface_hub/keras_mixin.py

@@ -2,6 +2,7 @@ import collections.abc as collections
 import json
 import os
 import warnings
+from functools import wraps
 from pathlib import Path
 from shutil import copytree
 from typing import Any, Dict, List, Optional, Union
@@ -18,12 +19,37 @@ from huggingface_hub.utils import (
 from .constants import CONFIG_NAME
 from .hf_api import HfApi
 from .utils import SoftTemporaryDirectory, logging, validate_hf_hub_args
+from .utils._typing import CallableT
 
 
 logger = logging.get_logger(__name__)
 
+keras = None
 if is_tf_available():
-    import tensorflow as tf  # type: ignore
+    # Depending on which version of TensorFlow is installed, we need to import
+    # keras from the correct location.
+    # See https://github.com/tensorflow/tensorflow/releases/tag/v2.16.1.
+    # Note: saving a keras model only works with Keras<3.0.
+    try:
+        import tf_keras as keras  # type: ignore
+    except ImportError:
+        import tensorflow as tf  # type: ignore
+
+        keras = tf.keras
+
+
+def _requires_keras_2_model(fn: CallableT) -> CallableT:
+    # Wrapper to raise if user tries to save a Keras 3.x model
+    @wraps(fn)
+    def _inner(model, *args, **kwargs):
+        if not hasattr(model, "history"):  # hacky way to check if model is Keras 2.x
+            raise NotImplementedError(
+                f"Cannot use '{fn.__name__}': Keras 3.x is not supported."
+                " Please save models manually and upload them using `upload_folder` or `huggingface-cli upload`."
+            )
+        return fn(model, *args, **kwargs)
+
+    return _inner  # type: ignore [return-value]
 
 
 def _flatten_dict(dictionary, parent_key=""):
@@ -57,21 +83,20 @@ def _flatten_dict(dictionary, parent_key=""):
 
 def _create_hyperparameter_table(model):
     """Parse hyperparameter dictionary into a markdown table."""
+    table = None
     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
+        optimizer_params["training_precision"] = 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(
+    keras.utils.plot_model(
         model,
         to_file=f"{save_directory}/model.png",
         show_shapes=False,
@@ -128,6 +153,7 @@ def _create_model_card(
     readme_path.write_text(model_card)
 
 
+@_requires_keras_2_model
 def save_pretrained_keras(
     model,
     save_directory: Union[str, Path],
@@ -162,9 +188,7 @@ def save_pretrained_keras(
             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:
+    if keras is None:
         raise ImportError("Called a Tensorflow-specific function but could not import it.")
 
     if not model.built:
@@ -210,7 +234,7 @@ def save_pretrained_keras(
                 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)
+    keras.models.save_model(model, save_directory, include_optimizer=include_optimizer, **model_save_kwargs)
 
 
 def from_pretrained_keras(*args, **kwargs) -> "KerasModelHubMixin":
@@ -273,6 +297,7 @@ def from_pretrained_keras(*args, **kwargs) -> "KerasModelHubMixin":
 
 
 @validate_hf_hub_args
+@_requires_keras_2_model
 def push_to_hub_keras(
     model,
     repo_id: str,
@@ -444,6 +469,7 @@ class KerasModelHubMixin(ModelHubMixin):
         resume_download,
         local_files_only,
         token,
+        config: Optional[Dict[str, Any]] = None,
         **model_kwargs,
     ):
         """Here we just call [`from_pretrained_keras`] function so both the mixin and
@@ -452,14 +478,9 @@ class KerasModelHubMixin(ModelHubMixin):
                 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:
+        if keras is None:
             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(
@@ -472,9 +493,10 @@ class KerasModelHubMixin(ModelHubMixin):
         else:
             storage_folder = model_id
 
-        model = tf.keras.models.load_model(storage_folder, **model_kwargs)
+        # TODO: change this in a future PR. We are not returning a KerasModelHubMixin instance here...
+        model = keras.models.load_model(storage_folder)
 
         # For now, we add a new attribute, config, to store the config loaded from the hub/a local dir.
-        model.config = cfg
+        model.config = config
 
         return model

huggingface_hub/lfs.py

@@ -13,6 +13,7 @@
 # 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
@@ -27,10 +28,10 @@ from typing import TYPE_CHECKING, BinaryIO, Dict, Iterable, List, Optional, Tupl
 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,
+    get_session,
     hf_raise_for_status,
     http_backoff,
     logging,
@@ -105,6 +106,7 @@ def post_lfs_batch_info(
     repo_id: str,
     revision: Optional[str] = None,
     endpoint: Optional[str] = None,
+    headers: Optional[Dict[str, str]] = None,
 ) -> Tuple[List[dict], List[dict]]:
     """
     Requests the LFS batch endpoint to retrieve upload instructions
@@ -120,10 +122,10 @@ def post_lfs_batch_info(
         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.
+        headers (`dict`, *optional*):
+            Additional headers to include in the request
 
     Returns:
         `LfsBatchInfo`: 2-tuple:
@@ -154,7 +156,12 @@ def post_lfs_batch_info(
     }
     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
+
+    headers = {
+        **LFS_HEADERS,
+        **build_hf_headers(token=token),
+        **(headers or {}),
+    }
     resp = get_session().post(batch_url, headers=headers, json=payload)
     hf_raise_for_status(resp)
     batch_info = resp.json()
@@ -181,7 +188,12 @@ class CompletionPayloadT(TypedDict):
     parts: List[PayloadPartT]
 
 
-def lfs_upload(operation: "CommitOperationAdd", lfs_batch_action: Dict, token: Optional[str]) -> None:
+def lfs_upload(
+    operation: "CommitOperationAdd",
+    lfs_batch_action: Dict,
+    token: Optional[str] = None,
+    headers: Optional[Dict[str, str]] = None,
+) -> None:
     """
     Handles uploading a given object to the Hub with the LFS protocol.
 
@@ -193,8 +205,8 @@ def lfs_upload(operation: "CommitOperationAdd", lfs_batch_action: Dict, token: O
         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
+        headers (`dict`, *optional*):
+            Headers to include in the request, including authentication and user agent headers.
 
     Raises:
         - `ValueError` if `lfs_batch_action` is improperly formatted
@@ -234,7 +246,7 @@ def lfs_upload(operation: "CommitOperationAdd", lfs_batch_action: Dict, token: O
         _validate_lfs_action(verify_action)
         verify_resp = get_session().post(
             verify_action["href"],
-            headers=build_hf_headers(token=token or True),
+            headers=build_hf_headers(token=token, headers=headers),
             json={"oid": operation.upload_info.sha256.hex(), "size": operation.upload_info.size},
         )
         hf_raise_for_status(verify_resp)

huggingface_hub/repocard.py

@@ -294,6 +294,7 @@ class RepoCard:
         cls,
         card_data: CardData,
         template_path: Optional[str] = None,
+        template_str: Optional[str] = None,
         **template_kwargs,
     ):
         """Initialize a RepoCard from a template. By default, it uses the default template.
@@ -322,7 +323,12 @@ class RepoCard:
 
         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())
+
+        if template_path is not None:
+            template_str = Path(template_path).read_text()
+        if template_str is None:
+            template_str = Path(cls.default_template_path).read_text()
+        template = jinja2.Template(template_str)
         content = template.render(card_data=card_data.to_yaml(), **kwargs)
         return cls(content)
 
@@ -337,6 +343,7 @@ class ModelCard(RepoCard):
         cls,
         card_data: ModelCardData,
         template_path: Optional[str] = None,
+        template_str: Optional[str] = None,
         **template_kwargs,
     ):
         """Initialize a ModelCard from a template. By default, it uses the default template, which can be found here:
@@ -404,7 +411,7 @@ class ModelCard(RepoCard):
 
             ```
         """
-        return super().from_template(card_data, template_path, **template_kwargs)
+        return super().from_template(card_data, template_path, template_str, **template_kwargs)
 
 
 class DatasetCard(RepoCard):
@@ -417,6 +424,7 @@ class DatasetCard(RepoCard):
         cls,
         card_data: DatasetCardData,
         template_path: Optional[str] = None,
+        template_str: Optional[str] = None,
         **template_kwargs,
     ):
         """Initialize a DatasetCard from a template. By default, it uses the default template, which can be found here:
@@ -468,7 +476,7 @@ class DatasetCard(RepoCard):
 
             ```
         """
-        return super().from_template(card_data, template_path, **template_kwargs)
+        return super().from_template(card_data, template_path, template_str, **template_kwargs)
 
 
 class SpaceCard(RepoCard):

huggingface_hub/repocard_data.py

@@ -312,7 +312,7 @@ class ModelCardData(CardData):
         self.language = language
         self.license = license
         self.library_name = library_name
-        self.tags = tags
+        self.tags = _to_unique_list(tags)
         self.base_model = base_model
         self.datasets = datasets
         self.metrics = metrics
@@ -507,7 +507,7 @@ class SpaceCardData(CardData):
         self.duplicated_from = duplicated_from
         self.models = models
         self.datasets = datasets
-        self.tags = tags
+        self.tags = _to_unique_list(tags)
         super().__init__(**kwargs)
 
 
@@ -717,3 +717,13 @@ def eval_results_to_model_index(model_name: str, eval_results: List[EvalResult])
         }
     ]
     return _remove_none(model_index)
+
+
+def _to_unique_list(tags: Optional[List[str]]) -> Optional[List[str]]:
+    if tags is None:
+        return tags
+    unique_tags = []  # make tags unique + keep order explicitly
+    for tag in tags:
+        if tag not in unique_tags:
+            unique_tags.append(tag)
+    return unique_tags

huggingface_hub/serialization/__init__.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 # ruff: noqa: F401
 """Contains helpers to serialize tensors."""
+
 from ._base import StateDictSplit, split_state_dict_into_shards_factory
 from ._numpy import split_numpy_state_dict_into_shards
 from ._tensorflow import split_tf_state_dict_into_shards

huggingface_hub/serialization/_base.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Contains helpers to split tensors into shards."""
+
 from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Optional, TypeVar
 

huggingface_hub/serialization/_numpy.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Contains numpy-specific helpers."""
+
 from typing import TYPE_CHECKING, Dict
 
 from ._base import FILENAME_PATTERN, MAX_SHARD_SIZE, StateDictSplit, split_state_dict_into_shards_factory

huggingface_hub/serialization/_tensorflow.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Contains tensorflow-specific helpers."""
+
 import math
 import re
 from typing import TYPE_CHECKING, Dict