EndpointR

EndpointR is a ‘batteries included’, open-source R package for connecting to various Application Programming Interfaces (APIs) for Machine Learning model predictions.

TIP: If you are an experienced programmer, or have experience with hitting APIs, consider going directly to httr2

Installation

EndpointR will not be put on CRAN, so you can download and install the latest development version with the following code:

library(EndpointR)
remotes::install_github("jpcompartir/EndpointR")

Quick Starts

Hugging Face - embeddings

Securely set your API key

set_api_key("HF_API_KEY")

Point to an endpoint - this is for the ‘all-mpnet-base-v2’ model with feature extraction (embeddings)

endpoint_url <- "https://router.huggingface.co/hf-inference/models/sentence-transformers/all-mpnet-base-v2/pipeline/feature-extraction" 

Embed a single text:

 hf_embed_text(
  text = "Convert this text to embeddings",
  endpoint_url = endpoint_url,
  key_name = "HF_API_KEY"
)

Embed a list of texts in batches:

review_texts <-c(
    "Absolutely fantastic service! The staff were incredibly helpful and friendly.",
    "Terrible experience. Food was cold and the waiter was rude.",
    "Pretty good overall, but nothing special. Average food and service.",
    "Outstanding meal! Best restaurant I've been to in years. Highly recommend!",
    "Disappointed with the long wait times. Food was okay when it finally arrived."
  )

hf_embed_batch(
  texts = review_texts,
  endpoint_url = endpoint_url,
  key_name = "HF_API_KEY",
  batch_size = 3,
  concurrent_requests = 2
)

Embed a data frame of texts:

review_data <- tibble::tibble(
  review_id = 1:5,
  review_text = review_texts
)

hf_embed_df(
  df = review_data,
  text_var = review_text,
  id_var = review_id,
  endpoint_url = endpoint_url,
  key_name = "HF_API_KEY",
  concurrent_requests = 2,
  batch_size = 3
)

Hugging Face - Classification

Select a Classification Endpoint URL

sentiment_endpoint <- "https://router.huggingface.co/hf-inference/models/cardiffnlp/twitter-roberta-base-sentiment"

Classify a single text:

You’ll need to grab the label2id mapping from the model’s card: Cardiff NLP model info

labelid_2class <- function() {
  return(list(negative = "LABEL_0",
              neutral = "LABEL_1",
              positive = "LABEL_2"))
}

 hf_classify_text(
  text = review_texts[[1]],
  endpoint_url = sentiment_endpoint,
  key_name = "HF_API_KEY"
) |> 
   dplyr::rename(!!!labelid_2class())

Classify a data frame:

hf_classify_df(
  df = review_data,
  text_var = review_text,
  id_var = review_id,
  endpoint_url = sentiment_endpoint,
  key_name = "HF_API_KEY",
  batch_size = 8,
  concurrent_requests = 3
) |>
  dplyr::rename(!!!labelid_2class())

Read the Hugging Face Inference Vignette for more infromation on embedding and classifying using Dedicated Inference Endpoints and the Inference API from Hugging Face.

OpenAI - Chat Completions API

Make sure you’ve set your API key:

set_api_key("OPENAI_API_KEY")

Complete a single text:

oai_complete_text(
  text = review_texts[[2]],
  system_prompt = "Classify the sentiment of the following text: "
)

Complete a single text with a schema and tidy:

sentiment_schema <- create_json_schema(
  name = "sentiment_analysis",
  schema = schema_object(
    sentiment = schema_string("positive, negative, or neutral"),
    confidence = schema_number("confidence score between 0 and 1"), # we don't necessarily recommend asking a model for its confidence score, this is mainly a schema-construction demo!
    required = list("sentiment", "confidence")
  )
)

oai_complete_text(
  text = review_texts[[2]],
  system_prompt = "Classify the sentiment of the following text: ",
  schema = sentiment_schema,
  tidy = TRUE
) |> 
  tibble::as_tibble()

Complete a Data Frame of texts:

oai_complete_df(
  df = review_data,
  text_var = review_text,
  id_var = review_id,
  system_prompt = "Classify the following review:",
  key_name = "OPENAI_API_KEY",
  concurrent_requests = 5 # send 5 rows of data simultaneously
)

Complete a Data Frame of texts with schema:

oai_complete_df(
  df = review_data,
  text_var = review_text,
  id_var = review_id,
  system_prompt = "Classify the following review:",
  schema = sentiment_schema,
  key_name = "OPENAI_API_KEY",
  concurrent_requests = 5 # send 5 rows of data simultaneously
)

Read the LLM Providers Vignette, and the Structured Outputs Vignette for more information on common workflows with the OpenAI Chat Completions API ¹

API Key Security

• Read the httr2 vignette on managing your API keys securely and encrypting them.

• Read the EndpointR API Keys vignette for information on which API keys you need for wach endpoint we support, and how to securely import those API keys into your .Renvironfile.