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=True, **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, uses fallback priority order.
level (str) – Alert level: info, warning, error, critical
fallback (bool) – If True and backend fails, try next in priority order.

Return type:

bool

Returns:

bool – True if any backend succeeded
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=True, **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, uses default with fallback.
level (str) – Alert level: info, warning, error, critical
fallback (bool) – If True and backend fails, try next in priority order. Default True when backend=None, False when backend specified.

Returns:

True if any backend succeeded

Return type:

bool

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_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`