nemoguardrails.guardrails.rail_guard
nemoguardrails.guardrails.rail_guard
The engine’s fail-closed error envelope, shared by every IORails rail.
A rail that fails blocks, with a redacted reason, so a rail bug cannot let content through. A failure carrying an upstream HTTP status propagates instead, so a provider outage reaches the client as the provider’s status rather than as a guardrail decision — the two mean very different things to a caller, and only one is worth retrying.
The policy is the engine’s, not any individual rail’s, which is why it lives here rather
than in a base class. Every rail calls it from its own except handler.
Module Contents
Functions
Data
API
Record exc on span and return a redacted block reason, or re-raise on an HTTP status.
The log keeps the full text, redacted once: a provider error can carry a credential in its message (CWE-532). exc itself propagates unmodified, so an operator still sees the real text in a traceback.
The returned reason is the client-facing form instead, because it reaches API callers
through client_reason: the streaming violation payload and a check’s reason.
See _client_facing_reason for what it may carry.
The span error is recorded only on the blocking path. Callers run inside action_span,
which records anything escaping it, so recording here too would double up.
Raises:
Exception: exc itself, when it carries an upstream HTTP status.
The block reason an API caller may see for a rail that raised exc.
Return the upstream HTTP status exc carries, or None when it carries none.
Map a failed rail to a blocking RailOutcome, or re-raise on an HTTP status.
Call this from the except handler of a rail’s own try — a CompiledRail’s
or a tool rail’s; both speak RailOutcome, so both fail closed the same way.
The outcome is a failure rather than a plain block: it stops the turn either way,
but an engine reading it can say the rail broke instead of implying the content was
refused, which is the difference between “fix your credentials” and “rephrase your
question”. This is the only place that distinction is recorded.
Raises:
Exception: exc itself, when it carries an upstream HTTP status.