% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/json_mode.R
\name{llm_mutate_structured}
\alias{llm_mutate_structured}
\title{Data-frame mutate with structured output}
\usage{
llm_mutate_structured(
  .data,
  output,
  prompt = NULL,
  .messages = NULL,
  .config,
  .system_prompt = NULL,
  .before = NULL,
  .after = NULL,
  .schema = NULL,
  .fields = NULL,
  ...
)
}
\arguments{
\item{.data}{A data.frame / tibble.}

\item{output}{Unquoted name that becomes \strong{the new column} (generative) \emph{or}
\strong{the prefix} for embedding columns. In shorthand form, omit this argument
and pass \code{newcol = "<glue prompt>"} or
\code{newcol = c(system = "...", user = "...")} through \code{...}.}

\item{prompt}{Optional glue template string for a single user turn; reference
any columns in \code{.data} (e.g. \code{"{id}. {question}\\nContext: {context}"}).
Ignored if \code{.messages} is supplied.}

\item{.messages}{Optional \strong{named} character vector of glue templates to build
a multi-turn message, using roles in \code{c("system","user","assistant","file")}.
Values are glue templates evaluated per-row; all can reference multiple columns.
For multimodal, use role \code{"file"} with a column containing a path template.}

\item{.config}{An \link{llm_config} object (generative or embedding).}

\item{.system_prompt}{Optional system message sent with every request when
\code{.messages} does not include a \code{system} entry.}

\item{.before, .after}{Standard \link[dplyr:relocate]{dplyr::relocate} helpers controlling where the
generated column(s) are placed.}

\item{.schema}{Optional JSON Schema (R list). When provided, this schema is sent to
the provider for strict validation and used for local parsing. When \code{NULL}, only
JSON mode is enabled (no strict schema validation). The schema should follow
JSON Schema specification (e.g., with \code{type}, \code{properties}, \code{required}).}

\item{.fields}{Optional character vector of fields to extract from parsed JSON.
Supports:
\itemize{
\item Character vector: \code{c("name", "score")} - extract these fields
\item Named vector: \code{c(person_name = "name", rating = "score")} - extract and rename
\item Nested paths: \code{c("user.name", "/data/items/0")} - dot notation or JSON Pointer
\item \code{NULL} (default): auto-extracts all top-level properties from \code{.schema}
\item \code{FALSE}: skip field extraction (keep only \code{structured_data} list-column)
}}

\item{...}{Passed to the underlying calls: \code{\link[=call_llm_broadcast]{call_llm_broadcast()}} in
generative mode, \code{\link[=get_batched_embeddings]{get_batched_embeddings()}} in embedding mode.}
}
\description{
Drop-in schema-first variant of \code{\link[=llm_mutate]{llm_mutate()}}. Produces parsed columns.
}
\section{Shorthand syntax}{

Like \code{\link[=llm_mutate]{llm_mutate()}}, this function supports shorthand syntax:

\preformatted{
df |> llm_mutate_structured(result = "{text}", .schema = schema)
df |> llm_mutate_structured(result = c(system = "Be brief.", user = "{text}"), .schema = schema)
}
}

\seealso{
\code{\link[=llm_mutate]{llm_mutate()}}, \code{\link[=llm_fn_structured]{llm_fn_structured()}}, \code{\link[=enable_structured_output]{enable_structured_output()}},
\code{\link[=llm_parse_structured_col]{llm_parse_structured_col()}}, \code{\link[=llm_mutate_tags]{llm_mutate_tags()}}
}
