Rail Manifest Reference

A rail manifest is the versioned, declarative contract for a built-in rail under nemoguardrails/library. It identifies the rail, describes its configuration and dependencies, declares its actions and Colang flows, and exposes action-backed input, output, or retrieval surfaces.

The manifest keeps discovery separate from execution. Import references remain strings until the runtime needs the corresponding configuration factory or action. This lets the catalog inspect a rail without eagerly importing its optional integration dependencies.

File Layout

A manifest-backed library rail uses the following files:

nemoguardrails/library/example_rail/
├── __init__.py
├── actions.py
├── flows.co
├── flows.v1.co
├── rail.py
└── rail_config.py

Only rail.py and actions.py are required. Add the other files when the rail provides Colang flows or typed configuration.

The rail.py module must:

• Import manifest types from nemoguardrails.manifests.
• Define one module-level RAIL value containing a RailManifest.
• Avoid importing the action implementation, configuration implementation, or optional provider packages.

The built-in catalog discovers rail.py modules under nemoguardrails/library. It does not discover arbitrary application or third-party package paths.

Minimal Manifest

The following manifest declares one action and one input surface:

1
from nemoguardrails.manifests import (
2
    ActionRef,
3
    Binding,
4
    RailActions,
5
    RailDirection,
6
    RailManifest,
7
    RailMetadata,
8
    RailPrivacy,
9
    RailSpec,
10
    RailSurface,
11
)
12
13
CHECK_CUSTOM_POLICY = ActionRef(
14
    name="check_custom_policy",
15
    target="nemoguardrails.library.example_rail.actions:check_custom_policy",
16
)
17
18
RAIL = RailManifest(
19
    name="example_rail",
20
    metadata=RailMetadata(
21
        display_name="Example Rail",
22
        description="Checks user messages against an example policy.",
23
        categories=("input",),
24
        capabilities=("allow", "block"),
25
        tags=("built-in",),
26
        docs_url="docs/configure-rails/guardrail-catalog/community/example-rail.mdx",
27
    ),
28
    spec=RailSpec(
29
        actions=RailActions(refs=(CHECK_CUSTOM_POLICY,)),
30
        surfaces=(
31
            RailSurface(
32
                name="example check input",
33
                direction=RailDirection.INPUT,
34
                action=CHECK_CUSTOM_POLICY,
35
                bindings=(Binding.context("text", "user_message"),),
36
            ),
37
        ),
38
        privacy=RailPrivacy(),
39
    ),
40
)

Top-Level Fields

The following table describes the top-level manifest fields:

RailMetadata supports display text, categories, capabilities, tags, documentation URL, lifecycle, owner, and version. Categories and capabilities use the manifest taxonomies. Use tags for labels that do not belong to those taxonomies.

Actions

Declare each rail action with an ActionRef:

1
CHECK_CUSTOM_POLICY = ActionRef(
2
    name="check_custom_policy",
3
    target="nemoguardrails.library.example_rail.actions:check_custom_policy",
4
)

The name is the registered action name. It must agree with the action decorator. The target uses the module:attribute import-reference format.

List every action reference in RailActions, including actions used by surfaces:

1
actions=RailActions(refs=(CHECK_CUSTOM_POLICY,))

The runtime registers manifest actions lazily. It imports the action module and its optional dependencies when it resolves the action, not when the catalog first reads the manifest.

Every action declared by a rail manifest must return a RailOutcome. Actions decide whether to allow, block, or transform content. Colang flows and other runtimes decide how to present and enforce that decision.

Colang Flows

Use RailFlows when the rail includes Colang implementations:

1
from nemoguardrails.manifests import RailFlows
2
3
flows=RailFlows(
4
    files=("flows.co",),
5
    v1_files=("flows.v1.co",),
6
    flow_names=("example check input",),
7
)

files lists Colang 2.x files, v1_files lists Colang 1.0 files, and flow_names declares the public flow names owned by the rail. The default file names are flows.co and flows.v1.co.

Keep both dialect implementations behaviorally equivalent when the rail supports both. The flows should consume RailOutcome properties and own presentation behavior such as refusal intents and stopping the flow.

Action-Backed Surfaces

A RailSurface describes how to invoke a declared action in one pipeline direction. It is independent of a Colang implementation.

The following table describes the surface fields:

Use binding constructors to identify where each action argument comes from:

Use Binding.model_param or Binding.model whenever the resolved value identifies a configured model type. These helpers set resource="model" so the runtime validates the model before invoking the action. A model resource cannot read its type from request context.

Manifest-driven IORails supplies conversation values only through explicit Binding.context entries. Declaring an action parameter named context does not inject the complete context dictionary on this execution path. Bind each conversation input the action requires.

The manifest does not bind runtime-owned collaborators. IORails injects llms, llm, llm_task_manager, config, http_client, model_caches, and events into actions that declare those parameters.

Set required=False on a context or surface-parameter binding only when the action can operate without that value. A surface cannot bind the same action parameter more than once.

When an action can return a transform outcome, set transform_target to the value it rewrites:

1
from nemoguardrails.manifests import TransformTarget
2
3
RailSurface(
4
    name="example sanitize retrieval",
5
    direction=RailDirection.RETRIEVAL,
6
    action=SANITIZE_CUSTOM_TEXT,
7
    bindings=(Binding.context("text", "relevant_chunks"),),
8
    transform_target=TransformTarget.RELEVANT_CHUNKS,
9
)

Typed Configuration

Use RailConfigSchema to project a rail-specific field under rails.config:

1
from nemoguardrails.manifests import ConfigSpecRef, RailConfigSchema
2
3
config_schema=RailConfigSchema(
4
    key="example_rail",
5
    spec=ConfigSpecRef(
6
        target="nemoguardrails.library.example_rail.rail_config:build_config_spec"
7
    ),
8
)

The referenced factory must return a RailConfigSpec. Keep the factory and its model types in rail_config.py so reading the manifest does not import the implementation eagerly.

Requirements and Privacy

Declare install and runtime requirements instead of leaving them implicit:

1
from nemoguardrails.manifests import (
2
    EnvVar,
3
    RailPrivacy,
4
    RailRequirements,
5
    ServiceRequirement,
6
)
7
8
requirements=RailRequirements(
9
    extras=("example",),
10
    env_vars=(EnvVar(name="EXAMPLE_API_KEY", required=True),),
11
    services=(ServiceRequirement(name="Example API", required=True),),
12
)
13
14
privacy=RailPrivacy(
15
    sends_user_text=True,
16
    remote_services=("Example API",),
17
    data_retention="See the provider data policy.",
18
)

RailRequirements can declare package extras, environment variables, services, model resources, and optional dependencies. RailPrivacy records whether the rail sends user messages, bot messages, or retrieved chunks to remote services, and can describe provider retention behavior.

These declarations must match the action’s actual behavior. Do not include credentials or secret values in the manifest.

Catalog Validation

The built-in RailCatalog validates the combined manifest set. Catalog construction fails when it finds:

• Duplicate manifest names.
• Duplicate configuration keys.
• Duplicate public flow names.
• Duplicate action names.
• Duplicate surface names in the same direction.
• A surface that references an action not declared by its manifest.

You can inspect the built-in catalog through the public manifest API:

1
from nemoguardrails.manifests import (
2
    RailDirection,
3
    all_rail_manifests,
4
    default_rail_catalog,
5
)
6
7
manifests = all_rail_manifests()
8
input_surfaces = default_rail_catalog().surfaces(direction=RailDirection.INPUT)

Author Checklist

Use the following checklist when you author a rail manifest:

• Define a lightweight RAIL value in rail.py.
• Use stable, globally unique manifest, action, flow, configuration, and surface names.
• Keep import targets declarative and point them to the owning implementation modules.
• Return RailOutcome from every declared action.
• Keep Colang 1.0 and 2.x flows equivalent when both are present.
• Bind every conversation value, configured surface parameter, literal, and model resource that the action requires; declare runtime-owned collaborators only in the action signature.
• Declare transform targets, dependencies, external services, environment variables, and privacy behavior accurately.
• Add unit tests for the action and manifest contract and recorded tests for LLM or HTTP boundaries when applicable.
• Add or update the rail’s catalog documentation page.