Notification Module (`stx.notification`)

Multi-backend notification system for alerting researchers when long-running tasks complete, errors occur, or results are ready.

Note

stx.notification delegates to the standalone scitex-notification package. Install with: pip install scitex-notification.

Supported Backends

Backend	Description
`desktop`	Native desktop notifications (Linux `notify-send`, macOS, Windows)
`email`	Email via SMTP
`slack`	Slack messages via webhook or Bot API
`webhook`	Generic HTTP POST to any URL

Quick Start

import scitex as stx

# Send a notification (uses default backend)
stx.notification.send("Training complete! Accuracy: 95.2%")

# Send to a specific backend
stx.notification.send("Job finished", backend="slack")

# List available backends
stx.notification.list_backends()

Key Functions

`send(message, backend=None, **kwargs)`

Send a notification through one or more backends.

# Simple message
stx.notification.send("Experiment finished successfully.")

# With title
stx.notification.send("95.2% accuracy achieved", title="Training Complete")

# To a specific backend
stx.notification.send("Results ready", backend="email")

`config(**kwargs)`

Configure notification backends. Settings persist across sessions.

# Configure Slack
stx.notification.config(
    slack_webhook="https://hooks.slack.com/services/...",
)

# Configure email
stx.notification.config(
    email_to="researcher@university.edu",
    email_from="scitex@lab.org",
    smtp_host="smtp.university.edu",
)

`list_backends()`

List available and configured backends.

backends = stx.notification.list_backends()
# [{'name': 'desktop', 'available': True, 'configured': True},
#  {'name': 'slack', 'available': True, 'configured': False}, ...]

Integration with `@stx.session`

Enable automatic notifications when a session completes:

import scitex as stx

@stx.session(notify=True)
def main(CONFIG=stx.INJECTED):
    """Long-running experiment."""
    result = train_model()
    return 0    # Sends "Session FINISHED_SUCCESS" notification

if __name__ == "__main__":
    main()

CLI Access

# Send a notification
scitex notify send "Job complete"

# Check backend status
scitex notify backends

# Configure a backend
scitex notify config --slack-webhook "https://..."

API Reference

SciTeX Notification Module - User alerts and feedback.

Usage:

import scitex_notification as stxn

# Simple alert - uses fallback priority (audio -> emacs -> desktop -> …) stxn.alert(“2FA required!”)

# Specify backend (no fallback) stxn.alert(“Error”, backend=”email”)

# Multiple backends (tries all) stxn.alert(“Critical”, backend=[“audio”, “email”])

# Use fallback explicitly stxn.alert(“Important”, fallback=True)

# Make a phone call via Twilio stxn.call(“Critical alert!”)

# Send an SMS via Twilio stxn.sms(“Build done!”)

Environment Variables:

SCITEX_NOTIFICATION_DEFAULT_BACKEND: audio, email, desktop, webhook SCITEX_NOTIFICATION_ENV_SRC: path to .env file to auto-load on import

scitex.notification.alert(message, title=None, backend=None, level='info', fallback=None, **kwargs)[source]

Send alert synchronously.

Parameters:

message (str) – Alert message
title (str, optional) – Alert title
backend (str or list[str], optional) – Backend(s) to use. If None, walks the fallback priority order. A single explicit backend is used on its own (no silent substitution) unless fallback=True is passed.
level (str) – Alert level: info, warning, error, critical
fallback (bool, optional) – If None (default) resolves to backend is None — an explicit backend never silently falls back. See alert_async().

Returns:

True if the requested backend(s) delivered the alert.

Return type:

bool

Raises:

ValueError / RuntimeError – When a single explicit backend (fallback disabled) is unavailable or fails — see alert_async(). The fallback path (backend=None) still returns False on total failure.
Fallback Order –
-------------- –
1. audio - TTS (fast, non-blocking) –
2. emacs - Minibuffer message –
3. matplotlib - Visual popup –
4. playwright - Browser popup –
5. email - Email (slowest) –

async scitex.notification.alert_async(message, title=None, backend=None, level='info', fallback=None, **kwargs)[source]

Send alert asynchronously.

Parameters:

message (str) – Alert message
title (str, optional) – Alert title
backend (str or list[str], optional) – Backend(s) to use. If None, walks the default fallback priority order. If a single backend name is given, ONLY that backend is used (no silent substitution) unless fallback=True is passed explicitly.
level (str) – Alert level: info, warning, error, critical
fallback (bool, optional) – Controls whether other backends are tried after the requested one(s). If left as None (default), it resolves to backend is None — i.e. an EXPLICIT backend request fails loud rather than silently falling through to another channel (no-silent-fallbacks policy). Pass True to opt back into fallback for an explicit backend, or False to forbid it even when backend is None.

Returns:

True if the requested backend(s) delivered the alert.

Return type:

bool

Raises:

ValueError – If a single explicit backend is requested with fallback disabled and that backend is not currently available — the caller asked for a specific channel that cannot fire, so we fail loud instead of returning a quiet False that looks like a transient send failure.

scitex.notification.available_backends()[source]

Return list of available alert backends.

Return type:: list[str]

scitex.notification.call(message, title=None, level='info', to_number=None, **kwargs)[source]

Make a phone call via Twilio.

Convenience wrapper for alert(backend=”twilio”).

Return type:: bool

async scitex.notification.call_async(message, title=None, level='info', to_number=None, **kwargs)[source]

Make a phone call via Twilio (async).

Return type:: bool

scitex.notification.notify(subject='', message=':)', file=None, ID='auto', sender_name=None, recipient_email=None, cc=None, attachment_paths=None, verbose=False)[source]

Send a script-aware notification email.

Builds a subject/body from the calling script’s name and appends a footer with host, script, package version and git branch, then delegates to send_gmail().

Credentials and recipient are read from environment variables (with backward-compatible aliases):

sender: SCITEX_SCHOLAR_EMAIL_NOREPLY / SCITEX_SCHOLAR_FROM_EMAIL_ADDRESS / SCITEX_EMAIL_NOREPLY / SCITEX_EMAIL_AGENT (default no-reply@scitex.ai)
password: SCITEX_SCHOLAR_EMAIL_PASSWORD / SCITEX_SCHOLAR_FROM_EMAIL_PASSWORD / SCITEX_EMAIL_PASSWORD
recipient: SCITEX_SCHOLAR_EMAIL_RECIPIENT / SCITEX_SCHOLAR_TO_EMAIL_ADDRESS (or pass recipient_email=)

Return type:: None

scitex.notification.send_email(to, subject, body, *, from_addr=None, password=None, smtp_host=None, smtp_port=None)[source]

Send a plain-text email synchronously with explicit credentials.

Public, side-channel-free wrapper over _send_email(). Unlike the env-driven EmailBackend (which resolves from/password from independent fallback chains and so can pair a sender from one identity with a password from another), every field here is passed in by the caller — the caller owns the coherent identity. Each argument left None still falls back to the SCITEX_NOTIFICATION_EMAIL_* env chain documented on _send_email().

Raises any smtplib error on failure (fail-loud — no silent False).

Return type:: None

scitex.notification.send_gmail(sender_gmail, sender_password, recipient_email, subject, message, sender_name=None, cc=None, ID=None, attachment_paths=None, verbose=True, smtp_server=None, smtp_port=None)[source]

Send an email via SMTP.

Despite the name, supports any SMTP server. Uses mail1030.onamae.ne.jp by default (for scitex.ai emails) and falls back to Gmail’s server when the sender address ends in @gmail.com.

Parameters:

sender_gmail (str) – Sender email address (and SMTP login).
sender_password (str) – SMTP password.
recipient_email (str) – Primary recipient address.
subject (str) – Email subject. If ID is given it is appended as (ID: ...).
message (str) – Plain-text body.
sender_name (str, optional) – Display name for the From header.
cc (str or list, optional) – CC recipient(s).
ID (str, optional) – Message ID. Pass "auto" to auto-generate one.
attachment_paths (list, optional) – Paths of files to attach. .log files are ANSI-stripped.
verbose (bool) – Print a confirmation line on success.
smtp_server (optional) – Override SMTP host/port auto-detection.
smtp_port (optional) – Override SMTP host/port auto-detection.

Return type:

None

scitex.notification.sms(message, title=None, to_number=None, **kwargs)[source]

Send an SMS via Twilio.

Parameters:

message (str) – SMS body text
title (str, optional) – Prepended to message if provided
to_number (str, optional) – Override SCITEX_NOTIFICATION_TWILIO_TO

Returns:

True if SMS sent successfully

Return type:

bool

async scitex.notification.sms_async(message, title=None, to_number=None, **kwargs)[source]

Send an SMS via Twilio (async).

Parameters:

message (str) – SMS body text
title (str, optional) – Prepended to message if provided
to_number (str, optional) – Override SCITEX_NOTIFICATION_TWILIO_TO

Returns:

True if SMS sent successfully

Return type:

bool

Notification Module (stx.notification)

Supported Backends

Quick Start

Key Functions

send(message, backend=None, **kwargs)

config(**kwargs)

list_backends()

Integration with @stx.session

CLI Access

API Reference

Notification Module (`stx.notification`)

`send(message, backend=None, **kwargs)`

`config(**kwargs)`

`list_backends()`

Integration with `@stx.session`