Custom Configuration Data for NeMo Guardrails | NVIDIA NeMo Guardrails Library Developer Guide

The custom_data field in config.yml allows you to pass additional configuration to your custom initialization code and actions.

Defining Custom Data

Add a custom_data section to your config.yml:

1 models:
2   - type: main
3     engine: openai
4     model: gpt-4
5 
6 custom_data:
7   api_endpoint: "https://api.example.com"
8   max_retries: 3
9   timeout_seconds: 30
10   feature_flags:
11     enable_caching: true
12     debug_mode: false

Accessing in config.py

Access custom data in your init function:

1 from nemoguardrails import LLMRails
2 
3 def init(app: LLMRails):
4     # Access custom_data from the configuration
5     custom_data = app.config.custom_data
6 
7     # Get individual values
8     api_endpoint = custom_data.get("api_endpoint")
9     max_retries = custom_data.get("max_retries", 3)  # with default
10 
11     # Access nested values
12     feature_flags = custom_data.get("feature_flags", {})
13     enable_caching = feature_flags.get("enable_caching", False)
14 
15     # Load sensitive values from environment variables
16     import os
17     api_key = os.environ.get("API_KEY")
18 
19     # Use to configure your providers
20     client = APIClient(
21         endpoint=api_endpoint,
22         api_key=api_key,
23         max_retries=max_retries
24     )
25 
26     app.register_action_param("api_client", client)

Accessing in Actions

You can also access custom data directly in actions via the config parameter:

1 from nemoguardrails.actions import action
2 
3 @action()
4 async def my_action(config=None):
5     """Access custom_data via the config parameter."""
6     custom_data = config.custom_data
7     timeout = custom_data.get("timeout_seconds", 30)
8 
9     # Use the configuration
10     return await do_something(timeout=timeout)

Sensitive Configuration

For sensitive values like API keys, use the api_key_env_var field on model configurations or load environment variables in your init() function:

config.py:

1 import os
2 from nemoguardrails import LLMRails
3 
4 def init(app: LLMRails):
5     custom_data = app.config.custom_data
6 
7     api_key = os.environ.get("API_KEY")
8     db_url = os.environ.get("DATABASE_URL", "postgresql://localhost/myapp")
9 
10     client = APIClient(
11         endpoint=custom_data.get("api_endpoint"),
12         api_key=api_key,
13     )
14 
15     app.register_action_param("api_client", client)

The custom_data field in config.yml uses standard YAML parsing and does not support inline environment variable substitution (e.g., ${VAR}). Load sensitive values from environment variables in your init() function instead.

Best Practices

Use environment variables for secrets: Never hardcode API keys or passwords.
Provide defaults: Use .get("key", default) for optional values.
Document your custom_data schema: Add comments in config.yml explaining expected fields.
Validate configuration: Check required fields in init() and raise clear errors.

1 def init(app: LLMRails):
2     custom_data = app.config.custom_data
3 
4     # Validate required fields
5     required_fields = ["api_endpoint", "api_key"]
6     missing = [f for f in required_fields if not custom_data.get(f)]
7 
8     if missing:
9         raise ValueError(f"Missing required custom_data fields: {missing}")