# huggingfaceR (development version) ## New features * Functions that send one request per input can now send several at once (#72). `hf_summarize()`, `hf_translate()`, `hf_ner()`, `hf_question_answer()`, `hf_table_question_answer()`, `hf_fill_mask()`, `hf_classify_zero_shot()`, `hf_generate()`, `hf_extract()`, `hf_classify_image()`, `hf_caption_image()`, `hf_detect_objects()`, `hf_describe_image()`, `hf_text_to_image()`, `hf_text_to_speech()`, and `hf_transcribe()` gain a `max_active` argument. It defaults to `getOption("huggingfaceR.max_active", 1L)`, so requests stay sequential unless you opt in. Results keep their input order, and the first failing input still stops the call with its error. Each request is billed, so a higher `max_active` spends credits faster but not in larger amounts. * `hf_load_dataset()` requests every page after the first together, up to `max_active` at a time (default 4). Loading 3,000 rows took about 2 seconds instead of 3.6. * `hf_load_dataset(format = "parquet")` reads a split from its Parquet export with the arrow package. A complete split often needs one request instead of one per 100 rows, which is faster and stays well inside rate limits. * New dataset viewer helpers query a split without loading it. `hf_dataset_search()` runs full-text search, `hf_dataset_filter()` selects rows with a SQL-style condition, `hf_dataset_statistics()` returns the per-column summaries and histograms the Hub computes, and `hf_dataset_validity()` reports which of these features work for a dataset. * `hf_search_models()` gains `inference_provider`, which keeps only models served by the named Inference Providers. Use `"all"` for any provider. ## Rate limits and billing * Requests that hit a Hugging Face rate limit (HTTP 429) now wait as long as the server asks, read from the `Retry-After` or `RateLimit` header, for up to 5 minutes. Before, retries used a short backoff that ended long before the 5-minute rate-limit window reset. * A 429 now explains the 5-minute limit window, notes that requests with a token get higher limits, and links the rate-limit documentation. Dataset calls also suggest `format = "parquet"` for large loads. * An exhausted credit balance (HTTP 402) now has its own message. Free accounts no longer include monthly Inference Providers credits, so it points to the billing page instead of suggesting a wait. * The README and vignettes describe current Inference Providers billing and routing. The first-party `hf-inference` provider has served CPU tasks such as classification and embeddings since July 2025, so chat and generation go to third-party providers through the router. ## Bug fixes * Batch functions no longer retry a failing request forever. Repeated 429 or 503 responses are retried a bounded number of times and then reported as errors. * Dropped connections and timeouts are now retried like other transient failures. * Images and audio already written by `hf_text_to_image()` and `hf_text_to_speech()` are kept when a later input fails. * `hf_describe_image()` streams one image at a time instead of failing when `max_active` is greater than 1. * `hf_embed_umap()` no longer fails when some `text` is `NA`. It returns one row per input with `NA` coordinates for the missing ones. * `hf_embed_umap()`, `hf_cluster_texts()`, and `step_hf_embed()` stop with a clear error when embeddings have different lengths, instead of recycling the shorter ones. # huggingfaceR 2.4.0 ## Performance These changes remove interpreted loops and repeated work from the R code that runs around each request. Hosted calls remain bounded by network latency and server-side inference, which a client written in any language must wait for. Functions that send one request per input, such as `hf_summarize()`, `hf_translate()`, and `hf_ner()`, still send those requests one at a time. An opt-in way to run them concurrently is tracked in #72. * `hf_similarity()` builds its pairs with vectorized primitives instead of `utils::combn()` and scores each embedding dimension with one BLAS cross-product. Inputs with mixed dimensions no longer fall back to an R loop over every pair, and embeddings with missing or infinite values now give `NA` similarities instead of an error. * `hf_nearest_neighbors()` scores the corpus with blocked matrix-vector products instead of one R function call per row. Embeddings that are non-numeric, zero-norm, or of a different dimension than the query now score `NA`. Previously they raised an error, returned `NaN`, or were silently recycled with a warning. * `hf_embed_batch()`, `hf_classify_batch()`, and `hf_classify_zero_shot_batch()` resolve the provider and build the request once per call, then write results straight into columns instead of building, binding, and sorting a tibble for every batch or label. A response with more embeddings than texts is now truncated with a warning instead of failing. * Embedding responses are parsed with the optional 'RcppSimdJson' package when it is installed. Well-formed numeric arrays go straight into a matrix instead of one R object per number, and any other shape falls back to 'jsonlite', so the embeddings returned are the same. Set `options(huggingfaceR.simdjson = FALSE)` to always use 'jsonlite'. * `hf_load_dataset()` and the paginated Hub searches combine pages once rather than growing a list on every request, and dataset rows are converted to columns with primitive field access. * `hf_search_models()`, `hf_search_datasets()`, `hf_search_spaces()`, `hf_search_papers()`, `hf_list_repo_files()`, and `hf_list_providers()` bind records by column instead of building a tibble for every record. * `step_hf_embed()` adds all embedding columns in one assignment when baked. * A developer workflow profiles these paths against the 2.3.0 release with HTTP mocked, and fails if any output changes. ## Dependencies * huggingfaceR now requires httr2 1.1.1 or later. Embedding and classification functions call `httr2::req_perform_parallel()` with its `max_active` argument, and streaming chat uses `httr2::req_perform_connection()`. Neither exists in earlier httr2 releases, so those functions failed with them. * The declared minimum versions of cli (3.0.0), dplyr (1.0.0), recipes (1.0.4), and testthat (3.1.7) now match the functions the package and its tests use. * 'RcppSimdJson' is a new suggested package, used only when installed. # huggingfaceR 2.3.0 ## Optional local models * `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. * Local loading keeps tokenizer and weights in the same snapshot, refuses remote custom code, supports cached offline use, and never falls back to hosted inference. Existing API-first functions and defaults are unchanged. Embedding snapshots require Sentence Transformers module metadata so a partial cache cannot silently change the model's pooling configuration. * A new local-model vignette and standalone online/offline validation script cover real downloads, predictions, and reuse across fresh R sessions. * Local internals are separated into public operations, Python integration, and validation/error handling. Loading a Hub model initializes its Python environment and validates its snapshot once, without introducing a session-wide validation cache. * Developer profiling compares the installed pre-refactor and current versions on the same native Linux runner, including cached loading, Python-native inference, R wrapper allocations, and unchanged prediction results. # huggingfaceR 2.2.0 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. ## Scope of task-based inference 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. ## Bug fixes * **`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. ## New features * **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. ## Improvements * 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. ## Known limitations * Provider availability is read from the Hub at call time and can change; a provider may report `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. * The cache is keyed by model and by whether a token was supplied, not by token value. Switching between tokens with different access within one session may reuse a mapping; clear the cache when doing so. * Third-party providers are not used for task requests. Reaching them requires provider-specific adapters, which this release does not implement. * An empty or unavailable Hub provider mapping is treated as "unknown" and the historical `hf-inference` route is still attempted, so Hub metadata gaps cannot block a request that would otherwise have worked. # huggingfaceR 2.1.0 ## New features * `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). ## Improvements * **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. # huggingfaceR 2.0.0 ## Breaking changes * 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. ## New features * **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. ## Improvements * 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.