> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llms.txt. # nemoguardrails.rails ## Subpackages * **[`nemoguardrails.rails.llm`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm)** ## Package Contents ### Classes | Name | Description | | ------------------------------------------------------------- | -------------------------------------------------- | | [`LLMRails`](#nemoguardrails-rails-llm-llmrails-LLMRails) | Rails based on a given configuration. | | [`RailsConfig`](#nemoguardrails-rails-llm-config-RailsConfig) | Configuration object for the models and the rails. | ### API ```python class nemoguardrails.LLMRails( config: nemoguardrails.rails.llm.config.RailsConfig, llm: typing.Optional[nemoguardrails.types.LLMModel] = None, verbose: bool = False ) ``` **Bases:** [BaseGuardrails](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/base_guardrails#nemoguardrails-base_guardrails-BaseGuardrails) Rails based on a given configuration. **`_default_embedding_engine`** `= 'FastEmbed'` --- **`_default_embedding_model`** `= 'all-MiniLM-L6-v2'` --- **`_default_embedding_params`** `= {}` --- **`_embedding_search_providers`** `= {}` --- **`_llm_generation_actions`** --- **`_log_adapters`** `= create_log_adapters(config.tracing)` --- **`events_history_cache`** `= {}` --- **`llm`** `Optional[LLMModel]` --- **`passthrough_fn`** The optional passthrough function that bypasses LLM generation. When set, the rails pipeline calls this function instead of the main LLM for generating responses. LLMGenerationActions is private, expose only `passthrough_fn` as a public API --- **`runtime`** `Runtime` --- ```python nemoguardrails.LLMRails.__getstate__() ``` ```python nemoguardrails.LLMRails.__setstate__( state ) ``` ```python nemoguardrails.LLMRails._create_model_cache( model ) -> nemoguardrails.llm.cache.LFUCache ``` Create cache instance for a model based on its configuration. **Parameters:** **`model`** The model configuration object --- **Returns:** [`LFUCache`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/llm/cache/lfu#nemoguardrails-llm-cache-lfu-LFUCache) The cache instance ```python nemoguardrails.LLMRails._ensure_explain_info() -> nemoguardrails.logging.explain.ExplainInfo ``` staticmethod Ensure that the ExplainInfo variable is present in the current context **Returns:** [`ExplainInfo`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/logging/explain#nemoguardrails-logging-explain-ExplainInfo) A ExplainInfo class containing the llm calls' statistics ```python nemoguardrails.LLMRails._get_embeddings_search_provider_instance( esp_config: typing.Optional[nemoguardrails.rails.llm.config.EmbeddingSearchProvider] = None ) -> nemoguardrails.embeddings.index.EmbeddingsIndex ``` ```python nemoguardrails.LLMRails._get_events_for_messages( messages: typing.List[dict], state: typing.Any ) ``` Return the list of events corresponding to the provided messages. Tries to find a prefix of messages for which we have already a list of events in the cache. For the rest, they are converted as is. The reason this cache exists is that we want to benefit from events generated in previous turns, which can't be computed again because it would be expensive (e.g., involving multiple LLM calls). When an explicit state object will be added, this mechanism can be removed. **Parameters:** **`messages`** `List[dict]` The list of messages. --- **Returns:** A list of events. ```python nemoguardrails.LLMRails._init_kb() ``` async Initializes the knowledge base. ```python nemoguardrails.LLMRails._init_llms() ``` Initializes the right LLM engines based on the configuration. There can be multiple LLM engines and types that can be specified in the config. The main LLM engine is the one that will be used for all the core guardrails generations. Other LLM engines can be specified for use in specific actions. The reason we provide an option for decoupling the main LLM engine from the action LLM is to allow for flexibility in using specialized LLM engines for specific actions. **Raises:** * `ModelInitializationError`: If any model initialization fails ```python nemoguardrails.LLMRails._initialize_model_caches() -> None ``` Initialize caches for configured models. ```python nemoguardrails.LLMRails._prepare_model_kwargs( model_config ) ``` Prepare kwargs for model initialization, including API key from environment variable. **Parameters:** **`model_config`** The model configuration object --- **Returns:** The prepared kwargs for model initialization ```python nemoguardrails.LLMRails._resolve_streaming_output_rail_actions() -> typing.List[typing.Tuple[str, typing.Tuple[str, typing.Any]]] ``` Pair each configured output rail flow, in order, with the action streaming calls on every chunk. ```python nemoguardrails.LLMRails._run_output_rails_in_streaming( streaming_handler: typing.AsyncIterator[typing.Union[str, dict, nemoguardrails.types.ToolCallChunk, nemoguardrails.types.ToolCallDeltaChunk]], output_rails_streaming_config: nemoguardrails.rails.llm.config.OutputRailsStreamingConfig, output_rail_actions: typing.List[typing.Tuple[str, typing.Tuple[str, typing.Any]]], prompt: typing.Optional[str] = None, messages: typing.Optional[typing.List[dict]] = None, stream_first: typing.Optional[bool] = None ) -> typing.AsyncIterator[str] ``` async 1. Buffers tokens from 'streaming_handler' via BufferStrategy. 2. Runs sequential (parallel for colang 2.0 in future) flows for each chunk. 3. Yields the chunk if not blocked, or STOP if blocked. ```python nemoguardrails.LLMRails._validate_config() ``` Runs additional validation checks on the config. ```python nemoguardrails.LLMRails._validate_public_state( state: typing.Optional[typing.Union[dict, nemoguardrails.colang.v2_x.runtime.flows.State]] ) -> None ``` Validate public dict state passed through generate/generate_async. ```python nemoguardrails.LLMRails._validate_streaming_with_output_rails() -> None ``` ```python nemoguardrails.LLMRails.check( messages: typing.List[dict], rail_types: typing.Optional[typing.List[nemoguardrails.rails.llm.options.RailType]] = None, tools: typing.Optional[typing.List[dict]] = None ) -> nemoguardrails.rails.llm.options.RailsResult ``` Run rails on messages based on their content (synchronous). This is a synchronous wrapper around check_async(). **Parameters:** **`messages`** `List[dict]` List of message dicts with 'role' and 'content' fields. --- **`rail_types`** `Optional[List[RailType]]` — default: None `Optional[List[` [`RailType`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/options#nemoguardrails-rails-llm-options-RailType) `]]` — Optional list of rail types to run. See check_async() for details. --- **`tools`** `Optional[List[dict]]` — default: None Not supported. See check_async() for details. --- **Returns:** [`RailsResult`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/options#nemoguardrails-rails-llm-options-RailsResult) RailsResult containing status, content, and optional blocking rail name. **Raises:** * `RailTypeNotSupportedError`: If `tools` is given, or a requested rail type is `tool_call` or `tool_result`, which only the IORails engine runs. * `RailTypeNotConfiguredError`: If a requested rail type has no configured flows. ```python nemoguardrails.LLMRails.check_async( messages: typing.List[dict], rail_types: typing.Optional[typing.List[nemoguardrails.rails.llm.options.RailType]] = None, tools: typing.Optional[typing.List[dict]] = None ) -> nemoguardrails.rails.llm.options.RailsResult ``` async Run rails on messages based on their content (asynchronous). When `rail_types` is not provided, automatically determines which rails to run based on message roles: * Only user messages: runs input rails * Only assistant messages: runs output rails * Both user and assistant messages: runs both input and output rails * No user/assistant messages: logs warning and returns passing result When `rail_types` is provided, runs exactly the specified rail types, skipping the auto-detection logic. **Parameters:** **`messages`** `List[dict]` List of message dicts with 'role' and 'content' fields. Messages can contain any roles, but only user/assistant roles determine which rails execute when `rail_types` is not provided. --- **`rail_types`** `Optional[List[RailType]]` — default: None `Optional[List[` [`RailType`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/options#nemoguardrails-rails-llm-options-RailType) `]]` — Optional list of rail types to run, e.g. `[RailType.INPUT]` or `[RailType.OUTPUT]`. When provided, overrides automatic detection. --- **`tools`** `Optional[List[dict]]` — default: None Not supported. Only a tool-call check reads tools, and only the IORails engine runs one. --- **Returns:** [`RailsResult`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/options#nemoguardrails-rails-llm-options-RailsResult) RailsResult containing: **Raises:** * `RailTypeNotSupportedError`: If `tools` is given, or a requested rail type is `tool_call` or `tool_result`, which only the IORails engine runs. * `RailTypeNotConfiguredError`: If a requested rail type has no configured flows. **Examples:** ```python Check user input (auto-detected):: result = await rails.check_async([{"role": "user", "content": "Hello!"}]) if result.status == RailStatus.BLOCKED: print(f"Blocked by: {result.rail}") Check bot output with context (auto-detected):: result = await rails.check_async([ {"role": "user", "content": "Hello!"}, {"role": "assistant", "content": "Hi there!"} ]) Run only input rails explicitly:: result = await rails.check_async(messages, rail_types=[RailType.INPUT]) ``` ```python nemoguardrails.LLMRails.explain() -> nemoguardrails.logging.explain.ExplainInfo ``` Helper function to return the latest ExplainInfo object. ```python nemoguardrails.LLMRails.generate( prompt: typing.Optional[str] = None, messages: typing.Optional[typing.List[dict]] = None, options: typing.Optional[typing.Union[dict, nemoguardrails.rails.llm.options.GenerationOptions]] = None, state: typing.Optional[dict] = None ) ``` Synchronous version of generate_async. ```python nemoguardrails.LLMRails.generate_async( prompt: typing.Optional[str] = None, messages: typing.Optional[typing.List[dict]] = None, options: typing.Optional[typing.Union[dict, nemoguardrails.rails.llm.options.GenerationOptions]] = None, state: typing.Optional[typing.Union[dict, nemoguardrails.colang.v2_x.runtime.flows.State]] = None, streaming_handler: typing.Optional[nemoguardrails.streaming.StreamingHandler] = None ) -> typing.Union[str, dict, nemoguardrails.rails.llm.options.GenerationResponse, typing.Tuple[dict, dict]] ``` async Generate a completion or a next message. The format for messages is the following: ```python [ {"role": "context", "content": {"user_name": "John"}}, {"role": "user", "content": "Hello! How are you?"}, {"role": "assistant", "content": "I am fine, thank you!"}, {"role": "event", "event": {"type": "UserSilent"}}, ... ] ``` System messages are not yet supported. **Parameters:** **`prompt`** `Optional[str]` — default: None The prompt to be used for completion. --- **`messages`** `Optional[List[dict]]` — default: None The history of messages to be used to generate the next message. --- **`options`** `Optional[Union[dict, GenerationOptions]]` — default: None `Optional[Union[dict,` [`GenerationOptions`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/options#nemoguardrails-rails-llm-options-GenerationOptions) `]]` — Options specific for the generation. --- **`state`** `Optional[Union[dict, State]]` — default: None The state object that should be used as the starting point. --- **`streaming_handler`** `Optional[StreamingHandler]` — default: None `Optional[` [`StreamingHandler`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/streaming#nemoguardrails-streaming-StreamingHandler) `]` — If specified, and the config supports streaming, the provided handler will be used for streaming. --- **Returns:** `Union[str, dict,` [`GenerationResponse`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/options#nemoguardrails-rails-llm-options-GenerationResponse) `, Tuple[dict, dict]]` The completion (when a prompt is provided) or the next message. ```python nemoguardrails.LLMRails.generate_events( events: typing.List[dict] ) -> typing.List[dict] ``` Synchronous version of `LLMRails.generate_events_async`. ```python nemoguardrails.LLMRails.generate_events_async( events: typing.List[dict] ) -> typing.List[dict] ``` async Generate the next events based on the provided history. The format for events is the following: ```python [ {"type": "...", ...}, ... ] ``` **Parameters:** **`events`** `List[dict]` The history of events to be used to generate the next events. --- **`options`** The options to be used for the generation. --- **Returns:** `List[dict]` The newly generate event(s). ```python nemoguardrails.LLMRails.process_events( events: typing.List[dict], state: typing.Union[typing.Optional[dict], nemoguardrails.colang.v2_x.runtime.flows.State] = None, blocking: bool = False ) -> typing.Tuple[typing.List[dict], typing.Union[dict, nemoguardrails.colang.v2_x.runtime.flows.State]] ``` Synchronous version of `LLMRails.process_events_async`. ```python nemoguardrails.LLMRails.process_events_async( events: typing.List[dict], state: typing.Union[typing.Optional[dict], nemoguardrails.colang.v2_x.runtime.flows.State] = None, blocking: bool = False ) -> typing.Tuple[typing.List[dict], typing.Union[dict, nemoguardrails.colang.v2_x.runtime.flows.State]] ``` async Process a sequence of events in a given state. The events will be processed one by one, in the input order. **Parameters:** **`events`** `List[dict]` A sequence of events that needs to be processed. --- **`state`** `Union[Optional[dict], State]` — default: None The state that should be used as the starting point. If not provided, a clean state will be used. --- **Returns:** `Tuple[List[dict], Union[dict, State]]` (output_events, output_state) Returns a sequence of output events and an output state. ```python nemoguardrails.LLMRails.register_action( action: typing.Callable, name: typing.Optional[str] = None ) -> typing_extensions.Self ``` Register a custom action for the rails configuration. ```python nemoguardrails.LLMRails.register_action_param( name: str, value: typing.Any ) -> typing_extensions.Self ``` Registers a custom action parameter. ```python nemoguardrails.LLMRails.register_embedding_provider( name: typing.Optional[str] = None ) -> typing_extensions.Self ``` Register a custom embedding provider. **Parameters:** **`model`** `Type[EmbeddingModel]` `Type[` [`EmbeddingModel`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/embeddings/providers/base#nemoguardrails-embeddings-providers-base-EmbeddingModel) `]` — The embedding model class. --- **`name`** `str` — default: None The name of the embedding engine. If available in the model, it will be used. --- **Raises:** * `ValueError`: If the engine name is not provided and the model does not have an engine name. * `ValueError`: If the model does not have 'encode' or 'encode_async' methods. ```python nemoguardrails.LLMRails.register_embedding_search_provider( name: str ) -> typing_extensions.Self ``` Register a new embedding search provider. **Parameters:** **`name`** `str` The name of the embedding search provider that will be used. --- **`cls`** `Type[EmbeddingsIndex]` `Type[` [`EmbeddingsIndex`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/embeddings/index#nemoguardrails-embeddings-index-EmbeddingsIndex) `]` — The class that will be used to generate and search embedding --- ```python nemoguardrails.LLMRails.register_filter( filter_fn: typing.Callable, name: typing.Optional[str] = None ) -> typing_extensions.Self ``` Register a custom filter for the rails configuration. ```python nemoguardrails.LLMRails.register_output_parser( output_parser: typing.Callable, name: str ) -> typing_extensions.Self ``` Register a custom output parser for the rails configuration. ```python nemoguardrails.LLMRails.register_prompt_context( name: str, value_or_fn: typing.Any ) -> typing_extensions.Self ``` Register a value to be included in the prompt context. :name: The name of the variable or function that will be used. :value_or_fn: The value or function that will be used to generate the value. ```python nemoguardrails.LLMRails.stream_async( prompt: typing.Optional[str] = None, messages: typing.Optional[typing.List[dict]] = None, options: typing.Optional[typing.Union[dict, nemoguardrails.rails.llm.options.GenerationOptions]] = None, state: typing.Optional[typing.Union[dict, nemoguardrails.colang.v2_x.runtime.flows.State]] = None, include_metadata: typing.Optional[bool] = False, generator: typing.Optional[typing.AsyncIterator[typing.Union[str, nemoguardrails.types.ToolCallChunk, nemoguardrails.types.ToolCallDeltaChunk]]] = None, include_generation_metadata: typing.Optional[bool] = None ) -> typing.AsyncIterator[typing.Union[str, dict, nemoguardrails.types.ToolCallChunk, nemoguardrails.types.ToolCallDeltaChunk]] ``` Simplified interface for getting directly the streamed tokens from the LLM. ```python nemoguardrails.LLMRails.update_llm( llm: nemoguardrails.types.LLMModel ) ``` Replace the main LLM with the provided one. **Parameters:** **`llm`** `LLMModel` [`LLMModel`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/types#nemoguardrails-types-LLMModel) — The new LLM that should be used. --- ```python class nemoguardrails.RailsConfig() ``` **Bases:** `BaseModel` Configuration object for the models and the rails. TODO: add typed config for user_messages, bot_messages, and flows. **`actions_server_url`** `Optional[str]` --- **`bot_messages`** `Dict[str, List[str]]` --- **`colang_version`** `str` --- **`config_path`** `Optional[str]` --- **`core`** `CoreConfig` --- **`custom_data`** `Dict` --- **`docs`** `Optional[List[Document]]` --- **`enable_multi_step_generation`** `Optional[bool]` --- **`enable_rails_exceptions`** `bool` --- **`event_source_uid`** `str` --- **`flows`** `List[Union[Dict, Any]]` --- **`hooks_server`** `HooksServerConfig` --- **`import_paths`** `Optional[List[str]]` --- **`imported_paths`** `Optional[Dict[str, str]]` --- **`instructions`** `Optional[List[Instruction]]` --- **`knowledge_base`** `KnowledgeBaseConfig` --- **`lowest_temperature`** `Optional[float]` --- **`metrics`** `MetricsConfig` --- **`models`** `List[Model]` --- **`passthrough`** `Optional[bool]` --- **`prompting_mode`** `Optional[str]` --- **`prompts`** `Optional[List[TaskPrompt]]` --- **`rails`** `Rails` --- **`raw_llm_call_action`** `Optional[str]` --- **`sample_conversation`** `Optional[str]` --- **`streaming`** `bool` --- **`tracing`** `TracingConfig` --- **`user_messages`** `Dict[str, List[str]]` --- ```python nemoguardrails.RailsConfig.__add__( other ) ``` Adds two RailsConfig objects. ```python nemoguardrails.RailsConfig.check_jailbreak_detection_config( values ) ``` classmethod Validate jailbreak detection configuration against enabled flows. ```python nemoguardrails.RailsConfig.check_model_exists_for_input_rails( values ) ``` classmethod Make sure we have a model for each input rail where one is provided using \$model=\ ```python nemoguardrails.RailsConfig.check_model_exists_for_output_rails( values ) ``` classmethod Make sure we have a model for each output rail where one is provided using \$model=\ ```python nemoguardrails.RailsConfig.check_model_exists_for_tool_rails() -> nemoguardrails.rails.llm.config.RailsConfig ``` Make sure we have every model a tool rail's manifest binds, such as the judge named by `$model=` ```python nemoguardrails.RailsConfig.check_output_parser_exists( values ) ``` classmethod ```python nemoguardrails.RailsConfig.check_prompt_exist_for_self_check_rails( values ) ``` classmethod ```python nemoguardrails.RailsConfig.check_streaming_can_apply_output_rewrites( values ) ``` classmethod Reject configs whose output rails transform response with `stream_first` == True ```python nemoguardrails.RailsConfig.fill_in_default_values_for_v2_x( values ) ``` classmethod ```python nemoguardrails.RailsConfig.from_content( colang_content: typing.Optional[str] = None, yaml_content: typing.Optional[str] = None, config: typing.Optional[dict] = None ) ``` classmethod Loads a configuration from the provided colang/YAML content/config dict. ```python nemoguardrails.RailsConfig.from_path( config_path: str ) ``` classmethod Loads a configuration from a given path. Supports loading a from a single file, or from a directory. ```python nemoguardrails.RailsConfig.parse_object( obj ) ``` classmethod Parses a configuration object from a given dictionary. ```python nemoguardrails.RailsConfig.validate_models_api_key_env_var( models ) ``` classmethod Model API Key Env var must be set to make LLM calls ```python nemoguardrails.RailsConfig.warn_unknown_keys( values: typing.Any, handler: pydantic.ModelWrapValidatorHandler[nemoguardrails.rails.llm.config.RailsConfig] ) -> nemoguardrails.rails.llm.config.RailsConfig ``` classmethod ## Docs - [nemoguardrails.rails.llm](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm.md) - [nemoguardrails.rails.llm.buffer](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/buffer.md) - [nemoguardrails.rails.llm.config](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/config.md) - [nemoguardrails.rails.llm.llmrails](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/llmrails.md) - [nemoguardrails.rails.llm.options](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/options.md) - [nemoguardrails.rails.llm.rails_config_fields](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/rails_config_fields.md) - [nemoguardrails.rails.llm.utils](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/rails/llm/utils.md)