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

Public API for rail manifests, catalog access, and configured surface references.

## Submodules

* **[`nemoguardrails.manifests.catalog`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/catalog)**
* **[`nemoguardrails.manifests.config_schema`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/config_schema)**
* **[`nemoguardrails.manifests.manifest`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/manifest)**
* **[`nemoguardrails.manifests.registry`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/registry)**
* **[`nemoguardrails.manifests.surface_reference`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/surface_reference)**

## Package 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.                   |
| [`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.                  |
| [`RailCatalog`](#nemoguardrails-manifests-catalog-RailCatalog)                | Immutable index of rail manifests keyed by name and surface.           |
| [`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.                       |
| [`RailManifestRecord`](#nemoguardrails-manifests-catalog-RailManifestRecord)  | Manifest plus provenance recorded in a rail catalog.                   |
| [`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.                       |
| [`TransformTarget`](#nemoguardrails-actions-rail_outcome-TransformTarget)     | The conversation variable a transform rewrites.                        |

### Functions

| Name                                                                                                                 | Description                                                           |
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`all_rail_manifests`](#nemoguardrails-manifests-registry-all_rail_manifests)                                        | Return built-in rail manifests keyed by manifest name.                |
| [`default_rail_catalog`](#nemoguardrails-manifests-registry-default_rail_catalog)                                    | Return the cached catalog of built-in rail manifests.                 |
| [`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. |
| [`normalize_configured_surface_name`](#nemoguardrails-manifests-surface_reference-normalize_configured_surface_name) | Return the surface name prefix without validating its parameters.     |
| [`parse_configured_surface`](#nemoguardrails-manifests-surface_reference-parse_configured_surface)                   | Parse one complete configured surface reference.                      |
| [`resolve_import_ref`](#nemoguardrails-manifests-manifest-resolve_import_ref)                                        | Import and return the Python object referenced by a manifest entry.   |

### Data

[`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.ActionRef()
```

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

Named import reference to a rail action.

**`name`** `str`

---

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

classmethod

```python
class nemoguardrails.manifests.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.Binding._source_must_match_kind() -> nemoguardrails.manifests.manifest.Binding
```

```python
nemoguardrails.manifests.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`](#nemoguardrails-manifests-manifest-Binding)

A `context` binding.

```python
nemoguardrails.manifests.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`](#nemoguardrails-manifests-manifest-Binding)

A `literal` binding.

```python
nemoguardrails.manifests.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`](#nemoguardrails-manifests-manifest-Binding)

A model resource binding with a fixed value.

```python
nemoguardrails.manifests.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`](#nemoguardrails-manifests-manifest-Binding)

A model resource binding backed by a surface parameter.

```python
nemoguardrails.manifests.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`](#nemoguardrails-manifests-manifest-Binding)

A `surface_param` binding.

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

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

Import reference to a rail configuration specification.

```python
class nemoguardrails.manifests.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.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.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.RailCatalog(
    records: typing.Iterable[nemoguardrails.manifests.catalog.RailManifestRecord] = ()
)
```

Immutable index of rail manifests keyed by name and surface.

Constructing a catalog validates the combined set of records and raises
`ValueError` on any collision: duplicate manifest names, duplicate config
keys, flow names, action names, or two rails claiming the same `(direction,
surface name)`. It also rejects a surface whose action is not declared in
that surface's own manifest.

**`manifests`** `Mapping[str, RailManifest]`

Return rail manifests keyed by manifest name.

---

**`records`** `Mapping[str, RailManifestRecord]`

Return catalog records keyed by manifest name.

---

```python
nemoguardrails.manifests.RailCatalog.discover_built_ins(
    library_path: typing.Optional[pathlib.Path] = None
) -> nemoguardrails.manifests.catalog.RailCatalog
```

classmethod

Discover built-in manifests from `rail.py` modules under the library.

```python
nemoguardrails.manifests.RailCatalog.owner_for_flow(
    flow_name: str
) -> typing.Optional[str]
```

Return the manifest that owns a declared public flow name.

```python
nemoguardrails.manifests.RailCatalog.surfaces(
    direction: typing.Optional[nemoguardrails.manifests.manifest.RailDirection] = None
) -> typing.Dict[typing.Tuple[nemoguardrails.manifests.manifest.RailDirection, str], nemoguardrails.manifests.manifest.RailSurface]
```

Return declared surfaces, optionally filtered by direction.

```python
class nemoguardrails.manifests.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.RailDirection
```

**Bases:** `enum.Enum`

Pipeline direction in which a rail surface runs.

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

---

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

---

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

---

**`TOOL_CALL`** `= 'tool_call'`

---

**`TOOL_RESULT`** `= 'tool_result'`

---

```python
class nemoguardrails.manifests.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.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.RailManifestRecord(
    manifest: nemoguardrails.manifests.manifest.RailManifest,
    source: str
)
```

Dataclass

Manifest plus provenance recorded in a rail catalog.

**`manifest`** `RailManifest`

---

**`source`** `str`

---

```python
class nemoguardrails.manifests.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.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_tool_call_text`** `bool = False`

---

**`sends_tool_result_text`** `bool = False`

---

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

---

```python
class nemoguardrails.manifests.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.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.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.RailSurface._validate_execution_contract() -> nemoguardrails.manifests.manifest.RailSurface
```

```python
class nemoguardrails.manifests.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
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.manifests.all_rail_manifests()
```

Return built-in rail manifests keyed by manifest name.

```python
nemoguardrails.manifests.default_rail_catalog() -> nemoguardrails.manifests.catalog.RailCatalog
```

Return the cached catalog of built-in rail manifests.

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

Return the import target encoded by a supported manifest reference.

```python
nemoguardrails.manifests.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.normalize_configured_surface_name(
    flow_text: str
) -> str
```

Return the surface name prefix without validating its parameters.

Malformed parameter syntax may still yield a normalized name.

```python
nemoguardrails.manifests.parse_configured_surface(
    flow_text: str
) -> typing.Tuple[str, typing.Dict[str, str]]
```

Parse one complete configured surface reference.

The accepted syntax is a bare surface name followed by zero or more
whitespace-separated `$name=value` parameters. Spaces around `=` and
parenthesized parameters are not supported. Values remain strings; bare
values end at whitespace, while single- or double-quoted values may contain
whitespace and punctuation.

**Raises:**

* `ValueError`: If the reference is empty, contains controls, or has malformed,
  blank, adjacent, or duplicate parameters.

```python
nemoguardrails.manifests.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.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_call', 'too...
```

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