tidyllm: Tidy Integration of Large Language Models

Description

A tidy interface for integrating large language model (LLM) APIs such as 'Claude', 'Openai', 'Gemini','Mistral' and local models via 'Ollama' into R workflows. The package supports text and media-based interactions, interactive message history, batch request APIs, and a tidy, pipeline-oriented interface for streamlined integration into data workflows. Web services are available at https://www.anthropic.com, https://openai.com, https://aistudio.google.com/, https://mistral.ai/ and https://ollama.com.

Author(s)

Maintainer: Eduard Brüll eduard.bruell@zew.de

Other contributors:

• Jia Zhang [contributor]

See Also

Useful links:

• https://edubruell.github.io/tidyllm/

• Report bugs at https://github.com/edubruell/tidyllm/issues

Large Language Model Message Class

Description

LLMMessage is an S7 class for managing a conversation history intended for use with large language models (LLMs). Please use llm_message()to create or modify LLMMessage objects.

Usage

LLMMessage(message_history = list(), system_prompt = character(0))

Arguments

Details

The LLMMessage class includes the following features:

• Stores message history in a structured format.

• Supports attaching media and metadata to messages.

• Provides generics like add_message(), has_image(), and remove_message() for interaction.

• Enables API-specific formatting through the to_api_format() generic.

• message_history: A list containing messages. Each message is a named list with keys like role, content, media, etc.

• system_prompt: A character string representing the default system prompt used for the conversation.

Azure OpenAI Endpoint Provider Function

Description

The azure_openai() function acts as an interface for interacting with the Azure OpenAI API through main tidyllm verbs.

Usage

azure_openai(..., .called_from = NULL)

Arguments

Details

azure_openai() currently routes messages only to azure_openai_chat() when used with chat().

send_batch(). It dynamically routes requests to OpenAI-specific functions like azure_openai_chat() and azure_openai_embedding() based on the context of the call.

Value

The result of the requested action, depending on the specific function invoked (currently, only an updated LLMMessage object for azure_openai_chat()).

Send LLM Messages to an Azure OpenAI Chat Completions endpoint

Description

This function sends a message history to the Azure OpenAI Chat Completions API and returns the assistant's reply.

Usage

azure_openai_chat(
  .llm,
  .endpoint_url = Sys.getenv("AZURE_ENDPOINT_URL"),
  .deployment = "gpt-4o-mini",
  .api_version = "2024-08-01-preview",
  .max_completion_tokens = NULL,
  .reasoning_effort = NULL,
  .frequency_penalty = NULL,
  .logit_bias = NULL,
  .presence_penalty = NULL,
  .seed = NULL,
  .stop = NULL,
  .stream = FALSE,
  .temperature = NULL,
  .top_p = NULL,
  .timeout = 60,
  .verbose = FALSE,
  .json_schema = NULL,
  .max_tries = 3,
  .dry_run = FALSE,
  .logprobs = NULL,
  .top_logprobs = NULL,
  .tools = NULL,
  .tool_choice = NULL,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Generate Embeddings Using OpenAI API on Azure

Description

Generate Embeddings Using OpenAI API on Azure

Usage

azure_openai_embedding(
  .input,
  .deployment = "text-embedding-3-small",
  .endpoint_url = Sys.getenv("AZURE_ENDPOINT_URL"),
  .api_version = "2023-05-15",
  .truncate = TRUE,
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3
)

Arguments

Value

A tibble with two columns: input and embeddings. The input column contains the texts sent to embed, and the embeddings column is a list column where each row contains an embedding vector of the sent input.

Cancel an In-Progress OpenAI Batch

Description

This function cancels an in-progress batch created through the OpenAI API. The batch will be moved to a "cancelling" state and, eventually, "cancelled."

Usage

cancel_openai_batch(.batch_id, .dry_run = FALSE, .max_tries = 3, .timeout = 60)

Arguments

Value

A list containing the response from the OpenAI API about the cancellation status.

Chat with a Language Model

Description

The chat() function sends a message to a language model via a specified provider and returns the response. It routes the provided LLMMessage object to the appropriate provider-specific chat function, while allowing for the specification of common arguments applicable across different providers.

Usage

chat(
  .llm,
  .provider = getOption("tidyllm_chat_default"),
  .dry_run = NULL,
  .stream = NULL,
  .temperature = NULL,
  .timeout = NULL,
  .top_p = NULL,
  .max_tries = NULL,
  .model = NULL,
  .verbose = NULL,
  .json_schema = NULL,
  .tools = NULL,
  .max_tool_rounds = NULL,
  .seed = NULL,
  .stop = NULL,
  .frequency_penalty = NULL,
  .presence_penalty = NULL
)

Arguments

Details

The chat() function provides a unified interface for interacting with different language model providers. Common arguments such as .temperature, .model, and .stream are supported by most providers and can be passed directly to chat(). If a provider does not support a particular argument, an error will be raised.

Advanced provider-specific configurations can be accessed via the provider functions.

Value

An updated LLMMessage object containing the response from the language model.

Examples

## Not run: 
# Basic usage with OpenAI provider
llm_message("Hello World") |>
   chat(ollama(.ollama_server = "https://my-ollama-server.de"),.model="mixtral")
   
   chat(mistral,.model="mixtral")

# Use streaming with Claude provider
llm_message("Tell me a story") |>
   chat(claude(),.stream=TRUE)

## End(Not run)

Send LLM Messages to Ellmer Chat Object

Description

This function converts an LLMMessage to the turns ellmer chat object. The ellmer object is cloned and its turn history is cleared internatlly. This maintains tidyllms stateless style.

Usage

chat_ellmer(
  .llm,
  .ellmer_chat,
  .stream = FALSE,
  .timeout = 60,
  .verbose = FALSE,
  .dry_run = FALSE,
  .tools = NULL,
  .max_tries = 3
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Alias for the OpenAI Provider Function

Description

The chatgpt function is an alias for the openai() provider function. It provides a convenient way to interact with the OpenAI API for tasks such as sending chat messages, generating embeddings, and handling batch operations using tidyllm verbs like chat(), embed(), and send_batch().

Usage

chatgpt(..., .called_from = NULL)

Arguments

Value

The result of the requested action, depending on the specific function invoked (e.g., an updated LLMMessage object for chat(), or a matrix for embed()).

Check Batch Processing Status for Azure OpenAI Batch API

Description

This function retrieves the processing status and other details of a specified Azure OpenAI batch ID from the Azure OpenAI Batch API.

Usage

check_azure_openai_batch(
  .llms = NULL,
  .endpoint_url = Sys.getenv("AZURE_ENDPOINT_URL"),
  .batch_id = NULL,
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with information about the status of batch processing.

Check Batch Processing Status

Description

This function retrieves the processing status and other details of a specified batchid or a list of LLMMessage objects with batch attribute. It routes the input to the appropriate provider-specific batch API function.

Usage

check_batch(
  .llms,
  .provider = getOption("tidyllm_cbatch_default"),
  .dry_run = NULL,
  .max_tries = NULL,
  .timeout = NULL
)

Arguments

Value

A tibble with information about the status of batch processing.

Check Batch Processing Status for Claude API

Description

This function retrieves the processing status and other details of a specified Claude batch ID from the Claude API.

Usage

check_claude_batch(
  .llms = NULL,
  .batch_id = NULL,
  .api_url = "https://api.anthropic.com/",
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with information about the status of batch processing

Check the Status of a Gemini Batch Operation

Description

Retrieves processing status and metadata for a Gemini batch operation.

Usage

check_gemini_batch(
  .llms = NULL,
  .batch_id = NULL,
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Details

You can supply either the .batch_id string (e.g. "batches/xyz...") or a list of LLMMessage objects (.llms) with a "batch_id" attribute as returned by send_gemini_batch().

Value

A tibble with the operation's metadata, including name, state, creation time, completion time, and done status.

Check Batch Processing Status for Groq API

Description

This function retrieves the processing status and other details of a specified Groq batch.

Usage

check_groq_batch(
  .llms = NULL,
  .batch_id = NULL,
  .api_url = "https://api.groq.com/",
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with information about the status of batch processing.

Check the Status of a Batch or Research Job

Description

check_job() dispatches to check_batch() for batch objects or perplexity_check_research() for tidyllm_research_job objects.

Usage

check_job(.job, ...)

Arguments

Value

Status information; type depends on .job class.

Check Batch Processing Status for Mistral Batch API

Description

This function retrieves the processing status and other details of a specified Mistral batch ID from the Mistral Batch API.

Usage

check_mistral_batch(
  .llms = NULL,
  .batch_id = NULL,
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with information about the status of batch processing.

Check Batch Processing Status for OpenAI Batch API

Description

This function retrieves the processing status and other details of a specified OpenAI batch ID from the OpenAI Batch API.

Usage

check_openai_batch(
  .llms = NULL,
  .batch_id = NULL,
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with information about the status of batch processing.

Provider Function for Claude models on the Anthropic API

Description

The claude() function acts as an interface for interacting with the Anthropic API through main tidyllm verbs such as chat(), embed(), and send_batch(). It dynamically routes requests to Claude-specific functions like claude_chat() and send_claude_batch() based on the context of the call.

Usage

claude(..., .called_from = NULL)

Arguments

Value

The result of the requested action, depending on the specific function invoked (e.g., an updated LLMMessage object for chat(), or a matrix for embed()).

Interact with Claude AI models via the Anthropic API

Description

Interact with Claude AI models via the Anthropic API

Usage

claude_chat(
  .llm,
  .model = "claude-sonnet-4-6",
  .max_tokens = 2048,
  .temperature = NULL,
  .top_k = NULL,
  .top_p = NULL,
  .metadata = NULL,
  .stop_sequences = NULL,
  .tools = NULL,
  .json_schema = NULL,
  .file_ids = NULL,
  .api_url = "https://api.anthropic.com/",
  .verbose = FALSE,
  .max_tries = 3,
  .timeout = 60,
  .stream = FALSE,
  .dry_run = FALSE,
  .thinking = FALSE,
  .thinking_budget = 1024,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus Claude's response.

Examples

## Not run: 
# Basic usage
msg <- llm_message("What is R programming?")
result <- claude_chat(msg)

# With custom parameters
result2 <- claude_chat(msg, 
                 .temperature = 0.7, 
                 .max_tokens = 1000)

## End(Not run)

Delete a File from Claude API

Description

Deletes a specific file from the Claude API using its file ID.

Usage

claude_delete_file(
  .file_id,
  .api_url = "https://api.anthropic.com/",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

Invisibly returns NULL. Prints a confirmation message upon successful deletion.

Retrieve Metadata for a File from Claude API

Description

Retrieves metadata for a specific file uploaded to the Claude API.

Usage

claude_file_metadata(
  .file_id,
  .api_url = "https://api.anthropic.com/",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

A tibble containing metadata fields such as file_id, filename, size, and MIME type.

List Files in Claude API

Description

Lists metadata for files uploaded to the Claude API, supporting pagination.

Usage

claude_list_files(
  .limit = 20,
  .order = "desc",
  .api_url = "https://api.anthropic.com/",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

A tibble containing metadata for each file, including file_id, filename, size, and MIME type.

List Available Models from the Anthropic Claude API

Description

List Available Models from the Anthropic Claude API

Usage

claude_list_models(
  .api_url = "https://api.anthropic.com",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE,
  .verbose = FALSE
)

Arguments

Value

A tibble containing model information (columns include type,id, display_name, and created_at), or NULL if no models are found.

Upload a File to Claude API

Description

Uploads a file to the Claude API and returns its metadata as a tibble.

Usage

claude_upload_file(
  .file_path,
  .api_url = "https://api.anthropic.com/",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

A tibble containing metadata about the uploaded file, including its file_id, name, and size.

Builtin Claude Web Search Tool

Description

Returns a TOOL object for Claude's builtin web_search tool.

Usage

claude_websearch()

Run Deep Research via a Provider

Description

The deep_research() function sends a message to a provider's deep research endpoint. Currently supported: Perplexity (sonar-deep-research via async API).

Usage

deep_research(.llm, .provider, .background = FALSE, ...)

Arguments

Value

If .background = FALSE, an LLMMessage with the research reply. If .background = TRUE, a tidyllm_research_job for use with check_job()/fetch_job().

Deepseek Provider Function

Description

The deepseek() function acts as a provider interface for interacting with the Deepseek API through tidyllm's chat() verb. It dynamically routes requests to deepseek-specific function. At the moment this is only deepseek_chat()

Usage

deepseek(..., .called_from = NULL)

Arguments

Value

The result of the requested action, depending on the specific function invoked (e.g., an updated LLMMessage object for chat()).

Send LLM Messages to the DeepSeek Chat API

Description

This function sends a message history to the DeepSeek Chat API and returns the assistant's reply. Currently tool calls cause problems on the DeepSeek API

Usage

deepseek_chat(
  .llm,
  .model = "deepseek-chat",
  .thinking = NULL,
  .max_tokens = 2048,
  .temperature = NULL,
  .top_p = NULL,
  .frequency_penalty = NULL,
  .presence_penalty = NULL,
  .stop = NULL,
  .stream = FALSE,
  .logprobs = NULL,
  .top_logprobs = NULL,
  .tools = NULL,
  .tool_choice = NULL,
  .api_url = "https://api.deepseek.com/",
  .timeout = 60,
  .verbose = FALSE,
  .dry_run = FALSE,
  .max_tries = 3,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Convert a Data Frame to an LLMMessage Object

Description

This function converts a data frame into an LLMMessage object representing a conversation history. The data frame must have specific columns (role and content), with each row representing a message.

Usage

df_llm_message(.df)

Arguments

Value

An LLMMessage object representing the structured conversation.

See Also

llm_message()

Other Message Creation Utilities: llm_message()

Alias for the Ellmer Provider Function

Description

The chat_ellmer() function acts as a provider interface for interacting with ellmer chat objects through tidyllm's verb interface

Usage

ellmer(..., .called_from = NULL)

Arguments

Details

This function allows you to use any ellmer chat object (e.g., from ellmer::chat_anthropic(), ellmer::chat_openai(), etc.) as a stateless backend for tidyllm. The ellmer object is cloned for each interaction to maintain tidyllm's stateless approach.

Value

A provider function that can be used with tidyllm::chat().

Convert an ellmer Tool to a tidyllm TOOL

Description

Converts an ellmer ToolDef or ToolBuiltIn object to a tidyllm TOOL object, allowing seamless integration of ellmer-defined tools and builtin provider tools with tidyllm workflows.

Usage

ellmer_tool(.ellmer_tool)

Arguments

Details

This function supports two types of ellmer tools:

Custom ToolDef objects: Extracts the function, description, and argument schemas from an ellmer tool and converts them to tidyllm's internal representation. Ellmer type objects are automatically converted to tidyllm field descriptors.

Builtin ToolBuiltIn objects: Converts provider-native builtin tools (like Claude's web search) to tidyllm format. For builtin tools, the tool definition is passed through as-is to the provider's API, which handles the tool execution natively.

Value

A TOOL class object that can be used with tidyllm chat() functions

Examples

## Not run: 
library(ellmer)

# Example 1: Custom tool
tool_rnorm <- ellmer::tool(
  rnorm,
  description = "Draw numbers from a random normal distribution",
  arguments = list(
    n = ellmer::type_integer("The number of observations"),
    mean = ellmer::type_number("The mean value"),
    sd = ellmer::type_number("The standard deviation")
  )
)

tidyllm_tool_rnorm <- ellmer_tool(tool_rnorm)

llm_message("Generate 100 random numbers") |> 
  chat(openai(), .tools = tidyllm_tool_rnorm)

# Example 2: Builtin tool
web_search <- ellmer_tool(ellmer::claude_tool_web_search())
llm_message("What are the latest AI developments?") |>
  chat(claude(), .tools = web_search)

## End(Not run)

Generate text embeddings

Description

The embed() function allows you to embed a text via a specified provider. It routes the input to the appropriate provider-specific embedding function.

Usage

embed(
  .input,
  .provider = getOption("tidyllm_embed_default"),
  .model = NULL,
  .truncate = NULL,
  .timeout = NULL,
  .dry_run = NULL,
  .max_tries = NULL
)

Arguments

Value

A tibble with two columns: input and embeddings. The input column contains the texts sent to embed, and the embeddings column is a list column where each row contains an embedding vector of the sent input.

Examples

## Not run: 
c("What is the meaning of life, the universe and everything?",
 "How much wood would a woodchuck chuck?",
 "How does the brain work?") |>
 embed(gemini)
 
## End(Not run)

Fetch Results for an Azure OpenAI Batch

Description

This function retrieves the results of a completed Azure OpenAI batch and updates the provided list of LLMMessage objects with the responses. It aligns each response with the original request using the custom_ids generated in send_azure_openai_batch().

Usage

fetch_azure_openai_batch(
  .llms,
  .endpoint_url = Sys.getenv("AZURE_ENDPOINT_URL"),
  .batch_id = NULL,
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A list of updated LLMMessage objects, each with the assistant's response added if successful.

Fetch Results from a Batch API

Description

This function retrieves the results of a completed batch and updates the provided list of LLMMessage objects with the responses. It aligns each response with the original request using the custom_ids generated in send_batch().

Usage

fetch_batch(
  .llms,
  .provider = getOption("tidyllm_fbatch_default"),
  .dry_run = NULL,
  .max_tries = NULL,
  .timeout = NULL
)

Arguments

Details

The function routes the input to the appropriate provider-specific batch API function.

Value

A list of updated LLMMessage objects, each with the assistant's response added if successful.

Fetch Results for a Claude Batch

Description

This function retrieves the results of a completed Claude batch and updates the provided list of LLMMessage objects with the responses. It aligns each response with the original request using the custom_ids generated in send_claude_batch().

Usage

fetch_claude_batch(
  .llms,
  .batch_id = NULL,
  .api_url = "https://api.anthropic.com/",
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A list of updated LLMMessage objects, each with the assistant's response added if successful.

Fetch Results for a Gemini Batch

Description

Retrieves the results of a completed Gemini batch and updates the provided list of LLMMessage objects with the assistant's responses, matching by original list order.

Usage

fetch_gemini_batch(
  .llms,
  .batch_name = NULL,
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

A list of updated LLMMessage objects with the assistant response appended to each, in the same order.

Fetch Results for a Groq Batch

Description

This function retrieves the results of a completed Groq batch and updates the provided list of LLMMessage objects with the responses.

Usage

fetch_groq_batch(
  .llms,
  .batch_id = NULL,
  .api_url = "https://api.groq.com/",
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A list of updated LLMMessage objects, each with the assistant's response added if successful.

Fetch Results from a Batch or Research Job

Description

fetch_job() dispatches to fetch_batch() for batch objects or perplexity_fetch_research() for tidyllm_research_job objects.

Usage

fetch_job(.job, .provider = NULL, ...)

Arguments

Value

Fetched results; type depends on .job class.

Fetch Results for an Mistral Batch

Description

This function retrieves the results of a completed Mistral batch and updates the provided list of LLMMessage objects with the responses. It aligns each response with the original request using the custom_ids generated in send_mistral_batch().

Usage

fetch_mistral_batch(
  .llms,
  .batch_id = NULL,
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A list of updated LLMMessage objects, each with the assistant's response added if successful.

Fetch Results for an OpenAI Batch

Description

This function retrieves the results of a completed OpenAI batch and updates the provided list of LLMMessage objects with the responses. It aligns each response with the original request using the custom_ids generated in send_openai_batch().

Usage

fetch_openai_batch(
  .llms,
  .batch_id = NULL,
  .dry_run = FALSE,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A list of updated LLMMessage objects, each with the assistant's response added if successful.

Define Field Descriptors for JSON Schema

Description

These functions create field descriptors used in tidyllm_schema() or field_object() to define JSON schema fields. They support character, factor, numeric, and logical types.

Usage

field_chr(.description = character(0), .vector = FALSE)

field_fct(.description = character(0), .levels, .vector = FALSE)

field_dbl(.description = character(0), .vector = FALSE)

field_lgl(.description = character(0), .vector = FALSE)

Arguments

Value

An S7 tidyllm_field object representing the field descriptor.

Examples

field_chr("A common street name")
field_fct("State abbreviation", .levels = c("CA", "TX", "Other"))
field_dbl("House number")
field_lgl("Is residential")
field_dbl("A list of appartment numbers at the address",.vector=TRUE )

Define a nested object field

Description

Define a nested object field

Usage

field_object(.description = character(0), ..., .vector = FALSE)

Arguments

Value

An S7 tidyllm_field object of type "object" containing nested fields.

Examples

# Define an address object with nested fields
address <- field_object("A mailing address",
  street = field_chr("Street name"),
  city = field_chr("City name"),
  zipcode = field_chr("Postal code")
)

# Create a vector of objects
addresses <- field_object("List of addresses", 
  street = field_chr("Street name"),
  city = field_chr("City name"),
  .vector = TRUE
)

Google Gemini Provider Function

Description

The gemini() function acts as a provider interface for interacting with the Google Gemini API through tidyllm's main verbs such as chat() and embed(). It dynamically routes requests to Gemini-specific functions like gemini_chat() and gemini_embedding() based on the context of the call.

Usage

gemini(..., .called_from = NULL)

Arguments

Details

Some functions, such as gemini_upload_file() and gemini_delete_file(), are specific to Gemini and do not have general verb counterparts.

Value

The result of the requested action, depending on the specific function invoked (e.g., an updated LLMMessage object for chat()).

Send LLMMessage to Gemini API

Description

Send LLMMessage to Gemini API

Usage

gemini_chat(
  .llm,
  .model = "gemini-2.5-flash",
  .fileid = NULL,
  .temperature = NULL,
  .max_output_tokens = NULL,
  .top_p = NULL,
  .top_k = NULL,
  .grounding_threshold = NULL,
  .presence_penalty = NULL,
  .frequency_penalty = NULL,
  .stop_sequences = NULL,
  .safety_settings = NULL,
  .json_schema = NULL,
  .tools = NULL,
  .thinking_budget = NULL,
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3,
  .verbose = FALSE,
  .stream = FALSE,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Delete a File from Gemini API

Description

Deletes a specific file from the Gemini API using its file ID.

Usage

gemini_delete_file(.file_name)

Arguments

Value

Invisibly returns NULL. Prints a confirmation message upon successful deletion.

Generate Embeddings Using the Google Gemini API

Description

Generate Embeddings Using the Google Gemini API

Usage

gemini_embedding(
  .input,
  .model = "gemini-embedding-2-preview",
  .truncate = TRUE,
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3
)

Arguments

Value

A matrix where each column corresponds to the embedding of a message in the message history.

Retrieve Metadata for a File from Gemini API

Description

Retrieves metadata for a specific file uploaded to the Gemini API.

Usage

gemini_file_metadata(.file_name)

Arguments

Value

A tibble containing metadata fields such as name, display name, MIME type, size, and URI.

List Files in Gemini API

Description

Lists metadata for files uploaded to the Gemini API, supporting pagination.

Usage

gemini_list_files(.page_size = 10, .page_token = NULL)

Arguments

Value

A tibble containing metadata for each file, including fields such as name, display name, MIME type, and URI.

List Available Models from the Google Gemini API

Description

List Available Models from the Google Gemini API

Usage

gemini_list_models(.timeout = 60, .max_tries = 3, .dry_run = FALSE)

Arguments

Value

A tibble containing model information with columns including name, base_model_id, version, display_name, description, input_token_limit, output_token_limit, supported_generation_methods, thinking, temperature, max_temperature, top_p, and top_k, or NULL if no models are found.

Upload a File to Gemini API

Description

Uploads a file to the Gemini API and returns its metadata as a tibble.

Usage

gemini_upload_file(.file_path)

Arguments

Value

A tibble containing metadata about the uploaded file, including its name, URI, and MIME type.

Retrieve Log Probabilities from Assistant Replies

Description

Extracts token log probabilities from assistant replies within an LLMMessage object. Each row represents a token with its log probability and top alternative tokens.

Usage

get_logprobs(.llm, .index = NULL)

Arguments

Details

An empty tibble is output if no logprobs were requested. Works with openai_chat(), llamacpp_chat(), and other providers that support logprobs.

Columns include:

• reply_index: The index of the assistant reply in the message history.

• token: The generated token.

• logprob: The log probability of the generated token.

• bytes: The byte-level encoding of the token.

• top_logprobs: A list column containing the top alternative tokens with their log probabilities.

Value

A tibble containing log probabilities for the specified assistant reply or all replies.

See Also

get_metadata()

Retrieve Metadata from Assistant Replies

Description

Retrieves metadata from assistant replies within an LLMMessage object. It returns the metadata as a tibble.

Usage

get_metadata(.llm, .index = NULL)

last_metadata(.llm)

Arguments

Details

Metadata columns may include:

• model: The model used for generating the reply.

• timestamp: The time when the reply was generated.

• prompt_tokens: The number of tokens in the input prompt.

• completion_tokens: The number of tokens in the assistant's reply.

• total_tokens: The total number of tokens (prompt + completion).

• api_specific: A list column with API-specific metadata.

For convenience, last_metadata() is provided to retrieve the metadata for the last message.

Value

A tibble containing metadata for the specified assistant reply or all replies.

See Also

last_metadata()

Retrieve Assistant Reply as Text

Description

Extracts the plain text content of the assistant's reply from an LLMMessage object. Use get_reply_data() for structured replies in JSON format.

Usage

get_reply(.llm, .index = NULL)

last_reply(.llm)

Arguments

Details

This function is the core utility for retrieving assistant replies by index. For convenience, last_reply() is provided as a wrapper to retrieve the latest assistant reply.

Value

Returns a character string containing the assistant's reply, or NA_character_ if no reply exists.

See Also

get_reply_data(), last_reply()

Retrieve Assistant Reply as Structured Data

Description

Parses the assistant's reply as JSON and returns the corresponding structured data. If the reply is not marked as JSON, attempts to extract and parse JSON content from the text.

Usage

get_reply_data(.llm, .index = NULL)

last_reply_data(.llm)

Arguments

Details

For convenience, last_reply_data() is provided as a wrapper to retrieve the latest assistant reply's data.

Value

Returns the parsed data from the assistant's reply, or NULL if parsing fails.

See Also

get_reply(), last_reply_data()

Retrieve a User Message by Index

Description

Extracts the content of a user's message from an LLMMessage object at a specific index.

Usage

get_user_message(.llm, .index = NULL)

last_user_message(.llm)

Arguments

Details

For convenience, last_user_message() is provided as a wrapper to retrieve the latest user message without specifying an index.

Value

Returns the content of the user's message at the specified index. If no messages are found, returns NA_character_.

See Also

last_user_message()

Groq API Provider Function

Description

The groq() function acts as an interface for interacting with the Groq API through tidyllm's main verbs. Currently, Groq only supports groq_chat() for chat-based interactions and groq_transcribe() for transcription tasks.

Usage

groq(..., .called_from = NULL)

Arguments

Details

Since groq_transcribe() is unique to Groq and does not have a general verb counterpart, groq() currently routes messages only to groq_chat() when used with verbs like chat().

Value

The result of the requested action, depending on the specific function invoked (currently, only an updated LLMMessage object for groq_chat()).

Send LLM Messages to the Groq Chat API

Description

This function sends a message history to the Groq Chat API and returns the assistant's reply.

Usage

groq_chat(
  .llm,
  .model = "moonshotai/kimi-k2-instruct-0905",
  .max_tokens = 1024,
  .temperature = NULL,
  .top_p = NULL,
  .frequency_penalty = NULL,
  .presence_penalty = NULL,
  .stop = NULL,
  .seed = NULL,
  .tools = NULL,
  .tool_choice = NULL,
  .api_url = "https://api.groq.com/",
  .json_schema = NULL,
  .timeout = 60,
  .verbose = FALSE,
  .stream = FALSE,
  .dry_run = FALSE,
  .max_tries = 3,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Examples

## Not run: 
# Basic usage
msg <- llm_message("What is Groq?")
result <- groq_chat(msg)

# With custom parameters
result2 <- groq_chat(msg, 
               .model = "llama-3.2-vision",
               .temperature = 0.5, 
               .max_tokens = 512)

## End(Not run)

List Available Models from the Groq API

Description

List Available Models from the Groq API

Usage

groq_list_models(
  .api_url = "https://api.groq.com",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE,
  .verbose = FALSE
)

Arguments

Value

A tibble containing model information (columns include id, created, owned_by, and context_window), or NULL if no models are found.

Transcribe an Audio File Using Groq transcription API

Description

This function reads an audio file and sends it to the Groq transcription API for transcription.

Usage

groq_transcribe(
  .audio_file,
  .model = "playai-tts",
  .language = NULL,
  .prompt = NULL,
  .temperature = 0,
  .api_url = "https://api.groq.com/openai/v1/audio/transcriptions",
  .dry_run = FALSE,
  .verbose = FALSE,
  .max_tries = 3
)

Arguments

Value

A character vector containing the transcription.

Examples

## Not run: 
# Basic usage
groq_transcribe(.audio_file = "example.mp3")

## End(Not run)

Create an Image Object

Description

This function reads an image file from disk, encodes it in base64, and returns a tidyllm_image object that can be used in multimodal embedding requests.

Usage

img(.path)

Arguments

Value

An tidyllm_image, containing:

• imagepath: The original file path

• imagename: The basename of the image

• imagebase64: a "data:image/...;base64,..." string

List Azure OpenAI Batch Requests

Description

Retrieves batch request details from the Azure OpenAI Batch API.

Usage

list_azure_openai_batches(
  .endpoint_url = Sys.getenv("AZURE_ENDPOINT_URL"),
  .limit = 20,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with batch details: batch ID, status, creation time, expiration time, and request counts (total, completed, failed).

List all Batch Requests on a Batch API

Description

List all Batch Requests on a Batch API

Usage

list_batches(.provider = getOption("tidyllm_lbatch_default"))

Arguments

Value

A tibble with information about the status of batch processing.

List Claude Batch Requests

Description

Retrieves batch request details from the Claude API.

Usage

list_claude_batches(
  .api_url = "https://api.anthropic.com/",
  .limit = 20,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with batch details: batch ID, status, creation time, expiration time, and request counts (succeeded, errored, expired, canceled).

List Recent Gemini Batch Operations

Description

Returns a tibble with recent Gemini batch operations and their metadata.

Usage

list_gemini_batches(
  .filter = NULL,
  .page_size = 20,
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

A tibble with columns: name, state, done, create_time, complete_time.

List Groq Batch Requests

Description

Retrieves batch request details from the Groq API.

Usage

list_groq_batches(
  .api_url = "https://api.groq.com/",
  .limit = 20,
  .max_tries = 3,
  .timeout = 60
)

Arguments

Value

A tibble with batch details including batch ID, status, creation time, and request counts.

List GGUF Files Available in a Hugging Face Repository

Description

Calls the Hugging Face Hub API to list all .gguf files in a repository, along with their sizes. Useful for choosing a quantization level before calling llamacpp_download_model().

Usage

list_hf_gguf_files(.repo, .timeout = 30)

Arguments

Value

A tibble with columns filename, size_gb, and url.

List Mistral Batch Requests

Description

Retrieves batch request details from the OpenAI Batch API.

Usage

list_mistral_batches(
  .limit = 100,
  .max_tries = 3,
  .timeout = 60,
  .status = NULL,
  .created_after = NULL
)

Arguments

Value

A tibble with batch details for all batches fitting the request

List Available Models for a Provider

Description

The list_models() function retrieves available models from the specified provider.

Usage

list_models(.provider = getOption("tidyllm_lmodels_default"), ...)

Arguments

Value

A tibble containing model information.

List OpenAI Batch Requests

Description

Retrieves batch request details from the OpenAI Batch API.

Usage

list_openai_batches(.limit = 20, .max_tries = 3, .timeout = 60)

Arguments

Value

A tibble with batch details: batch ID, status, creation time, expiration time, and request counts (total, completed, failed).

llama.cpp Provider Function

Description

The llamacpp() provider connects tidyllm to a locally running llama.cpp server. It exposes the same verb/provider pattern as every other tidyllm provider while also offering llama.cpp-specific features: BNF grammar constraints (.grammar), token logprobs (.logprobs), and model management helpers.

The server must be started separately before calling llamacpp(). See llamacpp_health() to verify the server is running, and llamacpp_download_model() / list_hf_gguf_files() to obtain models.

Usage

llamacpp(..., .called_from = NULL)

Arguments

Value

The result of the requested action (e.g., an updated LLMMessage for chat(), a tibble for embed() or list_models()).

Send LLM Messages to a llama.cpp Server

Description

Sends a message history to a local llama.cpp server using the OpenAI-compatible Chat Completions API. Supports BNF grammar constraints (a llama.cpp-specific feature that enforces output format at the token sampling level) and token logprobs for uncertainty quantification.

Usage

llamacpp_chat(
  .llm,
  .model = "local-model",
  .max_tokens = 1024,
  .temperature = NULL,
  .top_p = NULL,
  .stop = NULL,
  .stream = FALSE,
  .tools = NULL,
  .tool_choice = NULL,
  .json_schema = NULL,
  .grammar = NULL,
  .logprobs = FALSE,
  .top_logprobs = NULL,
  .seed = NULL,
  .thinking = NULL,
  .thinking_budget = NULL,
  .server = Sys.getenv("LLAMACPP_SERVER", "http://localhost:8080"),
  .api_key = Sys.getenv("LLAMACPP_API_KEY", ""),
  .timeout = 120,
  .verbose = FALSE,
  .dry_run = FALSE,
  .max_tries = 3,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Delete a Local GGUF Model File

Description

Deletes a GGUF file from disk. Issues a warning confirming the deletion. Mirrors the ollama_delete_model() pattern.

Usage

llamacpp_delete_model(.path)

Arguments

Value

Invisibly returns TRUE on success.

Download a GGUF Model from Hugging Face

Description

Downloads a single GGUF file from a Hugging Face repository with a streaming progress bar. Use list_hf_gguf_files() first to browse available quantizations.

Usage

llamacpp_download_model(
  .repo,
  .filename,
  .dir = Sys.getenv("LLAMACPP_MODEL_DIR", "~/models"),
  .timeout = 3600
)

Arguments

Value

Invisibly returns the full path of the downloaded file.

Generate Embeddings Using a llama.cpp Server

Description

Sends text to the ⁠/v1/embeddings⁠ endpoint of a running llama.cpp server and returns embedding vectors.

Usage

llamacpp_embedding(
  .input,
  .model = "local-model",
  .server = Sys.getenv("LLAMACPP_SERVER", "http://localhost:8080"),
  .api_key = Sys.getenv("LLAMACPP_API_KEY", ""),
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3
)

Arguments

Value

A tibble with columns input (text) and embeddings (list of numeric vectors).

Check Health of the llama.cpp Server

Description

Calls the ⁠/health⁠ endpoint of a running llama.cpp server. Returns the status string ("ok", "loading model", "no model loaded", or "error") along with the full parsed response body as a named list.

Usage

llamacpp_health(
  .server = Sys.getenv("LLAMACPP_SERVER", "http://localhost:8080"),
  .timeout = 10
)

Arguments

Value

A named list with at least a status element.

List Local GGUF Model Files

Description

Scans a directory for .gguf files and returns a tibble with their names, sizes, and modification times. No server needed.

Usage

llamacpp_list_local_models(
  .path = Sys.getenv("LLAMACPP_MODEL_DIR", "~/models")
)

Arguments

Value

A tibble with columns filename, size_gb, modified, and path.

List Models Loaded in the llama.cpp Server

Description

Calls the ⁠/v1/models⁠ endpoint of a running llama.cpp server and returns the currently loaded model(s) as a tibble. In normal operation this is one row; two rows appear when speculative decoding is active (main + draft model).

Usage

llamacpp_list_models(
  .server = Sys.getenv("LLAMACPP_SERVER", "http://localhost:8080"),
  .api_key = Sys.getenv("LLAMACPP_API_KEY", ""),
  .timeout = 30,
  .max_tries = 3
)

Arguments

Value

A tibble with columns id, object, and created.

Rerank Documents Using a llama.cpp Server

Description

Calls the ⁠/v1/reranking⁠ endpoint of a running llama.cpp server to score documents by relevance to a query. Useful for building fully-local RAG pipelines (embed → cosine search → rerank → chat, all with llamacpp()).

Usage

llamacpp_rerank(
  .query,
  .documents,
  .model = "local-model",
  .server = Sys.getenv("LLAMACPP_SERVER", "http://localhost:8080"),
  .api_key = Sys.getenv("LLAMACPP_API_KEY", ""),
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

A tibble with columns index (original position), document (text), and relevance_score, sorted by descending score.

Create or Update Large Language Model Message Object

Description

This function creates a new LLMMessage object or updates an existing one. It supports adding text prompts and various media types, such as images, PDFs, text files, or plots.

Usage

llm_message(
  .llm = NULL,
  .prompt = NULL,
  .role = "user",
  .system_prompt = "You are a helpful assistant",
  .imagefile = NULL,
  .pdf = NULL,
  .textfile = NULL,
  .capture_plot = FALSE,
  .f = NULL
)

Arguments

Value

Returns an updated or new LLMMessage object.

See Also

df_llm_message()

Other Message Creation Utilities: df_llm_message()

Mistral Provider Function

Description

The mistral() function acts as an interface for interacting with the Mistral API through main tidyllm verbs such as chat() and embed(). It dynamically routes requests to Mistral-specific functions like mistral_chat() and mistral_embedding() based on the context of the call.

Usage

mistral(..., .called_from = NULL)

Arguments

Value

The result of the requested action, depending on the specific function invoked (e.g., an updated LLMMessage object for chat(), or a matrix for embed()).

Send LLMMessage to Mistral API

Description

Send LLMMessage to Mistral API

Usage

mistral_chat(
  .llm,
  .model = "mistral-large-latest",
  .frequency_penalty = NULL,
  .logit_bias = NULL,
  .presence_penalty = NULL,
  .seed = NULL,
  .stop = NULL,
  .stream = FALSE,
  .temperature = 0.7,
  .top_p = 1,
  .min_tokens = NULL,
  .max_tokens = NULL,
  .json_schema = NULL,
  .safe_prompt = FALSE,
  .timeout = 120,
  .max_tries = 3,
  .dry_run = FALSE,
  .verbose = FALSE,
  .tools = NULL,
  .tool_choice = NULL,
  .max_tool_rounds = 10
)

Arguments

Value

Returns an updated LLMMessage object.

Generate Embeddings Using Mistral API

Description

Generate Embeddings Using Mistral API

Usage

mistral_embedding(
  .input,
  .model = "mistral-embed",
  .timeout = 120,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

A matrix where each column corresponds to the embedding of a message in the message history.

List Available Models from the Mistral API

Description

List Available Models from the Mistral API

Usage

mistral_list_models(
  .api_url = "https://api.mistral.ai",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE,
  .verbose = FALSE
)

Arguments

Value

A tibble containing model information (columns include id and created), or NULL if no models are found.

Ollama API Provider Function

Description

The ollama() function acts as an interface for interacting with local AI models via the Ollama API. It integrates seamlessly with the main tidyllm verbs such as chat() and embed().

Usage

ollama(..., .called_from = NULL)

Arguments

Details

Some functionalities, like ollama_download_model() or ollama_list_models() are unique to the Ollama API and do not have a general verb counterpart. These functions can be only accessed directly.

Supported Verbs:

• chat(): Sends a message to an Ollama model and retrieves the model's response.

• embed(): Generates embeddings for input texts using an Ollama model.

• send_batch(): Behaves different than the other send_batch() verbs since it immediately processes the answers

Value

The result of the requested action:

• For chat(): An updated LLMMessage object containing the model's response.

• For embed(): A matrix where each column corresponds to an embedding.

Interact with local AI models via the Ollama API

Description

Interact with local AI models via the Ollama API

Usage

ollama_chat(
  .llm,
  .model = "qwen3.5:4b",
  .stream = FALSE,
  .seed = NULL,
  .json_schema = NULL,
  .temperature = NULL,
  .num_ctx = 2048,
  .num_predict = NULL,
  .top_k = NULL,
  .top_p = NULL,
  .min_p = NULL,
  .mirostat = NULL,
  .mirostat_eta = NULL,
  .mirostat_tau = NULL,
  .repeat_last_n = NULL,
  .repeat_penalty = NULL,
  .tools = NULL,
  .max_tool_rounds = 10,
  .tfs_z = NULL,
  .stop = NULL,
  .think = NULL,
  .ollama_server = "http://localhost:11434",
  .timeout = 120,
  .keep_alive = NULL,
  .dry_run = FALSE
)

Arguments

Details

The function provides extensive control over the generation process through various parameters:

• Temperature (0-2): Higher values increase creativity, lower values make responses more focused

• Top-k/Top-p: Control diversity of generated text

• Mirostat: Advanced sampling algorithm for maintaining consistent complexity

• Repeat penalties: Prevent repetitive text

• Context window: Control how much previous conversation is considered

Value

A new LLMMessage object containing the original messages plus the model's response

Examples

## Not run: 
llm_message("user", "Hello, how are you?")
response <- ollama_chat(llm, .model = "gemma2", .temperature = 0.7)

# With custom parameters
response <- ollama_chat(
  llm,
  .model = "llama2",
  .temperature = 0.8,
  .top_p = 0.9,
  .num_ctx = 4096
)

## End(Not run)

Delete a model from the Ollama API

Description

This function sends a DELETE request to the Ollama API to remove a specified model.

Usage

ollama_delete_model(.model, .ollama_server = "http://localhost:11434")

Arguments

Download a model from the Ollama API

Description

This function sends a request to the Ollama API to download a specified model from Ollama's large online library of models.

Usage

ollama_download_model(.model, .ollama_server = "http://localhost:11434")

Arguments

Generate Embeddings Using Ollama API

Description

Generate Embeddings Using Ollama API

Usage

ollama_embedding(
  .input,
  .model = "qwen3-embedding:0.6b",
  .truncate = TRUE,
  .ollama_server = "http://localhost:11434",
  .timeout = 120,
  .dry_run = FALSE
)

Arguments

Value

A matrix where each column corresponds to the embedding of a message in the message history.

Retrieve and return model information from the Ollama API

Description

This function connects to the Ollama API and retrieves information about available models, returning it as a tibble.

Usage

ollama_list_models(.ollama_server = "http://localhost:11434")

Arguments

Value

A tibble containing model information, or NULL if no models are found.

OpenAI Provider Function

Description

The openai() function acts as an interface for interacting with the OpenAI API through main tidyllm verbs such as chat(), embed(), and send_batch(). It dynamically routes requests to OpenAI-specific functions like openai_chat() and openai_embedding() based on the context of the call.

Usage

openai(..., .called_from = NULL)

Arguments

Value

The result of the requested action, depending on the specific function invoked (e.g., an updated LLMMessage object for chat(), or a matrix for embed()).

Send LLM Messages to the OpenAI Chat Completions API

Description

This function sends a message history to the OpenAI Chat Completions API and returns the assistant's reply.

Usage

openai_chat(
  .llm,
  .model = "gpt-5.1-chat-latest",
  .max_completion_tokens = NULL,
  .reasoning_effort = NULL,
  .frequency_penalty = NULL,
  .logit_bias = NULL,
  .presence_penalty = NULL,
  .seed = NULL,
  .stop = NULL,
  .stream = FALSE,
  .temperature = NULL,
  .top_p = NULL,
  .api_url = "https://api.openai.com/",
  .timeout = 60,
  .verbose = FALSE,
  .json_schema = NULL,
  .max_tries = 3,
  .dry_run = FALSE,
  .compatible = FALSE,
  .api_path = "/v1/chat/completions",
  .logprobs = NULL,
  .top_logprobs = NULL,
  .tools = NULL,
  .tool_choice = NULL,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Generate Embeddings Using OpenAI API

Description

Generate Embeddings Using OpenAI API

Usage

openai_embedding(
  .input,
  .model = "text-embedding-3-small",
  .truncate = TRUE,
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3,
  .verbose = FALSE
)

Arguments

Value

A tibble with two columns: input and embeddings. The input column contains the texts sent to embed, and the embeddings column is a list column where each row contains an embedding vector of the sent input.

List Available Models from the OpenAI API

Description

List Available Models from the OpenAI API

Usage

openai_list_models(
  .api_url = "https://api.openai.com",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE,
  .verbose = FALSE
)

Arguments

Value

A tibble containing model information (columns include id, created, and owned_by), or NULL if no models are found.

OpenRouter Provider Function

Description

The openrouter() function provides access to hundreds of AI models from different providers through the OpenRouter API, using a single OpenAI-compatible interface.

Usage

openrouter(..., .called_from = NULL)

Arguments

Value

The result of the requested action (e.g., an updated LLMMessage for chat()).

Send LLM Messages to the OpenRouter Chat API

Description

Sends a message history to the OpenRouter API, which provides access to hundreds of models from different providers through a single OpenAI-compatible endpoint.

Usage

openrouter_chat(
  .llm,
  .model = "anthropic/claude-sonnet-4-6",
  .max_tokens = 2048,
  .temperature = NULL,
  .top_p = NULL,
  .frequency_penalty = NULL,
  .presence_penalty = NULL,
  .stop = NULL,
  .stream = FALSE,
  .json_schema = NULL,
  .tools = NULL,
  .tool_choice = NULL,
  .provider = NULL,
  .route = NULL,
  .models = NULL,
  .api_url = "https://openrouter.ai",
  .timeout = 60,
  .verbose = FALSE,
  .dry_run = FALSE,
  .max_tries = 3,
  .max_tool_rounds = 10
)

Arguments

Value

A new LLMMessage object containing the original messages plus the assistant's response.

Get OpenRouter Credit Balance

Description

Returns the total credits purchased and total usage so far for the current API key.

Usage

openrouter_credits(
  .api_url = "https://openrouter.ai",
  .timeout = 60,
  .max_tries = 3
)

Arguments

Value

A tibble with columns total_credits (USD purchased), total_usage (USD consumed so far), and remaining (USD remaining).

Generate Embeddings Using the OpenRouter API

Description

Sends text to an embedding model accessible via OpenRouter and returns embedding vectors. Note that embedding models are not listed in list_models(openrouter()) — specify the model ID directly. Known supported models include "openai/text-embedding-3-small", "openai/text-embedding-3-large", and "mistralai/mistral-embed".

Usage

openrouter_embedding(
  .input,
  .model = "openai/text-embedding-3-small",
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3
)

Arguments

Value

A tibble with columns input (text) and embeddings (list of numeric vectors).

Get Details for an OpenRouter Generation

Description

Fetches cost, latency, and token details for a past generation using its ID. The generation ID is available in get_metadata(result)$api_specific$id after a chat() call.

Usage

openrouter_generation(
  .id,
  .api_url = "https://openrouter.ai",
  .timeout = 60,
  .max_tries = 3
)

Arguments

Value

A named list with generation details including id, model, total_cost, tokens_prompt, tokens_completion, and latency.

List Available Models on OpenRouter

Description

Retrieves the list of models available through the OpenRouter API, including pricing and context window information.

Usage

openrouter_list_models(
  .api_url = "https://openrouter.ai",
  .timeout = 60,
  .max_tries = 3,
  .dry_run = FALSE,
  .verbose = FALSE
)

Arguments

Value

A tibble with columns id, name, context_length, prompt_price_per_million, and completion_price_per_million, or NULL if no models are found.

Batch Process PDF into LLM Messages

Description

This function processes a PDF file page by page. For each page, it extracts the text and converts the page into an image. It creates a list of LLMMessage objects with the text and the image for multimodal processing. Users can specify a range of pages to process and provide a custom function to generate prompts for each page.

Usage

pdf_page_batch(
  .pdf,
  .general_prompt,
  .system_prompt = "You are a helpful assistant",
  .page_range = NULL,
  .prompt_fn = NULL
)

Arguments

Value

A list of LLMMessage objects, each containing the text and image for a page.

Perplexity Provider Function

Description

The perplexity() function acts as a provider interface for interacting with the Perplexity API through tidyllm's chat() verb. It dynamically routes requests to Perplxeity-specific function. At the moment this is only perplexity_chat()

Usage

perplexity(..., .called_from = NULL)

Arguments

Value

The result of the requested action, depending on the specific function invoked (e.g., an updated LLMMessage object for chat()).

Send LLM Messages to the Perplexity Chat API

Description

Sends a chat message history to the Perplexity Chat API, supporting all documented API parameters.

Usage

perplexity_chat(
  .llm,
  .model = "sonar",
  .max_tokens = 1024,
  .temperature = NULL,
  .top_p = NULL,
  .frequency_penalty = NULL,
  .presence_penalty = NULL,
  .stop = NULL,
  .search_domain_filter = NULL,
  .search_language_filter = NULL,
  .language_preference = NULL,
  .return_images = FALSE,
  .image_domain_filter = NULL,
  .image_format_filter = NULL,
  .search_recency_filter = NULL,
  .search_mode = "web",
  .search_after_date_filter = NULL,
  .search_before_date_filter = NULL,
  .last_updated_after_filter = NULL,
  .last_updated_before_filter = NULL,
  .disable_search = FALSE,
  .enable_search_classifier = FALSE,
  .reasoning_effort = NULL,
  .return_related_questions = FALSE,
  .user_location = NULL,
  .search_context_size = NULL,
  .search_type = NULL,
  .stream_mode = NULL,
  .json_schema = NULL,
  .top_k = NULL,
  .web_search_options = NULL,
  .api_url = "https://api.perplexity.ai/",
  .timeout = 60,
  .stream = FALSE,
  .verbose = FALSE,
  .max_tries = 3,
  .dry_run = FALSE
)

Arguments

Value

An updated LLMMessage object with the assistant's reply and metadata, including citations and search_results.

Check the Status of a Perplexity Deep Research Job

Description

Check the Status of a Perplexity Deep Research Job

Usage

perplexity_check_research(
  .job,
  .api_key = Sys.getenv("PERPLEXITY_API_KEY"),
  .max_tries = 3
)

Arguments

Value

An updated tidyllm_research_job with a ⁠$status⁠ field and ⁠$response⁠ if completed.

Submit a Deep Research Request to Perplexity

Description

Submit a Deep Research Request to Perplexity

Usage

perplexity_deep_research(
  .llm,
  .background = FALSE,
  .reasoning_effort = "medium",
  .search_context_size = "medium",
  .search_domain_filter = NULL,
  .search_language_filter = NULL,
  .language_preference = NULL,
  .search_recency_filter = NULL,
  .search_mode = NULL,
  .search_after_date_filter = NULL,
  .search_before_date_filter = NULL,
  .last_updated_after_filter = NULL,
  .last_updated_before_filter = NULL,
  .user_location = NULL,
  .json_schema = NULL,
  .idempotency_key = NULL,
  .api_key = Sys.getenv("PERPLEXITY_API_KEY"),
  .timeout = 300,
  .max_tries = 3
)

Arguments

Value

If .background = FALSE, an updated LLMMessage with the research reply. If .background = TRUE, a tidyllm_research_job object.

Fetch Results from a Completed Perplexity Deep Research Job

Description

Fetch Results from a Completed Perplexity Deep Research Job

Usage

perplexity_fetch_research(
  .job,
  .api_key = Sys.getenv("PERPLEXITY_API_KEY"),
  .max_tries = 3
)

Arguments

Value

An updated LLMMessage with the research reply appended.

Get the current rate limit information for all or a specific API

Description

This function retrieves the rate limit details for the specified API, or for all APIs stored in the .tidyllm_rate_limit_env if no API is specified.

Usage

rate_limit_info(.api_name = NULL)

Arguments

Value

A tibble containing the rate limit information.

Send a Batch of Messages to Azure OpenAI Batch API

Description

This function creates and submits a batch of messages to the Azure OpenAI Batch API for asynchronous processing.

Usage

send_azure_openai_batch(
  .llms,
  .endpoint_url = Sys.getenv("AZURE_ENDPOINT_URL"),
  .deployment = "gpt-4o-mini",
  .api_version = "2024-10-01-preview",
  .max_completion_tokens = NULL,
  .reasoning_effort = NULL,
  .frequency_penalty = NULL,
  .logit_bias = NULL,
  .presence_penalty = NULL,
  .seed = NULL,
  .stop = NULL,
  .temperature = NULL,
  .top_p = NULL,
  .logprobs = NULL,
  .top_logprobs = NULL,
  .dry_run = FALSE,
  .overwrite = FALSE,
  .max_tries = 3,
  .timeout = 60,
  .verbose = FALSE,
  .json_schema = NULL,
  .id_prefix = "tidyllm_azure_openai_req_"
)

Arguments

Value

An updated and named list of .llms with identifiers that align with batch responses, including a batch_id attribute.

Send a batch of messages to a batch API

Description

The send_batch() function allows you to send a list of LLMMessage objects to an API. It routes the input to the appropriate provider-specific batch API function.

Usage

send_batch(
  .llms,
  .provider = getOption("tidyllm_sbatch_default"),
  .dry_run = NULL,
  .temperature = NULL,
  .timeout = NULL,
  .top_p = NULL,
  .max_tries = NULL,
  .model = NULL,
  .verbose = NULL,
  .json_schema = NULL,
  .seed = NULL,
  .stop = NULL,
  .frequency_penalty = NULL,
  .presence_penalty = NULL,
  .id_prefix = NULL
)

Arguments

Value

An updated and named list of .llms with identifiers that align with batch responses, including a batch_id attribute.

Send a Batch of Messages to Claude API

Description

This function creates and submits a batch of messages to the Claude API for asynchronous processing.

Usage

send_claude_batch(
  .llms,
  .model = "claude-sonnet-4-6",
  .max_tokens = 1024,
  .temperature = NULL,
  .top_k = NULL,
  .top_p = NULL,
  .stop_sequences = NULL,
  .json_schema = NULL,
  .thinking = FALSE,
  .thinking_budget = 1024,
  .api_url = "https://api.anthropic.com/",
  .verbose = FALSE,
  .dry_run = FALSE,
  .overwrite = FALSE,
  .max_tries = 3,
  .timeout = 60,
  .id_prefix = "tidyllm_claude_req_"
)

Arguments

Value

An updated and named list of .llms with identifiers that align with batch responses, including a batch_id attribute.

Submit a list of LLMMessage objects to Gemini's batch API

Description

Returns a named list (same as input) with batch_id and json attributes.

Usage

send_gemini_batch(
  .llms,
  .model = "gemini-2.5-flash",
  .temperature = NULL,
  .max_output_tokens = NULL,
  .top_p = NULL,
  .top_k = NULL,
  .presence_penalty = NULL,
  .frequency_penalty = NULL,
  .stop_sequences = NULL,
  .safety_settings = NULL,
  .json_schema = NULL,
  .grounding_threshold = NULL,
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3,
  .display = "tidyllm_batch",
  .id_prefix = "tidyllm_gemini_req_"
)

Arguments

Value

Named list of LLMMessage objects with attributes batch_id and json

Send a Batch of Messages to the Groq API

Description

This function creates and submits a batch of messages to the Groq API for asynchronous processing.

Usage

send_groq_batch(
  .llms,
  .model = "openai/gpt-oss-120b",
  .max_tokens = 1024,
  .temperature = NULL,
  .top_p = NULL,
  .frequency_penalty = NULL,
  .presence_penalty = NULL,
  .stop = NULL,
  .seed = NULL,
  .api_url = "https://api.groq.com/",
  .json_schema = NULL,
  .completion_window = "24h",
  .verbose = FALSE,
  .dry_run = FALSE,
  .overwrite = FALSE,
  .max_tries = 3,
  .timeout = 60,
  .id_prefix = "tidyllm_groq_req_"
)

Arguments

Value

An updated and named list of .llms with identifiers that align with batch responses, including a batch_id attribute.

Send a Batch of Requests to the Mistral API

Description

This function creates and submits a batch of messages to the Mistral API for asynchronous processing.

Usage

send_mistral_batch(
  .llms,
  .model = "mistral-small-latest",
  .endpoint = "/v1/chat/completions",
  .metadata = NULL,
  .temperature = 0.7,
  .top_p = 1,
  .max_tokens = 1024,
  .min_tokens = NULL,
  .frequency_penalty = NULL,
  .logit_bias = NULL,
  .presence_penalty = NULL,
  .seed = NULL,
  .stop = NULL,
  .safe_prompt = FALSE,
  .json_schema = NULL,
  .dry_run = FALSE,
  .overwrite = FALSE,
  .max_tries = 3,
  .timeout = 60,
  .id_prefix = "tidyllm_mistral_req_"
)

Arguments

Value

The prepared LLMMessage list with a batch_id attribute.

Send a Batch of Messages to Ollama API

Description

This function creates and submits a batch of messages to the Ollama API Contrary to other batch functions, this functions waits for the batch to finish and receives requests. The advantage compared to sending single messages via chat() is that Ollama handles large parallel requests quicker than many individual chat requests.

Usage

send_ollama_batch(
  .llms,
  .model = "qwen3.5:4b",
  .stream = FALSE,
  .seed = NULL,
  .json_schema = NULL,
  .temperature = NULL,
  .num_ctx = 2048,
  .num_predict = NULL,
  .top_k = NULL,
  .top_p = NULL,
  .min_p = NULL,
  .mirostat = NULL,
  .mirostat_eta = NULL,
  .mirostat_tau = NULL,
  .repeat_last_n = NULL,
  .repeat_penalty = NULL,
  .tfs_z = NULL,
  .stop = NULL,
  .ollama_server = "http://localhost:11434",
  .timeout = 120,
  .keep_alive = NULL,
  .dry_run = FALSE
)

Arguments

Details

The function provides extensive control over the generation process through various parameters:

• Temperature (0-2): Higher values increase creativity, lower values make responses more focused

• Top-k/Top-p: Control diversity of generated text

• Mirostat: Advanced sampling algorithm for maintaining consistent complexity

• Repeat penalties: Prevent repetitive text

• Context window: Control how much previous conversation is considered

Value

A list of updated LLMMessage objects, each with the assistant's response added if successful.

Send a Batch of Messages to OpenAI Batch API

Description

This function creates and submits a batch of messages to the OpenAI Batch API for asynchronous processing.

Usage

send_openai_batch(
  .llms,
  .model = "gpt-5.4",
  .max_completion_tokens = NULL,
  .reasoning_effort = NULL,
  .frequency_penalty = NULL,
  .logit_bias = NULL,
  .presence_penalty = NULL,
  .seed = NULL,
  .stop = NULL,
  .temperature = NULL,
  .top_p = NULL,
  .logprobs = NULL,
  .top_logprobs = NULL,
  .dry_run = FALSE,
  .overwrite = FALSE,
  .json_schema = NULL,
  .max_tries = 3,
  .timeout = 60,
  .verbose = FALSE,
  .id_prefix = "tidyllm_openai_req_"
)

Arguments

Value

An updated and named list of .llms with identifiers that align with batch responses, including a batch_id attribute.

Create a JSON Schema for Structured Outputs

Description

This function creates a JSON schema for structured outputs, supporting both character-based shorthand and S7 tidyllm_field objects. It also integrates with ellmer types like ellmer::type_string() if ellmer is in your namespace

Usage

tidyllm_schema(name = "tidyllm_schema", ...)

Arguments

Value

A list representing the JSON schema, suitable for use with .json_schema in LLM API calls.

Examples

## Not run: 
# Example using different field types
address_schema <- tidyllm_schema(
  name = "AddressSchema",
  Street = field_chr("A common street name"),
  house_number = field_dbl(),
  City = field_chr("Name of a city"),
  State = field_fct("State abbreviation", .levels = c("CA", "TX", "Other")),
  Country = "string",
  PostalCode = "string"
)

llm_message("Imagine an address") |> chat(openai, .json_schema = address_schema)

# Example with vector field
tidyllm_schema(
  plz = field_dbl(.vector = TRUE)
)

## End(Not run)

Create a Tool Definition for tidyllm

Description

Creates a tool definition for use with Language Model API calls that support function calling. This function wraps an existing R function with schema information for LLM interaction.

Usage

tidyllm_tool(.f, .description = character(0), ...)

Arguments

Details

Each parameter schema in ... should correspond to a parameter in the wrapped function. All required function parameters must have corresponding schema definitions.

Value

A TOOL class object that can be used with tidyllm chat() functions

Examples

get_weather <- function(location){}
weather_tool <- tidyllm_tool(
  get_weather,
  "Get the current weather in a given location",
  location = field_chr("The city and state, e.g., San Francisco, CA")
)

Voyage Provider Function

Description

The voyage() function acts as a provider interface for interacting with the Voyage.ai API through tidyllm's verbs. It dynamically routes requests to voyage-specific functions. At the moment this is only voyage_embed()

Usage

voyage(..., .called_from = NULL)

Arguments

Value

The result of the requested action, depending on the specific function invoked

Generate Embeddings Using Voyage AI API

Description

This function creates embedding vectors from text or multimodal inputs (text and images) using the Voyage AI API. It supports three types of input:

Usage

voyage_embedding(
  .input,
  .model = "voyage-4",
  .output_dimension = NULL,
  .timeout = 120,
  .dry_run = FALSE,
  .max_tries = 3,
  .verbose = FALSE
)

Arguments

Details

1. Character vector: Embeds each text string separately

2. LLMMessage object: Extracts and embeds text content from messages

3. List of mixed content: Processes a combination of text strings and image objects created with img()

For multimodal inputs, the function automatically switches to Voyage's multimodal API and formats the response with appropriate labels (e.g., "[IMG] image.png") for images.

Value

A tibble with two columns: input and embeddings.

• The input column contains the input texts or image labels

• The embeddings column is a list column where each row contains an embedding vector

Examples

## Not run: 
# Text embeddings
voyage_embedding("How does photosynthesis work?")

# Multimodal embeddings
list("A banana", img("banana.jpg"), "Yellow fruit") |>
  voyage_embedding()

## End(Not run)

Rerank Documents Using Voyage AI API

Description

Rerank Documents Using Voyage AI API

Usage

voyage_rerank(
  .query,
  .documents,
  .model = "rerank-2",
  .top_k = NULL,
  .api_key = Sys.getenv("VOYAGE_API_KEY"),
  .timeout = 60,
  .max_tries = 3
)

Arguments

Value

A tibble with columns index, document, and relevance_score, sorted by score descending.