feat(iorails)!: Support non-streaming GenerationResponse

nemoguardrails/base_guardrails.py

@@ -27,9 +27,10 @@
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, AsyncIterator
+from typing import Any, AsyncIterator, Optional, Union
 
 from nemoguardrails.rails.llm.config import RailsConfig
+from nemoguardrails.rails.llm.options import GenerationOptions
 
 
 class BaseGuardrails(ABC):
@@ -44,12 +45,14 @@ class BaseGuardrails(ABC):
     config: RailsConfig
 
     @abstractmethod
-    def generate(self, *args: Any, **kwargs: Any) -> Any:
+    def generate(self, *args: Any, options: Optional[Union[dict, GenerationOptions]] = None, **kwargs: Any) -> Any:
         """Generate an LLM response synchronously with guardrails applied."""
         ...
 
     @abstractmethod
-    async def generate_async(self, *args: Any, **kwargs: Any) -> Any:
+    async def generate_async(
+        self, *args: Any, options: Optional[Union[dict, GenerationOptions]] = None, **kwargs: Any
+    ) -> Any:
         """Generate an LLM response asynchronously with guardrails applied."""
         ...
 

nemoguardrails/guardrails/actions/content_safety_action.py

@@ -121,10 +121,13 @@ def _content_safety_to_rail_result(parsed: object) -> RailResult:
     """
     if isinstance(parsed, (list, tuple)):
         if parsed and parsed[0] is True:
-            return RailResult(is_safe=True)
+            return RailResult(is_safe=True, return_value={"allowed": True, "policy_violations": []})
         if parsed and parsed[0] is False:
-            if len(parsed) > 1:
-                categories = ", ".join(str(c) for c in parsed[1:])
-                return RailResult(is_safe=False, reason=f"Safety categories: {categories}")
-            return RailResult(is_safe=False, reason="Unknown")
+            violations = [str(c) for c in parsed[1:]]
+            verdict = {"allowed": False, "policy_violations": violations}
+            if violations:
+                return RailResult(
+                    is_safe=False, reason=f"Safety categories: {', '.join(violations)}", return_value=verdict
+                )
+            return RailResult(is_safe=False, reason="Unknown", return_value=verdict)
     raise RuntimeError(f"Unexpected content safety parse result: {parsed}")

nemoguardrails/guardrails/actions/jailbreak_detection_action.py

@@ -41,6 +41,7 @@ def _parse_response(self, response: Any) -> RailResult:
             raise RuntimeError(f"Jailbreak response missing 'jailbreak' field: {response}")
 
         score = response.get("score", "unknown")
-        if response["jailbreak"]:
-            return RailResult(is_safe=False, reason=f"Score: {score}")
-        return RailResult(is_safe=True, reason=f"Score: {score}")
+        is_jailbreak = response["jailbreak"]
+        if is_jailbreak:
+            return RailResult(is_safe=False, reason=f"Score: {score}", return_value=is_jailbreak)
+        return RailResult(is_safe=True, reason=f"Score: {score}", return_value=is_jailbreak)

nemoguardrails/guardrails/actions/topic_safety_action.py

@@ -63,5 +63,5 @@ async def _get_response(self, model_type: Optional[str], prompt: Any) -> str:
 
     def _parse_response(self, response: Any) -> RailResult:
         if response.lower().strip() == "off-topic":
-            return RailResult(is_safe=False, reason="Topic safety: off-topic")
-        return RailResult(is_safe=True)
+            return RailResult(is_safe=False, reason="Topic safety: off-topic", return_value={"on_topic": False})
+        return RailResult(is_safe=True, return_value={"on_topic": True})

nemoguardrails/guardrails/engine_registry.py

@@ -172,6 +172,10 @@ def _get_engine(self, name: str, expected_type: type[_EngineT]) -> _EngineT:
             raise TypeError(f"Engine '{name}' is {type(engine).__name__}, expected {expected_type.__name__}")
         return engine
 
+    def provider_name(self, model_type: str) -> str:
+        """Return the provider/engine name (e.g. 'nim', 'openai') for a model engine."""
+        return self._get_engine(model_type, ModelEngine).model_config.engine or "unknown"
+
     async def model_call(self, model_type: str, messages: list[dict], **kwargs: Any) -> LLMResponse:
         """Route a chat completion request to the named model engine.
 

nemoguardrails/guardrails/guardrails.py

@@ -38,7 +38,7 @@
 from nemoguardrails.logging.explain import ExplainInfo
 from nemoguardrails.rails.llm.config import RailsConfig
 from nemoguardrails.rails.llm.llmrails import LLMRails
-from nemoguardrails.rails.llm.options import GenerationResponse, RailsResult, RailType
+from nemoguardrails.rails.llm.options import GenerationOptions, GenerationResponse, RailsResult, RailType
 from nemoguardrails.types import LLMModel
 
 log = logging.getLogger(__name__)
@@ -205,43 +205,69 @@ async def _ensure_started(self) -> None:
             await self.startup()
 
     def generate(
-        self, prompt: str | None = None, messages: LLMMessages | None = None, **kwargs
+        self,
+        prompt: str | None = None,
+        messages: LLMMessages | None = None,
+        options: Optional[Union[dict, GenerationOptions]] = None,
+        **kwargs,
     ) -> Union[str, dict, GenerationResponse, Tuple[dict, dict]]:
         """Generate an LLM response synchronously with guardrails applied.
         Supported in both IORails and LLMRails
         """
 
         generate_messages = self._convert_to_messages(prompt, messages)
-        return self.rails_engine.generate(messages=generate_messages, **kwargs)
+        return self.rails_engine.generate(messages=generate_messages, options=options, **kwargs)
 
     @overload
-    async def generate_async(self, prompt: str | None = None, messages: LLMMessages | None = None, **kwargs) -> str: ...
+    async def generate_async(
+        self,
+        prompt: str | None = None,
+        messages: LLMMessages | None = None,
+        options: Optional[Union[dict, GenerationOptions]] = None,
+        **kwargs,
+    ) -> str: ...
 
     @overload
     async def generate_async(
-        self, prompt: str | None = None, messages: LLMMessages | None = None, **kwargs
+        self,
+        prompt: str | None = None,
+        messages: LLMMessages | None = None,
+        options: Optional[Union[dict, GenerationOptions]] = None,
+        **kwargs,
     ) -> dict: ...
 
     @overload
     async def generate_async(
-        self, prompt: str | None = None, messages: LLMMessages | None = None, **kwargs
+        self,
+        prompt: str | None = None,
+        messages: LLMMessages | None = None,
+        options: Optional[Union[dict, GenerationOptions]] = None,
+        **kwargs,
     ) -> GenerationResponse: ...
 
     @overload
     async def generate_async(
-        self, prompt: str | None = None, messages: LLMMessages | None = None, **kwargs
+        self,
+        prompt: str | None = None,
+        messages: LLMMessages | None = None,
+        options: Optional[Union[dict, GenerationOptions]] = None,
+        **kwargs,
     ) -> tuple[dict, dict]: ...
 
     async def generate_async(
-        self, prompt: str | None = None, messages: LLMMessages | None = None, **kwargs
+        self,
+        prompt: str | None = None,
+        messages: LLMMessages | None = None,
+        options: Optional[Union[dict, GenerationOptions]] = None,
+        **kwargs,
     ) -> str | dict | GenerationResponse | tuple[dict, dict]:
         """Generate an LLM response asynchronously with guardrails applied.
         Supported by both LLMRails and IORails
         """
         await self._ensure_started()
 
         generate_messages = self._convert_to_messages(prompt, messages)
-        return await self.rails_engine.generate_async(messages=generate_messages, **kwargs)
+        return await self.rails_engine.generate_async(messages=generate_messages, options=options, **kwargs)
 
     def stream_async(
         self, prompt: str | None = None, messages: LLMMessages | None = None, **kwargs

nemoguardrails/guardrails/guardrails_types.py

@@ -16,9 +16,11 @@
 
 import secrets
 from contextvars import ContextVar, Token
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, TypeAlias
+from typing import Any, Optional, TypeAlias
+
+from nemoguardrails.types import UsageInfo
 
 # LLMMessage can contain role/content, plus optional tool_calls / tool_call_id / name; content may be None
 LLMMessage: TypeAlias = dict[str, Any]
@@ -32,13 +34,56 @@ class RailDirection(Enum):
     OUTPUT = "Output"
 
 
+@dataclass(frozen=True, slots=True)
+class RailCallRecord:
+    """One rail's execution record, carried on RailResult for GenerationLog synthesis.
+
+    Captures what a single rail did — its verdict and the (at most one) model call it
+    made — as engine-neutral data. IORails maps a ``RailCallRecord`` to an
+    ``ActivatedRail`` (with a single synthetic ``ExecutedAction`` and ``LLMCallInfo``);
+    the raw ``usage``/timing is kept here so this module stays free of the pydantic
+    ``GenerationLog`` types. Tool rails that make no model call leave ``usage`` None.
+    """
+
+    flow: str
+    rail_type: str
+    is_safe: bool
+    made_call: bool = False
+    action_name: Optional[str] = None
+    return_value: Any = None
+    task: Optional[str] = None
+    request_id: Optional[str] = None
+    usage: Optional[UsageInfo] = None
+    llm_model_name: Optional[str] = None
+    llm_provider_name: Optional[str] = None
+    prompt: Optional[str] = None
+    completion: Optional[str] = None
+    started_at: Optional[float] = None
+    finished_at: Optional[float] = None
+    duration: Optional[float] = None
+
+
 @dataclass(frozen=True, slots=True)
 class RailResult:
-    """Result of a rail safety check."""
+    """Result of a rail safety check.
+
+    ``records`` carries the per-rail execution records for every rail that ran in this
+    check (not just the blocking one), so IORails can synthesize a ``GenerationLog``.
+    It is empty unless log collection is active. ``return_value`` is the rail's
+    structured verdict (e.g. ``{"allowed": ..., "policy_violations": [...]}``) when the
+    action supplies one, used as the log's ``ExecutedAction.return_value``.
+
+    ``records`` and ``return_value`` are log-capture metadata, not part of the safety
+    verdict, so they are excluded from equality and hashing (``compare=False``) — two
+    results with the same ``is_safe``/``reason``/``triggered_rail`` compare equal
+    regardless of captured log data.
+    """
 
     is_safe: bool
     reason: str | None = None
     triggered_rail: str | None = None
+    records: tuple[RailCallRecord, ...] = field(default=(), compare=False)
+    return_value: Any = field(default=None, compare=False)
 
 
 # Default max character length for truncate(). Used to keep DEBUG log lines short.
@@ -84,3 +129,13 @@ def truncate(text: object, max_len: int | None = None) -> str:
     if len(s) <= limit:
         return s
     return s[:limit] + "..."
+
+
+def serialize_prompt(messages: list[dict]) -> str:
+    """Render a chat message list to a role-labeled string for GenerationLog's ``prompt``.
+
+    Content parity with LLMRails' logged prompt, not byte-for-byte format parity: each
+    message becomes ``"<role>: <content>"`` and messages are blank-line separated. A
+    message with no content (e.g. a reasoning-only or tool-call turn) renders as empty.
+    """
+    return "\n\n".join(f"{m.get('role', '')}: {m.get('content') or ''}" for m in messages)