Add Hugging Face as a provider

[hanouticelina]

closes #1085.
Hi there, maintainer of huggingface_hub library 🤗 here,
This PR introduces support for Hugging Face's Inference Providers (documentation here) as a Model Provider.

Our API is fully compatible with the OpenAI REST API spec, and the implementation closely mirrors the existing OpenAIProvider / OpenAIModel pair. Under the hood, we use the huggingface_hub.AsyncInferenceClient client, which is a drop-in replacement of the async OpenAI client but includes provider-specific (de)serialization logic that cannot be reproduced reliably with the OpenAI client alone, see @Wauplin’s detailed explanation here).

Note that huggingface_hub is a stable and widely used library that was already listed as a dependency in the lockfile.

TODO:

• Add tests.
• Add documentation.

[Kludex]

Great! :)

How can I help here?

[hanouticelina]

Hi @Kludex,
i'm currently finishing adding tests and documentation and then the PR will be ready for review! :)

[Kludex]

Hi @Kludex, i'm currently finishing adding tests and documentation and then the PR will be ready for review! :)

Amazing! :)

[hyperlint-ai]

PR Change Summary

Added support for Hugging Face as a model provider, enhancing the library's capabilities for AI inference.

• Introduced Hugging Face as a new provider for model inference.
• Added documentation for setting up and using Hugging Face models.
• Updated existing provider documentation to include Hugging Face provider.

Modified Files

• docs/api/providers.md

Added Files

• docs/api/models/huggingface.md
• docs/models/huggingface.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[hanouticelina]

Hi @Kludex,
Sorry for the delay, the PR is finally ready for review! I'll have limited availability over the next two weeks, but I'll do my best to be responsive in case you have any feedback.
At 🤗, we're super excited to get this merged!

[hanouticelina]

Hi @Kludex,
Just wanted to follow up now that I'm back and have a bit more time, let me know if you get a chance to take a look at the PR! 😊

[Kludex]

How can we keep the list of those models up-to-date? Do you folks have an endpoint that we can call to list a lot of them, or something?

[hanouticelina]

yes! we've just shipped https://router.huggingface.co/v1/models that returns the list of models (sorted by trending score on the Hugging Face Hub). Not sure how can I update KnownModelName dynamically? i can do that for [LatestHuggingFaceModelNames](https://github.com/hanouticelina/pydantic-ai/blob/873f090197b6c7b8c2ae1c0760db17ef54814f86/pydantic_ai_slim/pydantic_ai/models/huggingface.py#L69, but KnownModelName needs to be update as well.

[Kludex]

We can create a test that: if run locally, it would call that endpoint and it will check against this list of models.

In CI it should use the cassette.

[Kludex]

I wrote some comments here.

We need to create ThinkingParts (does the HuggingFace client handles them?) and we need to add code coverage.

I prefer tests strictly with VCR, if possible.

[Kludex]

@hanouticelina Are you still working on this? Let me know when I should take over.

[hanouticelina]

Hey @Kludex,
Yes i'm still working on it, i have to finish some things before assigning it back to you, but will do as soon as i'm done! 🙂

[hanouticelina]

hey @Kludex,

We need to create ThinkingParts (does the HuggingFace client handles them?)

The HF client does not handle ThinkingParts, in 9b0edee, I added the splitting of the response content into text and thinking part, is there anything else to add for this?

[hanouticelina]

Hey @Kludex,
I've addressed your comments - could you take a look when you have a moment ? 🙏

[Copilot]

Pull Request Overview

Add Hugging Face as a first-class inference provider, mirroring the existing OpenAI support.

• Introduce HuggingFaceProvider and register it in provider selection.
• Implement HuggingFaceModel with full streaming and request/response handling.
• Update tests, CLI, examples, dependencies, and documentation to include Hugging Face.

Reviewed Changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pydantic_ai_slim/pydantic_ai/providers/huggingface.py	New HuggingFaceProvider implementation
pydantic_ai_slim/pydantic_ai/models/huggingface.py	New HuggingFaceModel implementation
tests/providers/test_huggingface.py	Unit tests for provider initialization and errors
docs/models/huggingface.md	User documentation for Hugging Face support
pyproject.toml & pydantic_ai_slim/pyproject.toml	Add huggingface optional dependency

Comments suppressed due to low confidence (1)

docs/models/huggingface.md:10

• [nitpick] The installation command appears incorrect (pip/uv-add). It should be pip install "pydantic-ai-slim[huggingface]" for clarity and accuracy.

pip/uv-add "pydantic-ai-slim[huggingface]"

[Kludex]

I think we are good here.

Thanks for handling all the coverage! :)