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        )
logger = <RTContextLoggingAdapter RT.guardrails (WARNING)>
class BaseLLMGuardrail(railtracks.guardrails.core.interfaces.BaseGuardrail[(<class 'railtracks.llm.history.MessageHistory'>, type[pydantic.main.BaseModel] | None, list[railtracks.llm.tools.tool.Tool] | None), railtracks.llm.response.Response], railtracks.llm.middleware.ModelOnlyMiddleware, typing.Generic[~_TValue]):
 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 LLMGuardrailPhase INPUT or OUTPUT events.
BaseLLMGuardrail(name: str | None = None, fail_open: bool = False)
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.
fail_open
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.

async def run( self, *, event: railtracks.guardrails.LLMGuardrailEvent, value: ~_TValue) -> tuple[~_TValue, list[railtracks.guardrails.GuardrailTrace], railtracks.guardrails.GuardrailDecision]:
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.