Run a guarded chat call — secure

Orchestrates prompt scanning, optional context scanning, chat execution, output scanning, rate guarding, and audit creation.

Usage

secure_chat(
  prompt,
  chat = NULL,
  policy = "enterprise_default",
  reviewer = NULL,
  checks = "rules",
  context = NULL,
  redaction = NULL,
  scanners = scanner_options(),
  show_tokens = FALSE,
  context_authorize = NULL,
  context_policy = NULL,
  audit_content = c("metadata", "full"),
  audit_key = NULL,
  allowed_tools = character(),
  tool_policy = NULL,
  tool_subject = NULL,
  output_contract = NULL,
  grounding = NULL,
  telemetry = NULL,
  show_stats = FALSE,
  provider = NULL,
  model = NULL,
  reviewer_model = NULL,
  provider_args = list(),
  reviewer_provider = NULL,
  reviewer_provider_args = NULL,
  ...
)

Arguments

prompt: User prompt.
chat: An existing ellmer chat object, an object with $chat(), or a function. Supply either chat or a provider name, not both.
policy: A shieldr_policy or built-in policy name such as "comprehensive".
reviewer: Optional reviewer function or object with $chat().
checks: One of "rules", "nlp", "llm", or "both".
context: Optional data frame of retrieved context.
redaction: Optional redaction strategy from redaction_strategy().
scanners: Optional scanner configuration from scanner_options().
show_tokens: Whether to attach token counts when ellmer is available.
context_authorize: Optional function passed to scan_context() to authorize each retrieved row before it is included in the model prompt.
context_policy: Optional provenance and authorization requirements from context_policy().
audit_content: "metadata" (default) omits prompt, output, finding excerpts and reviewer details from the audit. "full" retains them in memory; write_audit_log() requires a separate explicit opt-in to write them.
audit_key: Optional secret key used for HMAC fingerprints in metadata-only audit findings. The key is never stored.
allowed_tools: Explicit names of registered ellmer tools allowed during this call. The default empty vector denies tool-enabled chats before calling the model. Allowed calls are scanned before tool execution.
tool_policy: Optional richer policy from tool_policy(). Its allowlist replaces allowed_tools and it adds schema, subject, spend, and loop limits.
tool_subject: Optional authorization context passed to tool_policy.
output_contract: Optional destination contract from output_contract().
grounding: Optional citation policy from grounding_policy(). Citation IDs are checked against admitted context document_id values (or row IDs).
telemetry: Optional privacy-safe event exporter from telemetry_options().
show_stats: Show elapsed time, token use, network status, and transfer metrics when available.
provider: Any provider name supported by ellmer::chat(), optionally in ellmer's "provider/model" form. "gemini" is accepted as an alias for "google_gemini". An existing chat object passed as provider is still accepted as a legacy alias for chat.
model: Optional assistant model name. Do not supply it when provider already contains a model. With Ollama, NULL discovers the first local model.
reviewer_model: Model for the separate semantic reviewer, created only when checks = "llm" or "both" and reviewer is NULL. NULL uses the assistant provider and model.
provider_args: Named list of additional arguments passed to ellmer::chat() and then to the selected assistant provider constructor.
reviewer_provider: Optional ellmer provider name for the semantic reviewer. NULL uses the assistant provider.
reviewer_provider_args: Named list of provider arguments for the reviewer. When the reviewer uses the assistant provider, NULL reuses provider_args; otherwise it passes no additional arguments. Use list() to explicitly pass none.
...: Reserved for backwards-compatible aliases.

Value

A shieldr_result.

Details

secure_chat() accepts any provider supported by ellmer::chat(). Set provider to an ellmer provider name, optionally supply model, and pass provider-specific constructor options through provider_args. It creates a separate semantic-review chat when review is requested; that chat may use a different provider, model, and argument list. You can instead supply an existing ellmer chat object, another object with a $chat() method, or a function through chat. Provider-created assistant chats are initialized only after prompt and context checks permit a model call. A provider-created semantic reviewer is initialized earlier when checks requires it. The function executes these steps:

Scan the prompt with scan_prompt().
If the prompt is blocked, return a shieldr_result() without calling the chat.
If context is supplied, scan it with scan_context() and append only allowed context rows to the cleaned prompt, using row IDs, opaque source references, and separators.
Reserve request and token budget with the policy rate guard, if present.
Call the chat object.
Scan model output with scan_output().
Resolve the final action, update the rate guard, and build an audit.

The returned 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: block beats redact, and redact beats allow. Policy controls can map blocked prompt or output reports to final actions of refuse or escalate.

Examples

local_chat <- function(prompt) paste("Checked:", prompt)
result <- secure_chat(
  "Summarize this public note.",
  chat = local_chat,
  checks = "rules"
)
result[c("action", "output")]
#> $action
#> [1] "allow"
#> 
#> $output
#> [1] "Checked: Summarize this public note."
#> 

if (FALSE) { # \dontrun{
secure_chat("hello", provider = "ollama", model = "gemma3:1b")
secure_chat("hello", provider = "anthropic")
} # }