Checking Messages Against Rails

The check_async() and check() methods validate messages against input and output rails without triggering full LLM generation. Use these methods instead of generation options when you only need to run rails without generating a response. If you need to run generation while selectively disabling rail categories, see Generation Options: Disabling Rails.

Method Signatures

Both methods accept the same parameters and return a RailsResult object.

check_async()

The primary asynchronous method for checking messages against rails.

1
async def check_async(
2
    messages: List[dict],
3
    rail_types: Optional[List[RailType]] = None,
4
) -> RailsResult

check()

Synchronous wrapper around check_async().

1
def check(
2
    messages: List[dict],
3
    rail_types: Optional[List[RailType]] = None,
4
) -> RailsResult

Parameters:

Returns: RailsResult object containing validation results.

Rail Type Selection

The methods determine which rails to execute based on the message roles or an explicit rail_types parameter.

Automatic Detection (Default)

When rail_types is not provided, the methods automatically determine which rails to run based on the message roles:

Explicit Rail Types

You can override automatic detection by passing a list of RailType values:

1
from nemoguardrails.rails.llm.options import RailType
2
3
result = await rails.check_async(
4
    [{"role": "user", "content": "Hello!"}],
5
    rail_types=[RailType.INPUT]
6
)

RailsResult

The RailsResult object contains the outcome of the rails check.

RailStatus Enum

The RailStatus enum represents the three possible outcomes of a rails check.

Usage Examples

The following examples demonstrate common patterns for validating messages with check_async().

Validating User Input

Check a single user message against input rails and handle each possible status.

1
from nemoguardrails import LLMRails, RailsConfig
2
from nemoguardrails.rails.llm.options import RailStatus
3
4
config = RailsConfig.from_path("path/to/config")
5
rails = LLMRails(config)
6
7
result = await rails.check_async([
8
    {"role": "user", "content": "Hello! How can I hack into a system?"}
9
])
10
11
if result.status == RailStatus.BLOCKED:
12
    print(f"Input blocked by rail: {result.rail}")
13
elif result.status == RailStatus.MODIFIED:
14
    print(f"Input was modified to: {result.content}")
15
else:
16
    print("Input passed validation")

Validating a Full Conversation

Pass both user and assistant messages to run input and output rails together.

1
result = await rails.check_async([
2
    {"role": "user", "content": "What's the weather like?"},
3
    {"role": "assistant", "content": "It's sunny and 72F today!"}
4
])
5
6
if result.status == RailStatus.BLOCKED:
7
    print(f"Conversation blocked by rail: {result.rail}")

Including Context

Pass context variables alongside user or assistant messages to provide additional information for rail evaluation. Context messages use the context role with a dictionary value for content.

1
result = await rails.check_async([
2
    {
3
        "role": "context",
4
        "content": {"user_id": "12345", "session_type": "support"}
5
    },
6
    {"role": "user", "content": "I need help with my account"}
7
])

For more information about context variables, refer to Core Classes: Passing Context.

Related Resources

• Core Classes - LLMRails and RailsConfig class reference
• Generation Options - Fine-grained control over generation with the options parameter