huggingface-hub 0.31.3__py3-none-any.whl → 0.32.0__py3-none-any.whl

huggingface_hub/inference/_client.py

@@ -66,6 +66,7 @@ from huggingface_hub.inference._generated.types import (
     AudioToAudioOutputElement,
     AutomaticSpeechRecognitionOutput,
     ChatCompletionInputGrammarType,
+    ChatCompletionInputMessage,
     ChatCompletionInputStreamOptions,
     ChatCompletionInputTool,
     ChatCompletionInputToolChoiceClass,
@@ -100,7 +101,7 @@ from huggingface_hub.inference._generated.types import (
     ZeroShotClassificationOutputElement,
     ZeroShotImageClassificationOutputElement,
 )
-from huggingface_hub.inference._providers import PROVIDER_T, get_provider_helper
+from huggingface_hub.inference._providers import PROVIDER_OR_POLICY_T, get_provider_helper
 from huggingface_hub.utils import build_hf_headers, get_session, hf_raise_for_status
 from huggingface_hub.utils._auth import get_token
 from huggingface_hub.utils._deprecation import _deprecate_method
@@ -133,7 +134,7 @@ class InferenceClient:
             path will be appended to the base URL (see the [TGI Messages API](https://huggingface.co/docs/text-generation-inference/en/messages_api)
             documentation for details). When passing a URL as `model`, the client will not append any suffix path to it.
         provider (`str`, *optional*):
-            Name of the provider to use for inference. Can be `"black-forest-labs"`, `"cerebras"`, `"cohere"`, `"fal-ai"`, `"fireworks-ai"`, `"hf-inference"`, `"hyperbolic"`, `"nebius"`, `"novita"`, `"openai"`, `"replicate"`, "sambanova"` or `"together"`.
+            Name of the provider to use for inference. Can be `"black-forest-labs"`, `"cerebras"`, `"cohere"`, `"fal-ai"`, `"fireworks-ai"`, `"hf-inference"`, `"hyperbolic"`, `"nebius"`, `"novita"`, `"nscale"`, `"openai"`, `"replicate"`, "sambanova"` or `"together"`.
             Defaults to "auto" i.e. the first of the providers available for the model, sorted by the user's order in https://hf.co/settings/inference-providers.
             If model is a URL or `base_url` is passed, then `provider` is not used.
         token (`str`, *optional*):
@@ -164,7 +165,7 @@ class InferenceClient:
         self,
         model: Optional[str] = None,
         *,
-        provider: Union[Literal["auto"], PROVIDER_T, None] = None,
+        provider: Optional[PROVIDER_OR_POLICY_T] = None,
         token: Optional[str] = None,
         timeout: Optional[float] = None,
         headers: Optional[Dict[str, str]] = None,
@@ -446,7 +447,7 @@ class InferenceClient:
     @overload
     def chat_completion(  # type: ignore
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: Literal[False] = False,
@@ -472,7 +473,7 @@ class InferenceClient:
     @overload
     def chat_completion(  # type: ignore
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: Literal[True] = True,
@@ -498,7 +499,7 @@ class InferenceClient:
     @overload
     def chat_completion(
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: bool = False,
@@ -523,7 +524,7 @@ class InferenceClient:
 
     def chat_completion(
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: bool = False,

huggingface_hub/inference/_generated/_async_client.py

@@ -51,6 +51,7 @@ from huggingface_hub.inference._generated.types import (
     AudioToAudioOutputElement,
     AutomaticSpeechRecognitionOutput,
     ChatCompletionInputGrammarType,
+    ChatCompletionInputMessage,
     ChatCompletionInputStreamOptions,
     ChatCompletionInputTool,
     ChatCompletionInputToolChoiceClass,
@@ -85,7 +86,7 @@ from huggingface_hub.inference._generated.types import (
     ZeroShotClassificationOutputElement,
     ZeroShotImageClassificationOutputElement,
 )
-from huggingface_hub.inference._providers import PROVIDER_T, get_provider_helper
+from huggingface_hub.inference._providers import PROVIDER_OR_POLICY_T, get_provider_helper
 from huggingface_hub.utils import build_hf_headers, get_session, hf_raise_for_status
 from huggingface_hub.utils._auth import get_token
 from huggingface_hub.utils._deprecation import _deprecate_method
@@ -121,7 +122,7 @@ class AsyncInferenceClient:
             path will be appended to the base URL (see the [TGI Messages API](https://huggingface.co/docs/text-generation-inference/en/messages_api)
             documentation for details). When passing a URL as `model`, the client will not append any suffix path to it.
         provider (`str`, *optional*):
-            Name of the provider to use for inference. Can be `"black-forest-labs"`, `"cerebras"`, `"cohere"`, `"fal-ai"`, `"fireworks-ai"`, `"hf-inference"`, `"hyperbolic"`, `"nebius"`, `"novita"`, `"openai"`, `"replicate"`, "sambanova"` or `"together"`.
+            Name of the provider to use for inference. Can be `"black-forest-labs"`, `"cerebras"`, `"cohere"`, `"fal-ai"`, `"fireworks-ai"`, `"hf-inference"`, `"hyperbolic"`, `"nebius"`, `"novita"`, `"nscale"`, `"openai"`, `"replicate"`, "sambanova"` or `"together"`.
             Defaults to "auto" i.e. the first of the providers available for the model, sorted by the user's order in https://hf.co/settings/inference-providers.
             If model is a URL or `base_url` is passed, then `provider` is not used.
         token (`str`, *optional*):
@@ -154,7 +155,7 @@ class AsyncInferenceClient:
         self,
         model: Optional[str] = None,
         *,
-        provider: Union[Literal["auto"], PROVIDER_T, None] = None,
+        provider: Optional[PROVIDER_OR_POLICY_T] = None,
         token: Optional[str] = None,
         timeout: Optional[float] = None,
         headers: Optional[Dict[str, str]] = None,
@@ -480,7 +481,7 @@ class AsyncInferenceClient:
     @overload
     async def chat_completion(  # type: ignore
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: Literal[False] = False,
@@ -506,7 +507,7 @@ class AsyncInferenceClient:
     @overload
     async def chat_completion(  # type: ignore
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: Literal[True] = True,
@@ -532,7 +533,7 @@ class AsyncInferenceClient:
     @overload
     async def chat_completion(
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: bool = False,
@@ -557,7 +558,7 @@ class AsyncInferenceClient:
 
     async def chat_completion(
         self,
-        messages: List[Dict],
+        messages: List[Union[Dict, ChatCompletionInputMessage]],
         *,
         model: Optional[str] = None,
         stream: bool = False,

huggingface_hub/inference/_generated/types/__init__.py

@@ -24,10 +24,13 @@ from .chat_completion import (
     ChatCompletionInputFunctionDefinition,
     ChatCompletionInputFunctionName,
     ChatCompletionInputGrammarType,
-    ChatCompletionInputGrammarTypeType,
+    ChatCompletionInputJSONSchema,
     ChatCompletionInputMessage,
     ChatCompletionInputMessageChunk,
     ChatCompletionInputMessageChunkType,
+    ChatCompletionInputResponseFormatJSONObject,
+    ChatCompletionInputResponseFormatJSONSchema,
+    ChatCompletionInputResponseFormatText,
     ChatCompletionInputStreamOptions,
     ChatCompletionInputTool,
     ChatCompletionInputToolCall,

huggingface_hub/inference/_generated/types/chat_completion.py

@@ -3,7 +3,7 @@
 # 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 typing import Any, List, Literal, Optional, Union
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from .base import BaseInferenceType, dataclass_with_extra
 
@@ -45,17 +45,51 @@ class ChatCompletionInputMessage(BaseInferenceType):
     tool_calls: Optional[List[ChatCompletionInputToolCall]] = None
 
 
-ChatCompletionInputGrammarTypeType = Literal["json", "regex", "json_schema"]
+@dataclass_with_extra
+class ChatCompletionInputJSONSchema(BaseInferenceType):
+    name: str
+    """
+    The name of the response format.
+    """
+    description: Optional[str] = None
+    """
+    A description of what the response format is for, used by the model to determine
+    how to respond in the format.
+    """
+    schema: Optional[Dict[str, object]] = None
+    """
+    The schema for the response format, described as a JSON Schema object. Learn how
+    to build JSON schemas [here](https://json-schema.org/).
+    """
+    strict: Optional[bool] = None
+    """
+    Whether to enable strict schema adherence when generating the output. If set to
+    true, the model will always follow the exact schema defined in the `schema`
+    field.
+    """
 
 
 @dataclass_with_extra
-class ChatCompletionInputGrammarType(BaseInferenceType):
-    type: "ChatCompletionInputGrammarTypeType"
-    value: Any
-    """A string that represents a [JSON Schema](https://json-schema.org/).
-    JSON Schema is a declarative language that allows to annotate JSON documents
-    with types and descriptions.
-    """
+class ChatCompletionInputResponseFormatText(BaseInferenceType):
+    type: Literal["text"]
+
+
+@dataclass_with_extra
+class ChatCompletionInputResponseFormatJSONSchema(BaseInferenceType):
+    type: Literal["json_schema"]
+    json_schema: ChatCompletionInputJSONSchema
+
+
+@dataclass_with_extra
+class ChatCompletionInputResponseFormatJSONObject(BaseInferenceType):
+    type: Literal["json_object"]
+
+
+ChatCompletionInputGrammarType = Union[
+    ChatCompletionInputResponseFormatText,
+    ChatCompletionInputResponseFormatJSONSchema,
+    ChatCompletionInputResponseFormatJSONObject,
+]
 
 
 @dataclass_with_extra

huggingface_hub/inference/_mcp/agent.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import asyncio
+from typing import AsyncGenerator, Dict, Iterable, List, Optional, Union
+
+from huggingface_hub import ChatCompletionInputMessage, ChatCompletionStreamOutput, MCPClient
+
+from .._providers import PROVIDER_OR_POLICY_T
+from .constants import DEFAULT_SYSTEM_PROMPT, EXIT_LOOP_TOOLS, MAX_NUM_TURNS
+
+
+class Agent(MCPClient):
+    """
+    Implementation of a Simple Agent, which is a simple while loop built right on top of an [`MCPClient`].
+
+    <Tip warning={true}>
+
+    This class is experimental and might be subject to breaking changes in the future without prior notice.
+
+    </Tip>
+
+    Args:
+        model (`str`):
+            The model to run inference with. Can be a model id hosted on the Hugging Face Hub, e.g. `meta-llama/Meta-Llama-3-8B-Instruct`
+            or a URL to a deployed Inference Endpoint or other local or remote endpoint.
+        servers (`Iterable[Dict]`):
+            MCP servers to connect to. Each server is a dictionary containing a `type` key and a `config` key. The `type` key can be `"stdio"` or `"sse"`, and the `config` key is a dictionary of arguments for the server.
+        provider (`str`, *optional*):
+            Name of the provider to use for inference. Defaults to "auto" i.e. the first of the providers available for the model, sorted by the user's order in https://hf.co/settings/inference-providers.
+            If model is a URL or `base_url` is passed, then `provider` is not used.
+        api_key (`str`, *optional*):
+            Token to use for authentication. Will default to the locally Hugging Face saved token if not provided. You can also use your own provider API key to interact directly with the provider's service.
+        prompt (`str`, *optional*):
+            The system prompt to use for the agent. Defaults to the default system prompt in `constants.py`.
+    """
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        servers: Iterable[Dict],
+        provider: Optional[PROVIDER_OR_POLICY_T] = None,
+        api_key: Optional[str] = None,
+        prompt: Optional[str] = None,
+    ):
+        super().__init__(model=model, provider=provider, api_key=api_key)
+        self._servers_cfg = list(servers)
+        self.messages: List[Union[Dict, ChatCompletionInputMessage]] = [
+            {"role": "system", "content": prompt or DEFAULT_SYSTEM_PROMPT}
+        ]
+
+    async def load_tools(self) -> None:
+        for cfg in self._servers_cfg:
+            await self.add_mcp_server(cfg["type"], **cfg["config"])
+
+    async def run(
+        self,
+        user_input: str,
+        *,
+        abort_event: Optional[asyncio.Event] = None,
+    ) -> AsyncGenerator[Union[ChatCompletionStreamOutput, ChatCompletionInputMessage], None]:
+        """
+        Run the agent with the given user input.
+
+        Args:
+            user_input (`str`):
+                The user input to run the agent with.
+            abort_event (`asyncio.Event`, *optional*):
+                An event that can be used to abort the agent. If the event is set, the agent will stop running.
+        """
+        self.messages.append({"role": "user", "content": user_input})
+
+        num_turns: int = 0
+        next_turn_should_call_tools = True
+
+        while True:
+            if abort_event and abort_event.is_set():
+                return
+
+            async for item in self.process_single_turn_with_tools(
+                self.messages,
+                exit_loop_tools=EXIT_LOOP_TOOLS,
+                exit_if_first_chunk_no_tool=(num_turns > 0 and next_turn_should_call_tools),
+            ):
+                yield item
+
+            num_turns += 1
+            last = self.messages[-1]
+
+            if last.get("role") == "tool" and last.get("name") in {t.function.name for t in EXIT_LOOP_TOOLS}:
+                return
+
+            if last.get("role") != "tool" and num_turns > MAX_NUM_TURNS:
+                return
+
+            if last.get("role") != "tool" and next_turn_should_call_tools:
+                return
+
+            next_turn_should_call_tools = last.get("role") != "tool"

huggingface_hub/inference/_mcp/cli.py

@@ -0,0 +1,154 @@
+import asyncio
+import os
+import signal
+from functools import partial
+from typing import Any, Dict, List, Optional
+
+import typer
+from rich import print
+
+from .agent import Agent
+from .utils import _load_agent_config
+
+
+app = typer.Typer(
+    rich_markup_mode="rich",
+    help="A squad of lightweight composable AI applications built on Hugging Face's Inference Client and MCP stack.",
+)
+
+run_cli = typer.Typer(
+    name="run",
+    help="Run the Agent in the CLI",
+    invoke_without_command=True,
+)
+app.add_typer(run_cli, name="run")
+
+
+async def _ainput(prompt: str = "» ") -> str:
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, partial(typer.prompt, prompt, prompt_suffix=" "))
+
+
+async def run_agent(
+    agent_path: Optional[str],
+) -> None:
+    """
+    Tiny Agent loop.
+
+    Args:
+        agent_path (`str`, *optional*):
+            Path to a local folder containing an `agent.json` and optionally a custom `PROMPT.md` file or a built-in agent stored in a Hugging Face dataset.
+
+    """
+    config, prompt = _load_agent_config(agent_path)
+
+    servers: List[Dict[str, Any]] = config.get("servers", [])
+
+    abort_event = asyncio.Event()
+    first_sigint = True
+
+    loop = asyncio.get_running_loop()
+    original_sigint_handler = signal.getsignal(signal.SIGINT)
+
+    def _sigint_handler() -> None:
+        nonlocal first_sigint
+        if first_sigint:
+            first_sigint = False
+            abort_event.set()
+            print("\n[red]Interrupted. Press Ctrl+C again to quit.[/red]", flush=True)
+            return
+
+        print("\n[red]Exiting...[/red]", flush=True)
+
+        os._exit(130)
+
+    try:
+        loop.add_signal_handler(signal.SIGINT, _sigint_handler)
+
+        async with Agent(
+            provider=config["provider"],
+            model=config["model"],
+            servers=servers,
+            prompt=prompt,
+        ) as agent:
+            await agent.load_tools()
+            print(f"[bold blue]Agent loaded with {len(agent.available_tools)} tools:[/bold blue]")
+            for t in agent.available_tools:
+                print(f"[blue] • {t.function.name}[/blue]")
+
+            while True:
+                abort_event.clear()
+
+                try:
+                    user_input = await _ainput()
+                    first_sigint = True
+                except EOFError:
+                    print("\n[red]EOF received, exiting.[/red]", flush=True)
+                    break
+                except KeyboardInterrupt:
+                    if not first_sigint and abort_event.is_set():
+                        continue
+                    else:
+                        print("\n[red]Keyboard interrupt during input processing.[/red]", flush=True)
+                        break
+
+                try:
+                    async for chunk in agent.run(user_input, abort_event=abort_event):
+                        if abort_event.is_set() and not first_sigint:
+                            break
+
+                        if hasattr(chunk, "choices"):
+                            delta = chunk.choices[0].delta
+                            if delta.content:
+                                print(delta.content, end="", flush=True)
+                            if delta.tool_calls:
+                                for call in delta.tool_calls:
+                                    if call.id:
+                                        print(f"<Tool {call.id}>", end="")
+                                    if call.function.name:
+                                        print(f"{call.function.name}", end=" ")
+                                    if call.function.arguments:
+                                        print(f"{call.function.arguments}", end="")
+                        else:
+                            print(
+                                f"\n\n[green]Tool[{chunk.name}] {chunk.tool_call_id}\n{chunk.content}[/green]\n",
+                                flush=True,
+                            )
+
+                    print()
+
+                except Exception as e:
+                    print(f"\n[bold red]Error during agent run: {e}[/bold red]", flush=True)
+                    first_sigint = True  # Allow graceful interrupt for the next command
+
+    finally:
+        if loop and not loop.is_closed():
+            loop.remove_signal_handler(signal.SIGINT)
+        elif original_sigint_handler:
+            signal.signal(signal.SIGINT, original_sigint_handler)
+
+
+@run_cli.callback()
+def run(
+    path: Optional[str] = typer.Argument(
+        None,
+        help=(
+            "Path to a local folder containing an agent.json file or a built-in agent "
+            "stored in the 'tiny-agents/tiny-agents' Hugging Face dataset "
+            "(https://huggingface.co/datasets/tiny-agents/tiny-agents)"
+        ),
+        show_default=False,
+    ),
+):
+    try:
+        asyncio.run(run_agent(path))
+    except KeyboardInterrupt:
+        print("\n[red]Application terminated by KeyboardInterrupt.[/red]", flush=True)
+        raise typer.Exit(code=130)
+    except Exception as e:
+        print(f"\n[bold red]An unexpected error occurred: {e}[/bold red]", flush=True)
+        raise e
+
+
+if __name__ == "__main__":
+    app()

huggingface_hub/inference/_mcp/constants.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import List
+
+from huggingface_hub import ChatCompletionInputTool
+
+
+FILENAME_CONFIG = "agent.json"
+FILENAME_PROMPT = "PROMPT.md"
+
+DEFAULT_AGENT = {
+    "model": "Qwen/Qwen2.5-72B-Instruct",
+    "provider": "nebius",
+    "servers": [
+        {
+            "type": "stdio",
+            "config": {
+                "command": "npx",
+                "args": [
+                    "-y",
+                    "@modelcontextprotocol/server-filesystem",
+                    str(Path.home() / ("Desktop" if sys.platform == "darwin" else "")),
+                ],
+            },
+        },
+        {
+            "type": "stdio",
+            "config": {
+                "command": "npx",
+                "args": ["@playwright/mcp@latest"],
+            },
+        },
+    ],
+}
+
+
+DEFAULT_SYSTEM_PROMPT = """
+You are an agent - please keep going until the user’s query is completely
+resolved, before ending your turn and yielding back to the user. Only terminate
+your turn when you are sure that the problem is solved, or if you need more
+info from the user to solve the problem.
+If you are not sure about anything pertaining to the user’s request, use your
+tools to read files and gather the relevant information: do NOT guess or make
+up an answer.
+You MUST plan extensively before each function call, and reflect extensively
+on the outcomes of the previous function calls. DO NOT do this entire process
+by making function calls only, as this can impair your ability to solve the
+problem and think insightfully.
+""".strip()
+
+MAX_NUM_TURNS = 10
+
+TASK_COMPLETE_TOOL: ChatCompletionInputTool = ChatCompletionInputTool.parse_obj(  # type: ignore[assignment]
+    {
+        "type": "function",
+        "function": {
+            "name": "task_complete",
+            "description": "Call this tool when the task given by the user is complete",
+            "parameters": {"type": "object", "properties": {}},
+        },
+    }
+)
+
+ASK_QUESTION_TOOL: ChatCompletionInputTool = ChatCompletionInputTool.parse_obj(  # type: ignore[assignment]
+    {
+        "type": "function",
+        "function": {
+            "name": "ask_question",
+            "description": "Ask the user for more info required to solve or clarify their problem.",
+            "parameters": {"type": "object", "properties": {}},
+        },
+    }
+)
+
+EXIT_LOOP_TOOLS: List[ChatCompletionInputTool] = [TASK_COMPLETE_TOOL, ASK_QUESTION_TOOL]
+
+
+DEFAULT_REPO_ID = "tiny-agents/tiny-agents"