% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tags_mode.R
\name{llm_mutate_tags}
\alias{llm_mutate_tags}
\title{Data-frame mutate with XML-like tag output}
\usage{
llm_mutate_tags(
  .data,
  output,
  prompt = NULL,
  .messages = NULL,
  .config,
  .system_prompt = NULL,
  .before = NULL,
  .after = NULL,
  .tags,
  .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{.tags}{Character vector of tag names to request and parse.}

\item{.fields}{\code{NULL} to extract all tags, a character vector of tags, a named
vector such as \code{c(person_age = "age")}, or \code{FALSE} to keep only \code{tags_data}.}

\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{
Soft structured variant of \code{\link[=llm_mutate]{llm_mutate()}}. It asks the model to return simple
XML-like tags, then parses those tags into columns.
}
\details{
Returns the mutated data frame plus:
\describe{
\item{\code{tags_ok}}{\code{TRUE} when all requested tags were found.}
\item{\code{tags_data}}{A list-column of parsed tag lists.}
\item{tag columns}{One column per requested tag or field. Scalar columns are
coerced to numeric or logical when all non-missing values allow it.}
}
}
\section{Shorthand syntax}{

\preformatted{
df |> llm_mutate_tags(result = "{text}", .tags = c("age", "job"), .config = cfg)
}
}

\examples{
\dontrun{
df <- tibble::tibble(city = c("Cairo", "Lima"))
cfg <- llm_config("openai", "gpt-4.1-nano", temperature = 0)

df |>
  llm_mutate_tags(
    geo = "Where is {city}? Give country and continent in their own tags.",
    .config = cfg,
    .system_prompt = paste(
      "Use XML tags for different parts of the answer, but do not nest tags.",
      "Return <country>...</country> and <continent>...</continent>."
    ),
    .tags = c("country", "continent")
  )
}

}
\seealso{
\code{\link[=llm_mutate]{llm_mutate()}}, \code{\link[=llm_parse_tags]{llm_parse_tags()}}, \code{\link[=llm_parse_tags_col]{llm_parse_tags_col()}},
\code{\link[=llm_mutate_structured]{llm_mutate_structured()}}, \code{\link[=llm_parse_structured_col]{llm_parse_structured_col()}}
}
