railtracks.guardrails.llm.llm_guard
1import inspect 2from abc import abstractmethod 3from typing import Any, Awaitable, Generic, TypeVar, cast 4 5from pydantic import BaseModel 6from typing_extensions import Literal 7 8from railtracks.context.central import get_parent_id, get_run_id, is_context_present 9from railtracks.guardrails.core.decision import GuardrailAction, GuardrailDecision 10from railtracks.guardrails.core.errors import GuardrailBlockedError 11from railtracks.guardrails.core.event import LLMGuardrailEvent, LLMGuardrailPhase 12from railtracks.guardrails.core.interfaces import BaseGuardrail 13from railtracks.guardrails.core.trace import GuardrailTrace 14from railtracks.llm.history import MessageHistory 15from railtracks.llm.message import Message, UserMessage 16from railtracks.llm.middleware import ModelOnlyMiddleware 17from railtracks.llm.response import Response 18from railtracks.llm.tools.tool import Tool 19from railtracks.utils.logging.create import get_rt_logger 20from railtracks.utils.unpack import unpack_async_sync 21 22logger = get_rt_logger("guardrails") 23 24_TValue = TypeVar("_TValue", bound=MessageHistory | Message) 25 26 27class BaseLLMGuardrail( 28 BaseGuardrail[ 29 [MessageHistory, type[BaseModel] | None, list[Tool] | None], Response 30 ], 31 ModelOnlyMiddleware, 32 Generic[_TValue], 33): 34 """Abstract base class for guardrails that run on LLM input or output. 35 36 Attributes: 37 phase: Whether this rail expects :class:`LLMGuardrailPhase` ``INPUT`` or 38 ``OUTPUT`` events. 39 """ 40 41 phase: LLMGuardrailPhase 42 43 def __init__(self, name: str | None = None, fail_open: bool = False): 44 """Initialize the guardrail. 45 46 Args: 47 name: Rail name for traces and debugging; defaults to the class name. 48 fail_open: Whether to allow the request to continue when this guard raises an unexpected exception. 49 """ 50 super().__init__(name=name) 51 self.fail_open = fail_open 52 53 @abstractmethod 54 def __call__( 55 self, event: LLMGuardrailEvent 56 ) -> GuardrailDecision | Awaitable[GuardrailDecision]: 57 """Evaluate the event and return a decision. Implemented by each concrete guard. 58 59 May be sync or async. An ``async def`` implementation is awaited before its 60 decision is dispatched, so a guard is free to ``await rt.call(...)`` and 61 delegate the judgement to another agent. 62 """ 63 pass 64 65 @abstractmethod 66 def convert( 67 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 68 ) -> LLMGuardrailEvent: 69 """Build an event from a raw value. Implemented per phase by InputGuard and OutputGuard.""" 70 pass 71 72 def decide( 73 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 74 ) -> GuardrailDecision: 75 """Convert value to an event and run this guard on it directly, outside a chain. 76 77 Synchronous guards only. An ``async def`` guard would return an un-awaited 78 coroutine here, so use :meth:`adecide` for those. 79 """ 80 if self._is_async(): 81 raise TypeError( 82 f"Guardrail {self._rail_name()} is async; " 83 f"use `await {type(self).__name__}.adecide(...)` instead of `.decide(...)`." 84 ) 85 converted_event = self.convert(value) 86 87 return cast(GuardrailDecision, self(converted_event)) 88 89 async def adecide( 90 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 91 ) -> GuardrailDecision: 92 """Async counterpart to :meth:`decide`; accepts sync and async guards alike.""" 93 converted_event = self.convert(value) 94 95 return await unpack_async_sync(self(converted_event)) 96 97 def _is_async(self) -> bool: 98 """Whether this guard's ``__call__`` is a coroutine function.""" 99 return inspect.iscoroutinefunction(type(self).__call__) 100 101 @staticmethod 102 def _coerce_to_message_history( 103 input: str | Any | MessageHistory, 104 ) -> MessageHistory: 105 """Convert str, Message, or MessageHistory to a MessageHistory.""" 106 if isinstance(input, MessageHistory): 107 return input 108 if isinstance(input, str): 109 return MessageHistory([UserMessage(input)]) 110 if isinstance(input, Message): 111 return MessageHistory([input]) 112 raise TypeError( 113 f"Expected str, Message, or MessageHistory got {type(input).__name__}" 114 ) 115 116 @staticmethod 117 def _node_metadata() -> tuple[str | None, str | None]: 118 """``(node_uuid, run_id)`` for event observability. 119 120 Returns ``(None, None)`` when no run context is active — the gate logic never 121 depends on this metadata, so it must not raise just to populate it. 122 """ 123 if not is_context_present(): 124 return None, None 125 return get_parent_id(), get_run_id() 126 127 @staticmethod 128 def _raise_if_blocked( 129 decision: GuardrailDecision | None, traces: list[GuardrailTrace] 130 ) -> None: 131 """Raise :class:`GuardrailBlockedError` when a rail returned ``BLOCK``.""" 132 if decision is not None and decision.action == GuardrailAction.BLOCK: 133 rail_name = traces[-1].rail_name if traces else None 134 raise GuardrailBlockedError( 135 rail_name=rail_name, 136 reason=decision.reason, 137 user_facing_message=decision.user_facing_message, 138 traces=traces, 139 meta=decision.meta, 140 ) 141 142 def _handle_rail_exception( 143 self, 144 *, 145 exc: Exception, 146 traces: list[GuardrailTrace], 147 value: _TValue, 148 reason_prefix: str, 149 ) -> ( 150 tuple[Literal["continue"], _TValue] 151 | tuple[Literal["stop"], _TValue, GuardrailDecision] 152 ): 153 """Record exc as a trace and return a stop outcome with a blocking decision.""" 154 traces.append(self._trace_for_exception(exc=exc)) 155 156 if self.fail_open: 157 return ("continue", value) 158 159 block = GuardrailDecision.block( 160 reason=f"{reason_prefix}: {self._rail_name()}", 161 user_facing_message="Request blocked by guardrails.", 162 meta={ 163 "exception_type": exc.__class__.__name__, 164 "exception_message": str(exc), 165 }, 166 ) 167 return ("stop", value, block) 168 169 async def run( 170 self, 171 *, 172 event: LLMGuardrailEvent, 173 value: _TValue, 174 ) -> tuple[_TValue, list[GuardrailTrace], GuardrailDecision]: 175 """Run this guard once on event and value. 176 177 Returns the resulting value, the traces recorded, and the decision that 178 applies. A BLOCK (or a failed TRANSFORM) surfaces its own decision as-is. 179 A successful TRANSFORM also surfaces its own decision (its `reason`/`meta` 180 describe what changed, e.g. a PII redaction count -- callers like 181 `MiddlewareGuardInputResponseEvent` depend on that). A plain ALLOW, or an 182 exception swallowed via `fail_open=True`, has nothing rail-specific worth 183 keeping, so a generic `GuardrailDecision.allow()` is returned instead. 184 """ 185 traces: list[GuardrailTrace] = [] 186 187 step = await self._eval_one_rail( 188 event=event, 189 value=value, 190 traces=traces, 191 ) 192 193 if step[0] == "stop": 194 return step[1], traces, step[2] 195 196 _, value, event, decision = step 197 198 return ( 199 value, 200 traces, 201 decision if decision is not None else GuardrailDecision.allow(), 202 ) 203 204 async def _eval_one_rail( 205 self, 206 event: LLMGuardrailEvent, 207 value: _TValue, 208 traces: list[GuardrailTrace], 209 ) -> ( 210 tuple[Literal["continue"], _TValue, LLMGuardrailEvent, GuardrailDecision | None] 211 | tuple[Literal["stop"], _TValue, GuardrailDecision] 212 ): 213 """Call this guard, await it if async, validate the decision, and dispatch it.""" 214 try: 215 decision = await unpack_async_sync(self(event)) 216 if not isinstance(decision, GuardrailDecision): 217 raise TypeError( 218 f"Guardrail {self._rail_name()} returned {type(decision).__name__}, expected GuardrailDecision." 219 ) 220 except Exception as e: 221 outcome = self._handle_rail_exception( 222 exc=e, 223 traces=traces, 224 value=value, 225 reason_prefix="Guardrail raised exception", 226 ) 227 if outcome[0] == "continue": 228 return ("continue", value, event, None) 229 return ("stop", outcome[1], outcome[2]) 230 231 traces.append(self._trace_from_decision(decision=decision)) 232 233 if decision.action == GuardrailAction.ALLOW: 234 return ("continue", value, event, None) 235 236 return self._dispatch_non_allow_decision( 237 event=event, 238 value=value, 239 decision=decision, 240 traces=traces, 241 ) 242 243 def _dispatch_non_allow_decision( 244 self, 245 *, 246 event: LLMGuardrailEvent, 247 value: _TValue, 248 decision: GuardrailDecision, 249 traces: list[GuardrailTrace], 250 ) -> ( 251 tuple[Literal["continue"], _TValue, LLMGuardrailEvent, GuardrailDecision | None] 252 | tuple[Literal["stop"], _TValue, GuardrailDecision] 253 ): 254 """Apply a TRANSFORM, BLOCK, or unknown-action decision returned by this guard.""" 255 if decision.action == GuardrailAction.TRANSFORM: 256 try: 257 value = self._extract_transform_value(decision) 258 event = self._sync_event_after_transform(event, value) 259 except Exception as e: 260 outcome = self._handle_rail_exception( 261 exc=e, 262 traces=traces, 263 value=value, 264 reason_prefix="Guardrail transform failed", 265 ) 266 if outcome[0] == "continue": 267 return ("continue", value, event, None) 268 return ("stop", outcome[1], outcome[2]) 269 # Success: unlike a plain ALLOW, the caller needs this decision's own 270 # reason/meta (e.g. a PII redaction count) -- preserve it as-is. 271 return ("continue", value, event, decision) 272 273 if decision.action == GuardrailAction.BLOCK: 274 return ("stop", value, decision) 275 276 traces.append( 277 GuardrailTrace( 278 rail_name=self._rail_name(), 279 phase=self.phase.value, 280 action="error", 281 reason="Unknown guardrail action", 282 meta={"action": str(decision.action)}, 283 ) 284 ) 285 286 if self.fail_open: 287 return ("continue", value, event, None) 288 289 block = GuardrailDecision.block( 290 reason=f"Unknown guardrail action from {self._rail_name()}", 291 user_facing_message="Request blocked by guardrails.", 292 ) 293 return ("stop", value, block) 294 295 @abstractmethod 296 def _sync_event_after_transform( 297 self, 298 event: LLMGuardrailEvent, 299 value: _TValue, 300 ) -> LLMGuardrailEvent: 301 """Return a copy of event updated with the transformed value. Implemented per phase.""" 302 pass 303 304 @abstractmethod 305 def _extract_transform_value(self, decision: GuardrailDecision) -> _TValue: 306 """Extract the replacement value from a TRANSFORM decision. Implemented per phase.""" 307 pass 308 309 def _rail_name(self) -> str: 310 """Return this guard's name, falling back to its class name if unset.""" 311 name = self.name 312 if isinstance(name, str) and name.strip(): 313 return name 314 315 return self.__class__.__name__ 316 317 def _trace_from_decision( 318 self, 319 decision: GuardrailDecision, 320 ) -> GuardrailTrace: 321 """Build a trace recording this guard's decision.""" 322 return GuardrailTrace( 323 rail_name=self._rail_name(), 324 phase=self.phase.value, 325 action=decision.action.value, 326 reason=decision.reason, 327 meta=decision.meta, 328 ) 329 330 def _trace_for_exception( 331 self, 332 *, 333 exc: Exception, 334 ) -> GuardrailTrace: 335 """Build a trace recording an exception raised by this guard.""" 336 return GuardrailTrace( 337 rail_name=self._rail_name(), 338 phase=self.phase.value, 339 action="error", 340 reason="Guardrail raised exception", 341 meta={ 342 "exception_type": exc.__class__.__name__, 343 "exception_message": str(exc), 344 }, 345 )
28class BaseLLMGuardrail( 29 BaseGuardrail[ 30 [MessageHistory, type[BaseModel] | None, list[Tool] | None], Response 31 ], 32 ModelOnlyMiddleware, 33 Generic[_TValue], 34): 35 """Abstract base class for guardrails that run on LLM input or output. 36 37 Attributes: 38 phase: Whether this rail expects :class:`LLMGuardrailPhase` ``INPUT`` or 39 ``OUTPUT`` events. 40 """ 41 42 phase: LLMGuardrailPhase 43 44 def __init__(self, name: str | None = None, fail_open: bool = False): 45 """Initialize the guardrail. 46 47 Args: 48 name: Rail name for traces and debugging; defaults to the class name. 49 fail_open: Whether to allow the request to continue when this guard raises an unexpected exception. 50 """ 51 super().__init__(name=name) 52 self.fail_open = fail_open 53 54 @abstractmethod 55 def __call__( 56 self, event: LLMGuardrailEvent 57 ) -> GuardrailDecision | Awaitable[GuardrailDecision]: 58 """Evaluate the event and return a decision. Implemented by each concrete guard. 59 60 May be sync or async. An ``async def`` implementation is awaited before its 61 decision is dispatched, so a guard is free to ``await rt.call(...)`` and 62 delegate the judgement to another agent. 63 """ 64 pass 65 66 @abstractmethod 67 def convert( 68 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 69 ) -> LLMGuardrailEvent: 70 """Build an event from a raw value. Implemented per phase by InputGuard and OutputGuard.""" 71 pass 72 73 def decide( 74 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 75 ) -> GuardrailDecision: 76 """Convert value to an event and run this guard on it directly, outside a chain. 77 78 Synchronous guards only. An ``async def`` guard would return an un-awaited 79 coroutine here, so use :meth:`adecide` for those. 80 """ 81 if self._is_async(): 82 raise TypeError( 83 f"Guardrail {self._rail_name()} is async; " 84 f"use `await {type(self).__name__}.adecide(...)` instead of `.decide(...)`." 85 ) 86 converted_event = self.convert(value) 87 88 return cast(GuardrailDecision, self(converted_event)) 89 90 async def adecide( 91 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 92 ) -> GuardrailDecision: 93 """Async counterpart to :meth:`decide`; accepts sync and async guards alike.""" 94 converted_event = self.convert(value) 95 96 return await unpack_async_sync(self(converted_event)) 97 98 def _is_async(self) -> bool: 99 """Whether this guard's ``__call__`` is a coroutine function.""" 100 return inspect.iscoroutinefunction(type(self).__call__) 101 102 @staticmethod 103 def _coerce_to_message_history( 104 input: str | Any | MessageHistory, 105 ) -> MessageHistory: 106 """Convert str, Message, or MessageHistory to a MessageHistory.""" 107 if isinstance(input, MessageHistory): 108 return input 109 if isinstance(input, str): 110 return MessageHistory([UserMessage(input)]) 111 if isinstance(input, Message): 112 return MessageHistory([input]) 113 raise TypeError( 114 f"Expected str, Message, or MessageHistory got {type(input).__name__}" 115 ) 116 117 @staticmethod 118 def _node_metadata() -> tuple[str | None, str | None]: 119 """``(node_uuid, run_id)`` for event observability. 120 121 Returns ``(None, None)`` when no run context is active — the gate logic never 122 depends on this metadata, so it must not raise just to populate it. 123 """ 124 if not is_context_present(): 125 return None, None 126 return get_parent_id(), get_run_id() 127 128 @staticmethod 129 def _raise_if_blocked( 130 decision: GuardrailDecision | None, traces: list[GuardrailTrace] 131 ) -> None: 132 """Raise :class:`GuardrailBlockedError` when a rail returned ``BLOCK``.""" 133 if decision is not None and decision.action == GuardrailAction.BLOCK: 134 rail_name = traces[-1].rail_name if traces else None 135 raise GuardrailBlockedError( 136 rail_name=rail_name, 137 reason=decision.reason, 138 user_facing_message=decision.user_facing_message, 139 traces=traces, 140 meta=decision.meta, 141 ) 142 143 def _handle_rail_exception( 144 self, 145 *, 146 exc: Exception, 147 traces: list[GuardrailTrace], 148 value: _TValue, 149 reason_prefix: str, 150 ) -> ( 151 tuple[Literal["continue"], _TValue] 152 | tuple[Literal["stop"], _TValue, GuardrailDecision] 153 ): 154 """Record exc as a trace and return a stop outcome with a blocking decision.""" 155 traces.append(self._trace_for_exception(exc=exc)) 156 157 if self.fail_open: 158 return ("continue", value) 159 160 block = GuardrailDecision.block( 161 reason=f"{reason_prefix}: {self._rail_name()}", 162 user_facing_message="Request blocked by guardrails.", 163 meta={ 164 "exception_type": exc.__class__.__name__, 165 "exception_message": str(exc), 166 }, 167 ) 168 return ("stop", value, block) 169 170 async def run( 171 self, 172 *, 173 event: LLMGuardrailEvent, 174 value: _TValue, 175 ) -> tuple[_TValue, list[GuardrailTrace], GuardrailDecision]: 176 """Run this guard once on event and value. 177 178 Returns the resulting value, the traces recorded, and the decision that 179 applies. A BLOCK (or a failed TRANSFORM) surfaces its own decision as-is. 180 A successful TRANSFORM also surfaces its own decision (its `reason`/`meta` 181 describe what changed, e.g. a PII redaction count -- callers like 182 `MiddlewareGuardInputResponseEvent` depend on that). A plain ALLOW, or an 183 exception swallowed via `fail_open=True`, has nothing rail-specific worth 184 keeping, so a generic `GuardrailDecision.allow()` is returned instead. 185 """ 186 traces: list[GuardrailTrace] = [] 187 188 step = await self._eval_one_rail( 189 event=event, 190 value=value, 191 traces=traces, 192 ) 193 194 if step[0] == "stop": 195 return step[1], traces, step[2] 196 197 _, value, event, decision = step 198 199 return ( 200 value, 201 traces, 202 decision if decision is not None else GuardrailDecision.allow(), 203 ) 204 205 async def _eval_one_rail( 206 self, 207 event: LLMGuardrailEvent, 208 value: _TValue, 209 traces: list[GuardrailTrace], 210 ) -> ( 211 tuple[Literal["continue"], _TValue, LLMGuardrailEvent, GuardrailDecision | None] 212 | tuple[Literal["stop"], _TValue, GuardrailDecision] 213 ): 214 """Call this guard, await it if async, validate the decision, and dispatch it.""" 215 try: 216 decision = await unpack_async_sync(self(event)) 217 if not isinstance(decision, GuardrailDecision): 218 raise TypeError( 219 f"Guardrail {self._rail_name()} returned {type(decision).__name__}, expected GuardrailDecision." 220 ) 221 except Exception as e: 222 outcome = self._handle_rail_exception( 223 exc=e, 224 traces=traces, 225 value=value, 226 reason_prefix="Guardrail raised exception", 227 ) 228 if outcome[0] == "continue": 229 return ("continue", value, event, None) 230 return ("stop", outcome[1], outcome[2]) 231 232 traces.append(self._trace_from_decision(decision=decision)) 233 234 if decision.action == GuardrailAction.ALLOW: 235 return ("continue", value, event, None) 236 237 return self._dispatch_non_allow_decision( 238 event=event, 239 value=value, 240 decision=decision, 241 traces=traces, 242 ) 243 244 def _dispatch_non_allow_decision( 245 self, 246 *, 247 event: LLMGuardrailEvent, 248 value: _TValue, 249 decision: GuardrailDecision, 250 traces: list[GuardrailTrace], 251 ) -> ( 252 tuple[Literal["continue"], _TValue, LLMGuardrailEvent, GuardrailDecision | None] 253 | tuple[Literal["stop"], _TValue, GuardrailDecision] 254 ): 255 """Apply a TRANSFORM, BLOCK, or unknown-action decision returned by this guard.""" 256 if decision.action == GuardrailAction.TRANSFORM: 257 try: 258 value = self._extract_transform_value(decision) 259 event = self._sync_event_after_transform(event, value) 260 except Exception as e: 261 outcome = self._handle_rail_exception( 262 exc=e, 263 traces=traces, 264 value=value, 265 reason_prefix="Guardrail transform failed", 266 ) 267 if outcome[0] == "continue": 268 return ("continue", value, event, None) 269 return ("stop", outcome[1], outcome[2]) 270 # Success: unlike a plain ALLOW, the caller needs this decision's own 271 # reason/meta (e.g. a PII redaction count) -- preserve it as-is. 272 return ("continue", value, event, decision) 273 274 if decision.action == GuardrailAction.BLOCK: 275 return ("stop", value, decision) 276 277 traces.append( 278 GuardrailTrace( 279 rail_name=self._rail_name(), 280 phase=self.phase.value, 281 action="error", 282 reason="Unknown guardrail action", 283 meta={"action": str(decision.action)}, 284 ) 285 ) 286 287 if self.fail_open: 288 return ("continue", value, event, None) 289 290 block = GuardrailDecision.block( 291 reason=f"Unknown guardrail action from {self._rail_name()}", 292 user_facing_message="Request blocked by guardrails.", 293 ) 294 return ("stop", value, block) 295 296 @abstractmethod 297 def _sync_event_after_transform( 298 self, 299 event: LLMGuardrailEvent, 300 value: _TValue, 301 ) -> LLMGuardrailEvent: 302 """Return a copy of event updated with the transformed value. Implemented per phase.""" 303 pass 304 305 @abstractmethod 306 def _extract_transform_value(self, decision: GuardrailDecision) -> _TValue: 307 """Extract the replacement value from a TRANSFORM decision. Implemented per phase.""" 308 pass 309 310 def _rail_name(self) -> str: 311 """Return this guard's name, falling back to its class name if unset.""" 312 name = self.name 313 if isinstance(name, str) and name.strip(): 314 return name 315 316 return self.__class__.__name__ 317 318 def _trace_from_decision( 319 self, 320 decision: GuardrailDecision, 321 ) -> GuardrailTrace: 322 """Build a trace recording this guard's decision.""" 323 return GuardrailTrace( 324 rail_name=self._rail_name(), 325 phase=self.phase.value, 326 action=decision.action.value, 327 reason=decision.reason, 328 meta=decision.meta, 329 ) 330 331 def _trace_for_exception( 332 self, 333 *, 334 exc: Exception, 335 ) -> GuardrailTrace: 336 """Build a trace recording an exception raised by this guard.""" 337 return GuardrailTrace( 338 rail_name=self._rail_name(), 339 phase=self.phase.value, 340 action="error", 341 reason="Guardrail raised exception", 342 meta={ 343 "exception_type": exc.__class__.__name__, 344 "exception_message": str(exc), 345 }, 346 )
Abstract base class for guardrails that run on LLM input or output.
Attributes:
- phase: Whether this rail expects
LLMGuardrailPhaseINPUTorOUTPUTevents.
44 def __init__(self, name: str | None = None, fail_open: bool = False): 45 """Initialize the guardrail. 46 47 Args: 48 name: Rail name for traces and debugging; defaults to the class name. 49 fail_open: Whether to allow the request to continue when this guard raises an unexpected exception. 50 """ 51 super().__init__(name=name) 52 self.fail_open = fail_open
Initialize the guardrail.
Arguments:
- name: Rail name for traces and debugging; defaults to the class name.
- fail_open: Whether to allow the request to continue when this guard raises an unexpected exception.
66 @abstractmethod 67 def convert( 68 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 69 ) -> LLMGuardrailEvent: 70 """Build an event from a raw value. Implemented per phase by InputGuard and OutputGuard.""" 71 pass
Build an event from a raw value. Implemented per phase by InputGuard and OutputGuard.
73 def decide( 74 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 75 ) -> GuardrailDecision: 76 """Convert value to an event and run this guard on it directly, outside a chain. 77 78 Synchronous guards only. An ``async def`` guard would return an un-awaited 79 coroutine here, so use :meth:`adecide` for those. 80 """ 81 if self._is_async(): 82 raise TypeError( 83 f"Guardrail {self._rail_name()} is async; " 84 f"use `await {type(self).__name__}.adecide(...)` instead of `.decide(...)`." 85 ) 86 converted_event = self.convert(value) 87 88 return cast(GuardrailDecision, self(converted_event))
Convert value to an event and run this guard on it directly, outside a chain.
Synchronous guards only. An async def guard would return an un-awaited
coroutine here, so use adecide() for those.
90 async def adecide( 91 self, value: str | Message | MessageHistory | LLMGuardrailEvent, / 92 ) -> GuardrailDecision: 93 """Async counterpart to :meth:`decide`; accepts sync and async guards alike.""" 94 converted_event = self.convert(value) 95 96 return await unpack_async_sync(self(converted_event))
Async counterpart to decide(); accepts sync and async guards alike.
170 async def run( 171 self, 172 *, 173 event: LLMGuardrailEvent, 174 value: _TValue, 175 ) -> tuple[_TValue, list[GuardrailTrace], GuardrailDecision]: 176 """Run this guard once on event and value. 177 178 Returns the resulting value, the traces recorded, and the decision that 179 applies. A BLOCK (or a failed TRANSFORM) surfaces its own decision as-is. 180 A successful TRANSFORM also surfaces its own decision (its `reason`/`meta` 181 describe what changed, e.g. a PII redaction count -- callers like 182 `MiddlewareGuardInputResponseEvent` depend on that). A plain ALLOW, or an 183 exception swallowed via `fail_open=True`, has nothing rail-specific worth 184 keeping, so a generic `GuardrailDecision.allow()` is returned instead. 185 """ 186 traces: list[GuardrailTrace] = [] 187 188 step = await self._eval_one_rail( 189 event=event, 190 value=value, 191 traces=traces, 192 ) 193 194 if step[0] == "stop": 195 return step[1], traces, step[2] 196 197 _, value, event, decision = step 198 199 return ( 200 value, 201 traces, 202 decision if decision is not None else GuardrailDecision.allow(), 203 )
Run this guard once on event and value.
Returns the resulting value, the traces recorded, and the decision that
applies. A BLOCK (or a failed TRANSFORM) surfaces its own decision as-is.
A successful TRANSFORM also surfaces its own decision (its reason/meta
describe what changed, e.g. a PII redaction count -- callers like
MiddlewareGuardInputResponseEvent depend on that). A plain ALLOW, or an
exception swallowed via fail_open=True, has nothing rail-specific worth
keeping, so a generic GuardrailDecision.allow() is returned instead.