Engine

Engine for guardrail components.

DMGuardrailEngine(dm_invoker, engine_config=None)

Bases: DMComponent, GuardrailEngine

Guardrail engine that uses a decision model to evaluate atomic safety policies.

This engine targets Noul-capable decision models. Each policy key is used as the stable question identifier when invoking the model and when reading the answer from DMOutput.answers.

Attributes:

Name	Type	Description
config	DMGuardrailEngineConfig	Engine configuration.
dm_invoker	BaseDMInvoker	Decisions model invoker used for evaluations.
policies	dict[str, DMPolicyConfig]	Loaded and validated policy configurations.
questions	dict[str, DMQuestion]	Mapping of policy keys to DMQuestion.noul instances.

Initialize the DMGuardrailEngine.

Parameters:

Name	Type	Description	Default
dm_invoker	BaseDMInvoker	Pre-built decisions model invoker.	required
engine_config	DMGuardrailEngineConfig | None	Engine policy and template configuration. Defaults to an empty config (bundled policies).	None

Raises:

Type	Description
ValueError	If no policies are configured or an enabled category is unknown.

check_input(content, *, trace_attributes=None, **kwargs) async

Check input content against configured decision-model policies.

Parameters:

Name	Type	Description	Default
content	str	The input text to evaluate for safety.	required
trace_attributes	dict[str, Any] | None	Additional trace attributes. Defaults to None.	None
**kwargs	Any	hyperparameters forwarded to the DM invoker. Defaults to empty.	{}

Returns:

Name	Type	Description
GuardrailResult	GuardrailResult	Safe or unsafe result with category, policy, and score metadata.

check_output(content, *, trace_attributes=None, **kwargs) async

Check output content against configured decision-model policies.

Parameters:

Name	Type	Description	Default
content	str	The output text to evaluate for safety.	required
trace_attributes	dict[str, Any] | None	Additional trace attributes. Defaults to None.	None
**kwargs	Any	hyperparameters forwarded to the DM invoker. Defaults to empty.	{}

Returns:

Name	Type	Description
GuardrailResult	GuardrailResult	Safe or unsafe result with category, policy, and score metadata.

DMGuardrailEngineConfig

Bases: BaseGuardrailEngineConfig

Configuration for DMGuardrailEngine.

Attributes:

Name	Type	Description
policy_config_path	str | None	Path to a custom YAML policy file. Defaults to None.
policies	dict[str, DMPolicyConfig] | None	In-memory override of YAML policies. Defaults to None.
enabled_categories	list[str] | None	Category names of the loaded policies to check, including their aliases. None enables all policies; an empty list disables all policies. Defaults to None.
default_threshold	float	Probability threshold used when a policy omits one. Defaults to 0.5, tuned for the bundled openrouter/typesafe/jev-1.13 model.
state_template	dict[str, Any] | None	Decisions state template containing a {content} placeholder. Defaults to None.

GuardrailEngine

Bases: Protocol

Base engine interface for guardrail engines.

This protocol defines the contract that all guardrail engines must implement. Engines can check content for safety violations using various techniques such as phrase matching, topic classification, or external API calls.

All engines must be asynchronous to support both sync and async guardrail providers.

Attributes:

Name	Type	Description
config	BaseGuardrailEngineConfig	Engine configuration specifying what content types to check

check_input(content, **kwargs) async

Check input content for safety violations.

This method should implement provider-specific safety checks on user input such as query content, context, or prompts before sending to LLM.

Parameters:

Name	Type	Description	Default
content	str	The input text to evaluate for safety	required
**kwargs		Additional engine-specific parameters (optional)	{}

Returns:

Type	Description
GuardrailResult	GuardrailResult indicating if content is safe, with reason if unsafe

Raises:

Type	Description
Exception	If the safety check fails due to engine errors

check_output(content, **kwargs) async

Check output content for safety violations.

This method should implement provider-specific safety checks on system output such as LLM responses, generated text, or static messages before showing to users.

Parameters:

Name	Type	Description	Default
content	str	The output text to evaluate for safety	required
**kwargs		Additional engine-specific parameters (optional)	{}

Returns:

Type	Description
GuardrailResult	GuardrailResult indicating if content is safe, with reason if unsafe

Raises:

Type	Description
Exception	If the safety check fails due to engine errors

NemoGuardrailEngine(config)

Bases: GuardrailEngine

Default engine that keeps current NeMo Guardrails behavior.

This engine implements the GuardrailEngine protocol to provide NeMo Guardrails functionality for content safety checking.

Attributes:

Name	Type	Description
config	NemoGuardrailEngineConfig	Engine configuration specifying what content types to check.
rails	LLMRails | None	LLMRails instance.

Initializes a new instance of the NemoGuardrailEngine class.

The engine uses structured safety configuration via content_safety_config and topic_safety_config. Either or both can be provided; if only one is given, that check runs and the other is skipped.

LLM Invoker Override: If self.config.nemo_kwargs is provided and contains a model configuration with type: main, that model will be overridden by self.config.lm_invoker to ensure consistency across the SDK.

Example

Activate the new configuration by providing at least one safety config::

from gllm_guardrail.config.safety import ContentSafetyConfigBuilder, TopicSafetyConfigBuilder

# Both enabled (recommended)
config = NemoGuardrailEngineConfig(
    lm_invoker=my_invoker,
content_safety_config=ContentSafetyConfigBuilder(),
topic_safety_config=TopicSafetyConfigBuilder(),
)

# Only content safety enabled, topic safety skipped
config = NemoGuardrailEngineConfig(
    lm_invoker=my_invoker,
    content_safety_config=ContentSafetyConfigBuilder(),
)

engine = NemoGuardrailEngine(config=config)

Parameters:

Name	Type	Description	Default
config	NemoGuardrailEngineConfig	NemoGuardrailEngineConfig specifying both base and NeMo-specific settings.	required

check_input(content, **kwargs) async

Check input content for safety violations.

This method implements NeMo Guardrails checking for user input such as query content, context, or prompts before sending to LLM.

Parameters:

Name	Type	Description	Default
content	str	The input text to evaluate for safety.	required
**kwargs	Any	Additional engine-specific parameters.	{}

Returns:

Name	Type	Description
GuardrailResult	GuardrailResult	GuardrailResult indicating if content is safe, with reason if unsafe.

Raises:

Type	Description
RuntimeError	If the guardrail engine is not initialized.

check_input_stream(chunks, **kwargs)

Check an input stream with one complete-text NeMo safety call.

Parameters:

Name	Type	Description	Default
chunks	AsyncIterator[str]	Asynchronous iterator of source chunk strings.	required
**kwargs	Any	Additional engine-specific parameters.	{}

Returns:

Type	Description
AsyncIterator[GuardrailStreamChunk]	AsyncIterator[GuardrailStreamChunk]: Original chunks when safe, or one terminal unsafe marker when NeMo judges the joined text unsafe.

check_output(content, **kwargs) async

Check output content for safety violations.

This method implements NeMo Guardrails checking for system output such as LLM responses, generated text, or static messages before showing to users.

Parameters:

Name	Type	Description	Default
content	str	The output text to evaluate for safety.	required
**kwargs	Any	Additional engine-specific parameters.	{}

Returns:

Name	Type	Description
GuardrailResult	GuardrailResult	GuardrailResult indicating if content is safe, with reason if unsafe.

Raises:

Type	Description
RuntimeError	If the guardrail engine is not initialized.

check_output_stream(chunks, **kwargs)

Check an output stream with one complete-text NeMo safety call.

Parameters:

Name	Type	Description	Default
chunks	AsyncIterator[str]	Asynchronous iterator of source chunk strings.	required
**kwargs	Any	Additional engine-specific parameters.	{}

Returns:

Type	Description
AsyncIterator[GuardrailStreamChunk]	AsyncIterator[GuardrailStreamChunk]: Original chunks when safe, or one terminal unsafe marker when NeMo judges the joined text unsafe.

PhraseMatcherEngine(config=None, banned_phrases=None, use_spacy=None, model_name='en_core_web_sm')

Bases: GuardrailEngine

Engine that uses SpaCy PhraseMatcher or Regex for banned phrase detection.

This engine implements the GuardrailEngine protocol to check content for banned phrases using either SpaCy for optimized matching or regex as a fallback.

Attributes:

Name	Type	Description
config		Engine configuration specifying what content types to check
banned_phrases	list[str]	Phrases that are explicitly banned.
use_spacy	bool	Whether to use SpaCy for phrase matching.
model_name	str	SpaCy model name to load.
banned_phrases_regex	Pattern | None	Compiled regex pattern for fallback.
phrase_matcher	PhraseMatcher | None	SpaCy phrase matcher.
nlp	Language | None	SpaCy language model.

Initialize the PhraseMatcherEngine.

Parameters:

Name	Type	Description	Default
config	BaseGuardrailEngineConfig | None	Engine configuration. Defaults to BaseGuardrailEngineConfig with INPUT_ONLY mode.	None
banned_phrases	list[str] | None	List of banned phrases. Defaults to DEFAULT_BANNED_PHRASES.	None
use_spacy	bool | None	Whether to use SpaCy for phrase matching. Defaults to SPACY_AVAILABLE.	None
model_name	str	SpaCy model name to load. Defaults to "en_core_web_sm".	'en_core_web_sm'

check_input(content, **kwargs) async

Check input content for banned phrases.

Parameters:

Name	Type	Description	Default
content	str	The input text to evaluate for safety	required
**kwargs	Any	Additional engine-specific parameters (optional)	{}

Returns:

Type	Description
GuardrailResult	GuardrailResult indicating if content is safe, with reason if unsafe

Raises:

Type	Description
Exception	If the safety check fails due to engine errors

check_input_stream(chunks, max_stream_buffer_bytes=DEFAULT_MAX_STREAM_BUFFER_BYTES, max_stream_buffer_chunks=DEFAULT_MAX_STREAM_BUFFER_CHUNKS, **kwargs)

Check an input stream by buffering and evaluating the complete text.

Parameters:

Name	Type	Description	Default
chunks	AsyncIterator[str]	Asynchronous iterator of source chunk strings.	required
max_stream_buffer_bytes	int	Maximum cumulative UTF-8 bytes to buffer. Defaults to DEFAULT_MAX_STREAM_BUFFER_BYTES.	DEFAULT_MAX_STREAM_BUFFER_BYTES
max_stream_buffer_chunks	int	Maximum source chunks to buffer. Defaults to DEFAULT_MAX_STREAM_BUFFER_CHUNKS.	DEFAULT_MAX_STREAM_BUFFER_CHUNKS
**kwargs	Any	Additional engine-specific parameters.	{}

Returns:

Type	Description
AsyncIterator[GuardrailStreamChunk]	AsyncIterator[GuardrailStreamChunk]: Original chunks when safe, or one terminal unsafe marker when the joined text matches a banned phrase.

check_output(content, **kwargs) async

Check output content for banned phrases.

Parameters:

Name	Type	Description	Default
content	str	The output text to evaluate for safety	required
**kwargs	Any	Additional engine-specific parameters (optional)	{}

Returns:

Type	Description
GuardrailResult	GuardrailResult indicating if content is safe, with reason if unsafe

Raises:

Type	Description
Exception	If the safety check fails due to engine errors

check_output_stream(chunks, max_stream_buffer_bytes=DEFAULT_MAX_STREAM_BUFFER_BYTES, max_stream_buffer_chunks=DEFAULT_MAX_STREAM_BUFFER_CHUNKS, **kwargs)

Check an output stream by buffering and evaluating the complete text.

Parameters:

Name	Type	Description	Default
chunks	AsyncIterator[str]	Asynchronous iterator of source chunk strings.	required
max_stream_buffer_bytes	int	Maximum cumulative UTF-8 bytes to buffer. Defaults to DEFAULT_MAX_STREAM_BUFFER_BYTES.	DEFAULT_MAX_STREAM_BUFFER_BYTES
max_stream_buffer_chunks	int	Maximum source chunks to buffer. Defaults to DEFAULT_MAX_STREAM_BUFFER_CHUNKS.	DEFAULT_MAX_STREAM_BUFFER_CHUNKS
**kwargs	Any	Additional engine-specific parameters.	{}

Returns:

Type	Description
AsyncIterator[GuardrailStreamChunk]	AsyncIterator[GuardrailStreamChunk]: Original chunks when safe, or one terminal unsafe marker when the joined text matches a banned phrase.