Skip to navigation

nemoguardrails.actions.rail_outcome

View as MarkdownOpen in Claude

The engine-neutral outcome of a single rail check.

RailOutcome is the canonical, backend-agnostic verdict a rail produces. Each engine or Colang flow renders the consequence from the decision, its configuration, and any explicitly supported presentation metadata. For example, a consumer may use metadata["refusal_message"] as a localized refusal override; unsupported metadata must not be assumed to affect rendering.

Fields:

  • decision: ALLOW / BLOCK / TRANSFORM.
  • reason: optional neutral, human-readable explanation.
  • metadata: evidence the decision is based on (policy violations, categories, scores, or backend-specific details) and supported presentation hints. The top-level mapping is copied at construction and is never load-bearing for the decision itself. Consumers own serialization, disclosure, and the interpretation of presentation hints.
  • transforms: for TRANSFORM, which conversation variables are rewritten and to what. Transform outcomes are non-streaming; streaming output paths treat the check as non-blocking and do not apply the rewrite.
  • failed: the rail raised instead of returning a verdict, so this BLOCK is the engine’s fail-closed envelope rather than the rail’s own decision.

Exception types and Colang event/context-update channels remain the consumer’s responsibility. Presentation metadata does not change the verdict: a BLOCK always means “stop”; there is no soft-block flag.

Module Contents

Classes

NameDescription
RailDecisionThe three mutually exclusive things a rail can decide.
RailOutcomeThe engine-neutral verdict of one rail check.
TransformSpecA rewrite of a single conversation variable.
TransformTargetThe conversation variable a transform rewrites.

Functions

NameDescription
require_rail_outcome-

API

class nemoguardrails.actions.rail_outcome.RailDecision

Bases: enum.Enum

The three mutually exclusive things a rail can decide.

ALLOW
= 'allow'
BLOCK
= 'block'
TRANSFORM
= 'transform'
class nemoguardrails.actions.rail_outcome.RailOutcome(
reason: str | None = None,
metadata: collections.abc.Mapping[str, typing.Any] = dict(),
failed: bool = False
)
Dataclass

The engine-neutral verdict of one rail check.

transforms is non-empty if and only if decision is TRANSFORM. Each engine renders the consequence of a BLOCK its own way; this object does not determine how presentation metadata is rendered.

decision
RailDecision
failed
bool = False
is_blocked
bool

The single field both engines read to gate; rendering is theirs.

is_transform
bool
metadata
Mapping[str, Any] = field(default_factory=dict)
reason
str | None = None
transform_text
dict[str, str]
transforms
tuple[TransformSpec, ...] = ()
nemoguardrails.actions.rail_outcome.RailOutcome.__post_init__() -> None
reason: str | None = None,
metadata: collections.abc.Mapping[str, typing.Any] | None = None
classmethod
reason: str | None = None,
metadata: collections.abc.Mapping[str, typing.Any] | None = None
classmethod
reason: str | None = None,
metadata: collections.abc.Mapping[str, typing.Any] | None = None
classmethod

A block the engine synthesized because the rail raised instead of deciding.

rewrites: collections.abc.Sequence[tuple[nemoguardrails.actions.rail_outcome.TransformTarget, str]],
reason: str | None = None,
metadata: collections.abc.Mapping[str, typing.Any] | None = None
classmethod
class nemoguardrails.actions.rail_outcome.TransformSpec(
text: str
)
Dataclass

A rewrite of a single conversation variable.

target
TransformTarget
text
str
nemoguardrails.actions.rail_outcome.TransformSpec.__post_init__() -> None
class nemoguardrails.manifests.TransformTarget

Bases: enum.Enum

The conversation variable a transform rewrites.

BOT_MESSAGE
= 'bot_message'
RELEVANT_CHUNKS
= 'relevant_chunks'
USER_MESSAGE
= 'user_message'
nemoguardrails.actions.rail_outcome.require_rail_outcome(
result: object