> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/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'] ``` ## Docs - [nemoguardrails.manifests.catalog](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/catalog.md) - [nemoguardrails.manifests.config_schema](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/config_schema.md) - [nemoguardrails.manifests.manifest](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/manifest.md) - [nemoguardrails.manifests.registry](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/registry.md) - [nemoguardrails.manifests.surface_reference](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/manifests/surface_reference.md)