Package {rtemis.llm}

Title:	Large Language Models and Agentic AI
Version:	0.8.7
Date:	2026-09-17
Description:	Unified interface for creating LLM and Agent objects, generating responses and performing batch inference based on a type-checked and validated 'S7' backend. Features reasoning, structured output, memory management, and tool use. Supports 'Ollama' https://docs.ollama.com/api, 'OpenAI'-compatible https://developers.openai.com/api/reference/overview, and 'Anthropic'-compatible https://platform.claude.com/docs/en/api/getting-started endpoints. Runs Apple's on-device 'Foundation Models' through the 'rtemis-afm' bridge https://github.com/rtemis-org/rtemis-afm.
License:	GPL (≥ 3)
URL:	https://www.rtemis.org, https://docs.rtemis.org/r/llm, https://docs.rtemis.org/r/llm-api
BugReports:	https://github.com/rtemis-org/llm/issues
Encoding:	UTF-8
Imports:	data.table, digest, httr2, jsonlite, jsonvalidate (≥ 1.5.0), rtemis.core (≥ 0.4.6), S7
Suggests:	keyring, testthat (≥ 3.0.0), xml2
Config/testthat/edition:	3
Depends:	R (≥ 4.1.0)
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-09-24 12:08:28 UTC; sdg
Author:	E.D. Gennatas [aut, cre, cph]
Maintainer:	E.D. Gennatas <gennatas@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-24 12:40:12 UTC

rtemis.llm: Agentic AI for the rtemis ecosystem

Description

rtemis.llm provides functionality to interface with Large Language Models, part of the rtemis ecosystem. It provides an Agent class with support for reasoning, structured output, memory management, and tool use. Allows creation of custom LLM-based workflows and agentic AI systems using a functional user-facing frontend and an S7 backend. Includes llmapply() for quick batch LLM inference. Supports Ollama, OpenAI, and Anthropic endpoints.

Online Documentation and Vignettes

https://www.rtemis.org

Author(s)

Maintainer: E.D. Gennatas gennatas@gmail.com (ORCID) [copyright holder]

Authors:

• E.D. Gennatas gennatas@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://www.rtemis.org

• https://docs.rtemis.org/r/llm

• https://docs.rtemis.org/r/llm-api

• Report bugs at https://github.com/rtemis-org/llm/issues

Apply an Agent over a vector of prompts

Description

agentapply is the lapply-style entry point for running a single prompt against an Agent repeatedly over a vector of inputs. Pass either a model name (in which case an Agent is built on the fly using backend, system_prompt, tools, use_memory, max_tool_rounds, output_schema) or a pre-built Agent object.

Usage

agentapply(
  x,
  model_or_agent,
  backend = c("ollama", "openai", "anthropic"),
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  tools = NULL,
  use_memory = FALSE,
  max_tool_rounds = 3L,
  output_schema = NULL,
  verbosity = 1L,
  extract_responses = TRUE,
  on_error = c("na", "abort"),
  validate_output = TRUE,
  on_validation_failure = c("warn", "collect", "abort"),
  ...
)

Arguments

Details

Unlike llmapply, this function can carry tools and memory. The default is use_memory = FALSE because the common case for vectorized calls is independent queries.

Progress is reported through rtemis.core's nested progress API: one status line labelled with the model name, ticking once per element, with an ETA. Set verbosity = 0L to silence it. When a message sink is set (see rtemis.core::set_msg_sink()), progress is forwarded as structured events instead of being drawn, and nests under any enclosing progress node.

Value

If extract_responses = TRUE, a character vector the same length as x. Otherwise, a list of lists of Message objects. Under on_error = "na" the result carries an errors attribute: a data.frame of index and message, one row per failed call, so failures can be retried by position rather than found by scanning for NA. With a schema, validation_results retrieves per-input statuses and diagnostics. Invalid outputs remain in place under warn/collect; warn emits one informational summary message for the batch, respecting verbosity.

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  agentapply(
    c("today", "yesterday", "tomorrow"),
    "gemma4:e4b",
    system_prompt = "Return the date in ISO format",
    tools = list(tool_datetime),
    temperature = 0.2
  )

## End(Not run)

Check Anthropic Model Is Available

Description

Check Anthropic Model Is Available

Usage

anthropic_check_model(
  x,
  base_url = ANTHROPIC_URL_DEFAULT,
  api_key = NULL,
  api_key_env = ANTHROPIC_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  anthropic_version = ANTHROPIC_API_VERSION_DEFAULT
)

Arguments

Value

NULL, invisibly, if the model is available; otherwise throws an error.

Author(s)

EDG

Examples

# Requires running Anthropic-compatible server with /models endpoint
## Not run: 
  anthropic_check_model(
    x = "test-model",
    base_url = "http://localhost:1234/v1",
    api_key = "test-key"
  )

## End(Not run)

List Anthropic (Anthropic) Models

Description

List Anthropic (Anthropic) Models

Usage

anthropic_list_models(
  base_url = ANTHROPIC_URL_DEFAULT,
  api_key = NULL,
  api_key_env = ANTHROPIC_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  anthropic_version = ANTHROPIC_API_VERSION_DEFAULT
)

Arguments

Value

Character vector: Model ids.

Author(s)

EDG

Examples

# Requires running Anthropic-compatible server with /models endpoint
## Not run: 
  anthropic_list_models(
    base_url = "http://localhost:1234/v1",
   api_key = "test-key"
  )

## End(Not run)

Check the Apple Foundation Model Is Available

Description

Reads the bridge's health with apple_health and stops with a message that says what to do when the bridge is not running, the server is not rtemis-afm, or the model is unavailable (device not eligible, Apple Intelligence turned off, model still downloading).

Usage

apple_check_available(base_url = APPLE_URL_DEFAULT)

Arguments

Value

Named list, invisibly: The health response, if the model is available; otherwise throws an error.

Author(s)

EDG

Examples

# Requires a running rtemis-afm bridge
## Not run: 
  apple_check_available()

## End(Not run)

Read the rtemis-afm Bridge's Health

Description

Reads GET /health of a running rtemis-afm bridge and returns its body: status, version, and model, which carries the served model's id, name, availability ("available" or "unavailable"), reason when unavailable ("deviceNotEligible", "appleIntelligenceNotEnabled", or "modelNotReady"), and context_window in tokens.

Usage

apple_health(base_url = APPLE_URL_DEFAULT)

Arguments

Value

Named list: The parsed health response.

Author(s)

EDG

Examples

# Requires a running rtemis-afm bridge
## Not run: 
  apple_health()

## End(Not run)

Convert Message to List

Description

Convert Message to List

Usage

## S3 method for class 'Message'
as.list(x, ...)

Arguments

Value

A list representation of the Message object

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
  ## Not run: 
  llm <- create_Ollama("gemma4:e4b")
  res <- generate(llm, "How can anything exist?")
  as.list(res)

## End(Not run)

Convert to R list

Description

Generic method to convert various objects to R lists

Usage

as_list(x, ...)

Arguments

Value

A named R list

Author(s)

EDG

Examples

decay_time <- field("decay_time", "Time from peak amplitude to sustain level", type = "number")
as_list(decay_time)

Print built-in tools available for use by agents

Description

Prints the R handle (⁠tool_*⁠), the function_name the model sees, and the description of every built-in Tool exported by the package. Derived at call time from the namespace — no hardcoded list.

Usage

available_tools(verbosity = 1L)

Arguments

Value

A named list of Tool objects keyed by their R handle, invisibly.

Author(s)

EDG

Examples

available_tools()

Create a AnthropicConfig Object

Description

Creates a AnthropicConfig object which can be passed to create_agent()

Usage

config_Anthropic(
  model_name,
  temperature = TEMPERATURE_DEFAULT,
  base_url = ANTHROPIC_URL_DEFAULT,
  api_key = NULL,
  api_key_env = ANTHROPIC_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  anthropic_version = ANTHROPIC_API_VERSION_DEFAULT,
  anthropic_beta = NULL,
  max_tokens = ANTHROPIC_MAX_TOKENS_DEFAULT,
  timeout = ANTHROPIC_TIMEOUT_DEFAULT,
  extra_headers = NULL,
  extra_body = NULL,
  thinking_budget_tokens = NULL,
  validate_model = FALSE
)

Arguments

Value

AnthropicConfig object

Author(s)

EDG

Examples

cfg <- config <- config_Anthropic(
   model_name = "claude-sonnet-4-6",
   temperature = 0.4,
   api_key = "test-key",
   max_tokens = 1024L,
   validate_model = FALSE
)

Create an Apple Foundation Models Config Object

Description

Creates an AppleConfig object which can be passed to create_agent().

Usage

config_Apple(
  temperature = TEMPERATURE_DEFAULT,
  model_name = APPLE_MODEL_DEFAULT,
  base_url = APPLE_URL_DEFAULT,
  timeout = APPLE_TIMEOUT_DEFAULT,
  extra_headers = NULL,
  extra_body = NULL,
  validate_model = TRUE
)

Arguments

Details

Apple's on-device Foundation Model (the model behind Apple Intelligence) is reached through the rtemis-afm bridge, which serves it over the OpenAI Chat Completions wire on ⁠http://127.0.0.1:1977⁠. Install and start the bridge with ⁠curl -fsSL https://live.rtemis.org/afm.sh | sh⁠ (or ⁠brew install rtemis-org/tap/rtemis-afm⁠, then rtemis-afm). It needs an Apple silicon Mac, macOS 27 or later, and Apple Intelligence turned on. No API key is used or sent.

The model supports chat, structured output, and tool calling, with an 8,192-token context window on macOS 27.0; a prompt that does not fit is refused by the bridge with a context_length_exceeded error.

Value

AppleConfig object

Author(s)

EDG

Examples

# Requires a running rtemis-afm bridge
## Not run: 
  cfg <- config_Apple(temperature = 0.2)
  agent <- create_agent(cfg, system_prompt = "You are a concise assistant.")

## End(Not run)
# Build the configuration without contacting the bridge:
cfg <- config_Apple(validate_model = FALSE)

Create an OllamaConfig Object

Description

Creates an OllamaConfig object which can be passed to create_agent()

Usage

config_Ollama(
  model_name,
  temperature = TEMPERATURE_DEFAULT,
  base_url = OLLAMA_URL_DEFAULT,
  think = NULL
)

Arguments

Value

OllamaConfig object

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  config_Ollama(
    model_name = "gemma4:e4b",
    temperature = 0.2
  )

## End(Not run)

Create an OpenAI-compatible Config Object

Description

Creates an OpenAIConfig object which can be passed to create_agent()

Usage

config_OpenAI(
  model_name,
  temperature = TEMPERATURE_DEFAULT,
  base_url = OPENAI_URL_DEFAULT,
  api_key = NULL,
  api_key_env = OPENAI_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  organization = NULL,
  project = NULL,
  timeout = OPENAI_TIMEOUT_DEFAULT,
  extra_headers = NULL,
  extra_body = NULL,
  zero_data_retention = NULL,
  enable_thinking = NULL,
  validate_model = FALSE
)

Arguments

Details

With zero_data_retention = TRUE, each OpenRouter request includes provider.zdr = true. OpenRouter will then consider only endpoints with a ZDR policy. This option does not activate account-level ZDR at OpenAI, Anthropic, or other providers.

Value

OpenAIConfig object

Author(s)

EDG

Examples

cfg <- config_OpenAI(
   model_name = "local-model",
   temperature = 0.4,
   base_url = "http://localhost:1234/v1/",
   validate_model = FALSE
)
# Require an OpenRouter endpoint that does not retain prompts or responses:
openrouter_cfg <- config_OpenAI(
   model_name = "inclusionai/ling-3.0-flash-fin:free",
   base_url = "https://openrouter.ai/api/v1",
   api_key_env = "OPENROUTER_API_KEY",
   zero_data_retention = TRUE,
   validate_model = FALSE
)

Create a Anthropic LLM Object

Description

Create a Anthropic LLM Object

Usage

create_Anthropic(
  model_name,
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  temperature = TEMPERATURE_DEFAULT,
  output_schema = NULL,
  name = NULL,
  base_url = ANTHROPIC_URL_DEFAULT,
  api_key = NULL,
  api_key_env = ANTHROPIC_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  anthropic_version = ANTHROPIC_API_VERSION_DEFAULT,
  anthropic_beta = NULL,
  max_tokens = ANTHROPIC_MAX_TOKENS_DEFAULT,
  timeout = ANTHROPIC_TIMEOUT_DEFAULT,
  extra_headers = NULL,
  extra_body = NULL,
  thinking_budget_tokens = NULL,
  validate_model = FALSE
)

Arguments

Value

Anthropic LLM object

Author(s)

EDG

Examples

llm <- create_Anthropic(
   model_name = "claude-sonnet-4-6",
   system_prompt = "You are a meticulous research assistant.",
   api_key = "test-key",
   validate_model = FALSE
)

Create an Apple Foundation Models LLM Object

Description

A stateless LLM backed by Apple's on-device Foundation Model through the rtemis-afm bridge; see config_Apple for what the bridge is and how to start it.

Usage

create_Apple(
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  temperature = TEMPERATURE_DEFAULT,
  output_schema = NULL,
  name = NULL,
  model_name = APPLE_MODEL_DEFAULT,
  base_url = APPLE_URL_DEFAULT,
  timeout = APPLE_TIMEOUT_DEFAULT,
  extra_headers = NULL,
  extra_body = NULL,
  validate_model = TRUE
)

Arguments

Value

Apple LLM object

Author(s)

EDG

Examples

# Requires a running rtemis-afm bridge
## Not run: 
  llm <- create_Apple(system_prompt = "You are a meticulous research assistant.")
  generate(llm, "What is the capital of France?")

## End(Not run)

Create an Ollama Object

Description

Create an Ollama Object

Usage

create_Ollama(
  model_name,
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  temperature = TEMPERATURE_DEFAULT,
  output_schema = NULL,
  name = NULL,
  base_url = OLLAMA_URL_DEFAULT,
  think = NULL
)

Arguments

Value

Ollama LLM object

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  llm <- create_Ollama(
    model_name = "gemma4:e4b",
    system_prompt = "You are professor of Drum and Bass at the Institute of Advanced Beat Studies.",
    temperature = 1.0
  )
  generate(llm, "What is your name and who made you?")

## End(Not run)

Create an OpenAI-compatible LLM Object

Description

Create an OpenAI-compatible LLM Object

Usage

create_OpenAI(
  model_name,
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  temperature = TEMPERATURE_DEFAULT,
  output_schema = NULL,
  name = NULL,
  base_url = OPENAI_URL_DEFAULT,
  api_key = NULL,
  api_key_env = OPENAI_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  organization = NULL,
  project = NULL,
  timeout = OPENAI_TIMEOUT_DEFAULT,
  extra_headers = NULL,
  extra_body = NULL,
  zero_data_retention = NULL,
  enable_thinking = NULL,
  validate_model = FALSE
)

Arguments

Details

With zero_data_retention = TRUE, each OpenRouter request includes provider.zdr = true. OpenRouter will then consider only endpoints with a ZDR policy. This option does not activate account-level ZDR at OpenAI, Anthropic, or other providers.

Value

OpenAI LLM object

Author(s)

EDG

Examples

llm <- create_OpenAI(
   model_name = "local-model",
   base_url = "http://localhost:1234/v1",
   system_prompt = "You are a meticulous research assistant.",
   validate_model = FALSE
)

Create a rtemis.llm Agent

Description

Create a rtemis.llm Agent

Usage

create_agent(
  llmconfig,
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  use_memory = TRUE,
  tools = NULL,
  max_tool_rounds = 3L,
  output_schema = NULL,
  name = NULL,
  allow_custom_tools = FALSE,
  logfile = NULL,
  verbosity = 1L
)

Arguments

Value

Agent object

Author(s)

EDG

Examples

# Requires Ollama server running and gemma4:e4b model available
## Not run: 
  agent <- create_agent(
    config_Ollama(
      model_name = "gemma4:e4b",
      temperature = 0.2
    ),
    system_prompt = "You are professor of Trance at the Institute of Advanced Beat Studies.",
    use_memory = TRUE
  )

## End(Not run)

create_custom_tool

Description

Define a user-supplied tool for an agent. Unlike create_tool, the caller provides the R function to invoke (impl). Custom tools are outside the package's allowlist-and-hash enforcement, so the caller vouches for the code. An agent will refuse to carry a custom tool unless the agent is created with allow_custom_tools = TRUE (see create_agent).

Usage

create_custom_tool(name, function_name, description, parameters = list(), impl)

Arguments

Value

Tool object with impl populated.

Author(s)

EDG

Examples

add_numbers <- function(x, y) x + y
tool_addition <- create_custom_tool(
  name = "Addition",
  function_name = "add_numbers",
  description = "Performs arithmetic addition of two numbers.",
  parameters = list(
    tool_param("x", "number", "The first number to add", required = TRUE),
    tool_param("y", "number", "The second number to add", required = TRUE)
  ),
  impl = add_numbers
)

create_tool

Description

Define a tool for an agent

Usage

create_tool(name, function_name, description, parameters = list())

Arguments

Value

Tool object

Author(s)

EDG

Examples

tool_addition <- create_tool(
  name = "Addition",
  function_name = "add_numbers",
  description = "Performs arithmetic addition of two numbers.",
  parameters = list(
    tool_param(
      name = "x",
      type = "number",
      description = "The first number to add",
      required = TRUE
    ),
    tool_param(
      name = "y",
      type = "number",
      description = "The second number to add",
      required = TRUE
    )
  )
)

Define a schema field

Description

Define a schema field

Usage

field(
  name,
  description = name,
  type = c("string", "number", "integer", "boolean", "array"),
  enum = NULL,
  items = NULL,
  required = TRUE
)

Arguments

Value

Field object

Author(s)

EDG

Examples

# `type` defaults to "string", `required` defaults to TRUE
field("lab_name", "Name of the lab test")
field("normal_range_low", "Lower bound of normal range", type = "number")
field("flag", "Whether the result is out of range", enum = c("low", "normal", "high"))

# An array of strings: one element per item, so nothing has to be delimited
# inside a single string and later split back apart.
field("questions", "Each question, quoted as written", type = "array", items = "string")

# An array whose elements carry their own description
field(
  "codes", "ICD-10 codes found",
  type = "array",
  items = field("code", "One ICD-10 code, e.g. \"E11.9\"")
)

# An array of objects
field(
  "results", "One row per lab result",
  type = "array",
  items = schema(
    "LabResult",
    field("name", "Test name"),
    field("value", "Result value", type = "number")
  )
)

Generate Method

Description

Generic method for generating text or structured output from LLMs and Agents.

Usage

generate(
  x,
  prompt,
  temperature = NULL,
  top_p = NULL,
  max_tokens = NULL,
  stop = NULL,
  think = NULL,
  output_schema = NULL,
  verbosity = 1L,
  validate_output = TRUE,
  on_validation_failure = c("warn", "collect", "abort"),
  ...
)

Arguments

Details

The system prompt is set once at agent (or LLM) construction time and is not overridable per call. Construct a new agent if you need a different system prompt.

Backend-specific extra arguments accepted via ...:

• Ollama: top_k (integer), seed (integer), num_ctx (integer, mapped to options.num_ctx), keep_alive (character duration such as "10m", or seconds as a number, controlling how long the model stays loaded after the request), logprobs (logical), top_logprobs (integer)

• OpenAI: seed (integer), logprobs (logical), top_logprobs (integer [0, 20])

• Anthropic: top_k (integer)

Any argument set to NULL (the default) falls back to the value baked into the underlying LLMConfig at construction time.

Value

Message object or list of Message objects (for Agent). With a schema, validation_results retrieves the attached validation report. Invalid output is retained unless explicitly configured to abort. Agent validation checks only the final answer, before committing that answer to memory.

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  agent <- create_agent(
    config_Ollama(
      model_name = "gemma4:e4b",
      temperature = 0.2
    )
  )
  generate(agent, "What is your name?", temperature = 0.7)

## End(Not run)

Apply an LLM over a vector of prompts

Description

llmapply is the lapply-style entry point for running a single prompt against an LLM repeatedly over a vector of inputs. Pass either a model name (in which case an LLM is built on the fly using backend, system_prompt, output_schema) or a pre-built LLM object.

Usage

llmapply(
  x,
  model_or_llm,
  backend = c("ollama", "openai", "anthropic"),
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  output_schema = NULL,
  verbosity = 1L,
  extract_responses = TRUE,
  on_error = c("na", "abort"),
  validate_output = TRUE,
  on_validation_failure = c("warn", "collect", "abort"),
  ...
)

Arguments

Details

Per-call overrides such as temperature, top_p, max_tokens, stop, think, plus backend-specific options like top_k or seed, are forwarded via ... to generate. Vectors passed via ... are not yet recycled across x — they are forwarded as-is to each call.

Progress is reported through rtemis.core's nested progress API: one status line labelled with the model name, ticking once per element, with an ETA. Set verbosity = 0L to silence it. When a message sink is set (see rtemis.core::set_msg_sink()), progress is forwarded as structured events instead of being drawn, and nests under any enclosing progress node.

Value

If extract_responses = TRUE, a character vector the same length as x. Otherwise, a list of Message objects. Under on_error = "na" the result carries an errors attribute: a data.frame of index and message, one row per failed call, so failures can be retried by position rather than found by scanning for NA. With a schema, validation_results retrieves per-input statuses and diagnostics. Invalid outputs remain in place under warn/collect; warn emits one informational summary message for the batch, respecting verbosity.

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  llmapply(
    c("burgundy", "crimson", "maroon", "ruby", "scarlet"),
    "gemma4:e4b",
    system_prompt = "Return the hexadecimal code for the color provided in format #FFFFFF",
    temperature = 0.2
  )

## End(Not run)

Extract token log probabilities from a Message or list of Messages

Description

Returns the per-token log probabilities of the assistant's response, when the call was made with logprobs = TRUE. Reading a probability off the first token is better calibrated than asking a model to emit a number, so this is the basis for scoring a binary question.

Usage

logprobs(x, top = FALSE)

Arguments

Details

Supported on Ollama and OpenAI-compatible backends; Anthropic does not return log probabilities, so its messages yield NULL rather than an error.

Value

For a single Message, a data.table of position, token, logprob and prob, or NULL when the message carries no log probabilities. For a list, a list of those, one per element, so the length of the result matches the length of x.

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  llm <- create_Ollama("gemma4:e4b", system_prompt = "Answer Yes or No only.")
  msg <- generate(
    llm, "Is the sky blue?",
    think = FALSE, logprobs = TRUE, top_logprobs = 5L
  )
  logprobs(msg)

## End(Not run)

Map

Description

Map

Usage

map(x, f, ...)

Arguments

Details

Use responses to retrieve just the content from the assistant messages, or reasoning to retrieve the reasoning traces (if enabled).

Both methods accept:

• verbosity Integer [0, Inf): Verbosity level. Progress is reported through rtemis.core's nested progress API - one status line labelled with the model name, ticking once per element, with an ETA - and verbosity = 0L silences it. The per-call verbosity is verbosity - 1L. When a message sink is set (see rtemis.core::set_msg_sink()), progress is forwarded as structured events instead of being drawn, and nests under any enclosing progress node.

• on_error Character {"na", "abort"}: What to do when a single call fails. "na" (the default) warns, leaves NULL in that element's slot, and carries on; the result then carries an errors attribute, a data.frame of index and message with one row per failed call. responses and reasoning map those NULL slots to NA_character_. "abort" propagates the error and discards every result in the batch.

Value

A list of Message objects (for LLM) or list of lists of Message objects (for Agent). With an output schema, validation_results retrieves an aligned report. Validation happens per item; on_validation_failure = "warn" emits one summary message at completion, respecting verbosity. Validation options are forwarded to generate.

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  llm <- create_Ollama(
    "gemma4:e4b",
    system_prompt = "Convert color to hex code using the format #FFFFFF"
  )
  x <- c("ocean teal", "california poppy orange", "bougainvillea pink")
  hex <- map(x, llm)
  hex

## End(Not run)

Check Ollama Model is Available

Description

Check Ollama Model is Available

Usage

ollama_check_model(x)

Arguments

Value

NULL, invisibly if model is available; otherwise throws an error.

Author(s)

EDG

Examples

# Requires running Ollama server
## Not run: 
  ollama_check_model("gemma4:e4b")

## End(Not run)

Get Ollama Model Info

Description

Get Ollama Model Info

Usage

ollama_get_model_info(x = NULL, base_url = OLLAMA_URL_DEFAULT)

Arguments

Value

data.table

Author(s)

EDG

Examples

# Requires a running Ollama server
## Not run: 
  ollama_get_model_info()
  ollama_get_model_info(x = "gemma4:e4b")

## End(Not run)

List Ollama Models

Description

List Ollama Models

Usage

ollama_list_models(base_url = OLLAMA_URL_DEFAULT)

Arguments

Value

Character vector: Model names.

Author(s)

EDG

Examples

# Requires a running Ollama server
## Not run: 
ollama_list_models()

## End(Not run)

Check OpenAI-compatible Model Is Available

Description

Check OpenAI-compatible Model Is Available

Usage

openai_check_model(
  x,
  base_url = OPENAI_URL_DEFAULT,
  api_key = NULL,
  api_key_env = OPENAI_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  organization = NULL,
  project = NULL
)

Arguments

Value

NULL, invisibly, if model is available; otherwise throws an error.

Author(s)

EDG

Examples

# Requires running OpenAI-compatible server with /models endpoint
## Not run: 
  openai_check_model(
    x = "local-model",
    base_url = "http://localhost:1234/v1",
    api_key = "test-key"
  )

## End(Not run)

List OpenAI-compatible Models

Description

List OpenAI-compatible Models

Usage

openai_list_models(
  base_url = OPENAI_URL_DEFAULT,
  api_key = NULL,
  api_key_env = OPENAI_API_KEY_ENV_DEFAULT,
  keychain_service = NULL,
  organization = NULL,
  project = NULL
)

Arguments

Value

Character vector: Model ids.

Author(s)

EDG

Examples

# Requires running OpenAI-compatible server with /models endpoint
## Not run: 
  openai_list_models(
    base_url = "http://localhost:1234/v1",
    api_key = "test-key"
  )

## End(Not run)

Extract reasoning trace(s) from a Message or list of Messages

Description

Returns the assistant's reasoning trace (if any). Only LLMMessage objects carry a reasoning field; all other Message subclasses return NA_character_. Messages whose reasoning is unset (NULL) also return NA_character_.

Usage

reasoning(x)

Arguments

Value

Character vector of reasoning traces, with NA_character_ in slots where no reasoning is available (including failed calls).

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  llmapply(
    c("burgundy", "crimson", "maroon", "ruby", "scarlet"),
    "gemma4:e4b",
    system_prompt = "Return the hexadecimal code for the color provided in format #FFFFFF",
    temperature = 0.2
  ) |> reasoning()

## End(Not run)

Extract response(s) from a Message or list of Messages

Description

Returns the assistant content from a single Message, from a flat list of Message objects (e.g. the output of llmapply with extract_responses = FALSE), or from a list of lists of Message objects (e.g. the output of map() on an Agent with extract_responses = FALSE).

Usage

responses(x)

Arguments

Value

Character vector of assistant responses. Returns NA_character_ in slots where no assistant message is present (including failed calls), so that the length of the result matches the length of x. An agent history returned by generate yields only the final assistant response. Attached validation reports are preserved.

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  llmapply(
    c("burgundy", "crimson", "maroon", "ruby", "scarlet"),
    "gemma4:e4b",
    system_prompt = "Return the hexadecimal code for the color provided in format #FFFFFF",
    temperature = 0.2
  ) |> responses()

## End(Not run)

Define output schema for LLM responses

Description

Define output schema for LLM responses

Usage

schema(name = NULL, ..., description = NULL)

Arguments

Value

Schema object, named list, or JSON string.

Author(s)

EDG

Examples

schema(
  "LabSchema",
  field("Lab name"),
  field("normal range low", type = "number"),
  field("normal range high", type = "number")
)

Probability of specific tokens at one position

Description

Reads the probability of each candidate answer directly off the model's token distribution, rather than parsing a value the model emitted. Asking a binary question and taking P("Yes") at the first position is far better calibrated than asking the model for a number.

Usage

token_probs(x, tokens, position = 1L)

Arguments

Details

Candidates are matched on trimmed, case-folded token text, and the probabilities of every matching alternative are summed, so "Yes" picks up " Yes" and "yes" too. A candidate that does not appear among the returned alternatives is NA, not zero: its probability is unknown, only bounded above by the smallest one returned. Raise top_logprobs if candidates you care about come back NA.

Value

For a single Message, a named numeric vector, one element per token in tokens. For a list, a numeric matrix with one row per element of x and one column per token.

Author(s)

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
## Not run: 
  llm <- create_Ollama("gemma4:e4b", system_prompt = "Answer Yes or No only.")
  msg <- generate(
    llm, "Is the sky blue?",
    think = FALSE, logprobs = TRUE, top_logprobs = 5L
  )
  token_probs(msg, c("Yes", "No"))

## End(Not run)

tool_param

Description

Define a tool parameter schema

Usage

tool_param(name, type, description, required = FALSE)

Arguments

Value

ToolParameter object

Author(s)

EDG

Examples

tool_param("query", "string", "search query to send", required = TRUE)

Built-in Agent Tools

Description

Pre-defined Tool objects that can be passed to create_agent() via the tools argument, allowing an agent to search external services or retrieve local information.

Usage

tool_arxiv

tool_datetime

tool_duckduckgo_ia

tool_semanticscholar

tool_wikipedia

Format

Tool S7 objects:

tool_arxiv

Search arXiv.org for academic papers.

tool_wikipedia

Search Wikipedia articles.

tool_semanticscholar

Search Semantic Scholar for academic papers.

tool_duckduckgo_ia

Query the DuckDuckGo Instant Answer API.

tool_datetime

Return the current date, time, and timezone.

Author(s)

EDG

Examples

# Inspect a tool
tool_datetime

## Not run: 
# Requires a running Ollama server and the "gemma4:e4b" model
agent <- create_agent(
  llmconfig = config_Ollama(
    model_name = "gemma4:e4b",
    base_url = "http://localhost:11434"
  ),
  system_prompt = "You are a meticulous research assistant.",
  tools = list(tool_datetime, tool_semanticscholar, tool_wikipedia)
)
generate(agent, "Find recent papers on diffusion models.")

## End(Not run)

Validate saved structured responses

Description

Checks strict JSON syntax and the requested schema locally, without changing responses or logging validation failures. Does not coerce values or repair JSON. Extra properties are allowed by the current Schema; optional fields may be absent but may not be null. An object field constrains only its outer type; an array field also constrains its elements, since items says what it holds.

Usage

validate_output(x, schema)

Arguments

Value

An S7 validation report with ⁠@output⁠ (original text), ⁠@status⁠ (valid, invalid, unavailable, or not_validated), ⁠@schema⁠, and ⁠@issues⁠ (a data.frame with index, path, keyword, and message). Missing responses are unavailable; malformed JSON is invalid. Empty input gives an empty report.

Examples

sch <- schema("Count", field("n", type = "integer"))
report <- validate_output(c('{"n":10}', '{"n":"10"}', NA_character_), sch)
report@status
report@issues

Retrieve an attached validation report

Description

Retrieve an attached validation report

Usage

validation_results(x)

Arguments

Value

An OutputValidation report, or NULL if none is attached. With a supplied schema and disabled validation, the attached report records not_validated.

Examples

validation_results("unvalidated text")