nemoguardrails.manifests.manifest | NVIDIA NeMo Guardrails Library Developer Guide

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

Functions

Name	Description
`_validate_import_target`	-
`import_ref_target`	Return the import target encoded by a supported manifest reference.
`iter_manifest_import_refs`	Return every configuration and action import reference in a manifest.
`resolve_import_ref`	Import and return the Python object referenced by a manifest entry.

Data

API

class nemoguardrails.manifests.manifest.ActionRef()

Bases: ImportTargetRef

Named import reference to a rail action.

name

str

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

classmethod

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

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

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

boolDefaults to True

Whether the context variable must be present.

Returns: Binding

A context binding.

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.

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.

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

boolDefaults to True

Whether the surface parameter must be provided.

Returns: Binding

A model resource binding backed by a surface parameter.

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

boolDefaults to True

Whether the surface parameter must be provided.

Returns: Binding

A surface_param binding.

class nemoguardrails.manifests.manifest.ConfigSpecRef()

Bases: ImportTargetRef

Import reference to a rail configuration specification.

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

class nemoguardrails.manifests.manifest.ImportTargetRef()

Bases: BaseModel

model_config

= ConfigDict(extra='forbid', frozen=True)

target

str

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

classmethod

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

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

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

class nemoguardrails.manifests.manifest.RailDirection

Bases: enum.Enum

Pipeline direction in which a rail surface runs.

INPUT

= 'input'

OUTPUT

= 'output'

RETRIEVAL

= 'retrieval'

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

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

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

tags

Tuple[str, ...] = ()

version

Optional[str] = None

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

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

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

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

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

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

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

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

Return the import target encoded by a supported manifest reference.

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.

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

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

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

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_input', 'to...

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