Source code for smarter.apps.guardrail.receivers

"""
Django Signal Receivers for guardrail.

.. note::

    **Experimental.** The Guardrail was designed and coded by Claude Code (Anthropic's
    Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will
    be documented.
"""

# pylint: disable=W0613,C0115

from django.db.models.signals import post_save, pre_delete
from django.dispatch import receiver

from smarter.lib import logging
from smarter.lib.django.listview import connect_listview_cache
from smarter.lib.django.waffle import SmarterWaffleSwitches

from .models import Guardrail
from .signals import (
    guardrail_blocked,
    guardrail_escalated,
    guardrail_failed,
    guardrail_triggered,
)

logger = logging.getSmarterLogger(__name__, any_switches=[SmarterWaffleSwitches.GUARDRAIL_LOGGING])

module_prefix = __name__


[docs] @receiver(post_save, sender=Guardrail) def guardrail_saved(sender, instance: Guardrail, created: bool, **kwargs): """ Log a created or updated Guardrail, with its name and id. Its serialized fields are not logged: they include the owner's user profile, whose email address is personal data. :param sender: The model class, :class:`~smarter.apps.guardrail.models.Guardrail`. :param instance: The saved Guardrail. :param created: True if the Guardrail was created, False if it was updated. :param kwargs: The other ``post_save`` arguments. """ prefix = f"{logging.SmarterFormattedText.text(module_prefix)}.guardrail_saved()" action = "created" if created else "updated" logger.info("%s %s %s (id %s)", prefix, action, instance, instance.pk)
[docs] @receiver(pre_delete, sender=Guardrail) def guardrail_deleted(sender, instance: Guardrail, **kwargs): """ Log a Guardrail that is about to be deleted. :param sender: The model class, :class:`~smarter.apps.guardrail.models.Guardrail`. :param instance: The Guardrail being deleted. :param kwargs: The other ``pre_delete`` arguments. """ prefix = f"{logging.SmarterFormattedText.text(module_prefix)}.guardrail_deleted()" logger.info("%s %s", prefix, instance)
[docs] @receiver(guardrail_triggered, dispatch_uid="guardrail_triggered") def handle_guardrail_triggered(sender, guardrail: Guardrail, stage: str, disposition: str, **kwargs): """Log a triggered guardrail. What it matched is not logged, because it may be personal data. """ logger.info( "%s %s %s: %s", f"{logging.SmarterFormattedText.text(module_prefix)}.guardrail_triggered", guardrail.name, stage, disposition, )
[docs] @receiver(guardrail_blocked, dispatch_uid="guardrail_blocked") def handle_guardrail_blocked(sender, guardrail: Guardrail, stage: str, message: str, **kwargs): """ Log a blocked message or reply. :param sender: The object that sent the signal. :param guardrail: The Guardrail that blocked it. :param stage: The stage it ran at, e.g. ``input`` or ``output``. :param message: The message shown to the user in place of the blocked content. :param kwargs: The other signal arguments. """ logger.warning( "%s %s blocked the %s: %s", f"{logging.SmarterFormattedText.text(module_prefix)}.guardrail_blocked", guardrail.name, stage, message, )
[docs] @receiver(guardrail_escalated, dispatch_uid="guardrail_escalated") def handle_guardrail_escalated(sender, guardrail: Guardrail, stage: str, event=None, **kwargs): """Log an escalation to human review. Its event awaits review in the Smarter admin. """ logger.warning( "%s %s escalated the %s to human review, severity %s, event %s", f"{logging.SmarterFormattedText.text(module_prefix)}.guardrail_escalated", guardrail.name, stage, guardrail.severity, event.pk if event else None, )
[docs] @receiver(guardrail_failed, dispatch_uid="guardrail_failed") def handle_guardrail_failed(sender, guardrail: Guardrail, stage: str, error: str, fail_closed: bool, **kwargs): """ Log a guardrail that failed to run. :param sender: The object that sent the signal. :param guardrail: The Guardrail that failed. :param stage: The stage it ran at. :param error: The error message. :param fail_closed: True if the failure blocked the content, False if it was let through. :param kwargs: The other signal arguments. """ logger.error( "%s %s failed on the %s%s: %s", f"{logging.SmarterFormattedText.text(module_prefix)}.guardrail_failed", guardrail.name, stage, ", and blocked it" if fail_closed else "", error, )
# the list view's cached pages are stale when the resources that it shows change. See smarter.lib.django.listview. connect_listview_cache("Guardrail", "guardrail.Guardrail", "llmclient.LLMClientGuardrails")