Skip to navigation

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

Submodules

Package Contents

Classes

NameDescription
ActionRefNamed import reference to a rail action.
BindingMaps a single surface action parameter to its value source.
ConfigSpecRefImport reference to a rail configuration specification.
EnvVarEnvironment variable declared by a rail requirement.
ModelRequirementModel resource declared by a rail requirement.
RailActionsImport references for the actions declared by a rail.
RailCatalogImmutable index of rail manifests keyed by name and surface.
RailConfigSchemaManifest reference to a rail’s typed configuration schema.
RailDirectionPipeline direction in which a rail surface runs.
RailFlowsColang flow files and flow names declared by a rail.
RailManifestTop-level, versioned manifest for a single rail.
RailManifestRecordManifest plus provenance recorded in a rail catalog.
RailMetadataDescriptive, non-executable facets of a rail used by the catalog.
RailPrivacyData handling and remote-service behavior declared by a rail.
RailRequirementsInstallation and runtime resources declared by a rail.
RailSpecExecutable configuration, flows, actions, and requirements for a rail.
RailSurfaceConfigured flow surface mapped to a declared rail action.
ServiceRequirementExternal service declared by a rail requirement.
TransformTargetThe conversation variable a transform rewrites.

Functions

NameDescription
all_rail_manifestsReturn built-in rail manifests keyed by manifest name.
default_rail_catalogReturn the cached catalog of built-in rail manifests.
import_ref_targetReturn the import target encoded by a supported manifest reference.
iter_manifest_import_refsReturn every configuration and action import reference in a manifest.
normalize_configured_surface_nameReturn the surface name prefix without validating its parameters.
parse_configured_surfaceParse one complete configured surface reference.
resolve_import_refImport and return the Python object referenced by a manifest entry.

Data

BindingResource

ImportRef

RailCapability

RailCategory

RailLifecycle

API

class nemoguardrails.manifests.ActionRef()

Bases: ImportTargetRef

Named import reference to a rail action.

name
str
nemoguardrails.manifests.ActionRef._name_must_not_be_empty(
value: str
) -> str
classmethod
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
nemoguardrails.manifests.Binding._source_must_match_kind() -> nemoguardrails.manifests.manifest.Binding
nemoguardrails.manifests.Binding.context(
action_param: str,
key: str,
required: bool = True
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
boolDefaults to True

Whether the context variable must be present.

Returns: Binding

A context binding.

nemoguardrails.manifests.Binding.literal(
action_param: str,
value: typing.Any
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.

nemoguardrails.manifests.Binding.model(
action_param: str,
model_type: str
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.

nemoguardrails.manifests.Binding.model_param(
action_param: str,
name: str,
required: bool = True
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
boolDefaults to True

Whether the surface parameter must be provided.

Returns: Binding

A model resource binding backed by a surface parameter.

nemoguardrails.manifests.Binding.surface_param(
action_param: str,
name: str,
required: bool = True
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
boolDefaults to True

Whether the surface parameter must be provided.

Returns: Binding

A surface_param binding.

class nemoguardrails.manifests.ConfigSpecRef()

Bases: ImportTargetRef

Import reference to a rail configuration specification.

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
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
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, ...] = ()
class nemoguardrails.manifests.RailCatalog(
)

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.

nemoguardrails.manifests.RailCatalog.discover_built_ins(
library_path: typing.Optional[pathlib.Path] = None
classmethod

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

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

Return the manifest that owns a declared public flow name.

nemoguardrails.manifests.RailCatalog.surfaces(
direction: typing.Optional[nemoguardrails.manifests.manifest.RailDirection] = None

Return declared surfaces, optionally filtered by direction.

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
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'
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',)
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, ...]
class nemoguardrails.manifests.RailManifestRecord(
source: str
)
Dataclass

Manifest plus provenance recorded in a rail catalog.

manifest
RailManifest
source
str
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
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
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, ...] = ()
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, ...] = ()
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
nemoguardrails.manifests.RailSurface._validate_execution_contract() -> nemoguardrails.manifests.manifest.RailSurface
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
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'
nemoguardrails.manifests.all_rail_manifests()

Return built-in rail manifests keyed by manifest name.

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

Return the cached catalog of built-in rail manifests.

nemoguardrails.manifests.import_ref_target(
) -> str

Return the import target encoded by a supported manifest reference.

nemoguardrails.manifests.iter_manifest_import_refs(

Return every configuration and action import reference in a manifest.

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.

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.
nemoguardrails.manifests.resolve_import_ref(
) -> typing.Any

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

nemoguardrails.manifests.manifest.BindingResource = Literal['model']
nemoguardrails.manifests.manifest.ImportRef = Union[ConfigSpecRef, ActionRef]
nemoguardrails.manifests.manifest.RailCapability = Literal['allow', 'block', 'classify', 'content_safety', 'detect_jailbreak', 'det...
nemoguardrails.manifests.manifest.RailCategory = Literal['input', 'output', 'retrieval', 'dialog', 'execution', 'tool_call', 'too...
nemoguardrails.manifests.manifest.RailLifecycle = Literal['stable', 'experimental', 'deprecated']