improve client.zero_shot_classification()

src/huggingface_hub/inference/_client.py

@@ -2412,7 +2412,13 @@ def visual_question_answering(
         return VisualQuestionAnsweringOutputElement.parse_obj_as_list(response)
 
     def zero_shot_classification(
-        self, text: str, labels: List[str], *, multi_label: bool = False, model: Optional[str] = None
+        self,
+        text: str,
+        labels: List[str],
+        *,
+        multi_label: bool = False,
+        hypothesis_template: Optional[str] = None,
+        model: Optional[str] = None,
     ) -> List[ZeroShotClassificationOutputElement]:
         """
         Provide as input a text and a set of candidate labels to classify the input text.
@@ -2421,9 +2427,15 @@ def zero_shot_classification(
             text (`str`):
                 The input text to classify.
             labels (`List[str]`):
-                List of string possible labels. There must be at least 2 labels.
+                List of strings. Each string is the verbalization of a possible label for the input text.
             multi_label (`bool`):
-                Boolean that is set to True if classes can overlap.
+                Boolean. If True, the probability for each label is evaluated independently and multiple labels can have a probability close to 1 simultaneously or all probabilities can be close to 0.
+                If False, the labels are considered mutually exclusive and the probability over all labels always sums to 1. Defaults to False.
+            hypothesis_template (`str`, *optional*):
+                A template sentence string with curly brackets to which the label strings are added. The label strings are added at the position of the curly brackets "{}".
+                Zero-shot classifiers are based on NLI models, which evaluate if a hypothesis is entailed in another text or not.
+                For example, with hypothesis_template="This text is about {}." and labels=["economics", "politics"], the system internally creates the two hypotheses "This text is about economics." and "This text is about politics.".
+                The model then evaluates for both hypotheses if they are entailed in the provided `text` or not.
             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.
@@ -2437,7 +2449,7 @@ def zero_shot_classification(
             `HTTPError`:
                 If the request fails with an HTTP error status code other than HTTP 503.
 
-        Example:
+        Example with `multi_label=False`:
         ```py
         >>> from huggingface_hub import InferenceClient
         >>> client = InferenceClient()
@@ -2464,21 +2476,37 @@ def zero_shot_classification(
             ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354),
         ]
         ```
+
+        Example with `multi_label=True` and a custom `hypothesis_template`:
+        ```py
+        >>> from huggingface_hub import InferenceClient
+        >>> client = InferenceClient()
+        >>> client.zero_shot_classification(
+        ...    text="I really like our dinner and I'm very happy. I don't like the weather though.",
+        ...    labels=["positive", "negative", "pessimistic", "optimistic"],
+        ...    multi_label=True,
+        ...    hypothesis_template="This text is {} towards the weather"
+        ... )
+        [
+            ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467),
+            ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134),
+            ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062),
+            ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363)
+        ]
+        ```
         """
-        # Raise ValueError if input is less than 2 labels
-        if len(labels) < 2:
-            raise ValueError("You must specify at least 2 classes to compare.")
+
+        parameters = {"candidate_labels": labels, "multi_label": multi_label}
+        if hypothesis_template is not None:
+            parameters["hypothesis_template"] = hypothesis_template
 
         response = self.post(
             json={
                 "inputs": text,
-                "parameters": {
-                    "candidate_labels": ",".join(labels),
-                    "multi_label": multi_label,
-                },
+                "parameters": parameters,
             },
-            model=model,
             task="zero-shot-classification",
+            model=model,
         )
         output = _bytes_to_dict(response)
         return [

src/huggingface_hub/inference/_generated/_async_client.py

@@ -633,7 +633,7 @@ async def chat_completion(
         >>> messages = [
         ...     {
         ...         "role": "system",
-        ...         "content": "Don't make assumptions about what values to plug into functions. Ask async for clarification if a user request is ambiguous.",
+        ...         "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.",
         ...     },
         ...     {
         ...         "role": "user",
@@ -877,7 +877,7 @@ async def conversational(
         >>> 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.']}
+        {'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.']}
         >>> await client.conversational(
         ...     "Wow, that's scary!",
         ...     generated_responses=output["conversation"]["generated_responses"],
@@ -1960,7 +1960,7 @@ async def text_generation(
         >>> 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.
+        # Case 2: iterate over the generated tokens. Useful 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
@@ -2444,7 +2444,13 @@ async def visual_question_answering(
         return VisualQuestionAnsweringOutputElement.parse_obj_as_list(response)
 
     async def zero_shot_classification(
-        self, text: str, labels: List[str], *, multi_label: bool = False, model: Optional[str] = None
+        self,
+        text: str,
+        labels: List[str],
+        *,
+        multi_label: bool = False,
+        hypothesis_template: Optional[str] = None,
+        model: Optional[str] = None,
     ) -> List[ZeroShotClassificationOutputElement]:
         """
         Provide as input a text and a set of candidate labels to classify the input text.
@@ -2453,9 +2459,15 @@ async def zero_shot_classification(
             text (`str`):
                 The input text to classify.
             labels (`List[str]`):
-                List of string possible labels. There must be at least 2 labels.
+                List of strings. Each string is the verbalization of a possible label for the input text.
             multi_label (`bool`):
-                Boolean that is set to True if classes can overlap.
+                Boolean. If True, the probability for each label is evaluated independently and multiple labels can have a probability close to 1 simultaneously or all probabilities can be close to 0.
+                If False, the labels are considered mutually exclusive and the probability over all labels always sums to 1. Defaults to False.
+            hypothesis_template (`str`, *optional*):
+                A template sentence string with curly brackets to which the label strings are added. The label strings are added at the position of the curly brackets "{}".
+                Zero-shot classifiers are based on NLI models, which evaluate if a hypothesis is entailed in another text or not.
+                For example, with hypothesis_template="This text is about {}." and labels=["economics", "politics"], the system internally creates the two hypotheses "This text is about economics." and "This text is about politics.".
+                The model then evaluates for both hypotheses if they are entailed in the provided `text` or not.
             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.
@@ -2469,15 +2481,15 @@ async def zero_shot_classification(
             `aiohttp.ClientResponseError`:
                 If the request fails with an HTTP error status code other than HTTP 503.
 
-        Example:
+        Example with `multi_label=False`:
         ```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"
+        ...     "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 async for a run up a hill in Nice, France."
+        ...     " mysteries when he went for a run up a hill in Nice, France."
         ... )
         >>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"]
         >>> await client.zero_shot_classification(text, labels)
@@ -2497,21 +2509,38 @@ async def zero_shot_classification(
             ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354),
         ]
         ```
+
+        Example with `multi_label=True` and a custom `hypothesis_template`:
+        ```py
+        # Must be run in an async context
+        >>> from huggingface_hub import AsyncInferenceClient
+        >>> client = AsyncInferenceClient()
+        >>> await client.zero_shot_classification(
+        ...    text="I really like our dinner and I'm very happy. I don't like the weather though.",
+        ...    labels=["positive", "negative", "pessimistic", "optimistic"],
+        ...    multi_label=True,
+        ...    hypothesis_template="This text is {} towards the weather"
+        ... )
+        [
+            ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467),
+            ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134),
+            ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062),
+            ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363)
+        ]
+        ```
         """
-        # Raise ValueError if input is less than 2 labels
-        if len(labels) < 2:
-            raise ValueError("You must specify at least 2 classes to compare.")
+
+        parameters = {"candidate_labels": labels, "multi_label": multi_label}
+        if hypothesis_template is not None:
+            parameters["hypothesis_template"] = hypothesis_template
 
         response = await self.post(
             json={
                 "inputs": text,
-                "parameters": {
-                    "candidate_labels": ",".join(labels),
-                    "multi_label": multi_label,
-                },
+                "parameters": parameters,
             },
-            model=model,
             task="zero-shot-classification",
+            model=model,
         )
         output = _bytes_to_dict(response)
         return [

utils/generate_async_inference_client.py

@@ -377,15 +377,15 @@ def _update_example_code_block(code_block: str) -> str:
     code_block = "\n        # Must be run in an async context" + code_block
     code_block = code_block.replace("InferenceClient", "AsyncInferenceClient")
     code_block = code_block.replace("client.", "await client.")
-    code_block = code_block.replace(" for ", " async for ")
+    code_block = code_block.replace(">>> for ", ">>> async for ")
     return code_block
 
 
 def _update_examples_in_public_methods(code: str) -> str:
     for match in re.finditer(
         r"""
         \n\s*
-        Example:\n\s* # example section
+        Example.*?:\n\s* # example section
         ```py # start
         (.*?) # code block
         ``` # end