huggingface-hub 0.27.1__py3-none-any.whl → 0.28.0__py3-none-any.whl

huggingface_hub/inference/_generated/types/__init__.py

@@ -149,6 +149,7 @@ from .text_to_speech import (
     TextToSpeechOutput,
     TextToSpeechParameters,
 )
+from .text_to_video import TextToVideoInput, TextToVideoOutput, TextToVideoParameters
 from .token_classification import (
     TokenClassificationAggregationStrategy,
     TokenClassificationInput,

huggingface_hub/inference/_generated/types/image_to_image.py

@@ -4,7 +4,7 @@
 #   - 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, List, Optional
+from typing import Any, Optional
 
 from .base import BaseInferenceType
 
@@ -25,8 +25,8 @@ class ImageToImageParameters(BaseInferenceType):
     """For diffusion models. A higher guidance scale value encourages the model to generate
     images closely linked to the text prompt at the expense of lower image quality.
     """
-    negative_prompt: Optional[List[str]] = None
-    """One or several prompt to guide what NOT to include in image generation."""
+    negative_prompt: Optional[str] = None
+    """One prompt to guide what NOT to include in image generation."""
     num_inference_steps: Optional[int] = None
     """For diffusion models. The number of denoising steps. More denoising steps usually lead to
     a higher quality image at the expense of slower inference.

huggingface_hub/inference/_generated/types/text_to_audio.py

@@ -97,6 +97,5 @@ class TextToAudioOutput(BaseInferenceType):
 
     audio: Any
     """The generated audio waveform."""
-    sampling_rate: Any
-    text_to_audio_output_sampling_rate: Optional[float] = None
+    sampling_rate: float
     """The sampling rate of the generated audio waveform."""

huggingface_hub/inference/_generated/types/text_to_image.py

@@ -4,7 +4,7 @@
 #   - 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, List, Optional
+from typing import Any, Optional
 
 from .base import BaseInferenceType
 
@@ -25,8 +25,8 @@ class TextToImageParameters(BaseInferenceType):
     """A higher guidance scale value encourages the model to generate images closely linked to
     the text prompt, but values too high may cause saturation and other artifacts.
     """
-    negative_prompt: Optional[List[str]] = None
-    """One or several prompt to guide what NOT to include in image generation."""
+    negative_prompt: Optional[str] = None
+    """One prompt to guide what NOT to include in image generation."""
     num_inference_steps: Optional[int] = None
     """The number of denoising steps. More denoising steps usually lead to a higher quality
     image at the expense of slower inference.

huggingface_hub/inference/_generated/types/text_to_speech.py

@@ -93,12 +93,9 @@ class TextToSpeechInput(BaseInferenceType):
 
 @dataclass
 class TextToSpeechOutput(BaseInferenceType):
-    """Outputs for Text to Speech inference
-    Outputs of inference for the Text To Audio task
-    """
+    """Outputs of inference for the Text To Speech task"""
 
     audio: Any
-    """The generated audio waveform."""
-    sampling_rate: Any
-    text_to_speech_output_sampling_rate: Optional[float] = None
+    """The generated audio"""
+    sampling_rate: Optional[float] = None
     """The sampling rate of the generated audio waveform."""

huggingface_hub/inference/_generated/types/text_to_video.py

@@ -0,0 +1,47 @@
+# 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, List, Optional
+
+from .base import BaseInferenceType
+
+
+@dataclass
+class TextToVideoParameters(BaseInferenceType):
+    """Additional inference parameters for Text To Video"""
+
+    guidance_scale: Optional[float] = None
+    """A higher guidance scale value encourages the model to generate videos closely linked to
+    the text prompt, but values too high may cause saturation and other artifacts.
+    """
+    negative_prompt: Optional[List[str]] = None
+    """One or several prompt to guide what NOT to include in video generation."""
+    num_frames: Optional[float] = None
+    """The num_frames parameter determines how many video frames are generated."""
+    num_inference_steps: Optional[int] = None
+    """The number of denoising steps. More denoising steps usually lead to a higher quality
+    video at the expense of slower inference.
+    """
+    seed: Optional[int] = None
+    """Seed for the random number generator."""
+
+
+@dataclass
+class TextToVideoInput(BaseInferenceType):
+    """Inputs for Text To Video inference"""
+
+    inputs: str
+    """The input text data (sometimes called "prompt")"""
+    parameters: Optional[TextToVideoParameters] = None
+    """Additional inference parameters for Text To Video"""
+
+
+@dataclass
+class TextToVideoOutput(BaseInferenceType):
+    """Outputs of inference for the Text To Video task"""
+
+    video: Any
+    """The generated video returned as raw bytes in the payload."""

huggingface_hub/inference/_generated/types/visual_question_answering.py

@@ -15,7 +15,7 @@ class VisualQuestionAnsweringInputData(BaseInferenceType):
 
     image: Any
     """The image."""
-    question: Any
+    question: str
     """The question to answer based on the image."""
 
 

huggingface_hub/inference/_providers/__init__.py

@@ -0,0 +1,89 @@
+from typing import Dict, Literal
+
+from .._common import TaskProviderHelper
+from .fal_ai import FalAIAutomaticSpeechRecognitionTask, FalAITextToImageTask, FalAITextToVideoTask
+from .hf_inference import HFInferenceBinaryInputTask, HFInferenceConversational, HFInferenceTask
+from .replicate import ReplicateTask, ReplicateTextToSpeechTask
+from .sambanova import SambanovaConversationalTask
+from .together import TogetherTextGenerationTask, TogetherTextToImageTask
+
+
+PROVIDER_T = Literal[
+    "fal-ai",
+    "hf-inference",
+    "replicate",
+    "sambanova",
+    "together",
+]
+
+PROVIDERS: Dict[PROVIDER_T, Dict[str, TaskProviderHelper]] = {
+    "fal-ai": {
+        "text-to-image": FalAITextToImageTask(),
+        "automatic-speech-recognition": FalAIAutomaticSpeechRecognitionTask(),
+        "text-to-video": FalAITextToVideoTask(),
+    },
+    "hf-inference": {
+        "text-to-image": HFInferenceTask("text-to-image"),
+        "conversational": HFInferenceConversational(),
+        "text-generation": HFInferenceTask("text-generation"),
+        "text-classification": HFInferenceTask("text-classification"),
+        "question-answering": HFInferenceTask("question-answering"),
+        "audio-classification": HFInferenceBinaryInputTask("audio-classification"),
+        "automatic-speech-recognition": HFInferenceBinaryInputTask("automatic-speech-recognition"),
+        "fill-mask": HFInferenceTask("fill-mask"),
+        "feature-extraction": HFInferenceTask("feature-extraction"),
+        "image-classification": HFInferenceBinaryInputTask("image-classification"),
+        "image-segmentation": HFInferenceBinaryInputTask("image-segmentation"),
+        "document-question-answering": HFInferenceTask("document-question-answering"),
+        "image-to-text": HFInferenceTask("image-to-text"),
+        "object-detection": HFInferenceBinaryInputTask("object-detection"),
+        "audio-to-audio": HFInferenceTask("audio-to-audio"),
+        "zero-shot-image-classification": HFInferenceBinaryInputTask("zero-shot-image-classification"),
+        "zero-shot-classification": HFInferenceTask("zero-shot-classification"),
+        "image-to-image": HFInferenceBinaryInputTask("image-to-image"),
+        "sentence-similarity": HFInferenceTask("sentence-similarity"),
+        "table-question-answering": HFInferenceTask("table-question-answering"),
+        "tabular-classification": HFInferenceTask("tabular-classification"),
+        "text-to-speech": HFInferenceTask("text-to-speech"),
+        "token-classification": HFInferenceTask("token-classification"),
+        "translation": HFInferenceTask("translation"),
+        "summarization": HFInferenceTask("summarization"),
+        "visual-question-answering": HFInferenceBinaryInputTask("visual-question-answering"),
+    },
+    "replicate": {
+        "text-to-image": ReplicateTask("text-to-image"),
+        "text-to-speech": ReplicateTextToSpeechTask(),
+        "text-to-video": ReplicateTask("text-to-video"),
+    },
+    "sambanova": {
+        "conversational": SambanovaConversationalTask(),
+    },
+    "together": {
+        "text-to-image": TogetherTextToImageTask(),
+        "conversational": TogetherTextGenerationTask("conversational"),
+        "text-generation": TogetherTextGenerationTask("text-generation"),
+    },
+}
+
+
+def get_provider_helper(provider: PROVIDER_T, task: str) -> TaskProviderHelper:
+    """Get provider helper instance by name and task.
+
+    Args:
+        provider (str): Name of the provider
+        task (str): Name of the task
+
+    Returns:
+        TaskProviderHelper: Helper instance for the specified provider and task
+
+    Raises:
+        ValueError: If provider or task is not supported
+    """
+    if provider not in PROVIDERS:
+        raise ValueError(f"Provider '{provider}' not supported. Available providers: {list(PROVIDERS.keys())}")
+    if task not in PROVIDERS[provider]:
+        raise ValueError(
+            f"Task '{task}' not supported for provider '{provider}'. "
+            f"Available tasks: {list(PROVIDERS[provider].keys())}"
+        )
+    return PROVIDERS[provider][task]

huggingface_hub/inference/_providers/fal_ai.py

@@ -0,0 +1,159 @@
+import base64
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Union
+
+from huggingface_hub import constants
+from huggingface_hub.inference._common import RequestParameters, TaskProviderHelper, _as_dict
+from huggingface_hub.utils import build_hf_headers, get_session, get_token, logging
+
+
+logger = logging.get_logger(__name__)
+
+
+BASE_URL = "https://fal.run"
+
+SUPPORTED_MODELS = {
+    "automatic-speech-recognition": {
+        "openai/whisper-large-v3": "fal-ai/whisper",
+    },
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-schnell": "fal-ai/flux/schnell",
+        "black-forest-labs/FLUX.1-dev": "fal-ai/flux/dev",
+        "playgroundai/playground-v2.5-1024px-aesthetic": "fal-ai/playground-v25",
+        "ByteDance/SDXL-Lightning": "fal-ai/lightning-models",
+        "PixArt-alpha/PixArt-Sigma-XL-2-1024-MS": "fal-ai/pixart-sigma",
+        "stabilityai/stable-diffusion-3-medium": "fal-ai/stable-diffusion-v3-medium",
+        "Warlord-K/Sana-1024": "fal-ai/sana",
+        "fal/AuraFlow-v0.2": "fal-ai/aura-flow",
+        "stabilityai/stable-diffusion-3.5-large": "fal-ai/stable-diffusion-v35-large",
+        "Kwai-Kolors/Kolors": "fal-ai/kolors",
+    },
+    "text-to-video": {
+        "genmo/mochi-1-preview": "fal-ai/mochi-v1",
+        "tencent/HunyuanVideo": "fal-ai/hunyuan-video",
+    },
+}
+
+
+class FalAITask(TaskProviderHelper, ABC):
+    """Base class for FalAI API tasks."""
+
+    def __init__(self, task: str):
+        self.task = task
+
+    def prepare_request(
+        self,
+        *,
+        inputs: Any,
+        parameters: Dict[str, Any],
+        headers: Dict,
+        model: Optional[str],
+        api_key: Optional[str],
+        extra_payload: Optional[Dict[str, Any]] = None,
+    ) -> RequestParameters:
+        if api_key is None:
+            api_key = get_token()
+        if api_key is None:
+            raise ValueError(
+                "You must provide an api_key to work with fal.ai API or log in with `huggingface-cli login`."
+            )
+
+        mapped_model = self._map_model(model)
+        headers = {
+            **build_hf_headers(token=api_key),
+            **headers,
+        }
+
+        # Route to the proxy if the api_key is a HF TOKEN
+        if api_key.startswith("hf_"):
+            base_url = constants.INFERENCE_PROXY_TEMPLATE.format(provider="fal-ai")
+            logger.info("Calling fal.ai provider through Hugging Face proxy.")
+        else:
+            base_url = BASE_URL
+            headers["authorization"] = f"Key {api_key}"
+            logger.info("Calling fal.ai provider directly.")
+
+        payload = self._prepare_payload(inputs, parameters=parameters)
+
+        return RequestParameters(
+            url=f"{base_url}/{mapped_model}",
+            task=self.task,
+            model=mapped_model,
+            json=payload,
+            data=None,
+            headers=headers,
+        )
+
+    def _map_model(self, model: Optional[str]) -> str:
+        if model is None:
+            raise ValueError("Please provide a model available on FalAI.")
+        if self.task not in SUPPORTED_MODELS:
+            raise ValueError(f"Task {self.task} not supported with FalAI.")
+        mapped_model = SUPPORTED_MODELS[self.task].get(model)
+        if mapped_model is None:
+            raise ValueError(f"Model {model} is not supported with FalAI for task {self.task}.")
+        return mapped_model
+
+    @abstractmethod
+    def _prepare_payload(self, inputs: Any, parameters: Dict[str, Any]) -> Dict[str, Any]: ...
+
+
+class FalAIAutomaticSpeechRecognitionTask(FalAITask):
+    def __init__(self):
+        super().__init__("automatic-speech-recognition")
+
+    def _prepare_payload(self, inputs: Any, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        if isinstance(inputs, str) and inputs.startswith(("http://", "https://")):
+            # If input is a URL, pass it directly
+            audio_url = inputs
+        else:
+            # If input is a file path, read it first
+            if isinstance(inputs, str):
+                with open(inputs, "rb") as f:
+                    inputs = f.read()
+
+            audio_b64 = base64.b64encode(inputs).decode()
+            content_type = "audio/mpeg"
+            audio_url = f"data:{content_type};base64,{audio_b64}"
+
+        return {
+            "audio_url": audio_url,
+            **{k: v for k, v in parameters.items() if v is not None},
+        }
+
+    def get_response(self, response: Union[bytes, Dict]) -> Any:
+        text = _as_dict(response)["text"]
+        if not isinstance(text, str):
+            raise ValueError(f"Unexpected output format from FalAI API. Expected string, got {type(text)}.")
+        return text
+
+
+class FalAITextToImageTask(FalAITask):
+    def __init__(self):
+        super().__init__("text-to-image")
+
+    def _prepare_payload(self, inputs: Any, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        parameters = {k: v for k, v in parameters.items() if v is not None}
+        if "image_size" not in parameters and "width" in parameters and "height" in parameters:
+            parameters["image_size"] = {
+                "width": parameters.pop("width"),
+                "height": parameters.pop("height"),
+            }
+        return {"prompt": inputs, **parameters}
+
+    def get_response(self, response: Union[bytes, Dict]) -> Any:
+        url = _as_dict(response)["images"][0]["url"]
+        return get_session().get(url).content
+
+
+class FalAITextToVideoTask(FalAITask):
+    def __init__(self):
+        super().__init__("text-to-video")
+
+    def _prepare_payload(self, inputs: Any, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        parameters = {k: v for k, v in parameters.items() if v is not None}
+        return {"prompt": inputs, **parameters}
+
+    def get_response(self, response: Union[bytes, Dict]) -> Any:
+        url = _as_dict(response)["video"]["url"]
+        return get_session().get(url).content

huggingface_hub/inference/_providers/hf_inference.py

@@ -0,0 +1,202 @@
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from huggingface_hub.constants import ENDPOINT
+from huggingface_hub.inference._common import RequestParameters, TaskProviderHelper, _b64_encode, _open_as_binary
+from huggingface_hub.utils import build_hf_headers, get_session, hf_raise_for_status
+
+
+## RECOMMENDED MODELS
+
+# Will be globally fetched only once (see '_fetch_recommended_models')
+_RECOMMENDED_MODELS: Optional[Dict[str, Optional[str]]] = None
+
+BASE_URL = "https://api-inference.huggingface.co"
+
+
+def _first_or_none(items: List[Any]) -> Optional[Any]:
+    try:
+        return items[0] or None
+    except IndexError:
+        return 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 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
+
+
+class HFInferenceTask(TaskProviderHelper):
+    """Base class for HF Inference API tasks."""
+
+    def __init__(self, task: str):
+        self.task = task
+
+    def prepare_request(
+        self,
+        *,
+        inputs: Any,
+        parameters: Dict[str, Any],
+        headers: Dict,
+        model: Optional[str],
+        api_key: Optional[str],
+        extra_payload: Optional[Dict[str, Any]] = None,
+    ) -> RequestParameters:
+        if extra_payload is None:
+            extra_payload = {}
+        mapped_model = self.map_model(model)
+        url = self.build_url(mapped_model)
+        data, json = self._prepare_payload(inputs, parameters=parameters, model=model, extra_payload=extra_payload)
+        headers = self.prepare_headers(headers=headers, api_key=api_key)
+
+        return RequestParameters(
+            url=url,
+            task=self.task,
+            model=mapped_model,
+            json=json,
+            data=data,
+            headers=headers,
+        )
+
+    def map_model(self, model: Optional[str]) -> str:
+        return model if model is not None else get_recommended_model(self.task)
+
+    def build_url(self, model: str) -> str:
+        # hf-inference provider can handle URLs (e.g. Inference Endpoints or TGI deployment)
+        if model.startswith(("http://", "https://")):
+            return model
+
+        return (
+            # Feature-extraction and sentence-similarity are the only cases where we handle models with several tasks.
+            f"{BASE_URL}/pipeline/{self.task}/{model}"
+            if self.task in ("feature-extraction", "sentence-similarity")
+            # Otherwise, we use the default endpoint
+            else f"{BASE_URL}/models/{model}"
+        )
+
+    def prepare_headers(self, headers: Dict, *, api_key: Optional[Union[bool, str]] = None) -> Dict:
+        return {**build_hf_headers(token=api_key), **headers}
+
+    def _prepare_payload(
+        self, inputs: Any, parameters: Dict[str, Any], model: Optional[str], extra_payload: Dict[str, Any]
+    ) -> Tuple[Any, Any]:
+        if isinstance(inputs, bytes):
+            raise ValueError(f"Unexpected binary input for task {self.task}.")
+        if isinstance(inputs, Path):
+            raise ValueError(f"Unexpected path input for task {self.task} (got {inputs})")
+        return None, {
+            "inputs": inputs,
+            "parameters": {k: v for k, v in parameters.items() if v is not None},
+            **extra_payload,
+        }
+
+    def get_response(self, response: Union[bytes, Dict]) -> Any:
+        return response
+
+
+class HFInferenceBinaryInputTask(HFInferenceTask):
+    def _prepare_payload(
+        self, inputs: Any, parameters: Dict[str, Any], model: Optional[str], extra_payload: Dict[str, Any]
+    ) -> Tuple[Any, Any]:
+        parameters = {k: v for k, v in parameters.items() if v is not None}
+        has_parameters = len(parameters) > 0 or len(extra_payload) > 0
+
+        # Raise if not a binary object or a local path or a URL.
+        if not isinstance(inputs, (bytes, Path)) and not isinstance(inputs, str):
+            raise ValueError(f"Expected binary inputs or a local path or a URL. Got {inputs}")
+
+        # Send inputs as raw content when no parameters are provided
+        if not has_parameters:
+            with _open_as_binary(inputs) as data:
+                data_as_bytes = data if isinstance(data, bytes) else data.read()
+                return data_as_bytes, None
+
+        # Otherwise encode as b64
+        return None, {"inputs": _b64_encode(inputs), "parameters": parameters, **extra_payload}
+
+
+class HFInferenceConversational(HFInferenceTask):
+    def __init__(self):
+        super().__init__("text-generation")
+
+    def prepare_request(
+        self,
+        *,
+        inputs: Any,
+        parameters: Dict[str, Any],
+        headers: Dict,
+        model: Optional[str],
+        api_key: Optional[str],
+        extra_payload: Optional[Dict[str, Any]] = None,
+    ) -> RequestParameters:
+        model = self.map_model(model)
+        payload_model = parameters.get("model") or model
+
+        if payload_model is None or payload_model.startswith(("http://", "https://")):
+            payload_model = "tgi"  # use a random string if not provided
+
+        json = {
+            **{key: value for key, value in parameters.items() if value is not None},
+            "model": payload_model,
+            "messages": inputs,
+            **(extra_payload or {}),
+        }
+        headers = self.prepare_headers(headers=headers, api_key=api_key)
+
+        return RequestParameters(
+            url=self.build_url(model),
+            task=self.task,
+            model=model,
+            json=json,
+            data=None,
+            headers=headers,
+        )
+
+    def build_url(self, model: str) -> str:
+        base_url = model if model.startswith(("http://", "https://")) else f"{BASE_URL}/models/{model}"
+        return _build_chat_completion_url(base_url)
+
+
+def _build_chat_completion_url(model_url: str) -> str:
+    # Strip trailing /
+    model_url = model_url.rstrip("/")
+
+    # Append /chat/completions if not already present
+    if model_url.endswith("/v1"):
+        model_url += "/chat/completions"
+
+    # Append /v1/chat/completions if not already present
+    if not model_url.endswith("/chat/completions"):
+        model_url += "/v1/chat/completions"
+
+    return model_url