Package {huggingfaceR}

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling 'rhs(lhs)'.

Examples

1:3 %>% sum()

Split Vector into Batches

Description

Internal helper to split a vector into batches with index tracking.

Usage

batch_vector(x, batch_size)

Arguments

Value

A list of lists, each containing: - 'value': The batch values - 'indices': The original indices of the values

Continue a Conversation

Description

Add a message to an existing conversation and get a response.

Usage

chat(conversation, message, ...)

Arguments

Value

Updated conversation object with new messages in history.

Examples

## Not run: 
convo <- hf_conversation()
convo <- chat(convo, "Tell me a joke")

## End(Not run)

Make a Request to Hugging Face Inference API

Description

Internal helper function to construct and execute API requests.

Usage

hf_api_request(
  model_id,
  inputs,
  parameters = NULL,
  token = NULL,
  wait_for_model = TRUE,
  use_cache = TRUE,
  endpoint_url = NULL
)

Arguments

Value

The raw response from the API.

Build a Hugging Face API Request

Description

Internal factory function to construct httr2 request objects for batch processing.

Usage

hf_build_request(
  model_id,
  inputs,
  parameters = NULL,
  token = NULL,
  wait_for_model = TRUE,
  use_cache = TRUE,
  endpoint_url = NULL
)

Arguments

Value

An httr2 request object ready for execution.

Caption Images

Description

Generate short image captions. This uses a vision-capable chat model by default because the public 'hf-inference' provider did not expose a broadly available image-to-text captioning model during verification.

Usage

hf_caption_image(
  image,
  prompt = "Write a short, factual caption for this image.",
  model = hf_default_model("caption_image"),
  max_tokens = 80,
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: image, caption.

See Also

hf_describe_image

Examples

## Not run: 
hf_caption_image("cat.png")

## End(Not run)

LLM Chat Interface

Description

Have a conversation with an open-source language model via the Inference Providers API. Tool calling support depends on the model/provider. The default chat model is optimized for a low-friction first call; for tool-calling examples, use a tool-capable model such as "Qwen/Qwen2.5-72B-Instruct".

Usage

hf_chat(
  message,
  system = NULL,
  model = hf_default_model("chat"),
  max_tokens = 500,
  temperature = 0.7,
  token = NULL,
  tools = NULL,
  tool_choice = NULL,
  stream = FALSE,
  callback = NULL,
  image = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: role, content, model, tokens_used, and tool_calls.

Examples

## Not run: 
# Simple question
hf_chat("What is the capital of France?")

# With system prompt
hf_chat(
  "Explain gradient descent",
  system = "You are a statistics professor. Use simple analogies."
)

# Use a specific provider
hf_chat("Hello!", model = "meta-llama/Llama-3-8B-Instruct:together")

# Stream response deltas
hf_chat("Reply with exactly: OK", stream = TRUE)

## End(Not run)

Check Inference API Availability

Description

Check whether a model supports the Hugging Face Serverless Inference API. Not all models on the Hub are served by the Inference API. This function queries model metadata to determine availability before you make inference calls.

Usage

hf_check_inference(model_id, token = NULL, quiet = FALSE)

Arguments

Value

A list (invisibly if quiet = TRUE) with components:

Examples

## Not run: 
# Check if a model supports serverless inference
hf_check_inference("BAAI/bge-small-en-v1.5")

# Use programmatically
result <- hf_check_inference("some-org/some-model", quiet = TRUE)
if (result$available) {
  embeddings <- hf_embed("hello", model = "some-org/some-model")
}

## End(Not run)

Text Classification

Description

Classify text using a Hugging Face model. Commonly used for sentiment analysis, topic classification, etc. Vector inputs are sent in a single batched Inference API request when possible, which is substantially faster than one API request per text.

Usage

hf_classify(
  text,
  model = hf_default_model("classify"),
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: text, label, score

Examples

## Not run: 
# Sentiment analysis
hf_classify("I love R programming!")

# Multiple texts
hf_classify(c("This is great!", "This is terrible."))

# Use in a pipeline
library(dplyr)
reviews |>
  mutate(sentiment = hf_classify(review_text)) |>
  unnest(sentiment)

## End(Not run)

Batch Text Classification (In-Memory)

Description

Classify multiple texts in parallel. This function processes all inputs in memory and returns results in a single tibble.

Usage

hf_classify_batch(
  text,
  model = hf_default_model("classify"),
  token = NULL,
  batch_size = 100L,
  max_active = 10L,
  progress = TRUE,
  endpoint_url = NULL
)

Arguments

Value

A tibble with columns: - 'text': Original input text - 'label': Predicted label - 'score': Confidence score - '.input_idx': Original position in input vector - '.error': TRUE if request failed - '.error_msg': Error message or NA

Examples

## Not run: 
# Classify many texts in parallel
texts <- c("I love this!", "This is terrible.", "Meh, it's okay.")
result <- hf_classify_batch(texts, max_active = 5)

# Check for errors
errors <- result[result$.error, ]

## End(Not run)

Chunked Text Classification (Disk Checkpoints)

Description

Classify large datasets with automatic checkpointing to disk. Supports resuming interrupted processing.

Usage

hf_classify_chunks(
  text,
  output_dir,
  model = hf_default_model("classify"),
  token = NULL,
  chunk_size = 1000L,
  batch_size = 100L,
  max_active = 10L,
  resume = TRUE,
  progress = TRUE,
  endpoint_url = NULL
)

Arguments

Value

Invisibly returns the output directory path. Use 'hf_read_chunks()' to read results.

Examples

## Not run: 
# Process large dataset with checkpoints
texts <- rep("sample text", 5000)
hf_classify_chunks(texts, output_dir = "classify_output", chunk_size = 1000)

# Read results
results <- hf_read_chunks("classify_output")

## End(Not run)

Classify Images

Description

Classify images using an image-classification model via the Hugging Face Inference Providers API.

Usage

hf_classify_image(
  image,
  top_k = 5L,
  model = hf_default_model("classify_image"),
  token = NULL,
  endpoint_url = NULL,
  content_type = NULL,
  ...
)

Arguments

Value

A tibble with columns: image, label, score.

See Also

https://huggingface.co/docs/inference-providers/tasks/image-classification

Examples

## Not run: 
hf_classify_image("cat.png", top_k = 3)

## End(Not run)

Zero-Shot Classification

Description

Classify text into custom categories without training a model. The model determines which labels best describe the input text.

Usage

hf_classify_zero_shot(
  text,
  labels,
  model = hf_default_model("zero_shot"),
  multi_label = FALSE,
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: text, label, score (sorted by score descending)

Examples

## Not run: 
# Classify into custom categories
hf_classify_zero_shot(
  "I just bought a new laptop",
  labels = c("technology", "sports", "politics", "food")
)

# Multi-label classification
hf_classify_zero_shot(
  "This laptop is great for gaming",
  labels = c("technology", "gaming", "entertainment"),
  multi_label = TRUE
)

## End(Not run)

Batch Zero-Shot Classification (In-Memory)

Description

Classify multiple texts into custom categories in parallel without training.

Usage

hf_classify_zero_shot_batch(
  text,
  labels,
  model = hf_default_model("zero_shot"),
  multi_label = FALSE,
  token = NULL,
  batch_size = 50L,
  max_active = 10L,
  progress = TRUE,
  endpoint_url = NULL
)

Arguments

Value

A tibble with columns: - 'text': Original input text - 'label': Predicted label (or labels if multi_label) - 'score': Confidence score(s) - '.input_idx': Original position in input vector - '.error': TRUE if request failed - '.error_msg': Error message or NA

Examples

## Not run: 
texts <- c("I love my new laptop", "The game was exciting", "This recipe is delicious")
labels <- c("technology", "sports", "food")
result <- hf_classify_zero_shot_batch(texts, labels, max_active = 5)

## End(Not run)

Cluster Texts by Semantic Similarity

Description

Perform k-means clustering on text embeddings.

Usage

hf_cluster_texts(data, k = 3, ...)

Arguments

Value

The input data frame with an added 'cluster' column.

Examples

## Not run: 
library(ggplot2)

# Cluster documents
docs_clustered <- docs_embedded |>
  hf_cluster_texts(k = 3)

# Reduce dimensions and visualize
library(uwot)
emb_matrix <- do.call(rbind, docs_clustered$embedding)
coords <- umap(emb_matrix)

docs_clustered |>
  mutate(umap_1 = coords[, 1], umap_2 = coords[, 2]) |>
  ggplot(aes(umap_1, umap_2, color = factor(cluster))) +
  geom_point(size = 3)

## End(Not run)

Multi-turn Conversation

Description

Create and manage a multi-turn conversation with an LLM.

Usage

hf_conversation(
  system = NULL,
  model = hf_default_model("chat"),
  endpoint_url = NULL
)

Arguments

Value

A conversation object (list) that can be extended with chat().

Examples

## Not run: 
# Create conversation
convo <- hf_conversation(system = "You are a helpful R tutor.")

# Add messages (see chat() method)
convo <- chat(convo, "How do I read a CSV?")
convo <- chat(convo, "What about Excel files?")

# View history
convo$history

## End(Not run)

Create a Hub Repository

Description

Create a model, dataset, or Space repository. This is a write operation and requires an API token with write scope plus 'confirm = TRUE'.

Usage

hf_create_repo(
  repo_id,
  repo_type = "model",
  private = FALSE,
  exist_ok = FALSE,
  token = NULL,
  confirm = FALSE
)

Arguments

Value

The parsed Hub API response.

Examples

## Not run: 
hf_create_repo("my-dataset", repo_type = "dataset", private = TRUE, confirm = TRUE)

## End(Not run)

Get Dataset Information

Description

Retrieve metadata about a dataset from Hugging Face Hub.

Usage

hf_dataset_info(dataset, token = NULL)

Arguments

Value

A list with dataset information.

Examples

## Not run: 
hf_dataset_info("imdb")

## End(Not run)

Default Models for Hugging Face Tasks

Description

Central registry of the default model used by each 'huggingfaceR' inference function. Every 'hf_*' function that takes a 'model' argument resolves its default through this single function, so default models live in exactly one place and can be audited or updated without hunting through the codebase.

Usage

hf_default_model(task = NULL)

Arguments

Details

Defaults are chosen to be **beginner-friendly**: broadly known, small and fast, low cost, and usable with no extra arguments — the goal is the quickest path to a working first call (think of 'mtcars' in base R). Power users can always override any default by passing their own 'model'.

Value

When 'task' is supplied, a single model-ID character string. When 'task' is 'NULL', a tibble with columns 'task' and 'model' listing every default.

Examples

# The default model for a given task
hf_default_model("translate")

# The whole registry at a glance
hf_default_model()

Delete a Hub Repository

Description

Delete a model, dataset, or Space repository. This destructive operation is guarded: it requires 'confirm = TRUE' and is refused when 'CI=true'.

Usage

hf_delete_repo(repo_id, repo_type = "model", token = NULL, confirm = FALSE)

Arguments

Value

The parsed Hub API response.

Examples

## Not run: 
hf_delete_repo("me/old-test-dataset", repo_type = "dataset", confirm = TRUE)

## End(Not run)

Describe an Image

Description

Ask a vision-capable chat model to describe an image.

Usage

hf_describe_image(
  image,
  prompt = "Describe this image.",
  model = hf_default_model("vision_chat"),
  max_tokens = 200,
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: image, description.

Examples

## Not run: 
image <- paste0(
  "https://huggingface.co/datasets/huggingface/",
  "documentation-images/resolve/main/cat.png"
)
hf_describe_image(image)

## End(Not run)

Detect Default Config for a Dataset

Description

Query the splits endpoint to find the default config for a given dataset and split.

Usage

hf_detect_config(dataset, split, token = NULL)

Arguments

Value

Character string with the config name.

Detect Objects in Images

Description

Detect objects and bounding boxes in images using an object-detection model via the Hugging Face Inference Providers API.

Usage

hf_detect_objects(
  image,
  threshold = NULL,
  model = hf_default_model("detect_objects"),
  token = NULL,
  endpoint_url = NULL,
  content_type = NULL,
  ...
)

Arguments

Value

A tibble with columns: image, label, score, xmin, ymin, xmax, ymax.

See Also

https://huggingface.co/docs/inference-providers/tasks/object-detection

Examples

## Not run: 
boxes <- hf_detect_objects("cat.png", threshold = 0.5)
boxes

## End(Not run)

Generate Text Embeddings

Description

Generate dense vector representations (embeddings) for text using transformer models. Useful for semantic similarity, clustering, and as features for ML models. Vector inputs are sent in a single batched Inference API request when possible, which is substantially faster than one API request per text.

Usage

hf_embed(
  text,
  model = hf_default_model("embed"),
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: text, embedding (list-column of numeric vectors), n_dims

Examples

## Not run: 
# Generate embeddings
embeddings <- hf_embed(c("Hello world", "Goodbye world"))

# Access embedding vectors
embeddings$embedding[[1]]  # First embedding vector

## End(Not run)

Batch Embedding Generation (In-Memory)

Description

Generate embeddings for multiple texts in parallel. This function processes all inputs in memory and returns results in a single tibble.

Usage

hf_embed_batch(
  text,
  model = hf_default_model("embed"),
  token = NULL,
  batch_size = 100L,
  max_active = 10L,
  progress = TRUE,
  endpoint_url = NULL
)

Arguments

Value

A tibble with columns: - 'text': Original input text - 'embedding': List-column of numeric vectors - 'n_dims': Dimension of embedding (or NA on error) - '.input_idx': Original position in input vector - '.error': TRUE if request failed - '.error_msg': Error message or NA

Examples

## Not run: 
# Embed many texts in parallel
texts <- c("Hello world", "Goodbye world", "R is great")
result <- hf_embed_batch(texts, max_active = 5)

# Check for errors
errors <- result[result$.error, ]

## End(Not run)

Chunked Embedding Generation (Disk Checkpoints)

Description

Generate embeddings for large datasets with automatic checkpointing to disk. Supports resuming interrupted processing.

Usage

hf_embed_chunks(
  text,
  output_dir,
  model = hf_default_model("embed"),
  token = NULL,
  chunk_size = 1000L,
  batch_size = 100L,
  max_active = 10L,
  resume = TRUE,
  progress = TRUE,
  endpoint_url = NULL
)

Arguments

Value

Invisibly returns the output directory path. Use 'hf_read_chunks()' to read results.

Examples

## Not run: 
# Process large dataset with checkpoints
texts <- rep("sample text", 5000)
hf_embed_chunks(texts, output_dir = "embeddings_output", chunk_size = 1000)

# Read results
results <- hf_read_chunks("embeddings_output")

# Resume interrupted processing
hf_embed_chunks(more_texts, output_dir = "embeddings_output", resume = TRUE)

## End(Not run)

Embed Text with Tidytext Compatibility

Description

Generate embeddings for text in a tidy data frame. Designed to work seamlessly with tidytext workflows.

Usage

hf_embed_text(
  data,
  text_col,
  model = hf_default_model("embed"),
  token = NULL,
  keep_text = TRUE
)

Arguments

Value

The input data frame with added embedding and n_dims columns.

Examples

## Not run: 
library(dplyr)
library(tidytext)

# Embed documents
docs <- tibble(
  doc_id = 1:3,
  text = c("I love R", "Python is great", "Julia is fast")
)

docs_embedded <- docs |>
  hf_embed_text(text)

# Find similar documents
docs_embedded |>
  hf_nearest_neighbors("I love R", k = 2)

## End(Not run)

Dimensionality Reduction with UMAP

Description

Reduce embedding dimensions to 2D using UMAP for visualization. Requires the 'uwot' package to be installed.

Usage

hf_embed_umap(
  text,
  model = hf_default_model("embed"),
  token = NULL,
  endpoint_url = NULL,
  n_neighbors = 15,
  min_dist = 0.1,
  ...
)

Arguments

Value

A tibble with columns: text, umap_1, umap_2

Examples

## Not run: 
# Reduce and visualize
library(ggplot2)
texts <- c("cat", "dog", "kitten", "puppy", "car", "truck")
coords <- hf_embed_umap(texts)

ggplot(coords, aes(umap_1, umap_2, label = text)) +
  geom_text() +
  theme_minimal()

## End(Not run)

Extract Structured Data from Text

Description

Convert unstructured text into tidy columns using a chat model with structured JSON output. The schema argument can be a lightweight named character vector such as c(name = "string", score = "number") or a full JSON Schema list. The function returns one row per input text and one column per schema field.

Usage

hf_extract(
  text,
  schema,
  model = hf_default_model("chat"),
  strict = TRUE,
  system = paste("Extract the requested fields from the user's text.",
    "Return only JSON that matches the schema."),
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with one row per input and one column per schema field.

Examples

## Not run: 
hf_extract(
  "Amelie is a chef in Paris.",
  c(name = "string", occupation = "string", city = "string")
)

hf_extract(
  c("Great service.", "The delivery was late."),
  c(sentiment = "string", is_complaint = "boolean")
)

## End(Not run)

Extract Semantic Topics from Text

Description

Identify semantic topics by clustering embeddings and extracting representative keywords from each cluster.

Usage

hf_extract_topics(data, text_col = "text", k = 5, top_n = 10)

Arguments

Value

A tibble with topics and their top terms.

Examples

## Not run: 
library(tidytext)

# Extract topics
topics <- docs_embedded |>
  hf_extract_topics(text_col = "text", k = 3, top_n = 5)

## End(Not run)

Create a Conversational Agent

Description

This task corresponds to any chatbot like structure. Models tend to have shorter max_length, so please check with caution when using a given model if you need long range dependency or not.

Usage

hf_ez_conversational(model_id = "microsoft/DialoGPT-large", use_api = FALSE)

Arguments

Value

A conversational object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#zero-shot-classification-task

Examples

## Not run: 
# Load the default model
ez <- hf_ez_conversational()

# Continue the conversation
ez$infer(
  past_user_inputs = list("Which movie is the best?"),
  generated_responses = list("It's Die Hard for sure."),
  text = "Can you explain why?",
  min_length = 10,
  max_length = 50
)

## End(Not run)

Conversational API Inference

Description

Conversational API Inference

Usage

hf_ez_conversational_api_inference(
  text,
  generated_responses = NULL,
  past_user_inputs = NULL,
  min_length = NULL,
  max_length = NULL,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  max_time = NULL,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Conversational Local Inference

Description

Conversational Local Inference

Usage

hf_ez_conversational_local_inference(
  text,
  generated_responses = NULL,
  past_user_inputs = NULL,
  min_length = NULL,
  max_length = NULL,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  max_time = NULL,
  tidy = TRUE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Perform Fill-in-the-Blank Tasks

Description

Tries to fill in a hole with a missing word (token to be precise). That’s the base task for BERT models.

Usage

hf_ez_fill_mask(model_id = "google-bert/bert-base-uncased", use_api = FALSE)

Arguments

Value

A fill mask object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#fill-mask-task

Examples

## Not run: 
# Load the default model and use local inference
ez <- hf_ez_fill_mask()
ez$infer(string = "The answer to the universe is [MASK].")

# Load a specific model and use the API for inference.
# Note the mask is different for different models.
ez <- hf_ez_fill_mask(model_id = 'xlm-roberta-base', use_api = TRUE)
ez$infer(string = "The answer to the universe is <MASK>.")

## End(Not run)

Fill Mask API Inference

Description

Fill Mask API Inference

Usage

hf_ez_fill_mask_api_inference(
  string,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Fill Mask Local Inference

Description

Fill Mask Local Inference

Usage

hf_ez_fill_mask_local_inference(string, tidy = TRUE, ...)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Answer Questions about a Text based on Context

Description

Want to have a nice know-it-all bot that can answer any question?

Usage

hf_ez_question_answering(
  model_id = "deepset/roberta-base-squad2",
  use_api = FALSE
)

Arguments

Value

A question answering object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#question-answering-task

Examples

## Not run: 
# Load the default model and use local inference
ez <- hf_ez_question_answering()
ez$infer(question = "What's my name?", context = "My name is Clara and I live in Berkeley.")

# Use the api for inference.
ez <- hf_ez_fill_mask(use_api = TRUE)
ez$infer(question = "What's my name?", context = "My name is Clara and I live in Berkeley.")

## End(Not run)

Question Answering API Inference

Description

Question Answering API Inference

Usage

hf_ez_question_answering_api_inference(
  question,
  context,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Question Answering Local Inference

Description

Question Answering Local Inference

Usage

hf_ez_question_answering_local_inference(question, context, tidy = TRUE, ...)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Compare Sentence Similarity Semantically

Description

Calculate the semantic similarity between one text and a list of other sentences by comparing their embeddings.

Usage

hf_ez_sentence_similarity(
  model_id = "sentence-transformers/all-MiniLM-L6-v2",
  use_api = FALSE
)

Arguments

Value

A sentence similarity object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#sentence-similarity-task

Examples

## Not run: 
# Load the default model and use local inference
ez <- hf_ez_sentence_similarity()
ez$infer(
  source_sentence = "That is a happy person",
  sentences = list(
    "That is a happy dog",
    "That is a very happy person",
    "Today is a sunny day"
  )
)

# Use the API for inference.
ez <- hf_ez_sentence_similarity(use_api = TRUE)
ez$infer(
  source_sentence = "That is a happy person",
  sentences = list(
    "That is a happy dog",
    "That is a very happy person",
    "Today is a sunny day"
  )
)

## End(Not run)

Sentence Similarity API Inference

Description

Sentence Similarity API Inference

Usage

hf_ez_sentence_similarity_api_inference(
  source_sentence,
  sentences,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Sentence Similarity Local Inference

Description

Sentence Similarity Local Inference

Usage

hf_ez_sentence_similarity_local_inference(
  source_sentence,
  sentences,
  tidy = TRUE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Summarize a Text

Description

This task is well known to summarize longer text into shorter text. Be careful, some models have a maximum length of input. That means that the summary cannot handle full books for instance. Be careful when choosing your model.

Usage

hf_ez_summarization(model_id = "facebook/bart-large-cnn", use_api = FALSE)

Arguments

Value

A summarization object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#summarization-task

Examples

## Not run: 
# Load the default model and use local inference
ez <- hf_ez_summarization()
text <- paste(
  "The Eiffel Tower is 324 metres tall and located in Paris.",
  "It was the world's tallest man-made structure for 41 years."
)
ez$infer(string = text, min_length = 10, max_length = 40)

# Load a specific model and use the API for inference.
ez <- hf_ez_summarization(model_id = 'xlm-roberta-base', use_api = TRUE)
ez$infer(string = "huggingface is the <mask>!")

## End(Not run)

Summarization API Inference

Description

Summarization API Inference

Usage

hf_ez_summarization_api_inference(
  string,
  min_length = NULL,
  max_length = NULL,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  repetition_penalty = NULL,
  max_time = NULL,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Summarization Local Inference

Description

Summarization Local Inference

Usage

hf_ez_summarization_local_inference(
  string,
  min_length = NULL,
  max_length = NULL,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  repetition_penalty = NULL,
  max_time = NULL,
  tidy = TRUE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Answer Questions about a Data Table

Description

Don’t know SQL? Don’t want to dive into a large spreadsheet? Ask questions in plain english!

Usage

hf_ez_table_question_answering(
  model_id = "google/tapas-base-finetuned-wtq",
  use_api = FALSE
)

Arguments

Value

A table question answering object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#table-question-answering-task

Examples

## Not run: 
# Create a table to query
qa_table <-
  tibble::tibble(Repository = c('Transformers', 'Datasets', 'Tokenizers'),
                 Stars = c('36542', '4512', '3934'),
                 Contributors = c('651', '77', '34'),
                 Programming.language = c('Python', 'Python', 'Rust, Python and NodeJS'))

# Load the default model and use local inference
ez <- hf_ez_table_question_answering()
ez$infer(query = "How many stars does the transformers repository have?", table = qa_table)

# Use the api for inference.
ez <- hf_ez_fill_mask(use_api = TRUE)
ez$infer(query = "How many stars does the transformers repository have?", table = qa_table)

## End(Not run)

Table Question Answering API Inference

Description

Table Question Answering API Inference

Usage

hf_ez_table_question_answering_api_inference(
  query,
  table,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Table Question Answering Local Inference

Description

Table Question Answering Local Inference

Usage

hf_ez_table_question_answering_local_inference(query, table, tidy = TRUE, ...)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Answer General Questions

Description

Essentially Text-generation task. But uses Encoder-Decoder architecture, so might change in the future for more options.

Usage

hf_ez_text2text_generation(model_id = "google/flan-t5-large", use_api = FALSE)

Arguments

Value

A text2text generation object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#text2text-generation-task

Examples

## Not run: 
# Load the default model and use local inference
ez <- hf_ez_text2text_generation()
ez$infer("Please answer the following question. What is the boiling point of Nitrogen?")

# Use the api for inference.
ez <- hf_ez_text2text_generation(use_api = TRUE)
ez$infer("Please answer the following question. What is the boiling point of Nitrogen?")

## End(Not run)

Text2Text Generation API Inference

Description

Text2Text Generation API Inference

Usage

hf_ez_text2text_generation_api_inference(
  string,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Text2Text Generation Local Inference

Description

Text2Text Generation Local Inference

Usage

hf_ez_text2text_generation_local_inference(string, tidy = TRUE, ...)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Classify Texts into Pre-trained Categories

Description

Usually used for sentiment-analysis this will output the likelihood of classes of an input.

Usage

hf_ez_text_classification(
  model_id = "distilbert/distilbert-base-uncased-finetuned-sst-2-english",
  use_api = FALSE
)

Arguments

Value

A text classification object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#text-classification-task

Examples

## Not run: 
# Load the default model and use local inference
ez <- hf_ez_text_classification()
ez$infer(string = c('I like you. I love you'), flatten = FALSE)

# Use the API for inference.
ez <- hf_ez_text_classification(use_api = TRUE)
ez$infer(string = c('I like you. I love you'), flatten = FALSE)

## End(Not run)

Text Classification API Inference

Description

Text Classification API Inference

Usage

hf_ez_text_classification_api_inference(
  string,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Text Classification Local Inference

Description

Text Classification Local Inference

Usage

hf_ez_text_classification_local_inference(string, tidy = TRUE, ...)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Generate Text from a Prompt

Description

Use to continue text from a prompt. This is a very generic task.

Usage

hf_ez_text_generation(model_id = "openai-community/gpt2", use_api = FALSE)

Arguments

Value

A text generation object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#text-generation-task

Examples

## Not run: 
# Load the default model and use local inference
ez <- hf_ez_text_generation()
ez$infer(string = 'The answer to the universe is')

# Use the api for inference.
ez <- hf_ez_text_generation(use_api = TRUE)
ez$infer(string = 'The answer to the universe is')

## End(Not run)

Text Generation API Inference

Description

Text Generation API Inference

Usage

hf_ez_text_generation_api_inference(
  string,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  repetition_penalty = NULL,
  max_new_tokens = NULL,
  max_time = NULL,
  return_full_text = TRUE,
  num_return_sequences = 1L,
  do_sample = TRUE,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Text Generation Local Inference

Description

Text Generation Local Inference

Usage

hf_ez_text_generation_local_inference(
  string,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  repetition_penalty = NULL,
  max_new_tokens = NULL,
  max_time = NULL,
  return_full_text = TRUE,
  num_return_sequences = 1L,
  do_sample = TRUE,
  tidy = TRUE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Classify parts of a Text

Description

Usually used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text.

Usage

hf_ez_token_classification(
  model_id = "dbmdz/bert-large-cased-finetuned-conll03-english",
  use_api = FALSE
)

Arguments

Value

A text2text generation object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#token-classification-task

Examples

## Not run: 
# Load the default named entity recognition model
ez <- hf_ez_token_classification()

# Run NER. Note how the full name is aggregated into one named entity.
ez$infer(
  string = "My name is Sarah Jessica Parker but you can call me Jessica",
  aggregation_strategy = "simple"
)

# Run NER without aggregation.
# Note how the full name is separated into distinct named entities.
ez$infer(
  string = "My name is Sarah Jessica Parker but you can call me Jessica",
  aggregation_strategy = "none"
)

## End(Not run)

Token Classification API Inference

Description

Token Classification API Inference

Usage

hf_ez_token_classification_api_inference(
  string,
  aggregation_strategy = "simple",
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Token Classification Local Inference

Description

Token Classification Local Inference

Usage

hf_ez_token_classification_local_inference(
  string,
  aggregation_strategy = "simple",
  tidy = TRUE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Translate between Languages

Description

This task is well known to translate text from one language to another

Usage

hf_ez_translation(model_id = "Helsinki-NLP/opus-mt-en-es", use_api = FALSE)

Arguments

Value

A translation object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#translation-task

Examples

## Not run: 
# Load the default translation model
ez <- hf_ez_translation()

# Translate from English to Spanish.
ez$infer(string = "My name is Sarah and I live in London")

## End(Not run)

Translation API Inference

Description

Translation API Inference

Usage

hf_ez_translation_api_inference(
  string,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Translation Local Inference

Description

Translation Local Inference

Usage

hf_ez_translation_local_inference(string, tidy = TRUE, ...)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Perform Text Classification with No Context Required

Description

This task is super useful to try out classification with zero code, you simply pass a sentence/paragraph and the possible labels for that sentence, and you get a result.

Usage

hf_ez_zero_shot_classification(
  model_id = "facebook/bart-large-mnli",
  use_api = FALSE
)

Arguments

Value

A zero shot classification object

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#zero-shot-classification-task

Examples

## Not run: 
# Load the default model
ez <- hf_ez_zero_shot_classification()

# Classify the string
ez$infer(
  string = paste(
    "Hi, I recently bought a device from your company but it is not working",
    "as advertised and I would like to get reimbursed!"
  ),
  candidate_labels = c("refund", "legal", "faq")
)

## End(Not run)

Zero Shot Classification API Inference

Description

Zero Shot Classification API Inference

Usage

hf_ez_zero_shot_classification_api_inference(
  string,
  candidate_labels,
  multi_label = FALSE,
  tidy = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Zero Shot Classification Local Inference

Description

Zero Shot Classification Local Inference

Usage

hf_ez_zero_shot_classification_local_inference(
  string,
  candidate_labels,
  multi_label = FALSE,
  tidy = TRUE,
  ...
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Fill Mask

Description

Fill in a [MASK] token in text with predicted words. Commonly used with BERT-style models.

Usage

hf_fill_mask(
  text,
  model = hf_default_model("fill_mask"),
  mask_token = "[MASK]",
  top_k = 5,
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: text, token, score, filled (the complete text)

Examples

## Not run: 
# Fill in the blank
hf_fill_mask("The capital of France is [MASK].")

# Get top predictions
hf_fill_mask("Paris is the [MASK] of France.", top_k = 3)

# Use with different mask token
hf_fill_mask("The capital of France is <mask>.", mask_token = "<mask>")

## End(Not run)

Fill Mask Task Payload

Description

Tries to fill in a hole with a missing word (token to be precise). That’s the base task for BERT models.

Usage

hf_fill_mask_payload(string)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#fill-mask-task

Examples

hf_fill_mask_payload("The capital of France is [MASK].")

Text Generation

Description

Generate text from a prompt using a language model via the Inference Providers API.

Usage

hf_generate(
  prompt,
  model = hf_default_model("generate"),
  max_new_tokens = 50,
  temperature = 1,
  top_p = NULL,
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: prompt, generated_text

Examples

## Not run: 
# Simple text generation
hf_generate("Once upon a time in a land far away,")

# With different model
hf_generate("The future of AI is", model = "meta-llama/Llama-3-8B-Instruct:together")

## End(Not run)

Get Existing Chunk IDs

Description

Internal function to find which chunks have already been written.

Usage

hf_get_existing_chunks(output_dir, prefix = "chunk")

Arguments

Value

Integer vector of chunk IDs that already exist.

Get Hugging Face API Token

Description

Internal function to retrieve the API token from environment or parameter.

Usage

hf_get_token(token = NULL, required = FALSE)

Arguments

Value

Character string with token, or NULL if not found and not required.

Download a File from the Hub

Description

Download a single file from a model, dataset, or Space repository.

Usage

hf_hub_download(
  repo_id,
  filename,
  repo_type = "model",
  revision = "main",
  dest = NULL,
  token = NULL,
  overwrite = FALSE
)

Arguments

Value

The downloaded file path.

Examples

## Not run: 
hf_hub_download("BAAI/bge-small-en-v1.5", "README.md")

## End(Not run)

Inference using a downloaded Hugging Face model or pipeline, or using the Inference API

Description

If a model_id is provided, the Inference API will be used to make the prediction. If you wish to download a model or pipeline rather than running your predictions through the Inference API, download the model with one of the hf_load_*_model() or hf_load_pipeline() functions.

Usage

hf_inference(
  model,
  payload,
  flatten = TRUE,
  use_gpu = FALSE,
  use_cache = FALSE,
  wait_for_model = FALSE,
  use_auth_token = NULL,
  stop_on_error = FALSE
)

Arguments

Value

The results of the inference

See Also

https://huggingface.co/docs/api-inference/index

Examples

## Not run: 
payload <- hf_text_classification_payload("I love R.")
hf_inference("distilbert-base-uncased-finetuned-sst-2-english", payload)

## End(Not run)

List Authors

Description

List Model Authors

Usage

hf_list_authors(pattern = NULL)

Arguments

Value

A character vector of matching model authors.

See Also

https://huggingface.co/docs/hub/searching-the-hub

Examples

## Not run: 
hf_list_authors(pattern = "^sam")

## End(Not run)

List Datasets

Description

List Model Datasets

Usage

hf_list_datasets(pattern = NULL)

Arguments

Value

A character vector of matching dataset names.

See Also

https://huggingface.co/docs/hub/searching-the-hub

Examples

## Not run: 
hf_list_datasets("imdb")

## End(Not run)

List Languages

Description

List Model Languages

Usage

hf_list_languages(pattern = NULL)

Arguments

Value

A character vector of matching language tags.

See Also

https://huggingface.co/docs/hub/searching-the-hub

Examples

## Not run: 
hf_list_languages("es")

## End(Not run)

List Libraries

Description

List Model Libraries

Usage

hf_list_libraries(pattern = NULL)

Arguments

Value

A character vector of matching library names.

See Also

https://huggingface.co/docs/hub/searching-the-hub

Examples

## Not run: 
hf_list_libraries("pytorch|tensorflow")

## End(Not run)

List Licenses

Description

List Model Licenses

Usage

hf_list_licenses(pattern = NULL)

Arguments

Value

A character vector of matching license identifiers.

See Also

https://huggingface.co/docs/hub/searching-the-hub

Examples

## Not run: 
hf_list_licenses("mit")

## End(Not run)

List Models

Description

List Model Names

Usage

hf_list_models(pattern = NULL)

Arguments

Value

A tibble with a 'model' column containing matching model IDs.

See Also

https://huggingface.co/docs/hub/searching-the-hub

Examples

## Not run: 
hf_list_models("bert-base-cased")

## End(Not run)

List Inference Providers for a Model

Description

Query Hugging Face router metadata for provider availability, pricing, latency, and capabilities. Router provider metadata is available for OpenAI-compatible models; non-router task models return an empty tibble.

Usage

hf_list_providers(model_id, token = NULL)

Arguments

Value

A tibble with one row per provider.

Examples

## Not run: 
hf_list_providers("Qwen/Qwen2.5-72B-Instruct")

## End(Not run)

List Files in a Hub Repository

Description

List files and directories in a model, dataset, or Space repository.

Usage

hf_list_repo_files(
  repo_id,
  repo_type = "model",
  revision = "main",
  recursive = TRUE,
  token = NULL
)

Arguments

Value

A tibble with columns: path, type, size, oid.

Examples

## Not run: 
hf_list_repo_files("BAAI/bge-small-en-v1.5")

## End(Not run)

List Available Tasks

Description

List all available task types on Hugging Face.

Usage

hf_list_tasks(pattern = NULL)

Arguments

Value

A character vector of task names.

Examples

## Not run: 
# List all tasks
hf_list_tasks()

# Filter tasks
hf_list_tasks(pattern = "classification")

## End(Not run)

Import a pre-trained AutoModel object for a specific task.

Description

Use this function when you need to load an AutoModel for a specific task separate to a pipeline. The model's config should come ready-equipped for a specific task according to what you input as model_type.

Usage

hf_load_AutoModel_for_task(
  model_type = "AutoModelForSequenceClassification",
  model_id,
  use_auth_token = NULL
)

Arguments

Value

an AutoModel object for a specific task

See Also

https://huggingface.co/transformers/v3.0.2/model_doc/auto.html

Examples

## Not run: 
model <- hf_load_AutoModel_for_task(
  "AutoModelForSequenceClassification",
  "distilbert-base-uncased-finetuned-sst-2-english"
)

## End(Not run)

Load Dataset via Hugging Face Datasets Server API

Description

Load a dataset from Hugging Face Hub using the Datasets Server API. This is an API-first approach that doesn't require Python. For local dataset loading with Python, see the legacy function or advanced vignette.

Usage

hf_load_dataset(
  dataset,
  split = "train",
  config = NULL,
  limit = 1000,
  offset = 0,
  token = NULL
)

Arguments

Value

A tibble with dataset rows, plus .dataset and .split columns.

Examples

## Not run: 
# Load first 1000 rows of IMDB train set
imdb <- hf_load_dataset("imdb", split = "train", limit = 1000)

# Load test set
imdb_test <- hf_load_dataset("imdb", split = "test", limit = 500)

# Load a slice of a split
imdb_sample <- hf_load_dataset("imdb", split = "train[100:200]", limit = Inf)

## End(Not run)

Load a pre-trained AutoModel object from Hugging Face

Description

Load a pre-trained AutoModel object from Hugging Face

Usage

hf_load_model(model_id, ...)

Arguments

Value

a pre-trained model object

Examples

## Not run: 
model <- hf_load_model("distilbert-base-uncased")

## End(Not run)

Load a pipeline object from Hugging Face - pipelines usually include a model, tokenizer and task.

Description

Load Model from Hugging Face

Usage

hf_load_pipeline(model_id, tokenizer = NULL, task = NULL, ...)

Arguments

Value

A Hugging Face model ready for prediction.

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Examples

## Not run: 
pipe <- hf_load_pipeline("distilbert-base-uncased-finetuned-sst-2-english",
                         task = "sentiment-analysis")
pipe("I love R.")

## End(Not run)

Load a Sentence Transformers model to extract sentence/document embeddings

Description

Load a Sentence Transformers model to extract sentence/document embeddings

Usage

hf_load_sentence_model(model_id, ...)

Arguments

Value

A Huggingface model ready for prediction.

See Also

https://huggingface.co/sentence-transformers

Examples

## Not run: 
# Compute sentence embeddings
sentences <- c("Baby turtles are so cute!", "He walks as slowly as a turtle.")
sentences_two <- c("The lake is cold today.", "I enjoy swimming in the lake.")
sentences <- c(sentences, sentences_two)
model <- hf_load_sentence_model('paraphrase-MiniLM-L6-v2')
embeddings <- model$encode(sentences)
embeddings %>% dist() %>% as.matrix() %>% as.data.frame() %>% setNames(sentences)
embddings <- embeddings %>% dplyr::mutate(`sentence 1` = sentences) %>%
tidyr::pivot_longer(cols = -`sentence 1`, names_to = 'sentence 2', values_to = 'distance')
embeddings <- embeddings %>% filter(distance > 0)
# Cluster sentences
embeddings <- embeddings %>%
t() %>% prcomp() %>%
purrr::pluck('rotation') %>%
as.data.frame() %>%
dplyr::mutate(sentence = sentences)
plot <- embedidings %>% ggplot2::ggplot(aes(PC1, PC2)) +
ggplot2::geom_label(ggplot2::aes(PC1, PC2, label = sentence, vjust="inward", hjust="inward")) +
ggplot2::theme_minimal()

## End(Not run)

Load an AutoTokenizer from a pre-tained model

Description

Load Tokenizer for Hugging Face Model

Usage

hf_load_tokenizer(model_id, ...)

Arguments

Value

A Hugging Face model's tokenizer.

See Also

https://huggingface.co/docs/transformers/main/en/pipeline_tutorial

Examples

## Not run: 
tokenizer <- hf_load_tokenizer("distilbert-base-uncased")
tokenizer$tokenize("Hello from R")

## End(Not run)

Get Model Information

Description

Retrieve detailed information about a specific model.

Usage

hf_model_info(model_id, token = NULL)

Arguments

Value

A list with detailed model information.

Examples

## Not run: 
# Get model details
hf_model_info("sentence-transformers/all-MiniLM-L6-v2")

## End(Not run)

Find Nearest Neighbors by Semantic Similarity

Description

Find the k most similar texts to a query text based on embedding similarity.

Usage

hf_nearest_neighbors(
  data,
  query,
  k = 5,
  text_col = "text",
  model = hf_default_model("embed"),
  token = NULL
)

Arguments

Value

A tibble with the k nearest neighbors, sorted by similarity (descending).

Examples

## Not run: 
docs_embedded |>
  hf_nearest_neighbors("machine learning", k = 5)

## End(Not run)

Named Entity Recognition (Token Classification)

Description

Extract named entities (people, organizations, locations, etc.) from text using a token-classification model via the Hugging Face Inference Providers API. Returns one row per detected entity, with character offsets that let you highlight or join back to the source text. Inputs that produce no entities (and 'NA' inputs) yield a single row with 'NA' entity fields so every input is represented.

Usage

hf_ner(
  text,
  model = hf_default_model("ner"),
  aggregation_strategy = "simple",
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: text, word, entity_group, score, start, end.

See Also

https://huggingface.co/docs/inference-providers/tasks/token-classification

Examples

## Not run: 
hf_ner("Barack Obama was born in Hawaii.")

# One row per entity, ready to count or join
library(dplyr)
hf_ner(headlines) |>
  filter(!is.na(word)) |>
  count(entity_group, sort = TRUE)

## End(Not run)

Parse API Response to Tibble

Description

Internal helper to convert API JSON responses to tibbles.

Usage

hf_parse_response(resp, input_text = NULL)

Arguments

Value

A tibble with the parsed results.

Perform Parallel Batch Requests

Description

Internal function to execute multiple API requests in parallel with error handling.

Usage

hf_perform_batch(reqs, input_indices, max_active = 10L, progress = TRUE)

Arguments

Value

A tibble with columns: - '.input_idx': Original input index - 'response': The response object (or error) - '.error': Logical, TRUE if request failed - '.error_msg': Error message or NA

Push a Data Frame as a Dataset File

Description

Write a data frame to CSV or Parquet and upload it to a Hub dataset repository.

Usage

hf_push_dataset(
  data,
  repo_id,
  path_in_repo = NULL,
  format = c("csv", "parquet"),
  create_repo = FALSE,
  private = FALSE,
  commit_message = NULL,
  token = NULL,
  overwrite = FALSE,
  confirm = FALSE
)

Arguments

Value

The result from 'hf_upload_file()'.

Examples

## Not run: 
hf_push_dataset(mtcars, "me/mtcars-small", create_repo = TRUE, confirm = TRUE)

## End(Not run)

Install Python Dependencies

Description

Installs python packages needed to run huggingfaceR functions

Usage

hf_python_depends(
  packages = c("transformers", "sentencepiece", "huggingface_hub", "datasets",
    "sentence-transformers")
)

Arguments

Value

The value returned by 'reticulate::conda_install()', called for its side effect.

Examples

## Not run: 
hf_python_depends()

## End(Not run)

Extractive Question Answering

Description

Answer a question from a supplied context passage using an extractive question-answering model via the Hugging Face Inference Providers API. The answer is a span extracted verbatim from the context. 'question' and 'context' are recycled to a common length (each may be length 1).

Usage

hf_question_answer(
  question,
  context,
  model = hf_default_model("question_answer"),
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: question, answer, score, start, end.

See Also

https://huggingface.co/docs/inference-providers/tasks/question-answering

Examples

## Not run: 
hf_question_answer(
  question = "Where was Obama born?",
  context = "Barack Obama was born in Honolulu, Hawaii."
)

# One context, several questions
hf_question_answer(
  question = c("Who?", "Where?"),
  context = "Ada Lovelace worked in London."
)

## End(Not run)

Question Answering Payload

Description

Want to have a nice know-it-all bot that can answer any question?

Usage

hf_question_answering_payload(question, context)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#question-answering-task

Examples

hf_question_answering_payload(
  question = "What is R?",
  context = "R is a language for statistical computing."
)

Read All Chunks from Directory

Description

Read and combine all parquet chunk files from a directory.

Usage

hf_read_chunks(output_dir, pattern = "*.parquet")

Arguments

Value

A tibble combining all chunks, sorted by '.input_idx' if present.

Examples

## Not run: 
# After running hf_embed_chunks()
results <- hf_read_chunks("my_output_dir")

## End(Not run)

Resolve a Short Dataset Name to Full ID

Description

Uses the Hub API to find the full org/name ID for a dataset.

Usage

hf_resolve_dataset(dataset, token = NULL)

Arguments

Value

Character string with full dataset ID, or NULL if not found.

Run Tool Calls in a Conversation

Description

Execute tool calls requested by the last assistant message in an hf_conversation, append tool-result messages, and ask the model for the next response. The loop repeats until the model returns a response without tool calls.

Usage

hf_run_tools(conversation, tools, max_turns = 5L, token = NULL, ...)

Arguments

Value

Updated hf_conversation object.

Examples

## Not run: 
tool <- hf_tool("add", "Add two numbers.", c(x = "number", y = "number"))
convo <- hf_conversation(model = "Qwen/Qwen2.5-72B-Instruct")
convo <- chat(convo, "What is 2 + 3?", tools = list(tool))
convo <- hf_run_tools(convo, list(add = function(x, y) x + y))

## End(Not run)

Search Datasets on Hugging Face Hub

Description

Search for datasets using various filters.

Usage

hf_search_datasets(
  search = NULL,
  task = NULL,
  language = NULL,
  size = NULL,
  sort = "downloads",
  limit = 30,
  token = NULL
)

Arguments

Value

A tibble with dataset information.

Examples

## Not run: 
# Search datasets
hf_search_datasets(search = "sentiment", limit = 10)

## End(Not run)

Search Models on Hugging Face Hub

Description

Search for models using various filters. Returns a tibble of matching models.

Usage

hf_search_models(
  search = NULL,
  task = NULL,
  author = NULL,
  language = NULL,
  library = NULL,
  tags = NULL,
  sort = "downloads",
  direction = "desc",
  limit = 30,
  token = NULL
)

Arguments

Value

A tibble with model information.

Examples

## Not run: 
# Search by task
hf_search_models(task = "text-classification", limit = 10)

# Search by author
hf_search_models(author = "facebook", sort = "downloads")

# Search with query
hf_search_models(search = "sentiment", task = "text-classification")

## End(Not run)

Search Papers on Hugging Face

Description

Search papers indexed by Hugging Face.

Usage

hf_search_papers(search = NULL, limit = 30, token = NULL)

Arguments

Value

A tibble with paper metadata.

Examples

## Not run: 
hf_search_papers("transformers", limit = 10)

## End(Not run)

Search Spaces on Hugging Face Hub

Description

Search hosted Spaces and return one row per result.

Usage

hf_search_spaces(
  search = NULL,
  author = NULL,
  sort = "likes",
  direction = "desc",
  limit = 30,
  token = NULL
)

Arguments

Value

A tibble with Space metadata.

Examples

## Not run: 
hf_search_spaces(search = "chat", limit = 10)

## End(Not run)

Use a Sentence Transformers pipeline to extract document(s)/sentence(s) embedding(s)

Description

Use a Sentence Transformers pipeline to extract document(s)/sentence(s) embedding(s)

Usage

hf_sentence_encode(
  model,
  text,
  batch_size = 64L,
  show_progress_bar = TRUE,
  tidy = TRUE,
  ...
)

Arguments

Value

n-dimensional embeddings for every input 'text'

Examples

## Not run: 
text <- c("There are things we do know, things we don't know, and then there is quantum mechanics.")
sentence_mod <- hf_load_sentence_model("paraphrase-MiniLM-L6-v2")
embeddings <- hf_sentence_encode(model = sentence_mod, text, show_progress_bar = TRUE)

## End(Not run)

Sentence Similarity Payload

Description

Calculate the semantic similarity between one text and a list of other sentences by comparing their embeddings.

Usage

hf_sentence_similarity_payload(source_sentence, sentences)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#sentence-similarity-task

Examples

hf_sentence_similarity_payload(
  source_sentence = "A happy person",
  sentences = list("A joyful person", "A rainy day")
)

Try to set device to GPU for accelerated computation

Description

This function currently depends on having a working installation of torch for your GPU in this environment. If running an Apple silicon GPU, you'll need the native mac M+ build (ARM binary). You will also need rust and other transformers dependencies. As you need to make sure that everything that needs to be on the GPU (tensors, model, pipeline etc.), is on the GPU, we currently recommend this for advanced users only. We will be working on integrating this fully with the installation and build of the huggingfaceR environment.

Usage

hf_set_device()

Value

a device that models, pipelines, and tensors can be sent to.

Examples

## Not run: 
device <- hf_set_device()

## End(Not run)

Set Hugging Face API Token

Description

Set or update your Hugging Face API token for authentication. See https://huggingface.co/docs/hub/security-tokens for token setup.

Usage

hf_set_token(token = NULL, store = FALSE)

Arguments

Value

Invisibly returns TRUE if token was set successfully.

Examples

## Not run: 
# Set token for current session only
hf_set_token("hf_xxxxxxxxxxxxx")

# Set token interactively and store permanently
hf_set_token(store = TRUE)

## End(Not run)

Compute Pairwise Similarity

Description

Compute cosine similarity between all pairs of embeddings. Numeric embeddings with consistent dimensions use vectorized matrix operations for better performance on larger result sets; invalid, zero-length, zero-norm, or dimension-mismatched pairs return 'NA_real_'.

Usage

hf_similarity(embeddings, text_col = "text")

Arguments

Value

A tibble with columns: text_1, text_2, similarity.

Examples

## Not run: 
sentences <- c("I love cats", "I adore felines", "Dogs are great")
embeddings <- hf_embed(sentences)
similarities <- hf_similarity(embeddings)

## End(Not run)

Summarization Task Payload

Description

This task is well known to summarize longer text into shorter text. Be careful, some models have a maximum length of input. That means that the summary cannot handle full books for instance.

Usage

hf_summarization_payload(
  string,
  min_length = NULL,
  max_length = NULL,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  repetition_penalty = NULL,
  max_time = NULL
)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#summarization-task

Examples

hf_summarization_payload("R is a language for statistical computing.",
                         max_length = 20)

Summarize Text

Description

Condense longer text into a shorter summary using a summarization model via the Hugging Face Inference Providers API. Accepts a character vector and returns one row per input, composing naturally with dplyr pipelines.

Usage

hf_summarize(
  text,
  model = hf_default_model("summarize"),
  min_length = NULL,
  max_length = NULL,
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: text, summary.

See Also

https://huggingface.co/docs/inference-providers/tasks/summarization

Examples

## Not run: 
hf_summarize("Long article text goes here ...", max_length = 60)

library(dplyr)
articles |>
  mutate(tldr = hf_summarize(body)$summary)

## End(Not run)

Table Question Answering

Description

Ask a question in plain language about a data frame, using a table question-answering model (such as TAPAS) via the Hugging Face Inference Providers API. The data frame is converted to the string-cell format the API expects; all values are coerced to character.

Usage

hf_table_question_answer(
  query,
  table,
  model = hf_default_model("table_question_answer"),
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Value

A tibble with columns: query, answer, aggregator, cells (a list-column of the source cells the answer was drawn from).

See Also

https://huggingface.co/docs/inference-providers/tasks/table-question-answering

Examples

## Not run: 
sales <- data.frame(
  product = c("Widgets", "Gadgets", "Gizmos"),
  revenue = c(120, 80, 50)
)
hf_table_question_answer("Which product had the highest revenue?", sales)
hf_table_question_answer("What is the total revenue?", sales)

## End(Not run)

Table Question Answering Payload

Description

Don’t know SQL? Don’t want to dive into a large spreadsheet? Ask questions in plain english!

Usage

hf_table_question_answering_payload(query, table)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#table-question-answering-task

Examples

hf_table_question_answering_payload(
  query = "How many rows are shown?",
  table = list(name = c("Alice", "Bob"), rows = c("1", "2"))
)

Text2Text Generation Payload

Description

takes an input containing the sentence including the task and returns the output of the accomplished task.

Usage

hf_text2text_generation_payload(string)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#text2text-generation-task

Examples

hf_text2text_generation_payload("translate English to French: Hello")

Text Classification Payload

Description

Usually used for sentiment-analysis this will output the likelihood of classes of an input.

Usage

hf_text_classification_payload(string)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#text-classification-task

Examples

hf_text_classification_payload("I love using R.")

Text Generation Payload

Description

Use to continue text from a prompt. This is a very generic task.

Usage

hf_text_generation_payload(
  string,
  top_k = NULL,
  top_p = NULL,
  temperature = 1,
  repetition_penalty = NULL,
  max_new_tokens = NULL,
  max_time = NULL,
  return_full_text = TRUE,
  num_return_sequences = 1L,
  do_sample = TRUE
)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#text-generation-task

Examples

hf_text_generation_payload("Once upon a time", max_new_tokens = 10)

Generate an Image from Text

Description

Generate an image from a prompt and write it to disk using a text-to-image model via the Hugging Face Inference Providers API.

Usage

hf_text_to_image(
  prompt,
  output = NULL,
  seed = NULL,
  model = hf_default_model("text_to_image"),
  token = NULL,
  endpoint_url = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

A tibble with columns: prompt, path, content_type, image.

See Also

https://huggingface.co/docs/inference-providers/tasks/text-to-image

Examples

## Not run: 
img <- hf_text_to_image("a small red cube on a white background", seed = 42)
img$path

## End(Not run)

Convert Text to Speech

Description

Generate speech audio from text and write it to disk. The public 'hf-inference' provider did not expose a broadly available TTS model during verification; use this with a compatible model/provider or dedicated Inference Endpoint.

Usage

hf_text_to_speech(
  text,
  output = NULL,
  model = hf_default_model("text_to_speech"),
  token = NULL,
  endpoint_url = NULL,
  overwrite = FALSE,
  ...
)

Arguments

Value

A tibble with columns: text, path, content_type, audio.

See Also

https://huggingface.co/tasks/text-to-speech

Examples

## Not run: 
hf_text_to_speech("Hello from R.")

## End(Not run)

Token Classification Payload

Description

Usually used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text.

Usage

hf_token_classification_payload(string, aggregation_strategy = "simple")

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#token-classification-task

Examples

hf_token_classification_payload("My name is Sarah Jessica Parker.")

Define a Chat Tool

Description

Build an OpenAI-compatible function-calling tool definition for hf_chat(). The parameters argument can be a lightweight named character vector, for example c(city = "string"), or a full JSON Schema object.

Usage

hf_tool(
  name,
  description,
  parameters = list(type = "object", properties = list(), additionalProperties = FALSE)
)

Arguments

Value

A list suitable for the tools argument of hf_chat().

Examples

weather_tool <- hf_tool(
  "get_weather",
  "Get current weather for a city.",
  c(city = "string")
)

Transcribe Audio

Description

Transcribe speech from an audio file, URL, or raw vector using automatic speech recognition via the Hugging Face Inference Providers API.

Usage

hf_transcribe(
  audio,
  return_timestamps = FALSE,
  model = hf_default_model("transcribe"),
  token = NULL,
  endpoint_url = NULL,
  content_type = NULL,
  ...
)

Arguments

Value

A tibble with columns: audio, text, chunks.

See Also

https://huggingface.co/docs/inference-providers/tasks/automatic-speech-recognition

Examples

## Not run: 
hf_transcribe("interview.flac")
hf_transcribe("interview.flac", return_timestamps = "word")

## End(Not run)

Translate Text

Description

Translate text from one language to another using a translation model via the Hugging Face Inference Providers API.

Usage

hf_translate(
  text,
  model = hf_default_model("translate"),
  source = NULL,
  target = NULL,
  token = NULL,
  endpoint_url = NULL,
  ...
)

Arguments

Details

The default model, 'Helsinki-NLP/opus-mt-en-fr', translates English to French and is chosen for easy onboarding: it is small, fast, broadly known, and encodes the translation direction in the model ID, so 'hf_translate("Hello")' works with no extra arguments. To translate a different language pair, swap in another Helsinki-NLP 'opus-mt-*' model (for example '"Helsinki-NLP/opus-mt-en-es"' for English to Spanish).

Translation models vary in how they expect languages to be specified. Language-pair models such as the Helsinki-NLP 'opus-mt-*' family encode the direction in the model ID and ignore 'source'/'target'. Multilingual models such as NLLB ('facebook/nllb-200-distilled-600M') instead require 'source' and 'target' to be set to FLORES-200 codes (for example "eng_Latn", "fra_Latn").

Value

A tibble with columns: text, translation.

See Also

https://huggingface.co/docs/inference-providers/tasks/translation

Examples

## Not run: 
# Simplest call: English to French with the default model
hf_translate("Hello, how are you?")

# A different language pair (English to Spanish)
hf_translate("Hello, how are you?", model = "Helsinki-NLP/opus-mt-en-es")

# Multilingual model (FLORES-200 codes)
hf_translate(
  "Hello, how are you?",
  model = "facebook/nllb-200-distilled-600M",
  source = "eng_Latn",
  target = "fra_Latn"
)

## End(Not run)

Translation Payload

Description

This task is well known to translate text from one language to another

Usage

hf_translation_payload(string)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#translation-task

Examples

hf_translation_payload("Hello, world.")

Upload a File to a Hub Repository

Description

Upload a local file into a model, dataset, or Space repository. This is a write operation and requires an API token with write scope plus 'confirm = TRUE'.

Usage

hf_upload_file(
  path,
  repo_id,
  path_in_repo = NULL,
  repo_type = "model",
  commit_message = NULL,
  token = NULL,
  overwrite = FALSE,
  confirm = FALSE
)

Arguments

Value

The parsed Hub API response, or the response path when the endpoint returns no JSON body.

Examples

## Not run: 
hf_upload_file("results.csv", "me/my-dataset", repo_type = "dataset", confirm = TRUE)

## End(Not run)

Vectorize API Calls

Description

Internal helper to apply an API function to multiple inputs efficiently.

Usage

hf_vectorize(inputs, fn, ..., .progress = FALSE)

Arguments

Value

Combined results from all API calls.

Get Current Hugging Face User Information

Description

Retrieve information about the currently authenticated user. Requires a valid Hugging Face token to be set.

Usage

hf_whoami(token = NULL)

Arguments

Value

A tibble with user, billing, organization, and token-scope metadata.

Examples

## Not run: 
# Check current user
hf_whoami()

## End(Not run)

Write Chunk to Parquet

Description

Internal function to write a data chunk to a parquet file.

Usage

hf_write_chunk(data, output_dir, chunk_id, prefix = "chunk")

Arguments

Value

Invisibly returns the file path written.

Zero Shot Classification Payload

Description

This task is super useful to try out classification with zero code, you simply pass a sentence/paragraph and the possible labels for that sentence, and you get a result.

Usage

hf_zero_shot_classification_payload(
  string,
  candidate_labels,
  multi_label = FALSE
)

Arguments

Value

An inference payload

See Also

https://huggingface.co/docs/api-inference/detailed_parameters#zeroshot-classification-task

Examples

hf_zero_shot_classification_payload(
  "I need help with my laptop.",
  candidate_labels = c("technology", "sports", "food")
)

Dataset of model names, tasks & download info

Description

#'

model

name of model

#'

downloads

number of downloads

#'

task

task model performsl

#'

sha

model's secure hash algorithm

#'

private

whether model is public or private

Usage

models_with_downloads

Format

An object of class tbl_df (inherits from tbl, data.frame) with 55524 rows and 5 columns.

Null-coalescing operator

Description

Null-coalescing operator

Usage

x %||% y

Arguments

Embedding Recipe Step

Description

Create text embeddings using a Hugging Face model as part of a tidymodels recipe. This step converts text columns into embedding features for downstream modeling.

Usage

step_hf_embed(
  recipe,
  ...,
  role = "predictor",
  trained = FALSE,
  model = hf_default_model("embed"),
  token = NULL,
  embeddings = NULL,
  skip = FALSE,
  id = recipes::rand_id("hf_embed")
)

## S3 method for class 'step_hf_embed'
tidy(x, ...)

## S3 method for class 'step_hf_embed'
tunable(x, ...)

Arguments

Value

An updated recipe object.

Examples

## Not run: 
library(tidymodels)
library(dplyr)

# Create a recipe with embeddings
rec <- recipe(sentiment ~ text, data = train_data) |>
  step_hf_embed(text, model = "BAAI/bge-small-en-v1.5")

# Use in a workflow
wf <- workflow() |>
  add_recipe(rec) |>
  add_model(logistic_reg()) |>
  fit(data = train_data)

## End(Not run)