huggingface-hub 0.29.3rc0__py3-none-any.whl → 0.30.0rc0__py3-none-any.whl

huggingface_hub/inference/_providers/_common.py

@@ -84,7 +84,11 @@ class TaskProviderHelper:
             raise ValueError("Either payload or data must be set in the request.")
         return RequestParameters(url=url, task=self.task, model=mapped_model, json=payload, data=data, headers=headers)
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
         """
         Return the response in the expected format.
 
@@ -142,7 +146,7 @@ class TaskProviderHelper:
 
         Usually not overwritten in subclasses."""
         base_url = self._prepare_base_url(api_key)
-        route = self._prepare_route(mapped_model)
+        route = self._prepare_route(mapped_model, api_key)
         return f"{base_url.rstrip('/')}/{route.lstrip('/')}"
 
     def _prepare_base_url(self, api_key: str) -> str:
@@ -157,7 +161,7 @@ class TaskProviderHelper:
             logger.info(f"Calling '{self.provider}' provider directly.")
             return self.base_url
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         """Return the route to use for the request.
 
         Override this method in subclasses for customized routes.
@@ -192,7 +196,7 @@ class BaseConversationalTask(TaskProviderHelper):
     def __init__(self, provider: str, base_url: str):
         super().__init__(provider=provider, base_url=base_url, task="conversational")
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         return "/v1/chat/completions"
 
     def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
@@ -208,7 +212,7 @@ class BaseTextGenerationTask(TaskProviderHelper):
     def __init__(self, provider: str, base_url: str):
         super().__init__(provider=provider, base_url=base_url, task="text-generation")
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         return "/v1/completions"
 
     def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:

huggingface_hub/inference/_providers/black_forest_labs.py

@@ -1,7 +1,7 @@
 import time
 from typing import Any, Dict, Optional, Union
 
-from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._common import RequestParameters, _as_dict
 from huggingface_hub.inference._providers._common import TaskProviderHelper, filter_none
 from huggingface_hub.utils import logging
 from huggingface_hub.utils._http import get_session
@@ -15,7 +15,7 @@ POLLING_INTERVAL = 1.0
 
 class BlackForestLabsTextToImageTask(TaskProviderHelper):
     def __init__(self):
-        super().__init__(provider="black-forest-labs", base_url="https://api.us1.bfl.ai/v1", task="text-to-image")
+        super().__init__(provider="black-forest-labs", base_url="https://api.us1.bfl.ai", task="text-to-image")
 
     def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
         headers = super()._prepare_headers(headers, api_key)
@@ -24,8 +24,8 @@ class BlackForestLabsTextToImageTask(TaskProviderHelper):
             headers["X-Key"] = api_key
         return headers
 
-    def _prepare_route(self, mapped_model: str) -> str:
-        return mapped_model
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        return f"/v1/{mapped_model}"
 
     def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
         parameters = filter_none(parameters)
@@ -36,7 +36,7 @@ class BlackForestLabsTextToImageTask(TaskProviderHelper):
 
         return {"prompt": inputs, **parameters}
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> Any:
         """
         Polling mechanism for Black Forest Labs since the API is asynchronous.
         """

huggingface_hub/inference/_providers/cohere.py

@@ -11,5 +11,5 @@ class CohereConversationalTask(BaseConversationalTask):
     def __init__(self):
         super().__init__(provider=_PROVIDER, base_url=_BASE_URL)
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         return "/compatibility/v1/chat/completions"

huggingface_hub/inference/_providers/fal_ai.py

@@ -1,10 +1,19 @@
 import base64
+import time
 from abc import ABC
 from typing import Any, Dict, Optional, Union
+from urllib.parse import urlparse
 
-from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._common import RequestParameters, _as_dict
 from huggingface_hub.inference._providers._common import TaskProviderHelper, filter_none
-from huggingface_hub.utils import get_session
+from huggingface_hub.utils import get_session, hf_raise_for_status
+from huggingface_hub.utils.logging import get_logger
+
+
+logger = get_logger(__name__)
+
+# Arbitrary polling interval
+_POLLING_INTERVAL = 0.5
 
 
 class FalAITask(TaskProviderHelper, ABC):
@@ -17,7 +26,7 @@ class FalAITask(TaskProviderHelper, ABC):
             headers["authorization"] = f"Key {api_key}"
         return headers
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         return f"/{mapped_model}"
 
 
@@ -41,7 +50,7 @@ class FalAIAutomaticSpeechRecognitionTask(FalAITask):
 
         return {"audio_url": audio_url, **filter_none(parameters)}
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> 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)}.")
@@ -61,7 +70,7 @@ class FalAITextToImageTask(FalAITask):
             }
         return {"prompt": inputs, **parameters}
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> Any:
         url = _as_dict(response)["images"][0]["url"]
         return get_session().get(url).content
 
@@ -73,7 +82,7 @@ class FalAITextToSpeechTask(FalAITask):
     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:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> Any:
         url = _as_dict(response)["audio"]["url"]
         return get_session().get(url).content
 
@@ -82,9 +91,57 @@ class FalAITextToVideoTask(FalAITask):
     def __init__(self):
         super().__init__("text-to-video")
 
+    def _prepare_base_url(self, api_key: str) -> str:
+        if api_key.startswith("hf_"):
+            return super()._prepare_base_url(api_key)
+        else:
+            logger.info(f"Calling '{self.provider}' provider directly.")
+            return "https://queue.fal.run"
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        if api_key.startswith("hf_"):
+            # Use the queue subdomain for HF routing
+            return f"/{mapped_model}?_subdomain=queue"
+        return f"/{mapped_model}"
+
     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:
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        response_dict = _as_dict(response)
+
+        request_id = response_dict.get("request_id")
+        if not request_id:
+            raise ValueError("No request ID found in the response")
+        if request_params is None:
+            raise ValueError(
+                "A `RequestParameters` object should be provided to get text-to-video responses with Fal AI."
+            )
+
+        # extract the base url and query params
+        parsed_url = urlparse(request_params.url)
+        # a bit hacky way to concatenate the provider name without parsing `parsed_url.path`
+        base_url = f"{parsed_url.scheme}://{parsed_url.netloc}{'/fal-ai' if parsed_url.netloc == 'router.huggingface.co' else ''}"
+        query_param = f"?{parsed_url.query}" if parsed_url.query else ""
+
+        # extracting the provider model id for status and result urls
+        # from the response as it might be different from the mapped model in `request_params.url`
+        model_id = urlparse(response_dict.get("response_url")).path
+        status_url = f"{base_url}{str(model_id)}/status{query_param}"
+        result_url = f"{base_url}{str(model_id)}{query_param}"
+
+        status = response_dict.get("status")
+        logger.info("Generating the video.. this can take several minutes.")
+        while status != "COMPLETED":
+            time.sleep(_POLLING_INTERVAL)
+            status_response = get_session().get(status_url, headers=request_params.headers)
+            hf_raise_for_status(status_response)
+            status = status_response.json().get("status")
+
+        response = get_session().get(result_url, headers=request_params.headers).json()
         url = _as_dict(response)["video"]["url"]
         return get_session().get(url).content

huggingface_hub/inference/_providers/fireworks_ai.py

@@ -3,4 +3,7 @@ from ._common import BaseConversationalTask
 
 class FireworksAIConversationalTask(BaseConversationalTask):
     def __init__(self):
-        super().__init__(provider="fireworks-ai", base_url="https://api.fireworks.ai/inference")
+        super().__init__(provider="fireworks-ai", base_url="https://api.fireworks.ai")
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        return "/inference/v1/chat/completions"

huggingface_hub/inference/_providers/hf_inference.py

@@ -24,15 +24,16 @@ class HFInferenceTask(TaskProviderHelper):
         return api_key or get_token()  # type: ignore[return-value]
 
     def _prepare_mapped_model(self, model: Optional[str]) -> str:
-        if model is not None:
+        if model is not None and model.startswith(("http://", "https://")):
             return model
-        model = _fetch_recommended_models().get(self.task)
-        if model is None:
+        model_id = model if model is not None else _fetch_recommended_models().get(self.task)
+        if model_id 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
+        _check_supported_task(model_id, self.task)
+        return model_id
 
     def _prepare_url(self, api_key: str, mapped_model: str) -> str:
         # hf-inference provider can handle URLs (e.g. Inference Endpoints or TGI deployment)
@@ -120,3 +121,39 @@ 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()}
+
+
+@lru_cache(maxsize=None)
+def _check_supported_task(model: str, task: str) -> None:
+    from huggingface_hub.hf_api import HfApi
+
+    model_info = HfApi().model_info(model)
+    pipeline_tag = model_info.pipeline_tag
+    tags = model_info.tags or []
+    is_conversational = "conversational" in tags
+    if task in ("text-generation", "conversational"):
+        if pipeline_tag == "text-generation":
+            # text-generation + conversational tag -> both tasks allowed
+            if is_conversational:
+                return
+            # text-generation without conversational tag -> only text-generation allowed
+            if task == "text-generation":
+                return
+            raise ValueError(f"Model '{model}' doesn't support task '{task}'.")
+
+    if pipeline_tag == "text2text-generation":
+        if task == "text-generation":
+            return
+        raise ValueError(f"Model '{model}' doesn't support task '{task}'.")
+
+    if pipeline_tag == "image-text-to-text":
+        if is_conversational and task == "conversational":
+            return  # Only conversational allowed if tagged as conversational
+        raise ValueError("Non-conversational image-text-to-text task is not supported.")
+
+    # For all other tasks, just check pipeline tag
+    if pipeline_tag != task:
+        raise ValueError(
+            f"Model '{model}' doesn't support task '{task}'. Supported tasks: '{pipeline_tag}', got: '{task}'"
+        )
+    return

huggingface_hub/inference/_providers/hyperbolic.py

@@ -1,7 +1,7 @@
 import base64
 from typing import Any, Dict, Optional, Union
 
-from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._common import RequestParameters, _as_dict
 from huggingface_hub.inference._providers._common import BaseConversationalTask, TaskProviderHelper, filter_none
 
 
@@ -9,7 +9,7 @@ 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:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         return "/v1/images/generations"
 
     def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
@@ -25,7 +25,7 @@ class HyperbolicTextToImageTask(TaskProviderHelper):
             parameters["height"] = 512
         return {"prompt": inputs, "model_name": mapped_model, **parameters}
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> Any:
         response_dict = _as_dict(response)
         return base64.b64decode(response_dict["images"][0]["image"])
 

huggingface_hub/inference/_providers/nebius.py

@@ -1,7 +1,7 @@
 import base64
 from typing import Any, Dict, Optional, Union
 
-from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._common import RequestParameters, _as_dict
 from huggingface_hub.inference._providers._common import (
     BaseConversationalTask,
     BaseTextGenerationTask,
@@ -24,7 +24,7 @@ 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:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         return "/v1/images/generations"
 
     def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
@@ -36,6 +36,6 @@ class NebiusTextToImageTask(TaskProviderHelper):
 
         return {"prompt": inputs, **parameters, "model": mapped_model}
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> Any:
         response_dict = _as_dict(response)
         return base64.b64decode(response_dict["data"][0]["b64_json"])

huggingface_hub/inference/_providers/novita.py

@@ -1,26 +1,56 @@
+from typing import Any, Dict, Optional, Union
+
+from huggingface_hub.inference._common import RequestParameters, _as_dict
 from huggingface_hub.inference._providers._common import (
     BaseConversationalTask,
     BaseTextGenerationTask,
+    TaskProviderHelper,
+    filter_none,
 )
+from huggingface_hub.utils import get_session
 
 
 _PROVIDER = "novita"
-_BASE_URL = "https://api.novita.ai/v3/openai"
+_BASE_URL = "https://api.novita.ai"
 
 
 class NovitaTextGenerationTask(BaseTextGenerationTask):
     def __init__(self):
         super().__init__(provider=_PROVIDER, base_url=_BASE_URL)
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         # there is no v1/ route for novita
-        return "/completions"
+        return "/v3/openai/completions"
 
 
 class NovitaConversationalTask(BaseConversationalTask):
     def __init__(self):
         super().__init__(provider=_PROVIDER, base_url=_BASE_URL)
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         # there is no v1/ route for novita
-        return "/chat/completions"
+        return "/v3/openai/chat/completions"
+
+
+class NovitaTextToVideoTask(TaskProviderHelper):
+    def __init__(self):
+        super().__init__(provider=_PROVIDER, base_url=_BASE_URL, task="text-to-video")
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        return f"/v3/hf/{mapped_model}"
+
+    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], request_params: Optional[RequestParameters] = None) -> Any:
+        response_dict = _as_dict(response)
+        if not (
+            isinstance(response_dict, dict)
+            and "video" in response_dict
+            and isinstance(response_dict["video"], dict)
+            and "video_url" in response_dict["video"]
+        ):
+            raise ValueError("Expected response format: { 'video': { 'video_url': string } }")
+
+        video_url = response_dict["video"]["video_url"]
+        return get_session().get(video_url).content

huggingface_hub/inference/_providers/openai.py

@@ -0,0 +1,22 @@
+from typing import Optional
+
+from huggingface_hub.inference._providers._common import BaseConversationalTask
+
+
+class OpenAIConversationalTask(BaseConversationalTask):
+    def __init__(self):
+        super().__init__(provider="openai", base_url="https://api.openai.com")
+
+    def _prepare_api_key(self, api_key: Optional[str]) -> str:
+        if api_key is None:
+            raise ValueError("You must provide an api_key to work with OpenAI API.")
+        if api_key.startswith("hf_"):
+            raise ValueError(
+                "OpenAI provider is not available through Hugging Face routing, please use your own OpenAI API key."
+            )
+        return api_key
+
+    def _prepare_mapped_model(self, model: Optional[str]) -> str:
+        if model is None:
+            raise ValueError("Please provide an OpenAI model ID, e.g. `gpt-4o` or `o1`.")
+        return model

huggingface_hub/inference/_providers/replicate.py

@@ -1,6 +1,6 @@
 from typing import Any, Dict, Optional, Union
 
-from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._common import RequestParameters, _as_dict
 from huggingface_hub.inference._providers._common import TaskProviderHelper, filter_none
 from huggingface_hub.utils import get_session
 
@@ -18,7 +18,7 @@ class ReplicateTask(TaskProviderHelper):
         headers["Prefer"] = "wait"
         return headers
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         if ":" in mapped_model:
             return "/v1/predictions"
         return f"/v1/models/{mapped_model}/predictions"
@@ -30,7 +30,7 @@ class ReplicateTask(TaskProviderHelper):
             payload["version"] = version
         return payload
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> Any:
         response_dict = _as_dict(response)
         if response_dict.get("output") is None:
             raise TimeoutError(

huggingface_hub/inference/_providers/together.py

@@ -2,7 +2,7 @@ import base64
 from abc import ABC
 from typing import Any, Dict, Optional, Union
 
-from huggingface_hub.inference._common import _as_dict
+from huggingface_hub.inference._common import RequestParameters, _as_dict
 from huggingface_hub.inference._providers._common import (
     BaseConversationalTask,
     BaseTextGenerationTask,
@@ -21,7 +21,7 @@ class TogetherTask(TaskProviderHelper, ABC):
     def __init__(self, task: str):
         super().__init__(provider=_PROVIDER, base_url=_BASE_URL, task=task)
 
-    def _prepare_route(self, mapped_model: str) -> str:
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
         if self.task == "text-to-image":
             return "/v1/images/generations"
         elif self.task == "conversational":
@@ -54,6 +54,6 @@ class TogetherTextToImageTask(TogetherTask):
 
         return {"prompt": inputs, "response_format": "base64", **parameters, "model": mapped_model}
 
-    def get_response(self, response: Union[bytes, Dict]) -> Any:
+    def get_response(self, response: Union[bytes, Dict], request_params: Optional[RequestParameters] = None) -> Any:
         response_dict = _as_dict(response)
         return base64.b64decode(response_dict["data"][0]["b64_json"])

huggingface_hub/utils/__init__.py

@@ -107,4 +107,12 @@ from ._subprocess import capture_output, run_interactive_subprocess, run_subproc
 from ._telemetry import send_telemetry
 from ._typing import is_jsonable, is_simple_optional_type, unwrap_simple_optional_type
 from ._validators import smoothly_deprecate_use_auth_token, validate_hf_hub_args, validate_repo_id
+from ._xet import (
+    XetConnectionInfo,
+    XetFileData,
+    XetTokenType,
+    fetch_xet_connection_info_from_repo_info,
+    parse_xet_file_data_from_response,
+    refresh_xet_connection_info,
+)
 from .tqdm import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars, tqdm, tqdm_stream_file

huggingface_hub/utils/_http.py

@@ -453,7 +453,8 @@ def hf_raise_for_status(response: Response, endpoint_name: Optional[str] = None)
                 + f"Repository Not Found for url: {response.url}."
                 + "\nPlease make sure you specified the correct `repo_id` and"
                 " `repo_type`.\nIf you are trying to access a private or gated repo,"
-                " make sure you are authenticated."
+                " make sure you are authenticated. For more details, see"
+                " https://huggingface.co/docs/huggingface_hub/authentication"
             )
             raise _format(RepositoryNotFoundError, message, response) from e
 
@@ -577,6 +578,8 @@ def _curlify(request: requests.PreparedRequest) -> str:
         body = request.body
         if isinstance(body, bytes):
             body = body.decode("utf-8", errors="ignore")
+        elif hasattr(body, "read"):
+            body = "<file-like object>"  # Don't try to read it to avoid consuming the stream
         if len(body) > 1000:
             body = body[:1000] + " ... [truncated]"
         parts += [("-d", body.replace("\n", ""))]

huggingface_hub/utils/_runtime.py

@@ -36,6 +36,7 @@ _CANDIDATES = {
     "gradio": {"gradio"},
     "graphviz": {"graphviz"},
     "hf_transfer": {"hf_transfer"},
+    "hf_xet": {"hf_xet"},
     "jinja": {"Jinja2"},
     "keras": {"keras"},
     "numpy": {"numpy"},
@@ -151,6 +152,15 @@ def get_hf_transfer_version() -> str:
     return _get_version("hf_transfer")
 
 
+# xet
+def is_xet_available() -> bool:
+    return is_package_available("hf_xet")
+
+
+def get_xet_version() -> str:
+    return _get_version("hf_xet")
+
+
 # keras
 def is_keras_available() -> bool:
     return is_package_available("keras")
@@ -357,6 +367,7 @@ def dump_environment_info() -> Dict[str, Any]:
     info["numpy"] = get_numpy_version()
     info["pydantic"] = get_pydantic_version()
     info["aiohttp"] = get_aiohttp_version()
+    info["hf_xet"] = get_xet_version()
 
     # Environment variables
     info["ENDPOINT"] = constants.ENDPOINT