ReferencePython SDK ReferenceNemoguardrailsActions

nemoguardrails.actions.rail_outcome

View as Markdown

The engine-neutral outcome of a single rail check.

RailOutcome is the canonical, backend-agnostic verdict a rail produces. It carries only the DECISION and neutral evidence, never how a consequence is rendered: which exception to raise, which bot intent or refusal message to emit, and how to localize it are presentation concerns that each engine (the Colang flow, IORails) decides for itself from this outcome plus its config.

Fields:

  • decision: ALLOW / BLOCK / TRANSFORM.
  • reason: optional neutral, human-readable explanation.
  • metadata: neutral evidence the decision is based on (policy violations, categories, scores, or backend-specific details). The top-level mapping is copied at construction and is never load-bearing for the decision itself. Serialization and disclosure are concerns for consumers at their boundaries.
  • 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.

Deliberately NOT here (they are rendering, not decision): exception type, refusal intent/message, language, and Colang event/context-update channels. 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-

Data

__all__

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(
    decision: nemoguardrails.actions.rail_outcome.RailDecision,
    reason: str | None = None,
    metadata: collections.abc.Mapping[str, typing.Any] = dict(),
    transforms: tuple[nemoguardrails.actions.rail_outcome.TransformSpec, ...] = (),
    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 encode it.

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
nemoguardrails.actions.rail_outcome.RailOutcome.allow(
    reason: str | None = None,
    metadata: collections.abc.Mapping[str, typing.Any] | None = None
) -> nemoguardrails.actions.rail_outcome.RailOutcome
classmethod
nemoguardrails.actions.rail_outcome.RailOutcome.block(
    reason: str | None = None,
    metadata: collections.abc.Mapping[str, typing.Any] | None = None
) -> nemoguardrails.actions.rail_outcome.RailOutcome
classmethod
nemoguardrails.actions.rail_outcome.RailOutcome.failure(
    reason: str | None = None,
    metadata: collections.abc.Mapping[str, typing.Any] | None = None
) -> nemoguardrails.actions.rail_outcome.RailOutcome
classmethod

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

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

A rewrite of a single conversation variable.

target
TransformTarget
text
str
nemoguardrails.actions.rail_outcome.TransformSpec.__post_init__() -> None
class nemoguardrails.actions.rail_outcome.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
) -> nemoguardrails.actions.rail_outcome.RailOutcome
 
nemoguardrails.actions.rail_outcome.__all__ = ['RailDecision', 'TransformTarget', 'TransformSpec', 'RailOutcome', 'require_rai...