> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.actions.rail_outcome

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

| Name                                                                      | Description                                            |
| ------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`RailDecision`](#nemoguardrails-actions-rail_outcome-RailDecision)       | The three mutually exclusive things a rail can decide. |
| [`RailOutcome`](#nemoguardrails-actions-rail_outcome-RailOutcome)         | The engine-neutral verdict of one rail check.          |
| [`TransformSpec`](#nemoguardrails-actions-rail_outcome-TransformSpec)     | A rewrite of a single conversation variable.           |
| [`TransformTarget`](#nemoguardrails-actions-rail_outcome-TransformTarget) | The conversation variable a transform rewrites.        |

### Functions

| Name                                                                                | Description |
| ----------------------------------------------------------------------------------- | ----------- |
| [`require_rail_outcome`](#nemoguardrails-actions-rail_outcome-require_rail_outcome) | -           |

### Data

[`__all__`](#nemoguardrails-actions-rail_outcome-__all__)

### API

```python
class nemoguardrails.actions.rail_outcome.RailDecision
```

**Bases:** `enum.Enum`

The three mutually exclusive things a rail can decide.

**`ALLOW`** `= 'allow'`

---

**`BLOCK`** `= 'block'`

---

**`TRANSFORM`** `= 'transform'`

---

```python
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, ...] = ()`

---

```python
nemoguardrails.actions.rail_outcome.RailOutcome.__post_init__() -> None
```

```python
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

```python
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

```python
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.

```python
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

```python
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`

---

```python
nemoguardrails.actions.rail_outcome.TransformSpec.__post_init__() -> None
```

```python
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'`

---

```python
nemoguardrails.actions.rail_outcome.require_rail_outcome(
    result: object
) -> nemoguardrails.actions.rail_outcome.RailOutcome
```

```python
nemoguardrails.actions.rail_outcome.__all__ = ['RailDecision', 'TransformTarget', 'TransformSpec', 'RailOutcome', 'require_rai...
```