Metadata-Version: 2.4
Name: messenger-logger-callback
Version: 0.3.2
Summary: Messenger Logger Callback — send training logs to Telegram via a remote server. Standalone logger and Hugging Face Trainer callback.
Author-email: Riko0 <grigoriyalexeenko@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Riko0/messenger_logger_callback
Project-URL: Repository, https://github.com/Riko0/messenger_logger_callback
Project-URL: Bug Tracker, https://github.com/Riko0/messenger_logger_callback/issues
Project-URL: Documentation, https://github.com/Riko0/messenger_logger_callback#readme
Project-URL: Telegram Log Service, https://github.com/Riko0/telegram_log_service
Keywords: messenger-logger-callback,messenger_logger_callback,messenger logger callback,telegram,training,logger,callback,huggingface,transformers,machine learning,deep learning,training monitor,training logs,telegram bot,clearml,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: transformers>=4.0.0
Provides-Extra: standalone

# messenger-logger-callback

[![PyPI version](https://img.shields.io/pypi/v/messenger-logger-callback.svg)](https://pypi.org/project/messenger-logger-callback/)
[![Python](https://img.shields.io/pypi/pyversions/messenger-logger-callback.svg)](https://pypi.org/project/messenger-logger-callback/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**messenger-logger-callback** (`messenger_logger_callback`) — a Python library for sending training logs to a remote server with real-time **Telegram** notifications. Works as a **standalone logger** for any training loop (PyTorch, Lightning, custom) or as a **Hugging Face Trainer Callback**.

Pairs with [telegram-log-service](https://github.com/Riko0/telegram_log_service) for real-time Telegram bot alerts, metric monitoring, and stalled run detection.

## Installation

```bash
pip install messenger-logger-callback
```

Or equivalently:

```bash
pip install messenger_logger_callback
```

This installs everything including Hugging Face Transformers Trainer support. If you only need the standalone logger and want to avoid the `transformers` dependency, install with `--no-deps` and add `requests` and `python-dotenv` manually.

## Quick Start: Standalone Logger

Use `MessengerLogger` in any training loop — plain PyTorch, Lightning, or anything else.

```python
from messenger_logger import MessengerLogger

logger = MessengerLogger(
    server_url="http://your-server:5000/api/logs",
    project_name="resnet_experiment",
    run_id="run_v3",
    author_username="riko",
)

logger.start()

for epoch in range(num_epochs):
    for step, batch in enumerate(dataloader):
        loss = train_step(batch)
        global_step += 1
        logger.log(step=global_step, epoch=epoch, metrics={"loss": loss.item()})
    logger.epoch_end(epoch)

logger.finish()
```

### Available Methods

| Method | Description |
|--------|-------------|
| `start()` | Signal training start. Begins heartbeat. |
| `log(step, metrics, epoch=None)` | Log training metrics at a given step. |
| `epoch_end(epoch)` | Signal end of an epoch. |
| `log_custom(data)` | Send arbitrary custom data. |
| `finish()` | Signal training end. Stops heartbeat. |

## Quick Start: Hugging Face Trainer

Use `MessengerLoggerCallback` as a drop-in Trainer callback.

```python
from transformers import Trainer, TrainingArguments
from messenger_logger.callback import MessengerLoggerCallback

logger = MessengerLoggerCallback(
    server_url="http://your-server:5000/api/logs",
    project_name="bert_finetune",
    run_id="experiment_v2",
    auth_token="your_secret_token",
    author_username="riko",
    metadata={"model": "bert-large", "dataset": "squad"},
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    callbacks=[logger],
)
trainer.train()
```

The callback automatically captures `on_log`, `on_train_begin`, `on_train_end`, and `on_epoch_end` events.

You can also send custom data at any point:

```python
logger.send_custom_log({
    "event": "evaluation_complete",
    "accuracy": 0.95,
    "f1": 0.93,
})
```

## Heartbeat

A background thread sends a lightweight heartbeat signal to the server every 60 seconds by default. This allows the server to detect crashed or stalled runs much faster than waiting for missing log events.

- **On by default** with a 60-second interval.
- Starts when training begins, stops when training ends.
- If the training process crashes, the heartbeat stops automatically.

To change the interval or disable:

```python
# Custom interval (30 seconds)
logger = MessengerLogger(server_url="...", heartbeat_interval=30)

# Disable heartbeat
logger = MessengerLogger(server_url="...", heartbeat_interval=None)
```

## ClearML Integration

If [ClearML](https://clear.ml/) is active in your training script, the library automatically detects the current task and includes a link to the ClearML dashboard in every payload sent to the server. No configuration needed — if `clearml` is installed and a task is running, the link is captured.

## Configuration

Settings can be provided via constructor arguments, environment variables, or a `.env` file. Constructor arguments take highest precedence, then environment variables, then `.env` file values.

| Constructor Argument | Environment Variable | Description |
|---------------------|---------------------|-------------|
| `server_url` | `MESSENGER_LOGGER_SERVER_URL` | HTTP endpoint to send logs to. **Required.** |
| `project_name` | — | Project identifier. Default: `"default_project"`. |
| `run_id` | — | Unique run identifier. Auto-generated if omitted. |
| `auth_token` | `MESSENGER_LOGGER_AUTH_TOKEN` | Bearer token for the Authorization header. |
| `author_username` | `MESSENGER_LOGGER_AUTHOR_USERNAME` | Who started the run. Default: `"anonymous"`. |
| `metadata` | `MESSENGER_LOGGER_METADATA` | Static metadata dict. Env var should be a JSON string. |
| `dotenv_path` | `MESSENGER_LOGGER_DOTENV` | Path to a `.env` file to load config from. |
| `heartbeat_interval` | — | Seconds between heartbeats. Default: `60`. Set to `None` to disable. |

## Error Handling

Network errors (timeouts, connection failures, HTTP errors) are caught and printed as warnings. They never crash your training. Example messages:

```
Warning: Request to http://... timed out for step 10.
Error: Could not connect to server at http://... for step 20.
Error: HTTP error occurred while sending logs for step 30. Status: 401.
```

## Related Projects

- **[telegram-log-service](https://github.com/Riko0/telegram_log_service)** — the server that receives logs from this library and forwards them as Telegram bot alerts.

## License

MIT

---

<sub>messenger-logger-callback · messenger_logger_callback · pip install messenger-logger-callback · pip install messenger_logger_callback · Telegram training logger · Hugging Face Trainer callback logger · ML training Telegram notifications</sub>
