llm_client.py

"""
LLM client backed by Hugging Face Inference Providers.

The original chatbot was built against Azure OpenAI and the agents call:

    client.chat.completions.create(
        model=client._default_deployment,
        messages=[...],
        temperature=0,
    )

`huggingface_hub.InferenceClient` already exposes an OpenAI-compatible
``client.chat.completions.create(...)`` surface, so we just need to attach the
default model name as an attribute and the rest of the agent code works unchanged.
"""
from __future__ import annotations

import os
from typing import Any


DEFAULT_MODEL = "meta-llama/Llama-3.3-70B-Instruct"
DEFAULT_PROVIDER = "auto"


class MissingHFTokenError(RuntimeError):
    """Raised when no HF_TOKEN is available to authenticate with Inference Providers."""


def get_hf_token() -> str | None:
    """Return the first non-empty HF token from the usual environment variables."""
    for var in ("HF_TOKEN", "HUGGING_FACE_HUB_TOKEN", "HUGGINGFACEHUB_API_TOKEN"):
        value = os.environ.get(var, "").strip()
        if value:
            return value
    return None


def create_chat_client(
    model: str | None = None,
    provider: str | None = None,
    token: str | None = None,
) -> Any:
    """
    Create an `InferenceClient` configured for chat completions.

    The returned client exposes ``client.chat.completions.create(...)`` and is tagged
    with a ``_default_deployment`` attribute that the agents read as the model name.

    Parameters
    ----------
    model : str, optional
        HF model id (e.g. ``meta-llama/Llama-3.3-70B-Instruct``). Falls back to the
        ``HF_MODEL`` env var, then to :data:`DEFAULT_MODEL`.
    provider : str, optional
        HF Inference Providers routing (``auto``, ``hf-inference``, ``together``,
        ``cerebras``, …). Falls back to the ``HF_PROVIDER`` env var, then to ``auto``.
    token : str, optional
        Explicit HF token. Falls back to ``HF_TOKEN`` / ``HUGGING_FACE_HUB_TOKEN``.

    Raises
    ------
    MissingHFTokenError
        If no token is available — the Space cannot make LLM calls without one.
    """
    try:
        from huggingface_hub import InferenceClient
    except ImportError as exc:
        raise ImportError(
            "huggingface_hub is required. Install with `pip install huggingface_hub`."
        ) from exc

    model_id = (model or os.environ.get("HF_MODEL") or DEFAULT_MODEL).strip()
    provider_id = (provider or os.environ.get("HF_PROVIDER") or DEFAULT_PROVIDER).strip()
    hf_token = (token or get_hf_token() or "").strip()

    if not hf_token:
        raise MissingHFTokenError(
            "No Hugging Face token found. Set `HF_TOKEN` in the Space secrets "
            "(Settings → Variables and secrets) or in your local environment."
        )

    client = InferenceClient(
        provider=provider_id,
        token=hf_token,
        model=model_id,
    )
    client._default_deployment = model_id  # type: ignore[attr-defined]
    client._default_provider = provider_id  # type: ignore[attr-defined]
    return client


def describe_client(client: Any) -> dict:
    """Return a small dict describing the client config (handy for the UI)."""
    return {
        "model": getattr(client, "_default_deployment", "unknown"),
        "provider": getattr(client, "_default_provider", "unknown"),
    }