<!-- ---
!-- Timestamp: 2026-03-16 07:00:20
!-- Author: ywatanabe
!-- File: /home/ywatanabe/proj/scitex-notification/README.md
!-- --- -->

# SciTeX Notification (<code>scitex-notification</code>)

<p align="center">
  <a href="https://scitex.ai">
    <img src="docs/scitex-logo-blue-cropped.png" alt="SciTeX" width="400">
  </a>
</p>

<p align="center"><b>Multi-backend notification system for scientific workflows</b></p>

<p align="center">
  <a href="https://badge.fury.io/py/scitex-notification"><img src="https://badge.fury.io/py/scitex-notification.svg" alt="PyPI version"></a>
  <a href="https://scitex-notification.readthedocs.io/"><img src="https://readthedocs.org/projects/scitex-notification/badge/?version=latest" alt="Documentation"></a>
  <a href="https://github.com/ywatanabe1989/scitex-notification/actions/workflows/test.yml"><img src="https://github.com/ywatanabe1989/scitex-notification/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0"></a>
</p>

<p align="center">
  <a href="https://scitex-notification.readthedocs.io/">Full Documentation</a> · <code>pip install scitex-notification</code>
</p>

---

## Problem

Long-running scientific computations — model training, HPC jobs, large-scale analyses — complete while researchers are away from their desks. Researchers either poll their terminals continuously, or miss results entirely and come back hours later to a finished (or failed) job. There is no standard, composable way to route completion alerts across the varied backends researchers actually use: audio, SMS, email, or custom webhooks.

## Solution

SciTeX Notification provides a **unified notify interface** that routes completion alerts and status messages across multiple backends — audio alerts, SMS via Twilio, email via SMTP, and generic webhooks — with a single function call.

Named after the core problem it solves — knowing when something is done — it lets you:

- **Alert** yourself when a job finishes, regardless of where you are
- **Route** notifications to the right backend based on environment and urgency
- **Compose** multiple backends so critical alerts reach you through redundant channels
- **Integrate** with SciTeX sessions for automatic job completion notifications

## Installation

Requires Python >= 3.10.

```bash
pip install scitex-notification
```

Install with optional backends:

```bash
pip install "scitex-notification[audio]"    # audio alerts via scitex-audio
pip install "scitex-notification[twilio]"   # SMS via Twilio
pip install "scitex-notification[mcp]"      # MCP server for AI agents
pip install "scitex-notification[all]"      # everything
```

> **SciTeX users**: `pip install scitex` already includes Notification. Alerts are automatic via `@scitex.session`.

## Quickstart

```python
import scitex_notification as stxn

# Alert via default backend (audio → emacs → email fallback)
stxn.alert("Training complete. Val loss: 0.042")

# Alert via a specific backend
stxn.alert("Job finished", backend="email")

# Alert via multiple backends
stxn.alert("Critical failure", backend=["sms", "email"])

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

# Send an SMS via Twilio
stxn.sms("Build done!")
```

Configure backends via environment variables (see `.env.example`):

```bash
export SCITEX_NOTIFY_DEFAULT_BACKEND=audio
export SCITEX_NOTIFY_TWILIO_SID=ACxxxxxxx
export SCITEX_NOTIFY_TWILIO_TOKEN=...
export SCITEX_NOTIFY_TWILIO_TO=+1234567890
```

## Three Interfaces

<details>
<summary><strong>Python API</strong></summary>

<br>

```python
import scitex_notification as stxn

stxn.alert("Job done")                           # default backend (with fallback)
stxn.alert("Error", backend="email")             # specific backend
stxn.alert("Critical", backend=["sms", "email"]) # multiple backends
stxn.call("Urgent!")                             # phone call via Twilio
stxn.sms("Build done!")                          # SMS via Twilio
stxn.available_backends()                        # list installed backends
```

> **[Full API reference](https://scitex-notification.readthedocs.io/)**

</details>

<details>
<summary><strong>CLI Commands</strong></summary>

<br>

```bash
scitex-notification --help                       # Show all commands
scitex-notification send "Job done"              # Send via default backend
scitex-notification send "Done" --backend email  # Send via specific backend
scitex-notification status                       # Show configuration
scitex-notification backends                     # List available backends
scitex-notification mcp list-tools              # List MCP tools
```

> **[Full CLI reference](https://scitex-notification.readthedocs.io/)**

</details>

<details>
<summary><strong>MCP Server — for AI Agents</strong></summary>

<br>

AI agents can send notifications and check system status autonomously.

| Tool | Description |
|------|-------------|
| `notify_handler` | Send an alert via specified or fallback backends |
| `notify_by_level_handler` | Send alert using level-based backend config |
| `list_backends_handler` | List all backends with availability status |
| `get_config_handler` | Show current notification configuration |

```bash
scitex-notification mcp start
```

> **[Full MCP specification](https://scitex-notification.readthedocs.io/)**

</details>

## SSH Audio Relay

When running jobs on a remote server, audio alerts can play on your
local speakers via [scitex-audio](https://github.com/ywatanabe1989/scitex-audio)'s
SSH relay — no extra configuration needed on the notification side.

```bash
pip install "scitex-notification[audio]"
```

## Part of SciTeX

SciTeX Notification is part of [**SciTeX**](https://scitex.ai).

The SciTeX system follows the Four Freedoms for Research below, inspired by [the Free Software Definition](https://www.gnu.org/philosophy/free-sw.en.html):

>Four Freedoms for Research
>
>0. The freedom to **run** your research anywhere — your machine, your terms.
>1. The freedom to **study** how every step works — from raw data to final manuscript.
>2. The freedom to **redistribute** your workflows, not just your papers.
>3. The freedom to **modify** any module and share improvements with the community.
>
>AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.

---

<p align="center">
  <a href="https://scitex.ai" target="_blank"><img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
</p>

<!-- EOF -->