> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

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

# nemoguardrails.actions.rail_outcome

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

| 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) | -           |

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

---

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