The Init Function for NeMo Guardrails

If config.py contains an init function, it is called during LLMRails initialization. Use it to set up shared resources and register action parameters.

The init function must be synchronous (def init, not async def init). The framework calls it without await, so an async function would silently do nothing.

Any top-level code in config.py runs at import time, before init() is called. This can be used for provider registration that does not require the LLMRails instance.

Basic Usage

1 from nemoguardrails import LLMRails
2 
3 def init(app: LLMRails):
4     # Initialize database connection
5     db = DatabaseConnection()
6 
7     # Register as action parameter (available to all actions)
8     app.register_action_param("db", db)

Registering Action Parameters

Action parameters registered in config.py are automatically injected into actions that declare them. The runtime matches parameters by name, i.e., the parameter name in the action must match the name used during registration.

config.py:

1 import os
2 
3 from nemoguardrails import LLMRails
4 
5 def init(app: LLMRails):
6     # Initialize shared resources
7     db = DatabaseConnection(host="localhost", port=5432)
8     api_client = ExternalAPIClient(api_key=os.environ.get("API_KEY"))
9 
10     # Register as action parameters
11     app.register_action_param("db", db)
12     app.register_action_param("api_client", api_client)

actions.py:

1 from nemoguardrails.actions import action
2 
3 @action()
4 async def fetch_user_data(user_id: str, db=None):
5     """The 'db' parameter is injected from config.py."""
6     return await db.get_user(user_id)
7 
8 @action()
9 async def call_external_service(query: str, api_client=None):
10     """The 'api_client' parameter is injected from config.py."""
11     return await api_client.search(query)

Built-in Action Parameters

In addition to parameters you register, the runtime automatically injects these built-in parameters into any action that declares them:

Parameter	Type	Description
`config`	`RailsConfig`	The full rails configuration object
`context`	`dict`	The current conversation context
`events`	`list`	The event history
`llm`	LLM instance	The main LLM (auto-registered during initialization)
`llm_task_manager`	`LLMTaskManager`	Manages LLM task execution

See Custom Data for details on accessing config.custom_data inside actions.

Accessing the Configuration

The app parameter provides access to the full configuration:

1 def init(app: LLMRails):
2     # Access the RailsConfig object
3     config = app.config
4 
5     # Access custom data from config.yml
6     custom_settings = config.custom_data
7 
8     # Access model configurations
9     models = config.models

Example: Database Connection

1 import os
2 import psycopg2
3 from nemoguardrails import LLMRails
4 
5 def init(app: LLMRails):
6     # Create connection pool
7     conn = psycopg2.connect(
8         host=os.environ.get("DB_HOST", "localhost"),
9         database=os.environ.get("DB_NAME", "mydb"),
10         user=os.environ.get("DB_USER", "user"),
11         password=os.environ.get("DB_PASSWORD"),
12     )
13 
14     app.register_action_param("db_conn", conn)

HTTP Client Lifecycle

The synchronous init function has no asynchronous teardown hook. Do not create a long-lived HTTP client in init unless another application component owns and closes it.

Create a shared canonical client at the surrounding application lifecycle boundary, register it as an action parameter, and close it at shutdown:

1 from nemoguardrails import LLMRails, RailsConfig
2 from nemoguardrails.http import create_http_client
3 
4 
5 async def run():
6     http_client = create_http_client(timeout=10.0)
7     config = RailsConfig.from_path("config")
8     app = LLMRails(config)
9     app.register_action_param("http_client", http_client)
10 
11     try:
12         return await app.generate_async(
13             messages=[{"role": "user", "content": "Hello"}],
14         )
15     finally:
16         await http_client.close()

Actions that accept http_client: HTTPClient | None = None can use a shared injected client or let http_call create and close a call-scoped fallback. For details, refer to Outbound HTTP in Actions.