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

Versioned, declarative contract describing a rail and how it runs.

A `RailManifest` combines descriptive `RailMetadata` with an executable
`RailSpec` of configuration, flows, actions, and surfaces. Import references
remain declarative until `resolve_import_ref` explicitly imports their targets.
Descriptive fields are lenient so manifests stay forward-compatible, while the
executable spec is strict so misconfiguration fails loudly at load time.

## Module Contents

### Classes

| Name                                                                          | Description                                                            |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`ActionRef`](#nemoguardrails-manifests-manifest-ActionRef)                   | Named import reference to a rail action.                               |
| [`Binding`](#nemoguardrails-manifests-manifest-Binding)                       | Maps a single surface action parameter to its value source.            |
| [`ConfigSpecRef`](#nemoguardrails-manifests-manifest-ConfigSpecRef)           | Import reference to a rail configuration specification.                |
| [`EnvVar`](#nemoguardrails-manifests-manifest-EnvVar)                         | Environment variable declared by a rail requirement.                   |
| [`ImportTargetRef`](#nemoguardrails-manifests-manifest-ImportTargetRef)       | -                                                                      |
| [`ModelRequirement`](#nemoguardrails-manifests-manifest-ModelRequirement)     | Model resource declared by a rail requirement.                         |
| [`RailActions`](#nemoguardrails-manifests-manifest-RailActions)               | Import references for the actions declared by a rail.                  |
| [`RailConfigSchema`](#nemoguardrails-manifests-manifest-RailConfigSchema)     | Manifest reference to a rail's typed configuration schema.             |
| [`RailDirection`](#nemoguardrails-manifests-manifest-RailDirection)           | Pipeline direction in which a rail surface runs.                       |
| [`RailFlows`](#nemoguardrails-manifests-manifest-RailFlows)                   | Colang flow files and flow names declared by a rail.                   |
| [`RailManifest`](#nemoguardrails-manifests-manifest-RailManifest)             | Top-level, versioned manifest for a single rail.                       |
| [`RailMetadata`](#nemoguardrails-manifests-manifest-RailMetadata)             | Descriptive, non-executable facets of a rail used by the catalog.      |
| [`RailPrivacy`](#nemoguardrails-manifests-manifest-RailPrivacy)               | Data handling and remote-service behavior declared by a rail.          |
| [`RailRequirements`](#nemoguardrails-manifests-manifest-RailRequirements)     | Installation and runtime resources declared by a rail.                 |
| [`RailSpec`](#nemoguardrails-manifests-manifest-RailSpec)                     | Executable configuration, flows, actions, and requirements for a rail. |
| [`RailSurface`](#nemoguardrails-manifests-manifest-RailSurface)               | Configured flow surface mapped to a declared rail action.              |
| [`ServiceRequirement`](#nemoguardrails-manifests-manifest-ServiceRequirement) | External service declared by a rail requirement.                       |

### Functions

| Name                                                                                        | Description                                                           |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`_validate_import_target`](#nemoguardrails-manifests-manifest-_validate_import_target)     | -                                                                     |
| [`import_ref_target`](#nemoguardrails-manifests-manifest-import_ref_target)                 | Return the import target encoded by a supported manifest reference.   |
| [`iter_manifest_import_refs`](#nemoguardrails-manifests-manifest-iter_manifest_import_refs) | Return every configuration and action import reference in a manifest. |
| [`resolve_import_ref`](#nemoguardrails-manifests-manifest-resolve_import_ref)               | Import and return the Python object referenced by a manifest entry.   |

### Data

[`BindingKind`](#nemoguardrails-manifests-manifest-BindingKind)

[`BindingResource`](#nemoguardrails-manifests-manifest-BindingResource)

[`ImportRef`](#nemoguardrails-manifests-manifest-ImportRef)

[`RailCapability`](#nemoguardrails-manifests-manifest-RailCapability)

[`RailCategory`](#nemoguardrails-manifests-manifest-RailCategory)

[`RailLifecycle`](#nemoguardrails-manifests-manifest-RailLifecycle)

### API

```python
class nemoguardrails.manifests.manifest.ActionRef()
```

**Bases:** [ImportTargetRef](#nemoguardrails-manifests-manifest-ImportTargetRef)

Named import reference to a rail action.

**`name`** `str`

---

```python
nemoguardrails.manifests.manifest.ActionRef._name_must_not_be_empty(
    value: str
) -> str
```

classmethod

```python
class nemoguardrails.manifests.manifest.Binding()
```

**Bases:** `BaseModel`

Maps a single surface action parameter to its value source.

Each binding tells the runtime where one argument of a surface's action comes
from. Prefer the constructor classmethods over building instances directly, as
they set `kind` and the relevant fields correctly. A `resource` classifies the
resolved value for runtime validation; use `model` and `model_param` when that
value identifies a configured model type.

**`action_param`** `str`

---

**`key`** `Optional[str] = None`

---

**`kind`** `BindingKind`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`required`** `bool = True`

---

**`resource`** `Optional[BindingResource] = None`

---

```python
nemoguardrails.manifests.manifest.Binding._source_must_match_kind() -> nemoguardrails.manifests.manifest.Binding
```

```python
nemoguardrails.manifests.manifest.Binding.context(
    action_param: str,
    key: str,
    required: bool = True
) -> nemoguardrails.manifests.manifest.Binding
```

classmethod

Bind `action_param` to a context variable.

**Parameters:**

**`action_param`** `str`

Name of the action parameter to populate.

---

**`key`** `str`

Name of the context variable that supplies the value.

---

**`required`** `bool` — default: True

Whether the context variable must be present.

---

**Returns:** `Binding`

A `context` binding.

```python
nemoguardrails.manifests.manifest.Binding.literal(
    action_param: str,
    value: typing.Any
) -> nemoguardrails.manifests.manifest.Binding
```

classmethod

Bind `action_param` to a fixed value baked into the manifest.

**Parameters:**

**`action_param`** `str`

Name of the action parameter to populate.

---

**`value`** `Any`

Constant value passed to the action.

---

**Returns:** `Binding`

A `literal` binding.

```python
nemoguardrails.manifests.manifest.Binding.model(
    action_param: str,
    model_type: str
) -> nemoguardrails.manifests.manifest.Binding
```

classmethod

Bind an action parameter to a fixed model type.

The returned literal binding sets `resource="model"`, allowing the
runtime to validate a model that is selected by the manifest rather than
the configured flow. For example, `Binding.model("model_name",
"llama_guard")` always supplies `model_name="llama_guard"`.

**Parameters:**

**`action_param`** `str`

Name of the action parameter receiving the model type.

---

**`model_type`** `str`

Configured model type supplied to the action.

---

**Returns:** `Binding`

A model resource binding with a fixed value.

```python
nemoguardrails.manifests.manifest.Binding.model_param(
    action_param: str,
    name: str,
    required: bool = True
) -> nemoguardrails.manifests.manifest.Binding
```

classmethod

Bind an action parameter to a configurable model type.

The returned binding reads the model type from a configured surface
parameter and sets `resource="model"`, allowing the runtime to validate
the resolved model before invoking the action. For example,
`Binding.model_param("model_name", "model")` binds `$model=content_safety`
to `model_name="content_safety"`.

**Parameters:**

**`action_param`** `str`

Name of the action parameter receiving the model type.

---

**`name`** `str`

Name of the surface parameter that selects the model type.

---

**`required`** `bool` — default: True

Whether the surface parameter must be provided.

---

**Returns:** `Binding`

A model resource binding backed by a surface parameter.

```python
nemoguardrails.manifests.manifest.Binding.surface_param(
    action_param: str,
    name: str,
    required: bool = True
) -> nemoguardrails.manifests.manifest.Binding
```

classmethod

Bind `action_param` to a caller-supplied surface parameter.

**Parameters:**

**`action_param`** `str`

Name of the action parameter to populate.

---

**`name`** `str`

Name of the surface parameter that supplies the value.

---

**`required`** `bool` — default: True

Whether the surface parameter must be provided.

---

**Returns:** `Binding`

A `surface_param` binding.

```python
class nemoguardrails.manifests.manifest.ConfigSpecRef()
```

**Bases:** [ImportTargetRef](#nemoguardrails-manifests-manifest-ImportTargetRef)

Import reference to a rail configuration specification.

```python
class nemoguardrails.manifests.manifest.EnvVar()
```

**Bases:** `BaseModel`

Environment variable declared by a rail requirement.

**`description`** `Optional[str] = None`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`name`** `str`

---

**`required`** `bool = False`

---

```python
class nemoguardrails.manifests.manifest.ImportTargetRef()
```

**Bases:** `BaseModel`

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`target`** `str`

---

```python
nemoguardrails.manifests.manifest.ImportTargetRef._target_must_be_import_ref(
    value: str
) -> str
```

classmethod

```python
class nemoguardrails.manifests.manifest.ModelRequirement()
```

**Bases:** `BaseModel`

Model resource declared by a rail requirement.

**`description`** `Optional[str] = None`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`required`** `bool = False`

---

**`type`** `str`

---

```python
class nemoguardrails.manifests.manifest.RailActions()
```

**Bases:** `BaseModel`

Import references for the actions declared by a rail.

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`refs`** `Tuple[ActionRef, ...] = ()`

---

```python
class nemoguardrails.manifests.manifest.RailConfigSchema()
```

**Bases:** `BaseModel`

Manifest reference to a rail's typed configuration schema.

**`export_names`** `Tuple[str, ...] = ()`

---

**`key`** `str`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`spec`** `ConfigSpecRef`

---

```python
class nemoguardrails.manifests.manifest.RailDirection
```

**Bases:** `enum.Enum`

Pipeline direction in which a rail surface runs.

**`INPUT`** `= 'input'`

---

**`OUTPUT`** `= 'output'`

---

**`RETRIEVAL`** `= 'retrieval'`

---

```python
class nemoguardrails.manifests.manifest.RailFlows()
```

**Bases:** `BaseModel`

Colang flow files and flow names declared by a rail.

**`files`** `Tuple[str, ...] = ('flows.co',)`

---

**`flow_names`** `Tuple[str, ...] = ()`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`v1_files`** `Tuple[str, ...] = ('flows.v1.co',)`

---

```python
class nemoguardrails.manifests.manifest.RailManifest()
```

**Bases:** `BaseModel`

Top-level, versioned manifest for a single rail.

The nested `spec` holds executable declarations such as the config schema,
flows, actions, surfaces, requirements, and privacy metadata. Those fields
are also exposed as read-only properties for convenient access.

**`actions`** `Optional[RailActions]`

---

**`config_schema`** `Optional[RailConfigSchema]`

---

**`flows`** `Optional[RailFlows]`

---

**`manifest_version`** `Literal[1] = 1`

---

**`metadata`** `RailMetadata = Field(default_factory=RailMetadata)`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`name`** `str`

---

**`origin`** `str = Field(default='', exclude=True)`

---

**`privacy`** `RailPrivacy`

---

**`requirements`** `RailRequirements`

---

**`spec`** `RailSpec = Field(default_factory=RailSpec)`

---

**`surfaces`** `Tuple[RailSurface, ...]`

---

```python
class nemoguardrails.manifests.manifest.RailMetadata()
```

**Bases:** `BaseModel`

Descriptive, non-executable facets of a rail used by the catalog.

None of these fields change runtime behavior; they drive display, discovery,
and filtering. `categories` and `capabilities` are closed taxonomies (the
pipeline stage a rail runs in and the functional behavior it advertises,
respectively); use the free-form `tags` for labels that belong to neither.

Unknown keys are preserved rather than rejected (`extra="allow"`) so a
manifest authored against a newer schema still loads on an older install and
authors can attach custom annotations without a schema change.

**`capabilities`** `Tuple[RailCapability, ...] = ()`

---

**`categories`** `Tuple[RailCategory, ...] = ()`

---

**`description`** `Optional[str] = None`

---

**`display_name`** `Optional[str] = None`

---

**`docs_url`** `Optional[str] = None`

---

**`lifecycle`** `RailLifecycle = 'stable'`

---

**`long_description`** `Optional[str] = None`

---

**`model_config`** `= ConfigDict(extra='allow', frozen=True)`

---

**`owner`** `Optional[str] = None`

---

**`tags`** `Tuple[str, ...] = ()`

---

**`version`** `Optional[str] = None`

---

```python
class nemoguardrails.manifests.manifest.RailPrivacy()
```

**Bases:** `BaseModel`

Data handling and remote-service behavior declared by a rail.

**`data_retention`** `Optional[str] = None`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`remote_services`** `Tuple[str, ...] = ()`

---

**`sends_bot_text`** `bool = False`

---

**`sends_retrieved_chunks`** `bool = False`

---

**`sends_user_text`** `bool = False`

---

```python
class nemoguardrails.manifests.manifest.RailRequirements()
```

**Bases:** `BaseModel`

Installation and runtime resources declared by a rail.

**`env_vars`** `Tuple[EnvVar, ...] = ()`

---

**`extras`** `Tuple[str, ...] = ()`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`models`** `Tuple[ModelRequirement, ...] = ()`

---

**`optional_dependencies`** `Tuple[str, ...] = ()`

---

**`services`** `Tuple[ServiceRequirement, ...] = ()`

---

```python
class nemoguardrails.manifests.manifest.RailSpec()
```

**Bases:** `BaseModel`

Executable configuration, flows, actions, and requirements for a rail.

**`actions`** `Optional[RailActions] = None`

---

**`config_schema`** `Optional[RailConfigSchema] = None`

---

**`flows`** `Optional[RailFlows] = None`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`privacy`** `RailPrivacy = Field(default_factory=RailPrivacy)`

---

**`requirements`** `RailRequirements = Field(default_factory=RailRequirements)`

---

**`surfaces`** `Tuple[RailSurface, ...] = ()`

---

```python
class nemoguardrails.manifests.manifest.RailSurface()
```

**Bases:** `BaseModel`

Configured flow surface mapped to a declared rail action.

**`action`** `ActionRef`

---

**`bindings`** `Tuple[Binding, ...] = ()`

---

**`direction`** `RailDirection`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`name`** `str`

---

**`transform_target`** `Optional[TransformTarget] = None`

---

```python
nemoguardrails.manifests.manifest.RailSurface._validate_execution_contract() -> nemoguardrails.manifests.manifest.RailSurface
```

```python
class nemoguardrails.manifests.manifest.ServiceRequirement()
```

**Bases:** `BaseModel`

External service declared by a rail requirement.

**`description`** `Optional[str] = None`

---

**`model_config`** `= ConfigDict(extra='forbid', frozen=True)`

---

**`name`** `str`

---

**`required`** `bool = False`

---

```python
nemoguardrails.manifests.manifest._validate_import_target(
    target: str
) -> str
```

```python
nemoguardrails.manifests.manifest.import_ref_target(
    ref: nemoguardrails.manifests.manifest.ImportRef
) -> str
```

Return the import target encoded by a supported manifest reference.

```python
nemoguardrails.manifests.manifest.iter_manifest_import_refs(
    manifest: nemoguardrails.manifests.manifest.RailManifest
) -> typing.Tuple[nemoguardrails.manifests.manifest.ImportRef, ...]
```

Return every configuration and action import reference in a manifest.

```python
nemoguardrails.manifests.manifest.resolve_import_ref(
    ref: nemoguardrails.manifests.manifest.ImportRef
) -> typing.Any
```

Import and return the Python object referenced by a manifest entry.

```python
nemoguardrails.manifests.manifest.BindingKind = Literal['surface_param', 'context', 'literal']
```

```python
nemoguardrails.manifests.manifest.BindingResource = Literal['model']
```

```python
nemoguardrails.manifests.manifest.ImportRef = Union[ConfigSpecRef, ActionRef]
```

```python
nemoguardrails.manifests.manifest.RailCapability = Literal['allow', 'block', 'classify', 'content_safety', 'detect_jailbreak', 'det...
```

```python
nemoguardrails.manifests.manifest.RailCategory = Literal['input', 'output', 'retrieval', 'dialog', 'execution', 'tool_input', 'to...
```

```python
nemoguardrails.manifests.manifest.RailLifecycle = Literal['stable', 'experimental', 'deprecated']
```