[Feature Request] Add Hugging Face Provider (Inference API & Local Transformers)

[Leo-le-jeune]

Is your feature request related to a problem? Please describe.

Celeste currently abstracts providers like OpenAI, Anthropic, and Gemini wonderfully using a unified celeste.text.generate interface. However, users needing open-weights models (via Hugging Face) or offline capabilities are forced to bypass Celeste and lose the benefits of its type-safety and unified Content objects.

Describe the solution you'd like

I propose adding a huggingface (and/or local) provider integration that fits into the existing model string syntax. This would allow users to switch to open-source models without changing their code structure.

Proposed Usage Example

The integration should follow the existing async/await pattern found in the docs :

import celeste
import asyncio

async def main():
    # Scenario 1: Hugging Face Inference API (Serverless)
    # Proposed syntax: provider prefix "huggingface/"
    api_response = await celeste.text.generate(
        "Explain quantum entanglement.", 
        model="huggingface/meta-llama/Meta-Llama-3-70b-Instruct"
    )
    print(api_response.content)

    # Scenario 2: Local Inference (Offline / Transformers)
    # Proposed syntax: provider prefix "local/" or "transformers/"
    # This would require optional dependencies (pip install celeste[local])
    local_response = await celeste.text.generate(
        "Analyze this text.", 
        model="local/mistralai/Mistral-7B-Instruct-v0.2"
    )
    print(local_response.content)

if __name__ == "__main__":
    asyncio.run(main())

Implementation Details

• API Mode: Should wrap huggingface_hub.AsyncInferenceClient.
• Local Mode: Should wrap transformers.pipeline or AutoModelForCausalLM inside a thread pool to avoid blocking the asyncio event loop.
• Configuration: API keys for Hugging Face could be loaded from HUGGINGFACE_API_KEY env var, similar to ANTHROPIC_API_KEY.

Additional context

This would make Celeste the go-to SDK for hybrid AI strategies (Cloud + Local), allowing "Social Hacker" style workflows where sensitive data stays local while general queries go to the cloud.

🤖 Generated with Gemini

[Kamilbenkirane]

Thanks for the proposal @Leo-le-jeune!

Agreed with Scenario 1 (HF Inference API), it fits Celeste's architecture naturally since it's a standard HTTP endpoint. ✅

For local models, the supported pattern is running an inference server (Ollama, vLLM, text-generation-inference) and pointing Celeste at it via base_url. So local transformers within Celeste is out of scope.

We'll scope this issue to the HF Inference API provider only, I'll release it before the end of the week :)

[Leo-le-jeune]

Thank you for the quick feedback and for clarifying the architectural direction.

The base_url pattern makes perfect sense - it keeps CelesteAI lightweight while still guaranteeing our freedom to use open-source models through inference servers like Ollama or vLLM. This approach perfectly fits a privacy-focused and 'sovereign' workflow.

I will proceed with this pattern for my local integrations. Thanks again for the great work on this SDK!

[Leo-le-jeune]

P.S. Since version 0.10.2 is now live, the documentation at withceleste/docs might need a quick refresh to include the new huggingface/ model prefix and the HF_TOKEN requirement. To save you some time, you might want to task your Claude agent with drafting those updates. It would be a great way to keep the docs in sync with your rapid shipping pace!