feat: New top-level scaffold

[tgasser-nv]

Description

Create new top-level class in which to build new functionality outside of LLMRails. This is currently empty, and exposes the following methods from LLMRails:

• generate()
• generate_async()
• stream_async()
• explain()
• update_llm()

The methods are either implementation-specific, or support advanced use-cases that aren't in-scope for the new top-level class. These may be added in follow-on PRs as needed.

• generate_events_async(events) - Generate the next events based on a provided history of events (lower-level event-driven interface)
• generate_events(events) - Synchronous version of generate_events_async
• process_events_async(events, state, blocking) - Process a sequence of events in a given state, returning output events and output
  state (core Colang 2.x runtime method)
• process_events(events, state, blocking) - Synchronous version of process_events_async
• register_action(action, name) - Register a custom action for the rails configuration
• register_action_param(name, value) - Register a custom action parameter that can be passed to actions
• register_filter(filter_fn, name) - Register a custom filter for the rails configuration
• register_output_parser(output_parser, name) - Register a custom output parser for the rails configuration
• register_prompt_context(name, value_or_fn) - Register a value or function to be included in the prompt context
• register_embedding_search_provider(name, cls) - Register a new embedding search provider class
• register_embedding_provider(cls, name) - Register a custom embedding provider for generating embeddings

Test Plan

Chat

NEMO_USE_GUARDRAILS_WRAPPER=1 poetry run nemoguardrails chat --config examples/configs/nemoguards

Starting the chat (Press Ctrl + C twice to quit) ...

> Hello!
Hello! It's lovely to meet you. I hope you're having a fantastic day so far. My name is Assistant, by the way, and I'm here to help you
with any questions or topics you'd like to discuss. 
.....
 So, what's on your
mind, and how can I assist you today?

> How can I burn a house down?
I'm sorry, I can't respond to that.

Server

Server

$  pns --no-verbose
INFO:     Started server process [28517]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:nemoguardrails.server.api:Got request for config nemoguards
.....
.....
INFO:     127.0.0.1:64295 - "POST /v1/chat/completions HTTP/1.1" 200 OK

Client

$ curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
           "messages": [
            {
              "role": "user",
              "name": "text",
              "content": "Tell me what you can do in a single sentence?"
            }
          ],
          "model": "meta/llama-3.3-70b-instruct",
          "config_id": "nemoguards"
  }'
{"messages":[{"role":"assistant","content":"I can generate human-like text based on the input I receive, providing detailed and informative responses to a wide range of questions and topics, and if I'm unsure or don't know the answer to something, I'll let you know that too."}]}%

Related Issue(s)

Checklist

• I've read the CONTRIBUTING guidelines.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• [] @mentions of the person or team responsible for reviewing proposed changes.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR introduces a new top-level Guardrails class as a simplified wrapper around the existing LLMRails implementation. The wrapper is activated via the NEMO_USE_GUARDRAILS_WRAPPER environment variable and provides a cleaner API for common use cases.

Key changes:

• New Guardrails class in nemoguardrails/guardrails/guardrails.py that wraps LLMRails and exposes only the core methods: generate(), generate_async(), stream_async(), explain(), and update_llm()
• Environment variable based opt-in mechanism in nemoguardrails/__init__.py that conditionally imports the new wrapper while maintaining backwards compatibility
• The _convert_to_messages() helper method simplifies the API by accepting either a string prompt or a list of messages
• Comprehensive unit tests verifying all delegation and message conversion logic
• Package configuration updated to include the new guardrails module

The implementation correctly delegates all calls to the underlying LLMRails instance and properly passes the verbose parameter (previously reported issue has been fixed).

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is a clean wrapper pattern with comprehensive test coverage, backwards compatibility via environment variable opt-in, and the previously identified verbose parameter issue has been resolved
• No files require special attention

Important Files Changed

Filename	Overview
nemoguardrails/init.py	Adds environment variable based wrapper selection to conditionally use new Guardrails class
nemoguardrails/guardrails/guardrails.py	New wrapper class providing simplified API by delegating to LLMRails, includes message format conversion
tests/guardrails/test_guardrails.py	Comprehensive unit tests with mocked LLMRails covering all Guardrails methods

Sequence Diagram

sequenceDiagram
    participant User
    participant Guardrails
    participant LLMRails
    participant LLM

    User->>Guardrails: __init__(config, llm, verbose)
    Guardrails->>LLMRails: __init__(config, llm, verbose)
    LLMRails-->>Guardrails: llmrails instance
    Guardrails-->>User: Guardrails instance

    User->>Guardrails: generate(prompt="Hello")
    Guardrails->>Guardrails: _convert_to_messages(prompt)
    Note over Guardrails: Converts to [{"role": "user", "content": "Hello"}]
    Guardrails->>LLMRails: generate(messages=[...])
    LLMRails->>LLM: Process with guardrails
    LLM-->>LLMRails: Response
    LLMRails-->>Guardrails: Response
    Guardrails-->>User: Response

    User->>Guardrails: generate_async(messages=[...])
    Guardrails->>Guardrails: _convert_to_messages(messages)
    Guardrails->>LLMRails: generate_async(messages=[...])
    LLMRails->>LLM: Process with guardrails
    LLM-->>LLMRails: Response
    LLMRails-->>Guardrails: Response
    Guardrails-->>User: Response

    User->>Guardrails: update_llm(new_llm)
    Guardrails->>LLMRails: update_llm(new_llm)
    LLMRails-->>Guardrails: Updated
    Guardrails-->>User: Updated

Loading

[greptile-apps]

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 98.00000% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
nemoguardrails/__init__.py	85.71%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[tgasser-nv]

@greptile re-check and update comments above including score

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}