Add Hugging Face as a provider (#1911)

Co-authored-by: Marcelo Trylesinski <[email protected]>
Co-authored-by: burtenshaw <[email protected]>

Author: 3 people

docs/api/models/huggingface.md

@@ -0,0 +1,7 @@
+# `pydantic_ai.models.huggingface`
+
+## Setup
+
+For details on how to set up authentication with this model, see [model configuration for Hugging Face](../../models/huggingface.md).
+
+::: pydantic_ai.models.huggingface

docs/api/providers.md

@@ -31,3 +31,5 @@
 ::: pydantic_ai.providers.github.GitHubProvider
 
 ::: pydantic_ai.providers.openrouter.OpenRouterProvider
+
+::: pydantic_ai.providers.huggingface.HuggingFaceProvider

docs/models/huggingface.md

@@ -0,0 +1,95 @@
+# Hugging Face
+
+[Hugging Face](https://huggingface.co/) is an AI platform with all major open source models, datasets, MCPs, and demos. You can use [Inference Providers](https://huggingface.co/docs/inference-providers) to run open source models like DeepSeek R1 on scalable serverless infrastructure.
+
+## Install
+
+To use `HuggingFaceModel`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `huggingface` optional group:
+
+```bash
+pip/uv-add "pydantic-ai-slim[huggingface]"
+```
+
+## Configuration
+
+To use [Hugging Face](https://huggingface.co/) inference, you'll need to set up an account which will give you [free tier](https://huggingface.co/docs/inference-providers/pricing) allowance on [Inference Providers](https://huggingface.co/docs/inference-providers). To setup inference, follow these steps:
+
+1. Go to [Hugging Face](https://huggingface.co/join) and sign up for an account.
+2. Create a new access token in [Hugging Face](https://huggingface.co/settings/tokens).
+3. Set the `HF_TOKEN` environment variable to the token you just created.
+
+Once you have a Hugging Face access token, you can set it as an environment variable:
+
+```bash
+export HF_TOKEN='hf_token'
+```
+
+## Usage
+
+You can then use [`HuggingFaceModel`][pydantic_ai.models.huggingface.HuggingFaceModel] by name:
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent('huggingface:Qwen/Qwen3-235B-A22B')
+...
+```
+
+Or initialise the model directly with just the model name:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.huggingface import HuggingFaceModel
+
+model = HuggingFaceModel('Qwen/Qwen3-235B-A22B')
+agent = Agent(model)
+...
+```
+
+By default, the [`HuggingFaceModel`][pydantic_ai.models.huggingface.HuggingFaceModel] uses the
+[`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] that will select automatically
+the first of the inference providers (Cerebras, Together AI, Cohere..etc) available for the model, sorted by your
+preferred order in https://hf.co/settings/inference-providers.
+
+## Configure the provider
+
+If you want to pass parameters in code to the provider, you can programmatically instantiate the
+[`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] and pass it to the model:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.huggingface import HuggingFaceModel
+from pydantic_ai.providers.huggingface import HuggingFaceProvider
+
+model = HuggingFaceModel('Qwen/Qwen3-235B-A22B', provider=HuggingFaceProvider(api_key='hf_token', provider_name='nebius'))
+agent = Agent(model)
+...
+```
+
+## Custom Hugging Face client
+
+[`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] also accepts a custom
+[`AsyncInferenceClient`][huggingface_hub.AsyncInferenceClient] client via the `hf_client` parameter, so you can customise
+the `headers`, `bill_to` (billing to an HF organization you're a member of), `base_url` etc. as defined in the
+[Hugging Face Hub python library docs](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client).
+
+```python
+from huggingface_hub import AsyncInferenceClient
+
+from pydantic_ai import Agent
+from pydantic_ai.models.huggingface import HuggingFaceModel
+from pydantic_ai.providers.huggingface import HuggingFaceProvider
+
+client = AsyncInferenceClient(
+    bill_to='openai',
+    api_key='hf_token',
+    provider='fireworks-ai',
+)
+
+model = HuggingFaceModel(
+    'Qwen/Qwen3-235B-A22B',
+    provider=HuggingFaceProvider(hf_client=client),
+)
+agent = Agent(model)
+...
+```

mkdocs.yml

@@ -83,6 +83,7 @@ nav:
       - api/models/gemini.md
       - api/models/google.md
       - api/models/groq.md
+      - api/models/huggingface.md
       - api/models/instrumented.md
       - api/models/mistral.md
       - api/models/test.md

pydantic_ai_slim/pydantic_ai/models/__init__.py

@@ -227,6 +227,14 @@
         'heroku:claude-3-7-sonnet',
         'heroku:claude-4-sonnet',
         'heroku:claude-3-haiku',
+        'huggingface:Qwen/QwQ-32B',
+        'huggingface:Qwen/Qwen2.5-72B-Instruct',
+        'huggingface:Qwen/Qwen3-235B-A22B',
+        'huggingface:Qwen/Qwen3-32B',
+        'huggingface:deepseek-ai/DeepSeek-R1',
+        'huggingface:meta-llama/Llama-3.3-70B-Instruct',
+        'huggingface:meta-llama/Llama-4-Maverick-17B-128E-Instruct',
+        'huggingface:meta-llama/Llama-4-Scout-17B-16E-Instruct',
         'mistral:codestral-latest',
         'mistral:mistral-large-latest',
         'mistral:mistral-moderation-latest',
@@ -560,7 +568,7 @@ def override_allow_model_requests(allow_model_requests: bool) -> Iterator[None]:
         ALLOW_MODEL_REQUESTS = old_value  # pyright: ignore[reportConstantRedefinition]
 
 
-def infer_model(model: Model | KnownModelName | str) -> Model:
+def infer_model(model: Model | KnownModelName | str) -> Model:  # noqa: C901
     """Infer the model from the name."""
     if isinstance(model, Model):
         return model
@@ -624,6 +632,10 @@ def infer_model(model: Model | KnownModelName | str) -> Model:
         from .bedrock import BedrockConverseModel
 
         return BedrockConverseModel(model_name, provider=provider)
+    elif provider == 'huggingface':
+        from .huggingface import HuggingFaceModel
+
+        return HuggingFaceModel(model_name, provider=provider)
     else:
         raise UserError(f'Unknown model: {model}')  # pragma: no cover