fix(iorails): Add no-op events_history_cache when IORails is used (#2072)

Author: tgasser-nv

nemoguardrails/guardrails/guardrails.py

@@ -296,22 +296,24 @@ def update_llm(self, llm: LLMModel) -> None:
 
     @property
     def events_history_cache(self) -> dict:
-        """Per-session events history cache. Only supported for LLMRails.
+        """Per-session events history cache.
 
         Used by the server to persist conversation state across requests.
-        Stored by reference; assigning replaces the dict object, not its
-        contents.
+        For LLMRails this is stored by reference; assigning replaces the dict
+        object, not its contents.
+
+        IORails is stateless, return empty cache and drop cache-store writes
         """
         if isinstance(self.rails_engine, IORails):
-            raise NotImplementedError("IORails doesn't support events_history_cache attribute access")
+            return {}
 
         llmrails = cast(LLMRails, self.rails_engine)
         return llmrails.events_history_cache
 
     @events_history_cache.setter
     def events_history_cache(self, value: dict) -> None:
         if isinstance(self.rails_engine, IORails):
-            raise NotImplementedError("IORails doesn't support events_history_cache attribute access")
+            return
 
         llmrails = cast(LLMRails, self.rails_engine)
         llmrails.events_history_cache = value

nemoguardrails/guardrails/iorails.py

@@ -241,6 +241,9 @@ def unsupported_reason(cls, config: RailsConfig, llm: Optional[LLMModel] = None)
         if llm is not None:
             return "an `llm` argument was provided; IORails does not accept a custom LLM"
 
+        if config.colang_version != "1.0":
+            return f"IORails supports Colang 1.0 only; config uses Colang {config.colang_version}"
+
         unsupported_rails = sorted(config.rails.model_fields_set - cls.SUPPORTED_RAILS)
         if unsupported_rails:
             return f"config has rails outside the IORails-supported set: {unsupported_rails}"

tests/guardrails/test_guardrails.py

@@ -348,6 +348,19 @@ def test_llm_takes_precedence_over_config_issues(self):
         reason = IORails.unsupported_reason(config, llm=MagicMock())
         assert reason == "an `llm` argument was provided; IORails does not accept a custom LLM"
 
+    def test_colang_2x_config_is_unsupported(self):
+        """A Colang 2.x config is rejected: IORails has no Colang runtime, so 2.x falls back to LLMRails."""
+        config = RailsConfig.from_content(config={"colang_version": "2.x"})
+        reason = IORails.unsupported_reason(config, llm=None)
+        assert reason == "IORails supports Colang 1.0 only; config uses Colang 2.x"
+        assert IORails.can_handle(config, llm=None) is False
+
+    def test_llm_takes_precedence_over_colang_version(self):
+        """When both an llm is provided and the config is Colang 2.x, the llm reason is reported first."""
+        config = RailsConfig.from_content(config={"colang_version": "2.x"})
+        reason = IORails.unsupported_reason(config, llm=MagicMock())
+        assert reason == "an `llm` argument was provided; IORails does not accept a custom LLM"
+
     def test_can_handle_matches_reason_none(self, _content_safety_rails_config):
         """``can_handle`` is a thin wrapper that returns True iff reason is None."""
         assert IORails.can_handle(_content_safety_rails_config, llm=None) is True

tests/guardrails/test_public_api_deprecations.py

@@ -22,8 +22,10 @@
   default_embedding_{model,engine,params}, llm_generation_actions).
 * Deprecated read/write alias on LLMRails for explain_info.
 * First-class passthrough_fn property/setter on LLMRails (no warning).
-* Guardrails-facade proxies for explain_info (deprecated), passthrough_fn,
-  and events_history_cache — including the IORails-engine raise paths.
+* Guardrails-facade proxies for explain_info (deprecated) and passthrough_fn,
+  including the IORails-engine raise paths.
+* Guardrails-facade proxy for events_history_cache: delegates under LLMRails,
+  inert under IORails (reads return {}, writes are dropped).
 """
 
 from unittest.mock import MagicMock, patch
@@ -224,7 +226,7 @@ def test_write_raises_under_iorails(self, iorails_guardrails):
 
 
 class TestGuardrailsFacadeEventsHistoryCache:
-    """Facade proxy for events_history_cache: plain getter+setter under LLMRails, raises under IORails."""
+    """Facade proxy for events_history_cache: plain getter+setter under LLMRails, inert under IORails."""
 
     def test_read_delegates_to_llmrails(self, llmrails_guardrails):
         """Reading guardrails.events_history_cache returns the wrapped LLMRails's plain attribute."""
@@ -239,12 +241,15 @@ def test_write_delegates_to_llmrails(self, llmrails_guardrails):
         llmrails_guardrails.events_history_cache = sentinel
         assert llmrails_guardrails.rails_engine.events_history_cache is sentinel
 
-    def test_read_raises_under_iorails(self, iorails_guardrails):
-        """Reading guardrails.events_history_cache on an IORails-backed facade raises NotImplementedError."""
-        with pytest.raises(NotImplementedError, match=r"IORails doesn't support events_history_cache"):
-            _ = iorails_guardrails.events_history_cache
+    def test_read_returns_empty_dict_under_iorails(self, iorails_guardrails):
+        """Reading guardrails.events_history_cache on an IORails-backed facade returns an empty dict."""
+        assert iorails_guardrails.events_history_cache == {}
 
-    def test_write_raises_under_iorails(self, iorails_guardrails):
-        """Writing guardrails.events_history_cache on an IORails-backed facade raises NotImplementedError."""
-        with pytest.raises(NotImplementedError, match=r"IORails doesn't support events_history_cache"):
-            iorails_guardrails.events_history_cache = {}
+    def test_write_is_dropped_under_iorails(self, iorails_guardrails):
+        """Writing guardrails.events_history_cache on an IORails-backed facade is silently dropped.
+
+        IORails is stateless, so a write followed by a read still yields {} —
+        the value is never stored and never consulted during generation.
+        """
+        iorails_guardrails.events_history_cache = {"b": 2}
+        assert iorails_guardrails.events_history_cache == {}

tests/server/test_iorails_engine_compat.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Server compatibility when NEMO_GUARDRAILS_IORAILS_ENGINE aliases LLMRails to Guardrails.
+
+Under that env var, ``nemoguardrails.server.api`` builds a ``Guardrails`` wrapper that
+selects the stateless IORails engine for IORails-compatible configs. These tests
+reproduce the reported 500: ``_get_rails`` assigns ``events_history_cache``, which used
+to raise ``NotImplementedError`` on an IORails-backed wrapper. The alias is simulated by
+patching ``api.LLMRails`` to ``Guardrails`` and ``RailsConfig.from_path`` to return an
+IORails-compatible content-safety config, so the test does not depend on the global
+import-time env var.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+
+from nemoguardrails import Guardrails, RailsConfig
+from nemoguardrails.guardrails.iorails import IORails
+from nemoguardrails.server import api
+from tests.guardrails.test_data import CONTENT_SAFETY_CONFIG
+
+
+@pytest.fixture
+def iorails_compatible_config():
+    """An IORails-compatible Colang 1.0 content-safety config loaded once for the test."""
+    return RailsConfig.from_content(config=CONTENT_SAFETY_CONFIG)
+
+
+@pytest.fixture(autouse=True)
+def reset_server_state():
+    """Clear the per-config rails caches and force multi-config mode around each test."""
+    original_single_config_mode = api.app.single_config_mode
+    api.app.single_config_mode = False
+    api.llm_rails_instances.clear()
+    api.llm_rails_events_history_cache.clear()
+    yield
+    api.llm_rails_instances.clear()
+    api.llm_rails_events_history_cache.clear()
+    api.app.single_config_mode = original_single_config_mode
+
+
+@pytest.fixture
+def iorails_alias(monkeypatch, iorails_compatible_config):
+    """Simulate NEMO_GUARDRAILS_IORAILS_ENGINE: alias LLMRails->Guardrails and serve the IORails config."""
+    monkeypatch.setattr(api, "LLMRails", Guardrails)
+    monkeypatch.setattr(api.RailsConfig, "from_path", staticmethod(lambda full_path: iorails_compatible_config))
+    yield
+
+
+@pytest.mark.asyncio
+async def test_get_rails_does_not_raise_under_iorails_alias(iorails_alias):
+    """_get_rails returns an IORails-backed Guardrails with an inert events_history_cache instead of raising.
+
+    This is the exact crash site from the report: the events_history_cache assignment at
+    the end of _get_rails. Under IORails it must round-trip inertly (read -> {}) rather
+    than raise NotImplementedError.
+    """
+    rails = await api._get_rails(["content_safety"])
+
+    assert isinstance(rails, Guardrails)
+    assert isinstance(rails.rails_engine, IORails)
+    assert rails.events_history_cache == {}
+
+
+def test_chat_completion_returns_200_under_iorails_alias(iorails_alias, monkeypatch):
+    """POST /v1/chat/completions returns 200 when the server runs on the IORails engine.
+
+    Generation is stubbed at the IORails boundary (start + generate_async) so the test
+    exercises the server plumbing and the _get_rails cache assignment without any network
+    or provider credentials; the response shape is asserted to be OpenAI-compatible.
+    """
+
+    async def _fake_start(self):
+        self._running = True
+
+    async def _fake_generate_async(self, messages, **kwargs):
+        return {"role": "assistant", "content": "hello from iorails"}
+
+    monkeypatch.setattr(IORails, "start", _fake_start)
+    monkeypatch.setattr(IORails, "generate_async", _fake_generate_async)
+
+    client = TestClient(api.app, raise_server_exceptions=False)
+    response = client.post(
+        "/v1/chat/completions",
+        json={
+            "model": "test-model",
+            "messages": [{"role": "user", "content": "Hello"}],
+            "guardrails": {"config_id": "content_safety"},
+        },
+    )
+
+    assert response.status_code == 200
+    res = response.json()
+    assert res["object"] == "chat.completion"
+    assert res["choices"][0]["message"]["role"] == "assistant"
+    assert res["choices"][0]["message"]["content"] == "hello from iorails"