Notification Policy

Decide whether and what to notify per recipient — categories, quiet hours, detail levels

Notification policy lets you decide, per recipient, what the gateway may notify you about — filter by category, honour quiet hours in the recipient’s own timezone, and redact content before it leaves the gateway. Set it once in gateway.yaml and every scheduled agent result is gated for you.

Quick Start

1. Turn it on with one YAML block

   Add gateway.notifications to your gateway.yaml. Scheduled agent results are now gated automatically.

   agents:
     ops-agent:
       instructions: "Run the overnight sales report."
   
   gateway:
     notifications:
       defaults:
         detail: identified
         categories: [approval_requested]

   With these defaults a scheduled ops-agent result (agent_finished) is not opted in, so it is suppressed.

2. Set a per-recipient preference

   Key a recipient by platform:channel_id and override any default.

   gateway:
     notifications:
       defaults:
         detail: identified
         categories: [approval_requested]
       recipients:
         "telegram:12345":
           categories: [approval_requested, agent_finished]
           quiet_hours: "22:00-07:30"
           timezone: "Europe/London"
           detail: detailed

   telegram:12345 now receives full scheduled results, except between 22:00 and 07:30 London time.

3. Validate and hot-reload

   A bad entry fails at startup, not at send time:

   gateway:
     notifications:
       recipients:
         "telegram:12345":
           timezone: "Europe/Londn"   # ValueError: unknown notification timezone: 'Europe/Londn'

   Edit gateway.yaml and reload. The new policy applies without a restart:

   kill -HUP $(pgrep -f "praisonai gateway")
   # or
   systemctl reload praisonai-gateway

How Categorised Sends Flow Through the Gateway

Every proactive send that carries a category passes through the gate before the idempotency check and the channel.

• Suppressed sends count as handled — deliver() returns True, so the scheduler and outbox do not retry, and no idempotency key is claimed.
• Uncategorised sends are never gated — direct replies, hook replies and restart notices pass straight through.
• Quiet hours use the recipient’s timezone — the gate passes an aware UTC now, so the window is checked in the recipient’s timezone, not the gateway host’s clock.
• No notifications block, no gating — behaviour is unchanged when the block is absent.

What Gets Categorised Automatically

Where Recipients Come From

A recipient key is the resolved platform:channel_id of the delivery target — the same pair the gateway logs on each proactive send (Delivered scheduled result to telegram:12345, or notification suppressed for telegram:12345 when gated). A recipient with no entry falls back to defaults, and anything missing from defaults falls back to DEFAULT_PREFERENCE.

The Three Concerns

Categories

A recipient opts into each event class independently; an un-opted category is suppressed with reason category_not_subscribed.

gateway:
  notifications:
    recipients:
      "telegram:12345":
        categories: [approval_requested, agent_finished]

Quiet Hours

A per-recipient local window suppresses non-urgent categories; urgent events override when urgent_overrides_quiet is true.

gateway:
  notifications:
    recipients:
      "telegram:12345":
        quiet_hours: "22:00-07:30"
        timezone: "Europe/London"

The window is half-open [start, end). When start == end the window is empty (never quiet). When start > end it wraps past midnight — (22:00, 07:30) means 22:00–24:00 ∪ 00:00–07:30. A naive now is treated as already local; an aware now is converted to prefs.timezone via stdlib zoneinfo. When calling evaluate() directly, an unknown timezone name is ignored silently and now is left unconverted (so an aware UTC now is checked in UTC); the gateway rejects it at config load instead.

Detail Levels

Three levels control how much content leaves the gateway.

gateway:
  notifications:
    recipients:
      "telegram:12345":
        detail: private

Which Detail Level Should I Pick?

Match the level to how trusted the destination surface is.

YAML Reference

All keys live under gateway.notifications.

gateway:
  notifications:
    defaults:
      detail: identified
      categories: [approval_requested]
    recipients:
      "telegram:12345":
        categories: [approval_requested, agent_finished]
        quiet_hours: "22:00-07:30"
        timezone: "Europe/London"
        detail: detailed

<entry> is defaults or any recipients entry. A key missing from a recipient entry inherits from defaults; a key missing from defaults inherits from DEFAULT_PREFERENCE.

Validation and Hot-Reload

• Fails at startup — loading gateway.yaml builds the gate, so an unknown category or detail, a malformed quiet_hours, or an unknown timezone raises before the gateway serves traffic.
• Published schema — praisonai gateway schema prints the JSON schema, including the notifications block, for editor validation.
• Hot-reload — on file change or SIGHUP, the gateway applies the new notifications block to the live delivery router. Removing the block clears gating. See Gateway Hot Reload.

Under the Hood: evaluate()

The gate wraps one pure function, which you can also call from your own notifier before delivery; the decision carries the send flag and the already-redacted content.

evaluate() is pure and side-effect-free, so any process can call it at delivery-decision time without I/O. Pass prefs=None to fall back to DEFAULT_PREFERENCE; pass now=None to use the host’s naive local clock (prefs.timezone is not applied). To honour the recipient’s timezone, pass an aware now such as datetime.now(timezone.utc), as the gateway does.

Python Reference

NotificationPreference

Also exposes .allows(category) → bool, whether this recipient opted into category.

NotificationDecision

evaluate(...)

DEFAULT_PREFERENCE

Applied when a recipient has set nothing: the two interaction-blocking categories are on, at the identified (no-content) detail level, with no quiet hours.

DEFAULT_PREFERENCE = NotificationPreference(
    categories={
        NotificationCategory.APPROVAL_REQUESTED,
        NotificationCategory.AGENT_QUESTION,
    },
    detail=DetailLevel.IDENTIFIED,
)

Common Patterns

Mute scheduled results overnight, keep approvals — agent_finished is suppressed inside the window.

gateway:
  notifications:
    recipients:
      "slack:C01ABC":
        categories: [approval_requested, agent_finished]
        quiet_hours: "22:00-07:00"
        timezone: "America/New_York"

Privacy-first mobile recipient — detail: private so the lock-screen never shows content.

gateway:
  notifications:
    recipients:
      "telegram:12345":
        categories: [agent_finished]
        detail: private      # → "You have new activity"

The patterns below call evaluate() directly from your own notifier.

Gate a scheduler completion notification — the recipient opts into AGENT_FINISHED, and it is not urgent.

from praisonaiagents.push import (
    NotificationCategory, NotificationPreference, evaluate,
)

prefs = NotificationPreference(categories={NotificationCategory.AGENT_FINISHED})

decision = evaluate(
    NotificationCategory.AGENT_FINISHED,
    prefs=prefs,
    content="Nightly ETL finished in 12m",
    identity="etl-agent",
)
if decision.send:
    print(decision.redacted_content)   # → "Activity in etl-agent"

Approval request during quiet hours — the recipient is inside their window, but the urgent flag overrides it.

from datetime import datetime, time
from praisonaiagents.push import (
    NotificationCategory, NotificationPreference, evaluate,
)

prefs = NotificationPreference(
    categories={NotificationCategory.APPROVAL_REQUESTED},
    quiet_hours=(time(22, 0), time(7, 30)),
    timezone="Europe/London",
)

decision = evaluate(
    NotificationCategory.APPROVAL_REQUESTED,
    prefs=prefs,
    now=datetime(2026, 1, 1, 2, 15),   # 02:15 → inside quiet window
    is_urgent=True,
    identity="ops-agent",
)
print(decision.send, decision.reason)  # → True urgent_override

Privacy-first mobile push — DetailLevel.PRIVATE so the lock-screen never shows content.

from praisonaiagents.push import (
    NotificationCategory, DetailLevel, NotificationPreference, evaluate,
)

prefs = NotificationPreference(
    categories={NotificationCategory.HUMAN_MENTIONED},
    detail=DetailLevel.PRIVATE,
)

decision = evaluate(
    NotificationCategory.HUMAN_MENTIONED,
    prefs=prefs,
    content="Secret: launch is Tuesday",
    identity="strategy-session",
)
print(decision.redacted_content)       # → "You have new activity"

Best Practices

User Interaction Flow

An operator sets a preference once in gateway.yaml; later scheduled results are gated automatically.

Related