huggingface-hub 0.28.0rc5__py3-none-any.whl → 0.29.0rc0__py3-none-any.whl

huggingface_hub/inference/_providers/fal_ai.py

@@ -1,108 +1,31 @@
 import base64
-from abc import ABC, abstractmethod
+from abc import ABC
 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",
-    },
-}
+from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._providers._common import TaskProviderHelper, filter_none
+from huggingface_hub.utils import get_session
 
 
 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,
-        )
+        super().__init__(provider="fal-ai", base_url="https://fal.run", task=task)
 
-    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
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        headers = super()._prepare_headers(headers, api_key)
+        if not api_key.startswith("hf_"):
+            headers["authorization"] = f"Key {api_key}"
+        return headers
 
-    @abstractmethod
-    def _prepare_payload(self, inputs: Any, parameters: Dict[str, Any]) -> Dict[str, Any]: ...
+    def _prepare_route(self, mapped_model: str) -> str:
+        return f"/{mapped_model}"
 
 
 class FalAIAutomaticSpeechRecognitionTask(FalAITask):
     def __init__(self):
         super().__init__("automatic-speech-recognition")
 
-    def _prepare_payload(self, inputs: Any, parameters: Dict[str, Any]) -> Dict[str, Any]:
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
         if isinstance(inputs, str) and inputs.startswith(("http://", "https://")):
             # If input is a URL, pass it directly
             audio_url = inputs
@@ -116,10 +39,7 @@ class FalAIAutomaticSpeechRecognitionTask(FalAITask):
             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},
-        }
+        return {"audio_url": audio_url, **filter_none(parameters)}
 
     def get_response(self, response: Union[bytes, Dict]) -> Any:
         text = _as_dict(response)["text"]
@@ -132,9 +52,9 @@ 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:
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        parameters = filter_none(parameters)
+        if "width" in parameters and "height" in parameters:
             parameters["image_size"] = {
                 "width": parameters.pop("width"),
                 "height": parameters.pop("height"),
@@ -146,13 +66,24 @@ class FalAITextToImageTask(FalAITask):
         return get_session().get(url).content
 
 
+class FalAITextToSpeechTask(FalAITask):
+    def __init__(self):
+        super().__init__("text-to-speech")
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        return {"lyrics": inputs, **filter_none(parameters)}
+
+    def get_response(self, response: Union[bytes, Dict]) -> Any:
+        url = _as_dict(response)["audio"]["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 _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        return {"prompt": inputs, **filter_none(parameters)}
 
     def get_response(self, response: Union[bytes, Dict]) -> Any:
         url = _as_dict(response)["video"]["url"]

huggingface_hub/inference/_providers/fireworks_ai.py

@@ -0,0 +1,6 @@
+from ._common import BaseConversationalTask
+
+
+class FireworksAIConversationalTask(BaseConversationalTask):
+    def __init__(self):
+        super().__init__(provider="fireworks-ai", base_url="https://api.fireworks.ai/inference")

huggingface_hub/inference/_providers/hf_inference.py

@@ -1,134 +1,68 @@
+import json
+from functools import lru_cache
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, Optional
 
-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
+from huggingface_hub import constants
+from huggingface_hub.inference._common import _b64_encode, _open_as_binary
+from huggingface_hub.inference._providers._common import TaskProviderHelper, filter_none
+from huggingface_hub.utils import build_hf_headers, get_session, get_token, hf_raise_for_status
 
 
 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,
+        super().__init__(
+            provider="hf-inference",
+            base_url=constants.INFERENCE_PROXY_TEMPLATE.format(provider="hf-inference"),
+            task=task,
         )
 
-    def map_model(self, model: Optional[str]) -> str:
-        return model if model is not None else get_recommended_model(self.task)
+    def _prepare_api_key(self, api_key: Optional[str]) -> str:
+        # special case: for HF Inference we allow not providing an API key
+        return api_key or get_token()  # type: ignore[return-value]
 
-    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://")):
+    def _prepare_mapped_model(self, model: Optional[str]) -> str:
+        if model is not None:
             return model
-
+        model = _fetch_recommended_models().get(self.task)
+        if model is None:
+            raise ValueError(
+                f"Task {self.task} has no recommended model for HF Inference. Please specify a model"
+                " explicitly. Visit https://huggingface.co/tasks for more info."
+            )
+        return model
+
+    def _prepare_url(self, api_key: str, mapped_model: str) -> str:
+        # hf-inference provider can handle URLs (e.g. Inference Endpoints or TGI deployment)
+        if mapped_model.startswith(("http://", "https://")):
+            return mapped_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}"
+            f"{self.base_url}/pipeline/{self.task}/{mapped_model}"
             if self.task in ("feature-extraction", "sentence-similarity")
             # Otherwise, we use the default endpoint
-            else f"{BASE_URL}/models/{model}"
+            else f"{self.base_url}/models/{mapped_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]:
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
         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
+        return {"inputs": inputs, "parameters": filter_none(parameters)}
 
 
 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}
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        return None
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        parameters = filter_none({k: v for k, v in parameters.items() if v is not None})
+        extra_payload = extra_payload or {}
         has_parameters = len(parameters) > 0 or len(extra_payload) > 0
 
         # Raise if not a binary object or a local path or a URL.
@@ -139,51 +73,26 @@ class HFInferenceBinaryInputTask(HFInferenceTask):
         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
+                return data_as_bytes
 
         # Otherwise encode as b64
-        return None, {"inputs": _b64_encode(inputs), "parameters": parameters, **extra_payload}
+        return json.dumps({"inputs": _b64_encode(inputs), "parameters": parameters, **extra_payload}).encode("utf-8")
 
 
 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 _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        payload_model = "tgi" if mapped_model.startswith(("http://", "https://")) else mapped_model
+        return {**filter_none(parameters), "model": payload_model, "messages": inputs}
 
-    def build_url(self, model: str) -> str:
-        base_url = model if model.startswith(("http://", "https://")) else f"{BASE_URL}/models/{model}"
+    def _prepare_url(self, api_key: str, mapped_model: str) -> str:
+        base_url = (
+            mapped_model
+            if mapped_model.startswith(("http://", "https://"))
+            else f"{constants.INFERENCE_PROXY_TEMPLATE.format(provider='hf-inference')}/models/{mapped_model}"
+        )
         return _build_chat_completion_url(base_url)
 
 
@@ -200,3 +109,10 @@ def _build_chat_completion_url(model_url: str) -> str:
         model_url += "/v1/chat/completions"
 
     return model_url
+
+
+@lru_cache(maxsize=1)
+def _fetch_recommended_models() -> Dict[str, Optional[str]]:
+    response = get_session().get(f"{constants.ENDPOINT}/api/tasks", headers=build_hf_headers())
+    hf_raise_for_status(response)
+    return {task: next(iter(details["widgetModels"]), None) for task, details in response.json().items()}

huggingface_hub/inference/_providers/hyperbolic.py

@@ -0,0 +1,43 @@
+import base64
+from typing import Any, Dict, Optional, Union
+
+from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._providers._common import BaseConversationalTask, TaskProviderHelper, filter_none
+
+
+class HyperbolicTextToImageTask(TaskProviderHelper):
+    def __init__(self):
+        super().__init__(provider="hyperbolic", base_url="https://api.hyperbolic.xyz", task="text-to-image")
+
+    def _prepare_route(self, mapped_model: str) -> str:
+        return "/v1/images/generations"
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        parameters = filter_none(parameters)
+        if "num_inference_steps" in parameters:
+            parameters["steps"] = parameters.pop("num_inference_steps")
+        if "guidance_scale" in parameters:
+            parameters["cfg_scale"] = parameters.pop("guidance_scale")
+        # For Hyperbolic, the width and height are required parameters
+        if "width" not in parameters:
+            parameters["width"] = 512
+        if "height" not in parameters:
+            parameters["height"] = 512
+        return {"prompt": inputs, "model_name": mapped_model, **parameters}
+
+    def get_response(self, response: Union[bytes, Dict]) -> Any:
+        response_dict = _as_dict(response)
+        return base64.b64decode(response_dict["images"][0]["image"])
+
+
+class HyperbolicTextGenerationTask(BaseConversationalTask):
+    """
+    Special case for Hyperbolic, where text-generation task is handled as a conversational task.
+    """
+
+    def __init__(self, task: str):
+        super().__init__(
+            provider="hyperbolic",
+            base_url="https://api.hyperbolic.xyz",
+        )
+        self.task = task

huggingface_hub/inference/_providers/nebius.py

@@ -0,0 +1,41 @@
+import base64
+from typing import Any, Dict, Optional, Union
+
+from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._providers._common import (
+    BaseConversationalTask,
+    BaseTextGenerationTask,
+    TaskProviderHelper,
+    filter_none,
+)
+
+
+class NebiusTextGenerationTask(BaseTextGenerationTask):
+    def __init__(self):
+        super().__init__(provider="nebius", base_url="https://api.studio.nebius.ai")
+
+
+class NebiusConversationalTask(BaseConversationalTask):
+    def __init__(self):
+        super().__init__(provider="nebius", base_url="https://api.studio.nebius.ai")
+
+
+class NebiusTextToImageTask(TaskProviderHelper):
+    def __init__(self):
+        super().__init__(task="text-to-image", provider="nebius", base_url="https://api.studio.nebius.ai")
+
+    def _prepare_route(self, mapped_model: str) -> str:
+        return "/v1/images/generations"
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        parameters = filter_none(parameters)
+        if "guidance_scale" in parameters:
+            parameters.pop("guidance_scale")
+        if parameters.get("response_format") not in ("b64_json", "url"):
+            parameters["response_format"] = "b64_json"
+
+        return {"prompt": inputs, **parameters, "model": mapped_model}
+
+    def get_response(self, response: Union[bytes, Dict]) -> Any:
+        response_dict = _as_dict(response)
+        return base64.b64decode(response_dict["data"][0]["b64_json"])

huggingface_hub/inference/_providers/novita.py

@@ -0,0 +1,26 @@
+from huggingface_hub.inference._providers._common import (
+    BaseConversationalTask,
+    BaseTextGenerationTask,
+)
+
+
+_PROVIDER = "novita"
+_BASE_URL = "https://api.novita.ai/v3/openai"
+
+
+class NovitaTextGenerationTask(BaseTextGenerationTask):
+    def __init__(self):
+        super().__init__(provider=_PROVIDER, base_url=_BASE_URL)
+
+    def _prepare_route(self, mapped_model: str) -> str:
+        # there is no v1/ route for novita
+        return "/completions"
+
+
+class NovitaConversationalTask(BaseConversationalTask):
+    def __init__(self):
+        super().__init__(provider=_PROVIDER, base_url=_BASE_URL)
+
+    def _prepare_route(self, mapped_model: str) -> str:
+        # there is no v1/ route for novita
+        return "/chat/completions"