Metadata-Version: 2.4
Name: aailab-tools
Version: 0.1.2
Summary: Utilities for interacting with the AAILab blade dashboard.
Author: AAILab
License: MIT
Project-URL: Homepage, https://github.com/vrbaj/aailab-tools
Keywords: decorator,notification,email,blade-dashboard
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# aailab-tools

`aailab-tools` provides a `notify()` decorator that reports the completion status
of a function to the `blade_dashboard` notification API.

## Installation

```bash
pip install aailab-tools
```

## Configuration

The decorator reads its configuration from environment variables. On a
multi-user server, the recommended setup is to export them globally once and
let each project inherit them.

Recommended variables:

- `SERVER_NOTIFY`: full notification endpoint URL, for example
  `http://127.0.0.1:8000/api/notify`
- `API_TOKEN`: API token expected by `blade_dashboard server`
- `AAILAB_MACHINE_ID`: optional machine identifier; if omitted, hostname is used

Example global setup:

```bash
cat > /etc/profile.d/aailab-tools.sh <<'EOF'
export SERVER_NOTIFY=http://127.0.0.1:8000/api/notify
export API_TOKEN=your-token
export AAILAB_MACHINE_ID=$(hostname)
EOF
chmod 644 /etc/profile.d/aailab-tools.sh
```

The decorator checks configuration in this order:

1. Process environment variables
2. `.env` in the current working directory
3. `.env` next to the calling script
4. `~/.config/aailab-tools/.env` or `$XDG_CONFIG_HOME/aailab-tools/.env`
5. `~/.aailab-tools.env`

The `.env` files are fallback sources for cases where the process environment is
not set explicitly.

## Usage

```python
from aailab_tools import notify


@notify("user@example.com", "admin@example.com")
def run_job():
    return 42
```

On success, the server receives status `0`. If the function raises an exception,
the exception text is sent as the status and the exception is re-raised.
