# 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.