Apply an LLM over a vector of prompts

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"),
  image_path = NULL,
  ...
)

Arguments

x

Character or list: Values to iterate over. Each element forms the user prompt for one call to the LLM.

model_or_llm

Character or LLM: Either the name of a model (a string) or a pre-built LLM object (for example from create_Ollama, create_OpenAI, or create_Anthropic).

backend

Character {"ollama", "openai", "anthropic"}: Backend to use when model_or_llm is a string. Ignored when model_or_llm is an LLM object.

system_prompt

Character: System prompt to use when building the LLM from a model name. Ignored when model_or_llm is an LLM object.

output_schema

Optional Schema: Output schema to enforce, created with schema. When model_or_llm is a string, this is baked into the built LLM. When model_or_llm is a pre-built LLM, supplying this here is a conflict and will error.

verbosity

Integer [0, Inf): Verbosity level. The per-call verbosity is verbosity - 1L.

extract_responses

Logical: If TRUE, return a character vector of assistant responses (with NA_character_ for missing assistant content). If FALSE, return the raw list of Message objects from each call.

on_error

Character {"na", "abort"}: What to do when a single call fails. "na" warns, keeps that element's slot as NA_character_ (or NULL when extract_responses = FALSE), and carries on, so a run of thousands of calls is not lost to one timeout. "abort" propagates the error and discards every result in the batch.

validate_output

Logical: Validate final output locally when a schema is supplied. Disabling this does not disable the schema sent to the model.

on_validation_failure

Character {"warn", "collect", "abort"}: Preserve invalid output and report a styled rtemis.core message (not an R warning), collect silently, or abort with an error carrying output and validation. See validate_output.

image_path

Optional character or list: Local image files to send with the prompts. A character vector sends one image with each element of x; a list of character vectors sends several (a NULL entry sends none). Length 1 is recycled across x, and a single prompt in x is recycled across image_path, so one question can be asked of many images. Every file is checked before the first request. See generate.

...

Additional per-call arguments forwarded to generate (e.g. temperature, top_p, max_tokens, stop, think, top_k, seed, and for Ollama num_ctx and keep_alive).

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.

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.

Author

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
if (FALSE) { # \dontrun{
  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
  )
  # One question over many images, with a structured answer per image
  llmapply(
    "Describe this figure.",
    "gemma4:e4b",
    output_schema = schema(
      "Figure",
      field("chart type", "Type of chart"),
      field("series", "Number of data series", type = "integer")
    ),
    image_path = c("fig1.png", "fig2.png")
  )
} # }