Skip to navigation

nemoguardrails.guardrails.rail_guard

View as MarkdownOpen in Claude

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

NameDescription
_blocked_reason_or_reraiseRecord exc on span and return a redacted block reason, or re-raise on an HTTP status.
_client_facing_reasonThe block reason an API caller may see for a rail that raised exc.
_upstream_http_statusReturn the upstream HTTP status exc carries, or None when it carries none.
rail_error_outcomeMap a failed rail to a blocking RailOutcome, or re-raise on an HTTP status.

Data

_STATUS_BEARING_ERRORS

log

API

nemoguardrails.guardrails.rail_guard._blocked_reason_or_reraise(
span: typing.Optional['Span'],
action_name: str,
exc: Exception
) -> str

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.
nemoguardrails.guardrails.rail_guard._client_facing_reason(
action_name: str,
exc: Exception
) -> str

The block reason an API caller may see for a rail that raised exc.

nemoguardrails.guardrails.rail_guard._upstream_http_status(
exc: Exception
) -> typing.Optional[int]

Return the upstream HTTP status exc carries, or None when it carries none.

nemoguardrails.guardrails.rail_guard.rail_error_outcome(
span: typing.Optional['Span'],
action_name: str,
exc: Exception

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.
nemoguardrails.guardrails.rail_guard._STATUS_BEARING_ERRORS = (ModelEngineError, LLMCallException)
nemoguardrails.guardrails.rail_guard.log = logging.getLogger(__name__)