hf_load_local_model() uses
processor_kwargs on newer Sentence Transformers interfaces,
avoiding the deprecated tokenizer_kwargs argument, while
retaining compatibility with older constructors and preserving
local-only loading flags.hf_local_setup(), hf_download_model(), and
hf_load_local_model() provide an explicit setup,
revision-aware download, and reusable local-model workflow. Python
dependencies are optional and are not initialized at package load.hf_embed_local() and hf_classify_local()
run standard safetensors-based embedding and text-classification models
on the CPU by default, returning the same tidy columns as their API
counterparts. Input order, duplicates, and missing values are
preserved.This release re-aligns the package with the current Hugging Face
Inference Providers platform. Since mid-2025 the first-party
hf-inference provider has narrowed to CPU-friendly classic
models, and several models the package shipped as defaults are no longer
served by it.
huggingfaceR’s task functions (hf_classify(),
hf_summarize(), hf_embed(),
hf_text_to_image() and friends) speak the Hugging Face
task API contract: POST .../models/{model}
with an {"inputs": ...} body. Only the first-party
hf-inference provider implements that contract. Other
Inference Providers (Fal AI, nscale, DeepInfra, Together, and so on)
expose their own routes, payloads, and response shapes, and are
reachable through the Hugging Face clients rather than this
contract.
This release makes that boundary explicit instead of silently
producing confusing failures. Chat (hf_chat(),
hf_generate(), hf_describe_image()) is
unaffected: it uses the OpenAI-compatible router endpoint, which selects
a provider server-side and supports every routed chat model.
hf_load_dataset() no longer multiplies rows
for datasets with variable-length fields (#61). Row payloads
were converted with tibble::as_tibble(), which recycles a
row to the length of its longest field. A dataset such as
openai/gdpval, whose rows carry fields like
reference_files, therefore returned more rows than
requested: asking for 3 rows returned 8, silently duplicating scalar
values. Fields that are ever non-scalar are now returned as
list-columns, so one source row always yields exactly one output row.
Scalar fields are unchanged, and a JSON null is still read
as NA rather than forcing a list-column.
Documentation links updated. 36 links pointed at
huggingface.co/docs/api-inference, which Hugging Face
retired; they now point at the corresponding Inference Providers task
pages. This also clears an R CMD check --as-cran NOTE about
unreachable URLs.
Short dataset names resolve more reliably.
hf_load_dataset("imdb") expands short names to their full
owner/name form by querying the Hub. That lookup had no
retry, so a transient network failure silently fell through to the
unexpanded name and surfaced as a confusing “dataset has been renamed”
error. The lookup now retries, and if it still cannot expand the name
the error says so and suggests passing the full ID.
Unroutable models now fail with an actionable
error. Task requests previously went to
hf-inference unconditionally, so a model that provider does
not serve returned an opaque “not found”. The package now checks the
Hub’s provider mapping and raises an error naming the providers that do
serve the model, and suggesting endpoint_url for a
dedicated Inference Endpoint. Resolved mappings are cached for the
session. If the Hub is unreachable the historical
hf-inference route is used unchanged, so Hub metadata is
not a new hard dependency for models that already worked.
hf_text_to_image() default
replaced. The previous default,
black-forest-labs/FLUX.1-schnell, is served only by
third-party providers and so was never reachable through the task
contract. The default is now
stabilityai/stable-diffusion-3-medium-diffusers, which
hf-inference serves. It is a gated model: accept the
licence on its model page once before first use.
hf_text_to_speech() default replaced, and
its limits documented. The previous default,
facebook/mms-tts-eng, is no longer served by any Inference
Provider. The default is now hexgrad/Kokoro-82M. Note that
hf-inference currently serves no
text-to-speech model, so serverless text-to-speech is not reachable
through the task contract; the function now says so clearly and points
to endpoint_url.
HF_TOKEN is now recognised. The
package previously read only the legacy
HUGGING_FACE_HUB_TOKEN, so a token configured by following
current Hugging Face documentation (or set up for the hf
CLI or Python client) was ignored and users were told no token was
found. HF_TOKEN is now checked first, with
HUGGING_FACE_HUB_TOKEN still honoured as a fallback. This
also applies to the legacy hf_inference() and
hf_ez_*() functions, which previously read the legacy
variable directly.
hf_list_providers() now covers non-chat
models. It previously queried only the router catalogue, which
contains chat-completion models, and so returned an empty tibble for
embedding, classification, and other task models. It now merges the Hub
provider mapping (all models, all tasks) with router pricing and latency
metrics where available, and gained a task column. Select
columns by name rather than position.
Router routing policies are no longer mistaken for
providers. Model specifications such as
model:cheapest, model:fastest, and
model:preferred were previously treated as literal provider
names and would have produced invalid task URLs. These policies are
resolved by the router for chat completions, where they
are passed through unchanged; for task requests the suffix is now
recognised and ignored rather than corrupting the route.
Organization billing. Set the
HF_BILL_TO environment variable to send the
X-HF-Bill-To header so Team and Enterprise usage is billed
to the organization instead of the individual user.
hf_clear_provider_cache() discards the session’s
cached provider mappings, which is useful after provider availability
changes.
Token errors now link to the fine-grained token page with the required “Make calls to Inference Providers” permission, and rate-limit errors mention the monthly credit allowance.
Documentation describes the Inference Providers token permission,
HF_TOKEN, organization billing, and the
hf-inference task-contract boundary, and no longer links to
the retired huggingface.co/docs/api-inference
page.
status = "error" transiently.
Successful lookups are cached for 15 minutes and failed lookups for 60
seconds; call hf_clear_provider_cache() to discard them
sooner.hf-inference route is still attempted,
so Hub metadata gaps cannot block a request that would otherwise have
worked.hf_extract() turns unstructured text into tidy
columns with chat-model structured JSON output. Pass a lightweight named
schema such as c(name = "string", score = "number") or a
full JSON Schema list, and the function returns one row per input text
with one column per schema field (#55).
hf_chat() now supports tool/function calling,
streaming callbacks, and image inputs for vision-capable chat models.
New helpers hf_tool(), hf_run_tools(), and
hf_describe_image() make these capabilities available from
R pipelines (#55).
Multimodal inference wrappers. New functions add
audio, image, and generation workflows: hf_transcribe(),
hf_text_to_image(), hf_classify_image(),
hf_caption_image(), hf_detect_objects(), and
hf_text_to_speech() (#55). Live verification passed for
ASR, text-to-image, image classification, captioning, and object
detection; public hosted TTS provider support is currently blocked, so
hf_text_to_speech() is documented for compatible providers
or dedicated Inference Endpoints.
Hub files, providers, and guarded writes. New
Hub helpers include hf_hub_download(),
hf_list_repo_files(), hf_search_spaces(),
hf_search_papers(), hf_list_providers(),
hf_create_repo(), hf_upload_file(),
hf_push_dataset(), and guarded
hf_delete_repo() (#55). Search helpers now follow Hub
pagination links, and write/destructive operations require
confirm = TRUE.
First-class text tasks. New API-first,
tidyverse-native wrappers round out the text toolkit, each accepting
character vectors and returning tibbles: hf_summarize()
(summarization), hf_translate() (translation),
hf_ner() (named-entity recognition, one tidy row per entity
with character offsets), hf_question_answer() (extractive
QA), and hf_table_question_answer() (ask a data frame a
question in plain language).
Centralized default models. A new exported
helper, hf_default_model(), is the single source of truth
for every task’s default model. All hf_* functions now
resolve their model default through it (no behavior change
— the resolved values are identical), so defaults can be audited or
updated in one place. Call hf_default_model() to see the
whole registry, or hf_default_model("translate") for a
single task’s default.
hf_whoami() now returns billing/pro status and
token-role metadata so users can check whether their token is read-only
or write-capable before Hub write operations.
Beginner-friendly default translation model.
hf_translate() now defaults to
Helsinki-NLP/opus-mt-en-fr (English to French) instead of
facebook/nllb-200-distilled-600M. The Helsinki-NLP
opus-mt-* family encodes the translation direction in the
model ID, so hf_translate("Hello") works with no FLORES-200
language codes — a smoother first experience. NLLB remains fully
supported for multilingual translation via the model,
source, and target arguments.
Unified request engine with inference-provider
routing. Internal request construction is consolidated in
R/request.R (hf_parse_model(),
hf_inference_url(), hf_error_body(),
hf_is_transient(), hf_task_request()). As a
result, the model = "id:provider" suffix now selects an
inference provider for all serverless tasks — including
embeddings, classification, and the new text tasks — not just chat.
Retries now back off only on genuinely transient status codes (429/5xx),
and error messages are consistent across every inference
function.
The package no longer requires Python or reticulate for core functionality. All inference is handled through the Hugging Face Inference API via httr2. Legacy functions that depend on Python/reticulate remain available but are not required for new workflows.
Default chat and generation model changed from
HuggingFaceTB/SmolLM3-3B to
meta-llama/Llama-3.1-8B-Instruct, which has broader
provider support.
API-first architecture: All core functions
(hf_classify(), hf_embed(),
hf_chat(), hf_generate(),
hf_fill_mask()) use the Hugging Face Inference API
directly. No Python installation needed.
Text classification: hf_classify()
for sentiment analysis and hf_classify_zero_shot() for
custom label classification without training.
Embeddings and similarity:
hf_embed() generates dense vector representations.
hf_similarity() computes pairwise cosine similarity.
hf_nearest_neighbors(), hf_cluster_texts(),
and hf_extract_topics() provide higher-level semantic
analysis. hf_embed_umap() reduces embeddings to 2D for
visualization.
Chat and generation: hf_chat() for
single-turn LLM interaction with system prompts.
hf_conversation() and chat() for multi-turn
conversations with persistent history. hf_generate() for
text completion. hf_fill_mask() for BERT-style masked token
prediction.
Hub discovery: hf_search_models(),
hf_model_info(), hf_search_datasets(),
hf_dataset_info(), and hf_list_tasks() for
exploring the Hugging Face Hub from R.
Datasets: hf_load_dataset() loads
dataset rows directly into tibbles, with support for splits, pagination,
and column selection.
Batch processing: hf_embed_batch(),
hf_classify_batch(), and
hf_classify_zero_shot_batch() process large inputs with
parallel requests. hf_embed_chunks() and
hf_classify_chunks() add disk checkpointing for datasets
too large to hold in memory.
tidymodels integration:
step_hf_embed() recipe step embeds text columns as part of
a tidymodels preprocessing pipeline.
tidytext integration:
hf_embed_text() works directly with data frame text columns
for tidytext-style workflows.
Model availability checking:
hf_check_inference() queries model metadata to verify
whether a model supports the free serverless Inference API before you
make inference calls.
Dedicated Inference Endpoints: All inference
functions accept an endpoint_url parameter to route
requests to a dedicated Inference Endpoint instead of the public
serverless API. This supports models not available on the free tier and
production workloads requiring dedicated capacity.
All functions return tibbles and accept character vectors, enabling natural composition with dplyr, tidyr, and the rest of the tidyverse.
Improved error messages for 404 responses explain that the model
may exist on the Hub but not be available for serverless inference, and
suggest using hf_check_inference().
Documentation updated to clarify that the Inference API serves a curated subset of the Hub’s 500,000+ models, not all of them.