Metadata-Version: 2.4
Name: telewrapperz
Version: 0.1.0
Summary: Remote command wrapper and monitoring tool for Telegram
Author-email: Duccio <duccio@example.com>
License: MIT
Project-URL: Homepage, https://github.com/duccioo/telewrapper
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: python-telegram-bot>=20.0
Requires-Dist: psutil
Requires-Dist: nvidia-ml-py
Requires-Dist: pyyaml
Requires-Dist: rich>=13.0

# 🤖 Telewrapperz

> **Remote command monitoring made simple** — Execute any command and get real-time updates directly on Telegram with live system stats.

[![Python](https://img.shields.io/badge/Python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![Telegram Bot API](https://img.shields.io/badge/Telegram-Bot%20API-26A5E4?style=flat-square&logo=telegram&logoColor=white)](https://core.telegram.org/bots/api)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 📊 **Live Dashboard** | Single auto-updating Telegram message with command output |
| 🖥️ **System Monitoring** | Real-time CPU, RAM usage tracking |
| 🎮 **GPU Support** | NVIDIA GPU utilization & VRAM stats (via `pynvml`) |
| 🌐 **Multi-Host Ready** | Run on multiple machines with the same bot token |
| ⏱️ **Execution Timer** | Track how long your commands have been running |
| 🎛️ **Remote Control** | Terminate processes or close wrapper via inline buttons |
| 🖥️ **Cross-Platform** | Works on Windows, macOS, and Linux |
| 📈 **Progress Bar Support** | Smart handling of `tqdm` and `rich` progress bars, with proper terminal emulation |
| 💾 **Log Saving** | Use `--log` to automatically save the full command output locally and download it via Telegram |

---

## 📦 Installation

```bash
# Clone the repository
git clone https://github.com/duccioo/telewrapper.git
cd telewrapper

# Install the package
pip install .

# Development install, useful when editing this checkout
pip install -e .
```

**Dependencies:** Automatically installed via pip
- `python-telegram-bot>=20.0`
- `psutil`
- `pynvml` (optional, for NVIDIA GPU stats)
- `rich` (used by the long progress demo and supported command output)

---

## ⚙️ Configuration

### Option 1: Environment Variables (Recommended)

```bash
export TELEGRAM_TOKEN="your_bot_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"
```

### Option 2: Command Line Arguments

```bash
telewrapperz --token "your_token" --chat_id "your_chat_id" "your_command"
```

### Option 3: Config File (YAML or INI)

Create a config file and pass it with `--config`:

**YAML format** (recommended):
```yaml
telegram:
  token: your_bot_token_here
  chat_id: your_chat_id_here

settings:
  update_interval: 5.0  # seconds between dashboard updates
  enable_log: true      # save full output and enable the Telegram download button
```

**INI format** (legacy):
```ini
[Telegram]
token = your_bot_token_here
chat_id = your_chat_id_here

[Settings]
update_interval = 5.0
enable_log = true
```

You can also enable persistent log files with an environment variable:

```bash
export TELEWRAPPERZ_ENABLE_LOG=true
```

---

## 🚀 Usage

### Basic Usage

```bash
# Run any command
telewrapperz "python train.py"

# Run a long-running script
telewrapperz "python -u my_training_script.py --epochs 100"

# Save the full output locally and show a "Download Log" button
telewrapperz --log "python -u my_training_script.py --epochs 100"

# Test your bot connection
telewrapperz --test
```

### Progress Bar Demo

The repository includes a longer local demo that exercises different terminal output styles:

- plain log lines
- carriage-return spinners
- single-line progress bars
- training-style progress bars with metrics
- multi-line cursor-up dashboards
- Rich progress bars with multiple concurrent tasks

Run it directly:

```bash
python test/long_test.py
```

Run it through Telewrapperz:

```bash
telewrapperz --config config.yaml "python test/long_test.py"
```

For live progress demos, keep `settings.update_interval` low, for example `5.0`. Higher values such as `60.0` reduce Telegram traffic but may make short commands appear stuck on the initial `Starting...` message until the next update or the final forced refresh.

### What You'll See on Telegram

```
🖥 MacBook-Pro (PID: 12345)
⚙️ python train.py

Status: 🟢 Running
Time: 1:23:45
CPU: 45% | RAM: 62%
GPU 0: 87% | VRAM: 8.2/24.0GB (34%)

📜 Recent Log (Last 50):
┌──────────────────────────────
│ Epoch 15/100
│ Loss: 0.0234, Accuracy: 98.7%
│ Validation: 97.2%
│ ...
└──────────────────────────────

[🔄 Refresh] [🛑 Terminate Process]
```

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────┐
│                Telewrapperz                  │
├─────────────────────────────────────────────┤
│                                             │
│  ┌─────────────┐     ┌─────────────────┐   │
│  │   Command   │────▶│   Log Buffer    │   │
│  │   Process   │     │  (Last 50 lines)│   │
│  └─────────────┘     └────────┬────────┘   │
│                               │            │
│  ┌─────────────┐              │            │
│  │   System    │              │            │
│  │   Monitor   │──────────────┤            │
│  │ (CPU/RAM/GPU)              │            │
│  └─────────────┘              │            │
│                               ▼            │
│                    ┌─────────────────┐     │
│                    │    Telegram     │     │
│                    │    Dashboard    │     │
│                    │  (Auto-update)  │     │
│                    └─────────────────┘     │
│                                             │
└─────────────────────────────────────────────┘
```

---

## 📋 Command Line Options

| Option | Description |
|--------|-------------|
| `command` | The command to execute (wrap in quotes) |
| `--token` | Telegram Bot Token |
| `--chat_id` | Telegram Chat ID |
| `--config` | Path to configuration file |
| `--log` | Save full command output to a file and enable download button |
| `--test` | Run a connection test |

---

## 💾 Log Files

Full log files are disabled by default unless you pass `--log`, set `settings.enable_log: true`, or export `TELEWRAPPERZ_ENABLE_LOG=true`.

When enabled, Telewrapperz writes logs to:

```text
telewrapperz_log/telewrapperz_YYYYMMDD_HHMMSS.log
```

The Telegram dashboard also shows a **Scarica Log / Download Log** button while that file exists.

---

## 🔧 How to Get Your Telegram Credentials

### 1. Create a Bot Token
1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
2. Send `/newbot` and follow the instructions
3. Copy the token provided

### 2. Get Your Chat ID
1. Start a chat with your new bot
2. Send any message to the bot
3. Visit: `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
4. Look for `"chat":{"id":XXXXXXXX}` — that's your Chat ID

---

## 💡 Tips & Best Practices

- 🐍 Use `python -u` for unbuffered Python output
- 📝 The dashboard shows the **last 50 lines** of output
- ⏰ Dashboard updates every **5 seconds** (configurable via `update_interval`)
- 🖥️ GPU stats only appear if NVIDIA GPU is detected
- 🔄 Use the **Refresh** button for immediate updates
- 📈 Progress bars (`tqdm`, `rich`, carriage-return bars, and simple cursor-up dashboards) are handled by the log buffer
- 🤖 Run only one active Telewrapperz polling instance per Telegram bot token. Telegram will raise `Conflict: terminated by other getUpdates request` if two wrappers poll the same bot at once, which can break inline buttons.

---

## 🖥️ Platform Support

| Platform | Terminal Emulation | Notes |
|----------|-------------------|-------|
| **Linux** | PTY (full) | Best support, native terminal emulation |
| **macOS** | PTY (full) | Native terminal emulation |
| **Windows** | PIPE | Subprocess with line-buffered output |

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<p align="center">
  Made with ❤️ for remote monitoring
</p>
