% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/secure_chat.R
\name{secure_chat}
\alias{secure_chat}
\title{Run a guarded chat call}
\usage{
secure_chat(
  prompt,
  chat = NULL,
  policy = "enterprise_default",
  reviewer = NULL,
  checks = "rules",
  context = NULL,
  redaction = NULL,
  scanners = scanner_options(),
  show_tokens = FALSE,
  ...
)
}
\arguments{
\item{prompt}{User prompt.}

\item{chat}{An \code{ellmer} chat object, an object with \verb{$chat()}, or a function.}

\item{policy}{A \code{shieldr_policy} or built-in policy name such as \code{"comprehensive"}.}

\item{reviewer}{Optional reviewer function or object with \verb{$chat()}.}

\item{checks}{One of \code{"rules"}, \code{"nlp"}, \code{"llm"}, or \code{"both"}.}

\item{context}{Optional data frame of retrieved context.}

\item{redaction}{Optional redaction strategy from \code{\link[=redaction_strategy]{redaction_strategy()}}.}

\item{scanners}{Optional scanner configuration from \code{\link[=scanner_options]{scanner_options()}}.}

\item{show_tokens}{Whether to attach token counts when \code{ellmer} is available.}

\item{...}{Reserved for backwards-compatible aliases.}
}
\value{
A \code{shieldr_result}.
}
\description{
Orchestrates prompt scanning, optional context scanning, chat execution,
output scanning, rate guarding, and audit creation.
}
\details{
\code{secure_chat()} is the main end-to-end workflow when you already have an
\code{ellmer} chat object or another object with a \verb{$chat()} method. Plain
functions are also accepted for small tests. The function executes these
steps:
\enumerate{
\item Scan the prompt with \code{\link[=scan_prompt]{scan_prompt()}}.
\item If the prompt is blocked, return a \code{\link[=shieldr_result]{shieldr_result()}} without calling the chat.
\item If context is supplied, scan it with \code{\link[=scan_context]{scan_context()}} and append only
allowed context rows to the cleaned prompt, using row IDs, source labels,
and separators.
\item Reserve request and token budget with the policy rate guard, if present.
\item Call the chat object.
\item Scan model output with \code{\link[=scan_output]{scan_output()}}.
\item Resolve the final action, update the rate guard, and build an audit.
}

The returned \code{risk_summary} aggregates finding severity scores by OWASP
category across prompt, context, and output reports. The final action is the
most conservative action across input and output: \code{block} beats \code{redact},
and \code{redact} beats \code{allow}. Policy controls can map blocked prompt or output
reports to final actions of \code{refuse} or \code{escalate}.
}
\examples{
\dontrun{
model <- ellmer::models_ollama()$id[1]
if (is.na(model)) {
  stop(
    "Check if you have any Ollama models available, ",
    "or enter a specific name as a string for the model argument."
  )
}
chat <- ellmer::chat_ollama(model = model)
secure_chat("hello", chat, show_tokens = TRUE)
}
}
