% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/evaluation.R
\name{evaluate_security_cases}
\alias{evaluate_security_cases}
\title{Evaluate scanner behavior on a labeled corpus}
\usage{
evaluate_security_cases(
  cases = NULL,
  policy = "comprehensive",
  reviewer = NULL,
  checks = "rules",
  redaction = NULL,
  scanners = scanner_options()
)
}
\arguments{
\item{cases}{Optional data frame. If \code{NULL}, the packaged
\code{inst/extdata/security_eval_cases.csv} corpus is loaded.}

\item{policy}{A \code{shieldr_policy} or built-in policy name.}

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

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

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

\item{scanners}{Optional scanner configuration from \code{\link[=scanner_options]{scanner_options()}}.}
}
\value{
A data frame with case metadata, expected and actual actions,
\code{matched}, \code{latency_ms}, and \code{n_findings}.
}
\description{
\code{evaluate_security_cases()} runs llmshieldr scanners over a small labeled
corpus and returns action-level metrics. It is designed for repeatable local
evaluation, release notes, and adoption reviews; it is not a substitute for
a full red-team benchmark.
}
\details{
The input corpus should contain at least \code{stage}, \code{text}, and
\code{expected_action} columns. If \code{stage} is \code{"output"}, rows are scanned with
\code{\link[=scan_output]{scan_output()}}. If \code{stage} is \code{"context"}, each row is scanned as a one-row
context data frame with \code{\link[=scan_context]{scan_context()}}. All other stages are scanned with
\code{\link[=scan_prompt]{scan_prompt()}}.

The returned data frame includes per-case latency in milliseconds and a
Boolean \code{matched} column. Use the summary columns to calculate detection
rate, false-positive rate, action accuracy, and latency percentiles in
vignettes or release notes.
}
\examples{
\dontrun{
results <- evaluate_security_cases(policy = "comprehensive")
mean(results$matched)
}
}
