feat(iorails): Support blocking rails

[tgasser-nv]

Description

Related Issue(s)

Verification

AI Assistance

• No AI tools were used.
• AI tools were used; a human reviewed and can explain every change (tool: ___).

Checklist

• I've read the CONTRIBUTING guidelines.
• This PR links to a triaged issue assigned to me.
• My PR title follows the project commit convention.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• I've noted any verification beyond CI and any checks I couldn't run.
• I did not update generated changelog files manually.
• I addressed all CodeRabbit, Greptile, and other review comments, or replied with why no change is needed.
• @mentions of the person or team responsible for reviewing proposed changes.

[codecov]

Codecov Report

❌ Patch coverage is 97.70115% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
nemoguardrails/guardrails/compiled_rail.py	97.40%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Pouyanpi]

I’m concerned about intentionally coupling IORails to every individual surface name here. The manifest already describes the surface, its direction, bindings, context inputs, and transform target. Repeating those names in IORails creates a second source of truth, and every rail addition or rename now requires an engine change as well. That partly defeats the purpose of the manifest work, which was to let engines consume the library’s declared execution contract instead of maintaining their own knowledge of each rail.

I understand the concern that adding a surface to the catalog shouldn’t automatically enable unsupported behavior. Could we make that capability-driven instead? IORails can declare what it supports, and compilation can explicitly reject surfaces whose manifest requirements it cannot satisfy. If we still need an intentional rollout flag, I think it should live alongside the surface in the manifest/catalog rather than in a parallel list here. Should be a separate PR if it has to touches manifests.

Also, I wouldn’t connect relevant_chunks specifically to having a KB. From the rail’s perspective, it is another context input, similar to user_message and bot_message. The current limitation is that IORails cannot supply that context value yet.

[Pouyanpi]

And I think this is another smell.

If IORails needs to inspect provider-specific metadata to construct the caller facing explanation, then the shared outcome boundary is incomplete. The actions already have the information needed to construct that explanation. We should define whether RailOutcome.reason is caller safe and require blocking actions to populate it consistently. If structured evidence also needs to be exposed, that should be represented explicitly in the shared RailOutcome contract. either way, I don’t think IORails should maintain knowledge of each integration’s metadata fields.

I checked the actions behind these fields. ActiveFence, GCP moderation, and PolicyAI already provide a reason, so those entries appear redundant. Content Safety, Llama Guard, Cleanlab, and AutoAlign do not provide one, but they already have enough information to construct it at the point where they create the blocking outcome.

[Pouyanpi]

I think this is a consequence of the RailResult boundary discussed in #2261. If RailResult carried the complete RailOutcome, IORails would not need to maintain a list of provider-specific metadata fields here. I’d prefer fixing that shared boundary

[Pouyanpi]

I don’t think accepting an http_client parameter is a reliable signal that the action does not need its optional dependency. It only says what the function can receive; it does not tell us which backend the configuration selected.

For example, an action may accept http_client and still use its local backend depending on its configuration. If we have conditional or alternative dependencies, I think that needs to be expressed in the manifest or validated against the selected backend rather than inferred from the Python signature.

[Pouyanpi]

here model dependencies are inferred from the action parameter name model_name, even though the manifest already has RailRequirements.models. If that information is not sufficient to connect a binding to a configured model, I think we should extend the manifest/binding contract. Hard-coding a parameter name means renaming it could silently disable validation.

It also looks like compile-time capabilities and runtime dependencies are being mixed together. We create an llms mapping containing None values only to communicate the configured model types.

Could compilation receive the available model types explicitly and validate them against the manifest requirements? That would avoid coupling validation to an action parameter naming convention and keep RailDependencies.llms for actual runtime models.

[Pouyanpi]

This also looks like a sign that compile-time capabilities and runtime dependencies are being mixed together.

we create an llms mapping containing None values just to communicate the configured model types, and then infer that a binding is a model dependency because its action parameter happens to be named model_name.

Could compilation receive the available model types explicitly and validate them against the manifest’s model requirements? that would avoid coupling the compiler to an action parameter naming convention and keep RailDependencies.llms for actual runtime models.