Metadata-Version: 2.4
Name: owlbot-remote
Version: 1.0.0b0
Summary: OwlBot — Modular Telegram Remote Control Agent for Windows
Author: sepehrHi
License-Expression: MIT
Project-URL: Homepage, https://github.com/sepehrHi/OwlBot
Project-URL: Repository, https://github.com/sepehrHi/OwlBot
Project-URL: Bug Tracker, https://github.com/sepehrHi/OwlBot/issues
Project-URL: Documentation, https://github.com/sepehrHi/OwlBot#readme
Keywords: remote-control,telegram-bot,windows,automation,owlbot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Communications :: Chat
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Natural Language :: English
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyTelegramBotAPI>=4.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pyperclip>=1.8.2
Provides-Extra: ui
Requires-Dist: pyautogui>=0.9.53; extra == "ui"
Requires-Dist: opencv-python>=4.7.0; extra == "ui"
Requires-Dist: numpy>=1.24.0; extra == "ui"
Provides-Extra: windows
Requires-Dist: wmi>=1.5.1; sys_platform == "win32" and extra == "windows"
Requires-Dist: pycaw>=20181208; sys_platform == "win32" and extra == "windows"
Requires-Dist: keyboard>=0.13.5; sys_platform == "win32" and extra == "windows"
Requires-Dist: pywifi>=1.1.12; sys_platform == "win32" and extra == "windows"
Requires-Dist: pyaudio>=0.2.11; sys_platform == "win32" and extra == "windows"
Provides-Extra: all
Requires-Dist: owlbot-remote[ui,windows]; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: wheel>=0.40.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# 🦉 OwlBot (owlbot-remote)

[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/owlbot-remote.svg)](https://pypi.org/project/owlbot-remote/)
[![CI](https://github.com/sepehrHi/OwlBot/actions/workflows/python-package.yml/badge.svg)](https://github.com/sepehrHi/OwlBot/actions/workflows/python-package.yml)

**OwlBot** is a production‑ready modular remote‑control agent for **Windows**, operated via **Telegram**. It lets you monitor system resources, manage files, control peripherals, capture screen / webcam, and more — all from your phone.

---

## ✨ Features

- 🧩 **100% Modular** — load only the modules you need
- 💉 **Dependency‑Injected** core — ready for extra platforms (Discord, SSH, …)
- 🛡️ **User‑ID whitelisting** and centralized error handling
- 📊 **Live resource monitoring** (CPU, RAM, Disk, temperature)
- 🎹 **Peripheral control** — keyboard, mouse, hotkeys, audio volume
- 📸 **Screen capture, webcam, timelapse, and screen streaming**
- 🔊 **Voice recording, volume control, and incoming‑voice playback**

---

## 🚀 Quick Start

### Prerequisites

- Python **3.11+**
- Windows (some modules require Win32 API)
- `ffmpeg` in `PATH` if you use voice playback (download from [ffmpeg.org](https://ffmpeg.org/))
- A [Telegram Bot Token](https://t.me/BotFather)

### Install from PyPI

```bash
pip install owlbot-remote[all]
```

To install only the cross‑platform subset (no audio, no keyboard, no WMI):

```bash
pip install owlbot-remote
```

### Minimal deployment script

```python
from owlbot import OwlBot

bot = OwlBot(
    token="YOUR_BOT_TOKEN",
    authorized_users=[123456789],       # your Telegram user ID
    modules=["system", "screen", "files", "input", "processes", "monitoring"],
)
bot.run()
```

Or via the CLI entry point:

```bash
owlbot --token YOUR_BOT_TOKEN --users 123456789,987654321
```

---

## 📝 Logging

By default OwlBot logs to both the console **and** a rotating‑free log file
(`owlbot.log` in the current directory). All of this is configurable:

```python
from owlbot import OwlBot

bot = OwlBot(
    token="YOUR_BOT_TOKEN",
    authorized_users=[123456789],
    log_level="DEBUG",       # DEBUG | INFO | WARNING | ERROR | CRITICAL
    log_file="owlbot.log",   # set to None (or "") to disable the log file only
    enable_logging=True,     # set to False to disable logging entirely
)
```

| Goal | Setting |
|---|---|
| Console + file logging (default) | leave as default |
| Console only, no log file on disk | `log_file=None` |
| Completely silent (no console, no file) | `enable_logging=False` |

The same options are available from the CLI:

```bash
owlbot --token TOKEN --users 123 --log-level DEBUG   # verbose logging
owlbot --token TOKEN --users 123 --no-log-file        # console only, no file
owlbot --token TOKEN --users 123 --disable-logging    # fully silent
```

---

## 🕹️ Available Modules & Commands

| Module | Command | Description |
|---|---|---|
| **system** | `/status` | CPU, RAM, Disk, Network, Battery |
| | `/uptime` | System uptime |
| | `/ping` | Health‑check |
| | `/lock` | Lock workstation |
| | `/shutdown` | Shut down PC |
| | `/restart` | Reboot PC |
| **screen** | `/screenshot` | Capture desktop |
| | `/webcam` | Capture webcam photo |
| | `/timelapse <s> <n>` | Series of screenshots |
| | `/startstream` | Start screen streaming |
| | `/stopstream` | Stop & send video |
| **input** | `/type <text>` | Type text |
| | `/move <x> <y>` | Move mouse |
| | `/mousepos` | Get mouse position |
| | `/mouse <action>` | Click / scroll / drag |
| | `/hotkey <k1+k2>` | Send hotkey |
| | `/msg <text>` | Show message box |
| **audio** | `/mute` / `/unmute` | Toggle mute |
| | `/volume <0‑100>` | Set volume |
| | `/startrec [sec]` | Record microphone |
| | `/stoprec` | Stop & send recording |
| | `/playvoice` | Toggle incoming‑voice playback |
| **files** | `/listdir [path]` | List directory |
| | `/getfile <path>` | Download file |
| | `/hide` / `/show` | Toggle hidden attribute |
| | `/file copy/move/delete` | File operations |
| **processes** | `/tasklist` | List running processes |
| | `/killtask <exe>` | Kill a process |
| | `/run` / `/cmd` / `/script` | Execute commands |
| **monitoring** | `/monitor <cpu\|ram\|disk\|temp>` | Periodic alerts |
| | `/stopmonitor` | Stop alerts |
| **network** | `/wifiscan` | Scan Wi‑Fi networks |
| | `/clipboard get\|set` | Read / write clipboard |

---

## 📂 Project Structure

```
owlbot/
├── __init__.py           # Package exports & version
├── config/               # BotConfig dataclass
├── core/
│   ├── bot.py            # Main OwlBot engine
│   ├── decorators.py     # @authorized_only / @safe_reply
│   └── utils.py          # Shared helpers
├── modules/
│   ├── base.py           # BaseModule interface
│   ├── system.py         # System control
│   ├── screen.py         # Screen/webcam/stream
│   ├── files.py          # File operations
│   ├── processes.py      # Process management
│   ├── input.py          # Keyboard/mouse (Windows)
│   ├── audio.py          # Audio control (Windows)
│   ├── monitoring.py     # Resource monitoring
│   └── network.py        # Wi‑Fi / clipboard
└── platform/
    └── telegram.py       # Telegram adapter
```

---

## 🧪 Testing

The test suite uses `pytest` and makes no real network / Telegram calls.

```bash
pip install -e .[dev]
pytest -v
```

Lint (matches CI, config lives in `.flake8`):

```bash
flake8 src tests
```

---

## 🔧 Installation extras

| Extra | Includes |
|---|---|
| `owlbot-remote[ui]` | `pyautogui`, `opencv‑python`, `numpy` |
| `owlbot-remote[windows]` | `wmi`, `pycaw`, `keyboard`, `pywifi`, `pyaudio` |
| `owlbot-remote[all]` | Everything above |
| `owlbot-remote[dev]` | Dev / CI tools (`build`, `flake8`, `pytest`) |

---

## 📄 License

Distributed under the **MIT License**. See `LICENSE` for details.

---

*Maintained by **MR_owl** 🦉*
