TeleFaceBot

A Telegram bot designed to find faces in photos similar to a provided photo, using pre-indexed embeddings from other Telegram messages (e.g., from a channel or group). It leverages facenet-pytorch for face detection and embedding generation and pyrogram for interacting with the Telegram API.

This version has been refactored for better configuration and modularity.

Features

• Accepts photos via private message.
• Detects faces in the submitted photo.
• Compares detected faces against a pre-built index of face embeddings.
• Forwards the original messages containing the most similar faces.
• Uses a .env file for configuration.
• Separates face processing logic (processing.py) from bot logic (bot.py).

Project Structure

.
├── .env                # Configuration file (you need to create this)
├── bot.py              # Main Pyrogram bot application logic
├── processing.py       # Face detection, embedding, and similarity functions
├── downloader.py       # Script to download media (needs specific chat ID)
├── indexer.py          # Script to create face embedding indexes (.pkl files)
├── indexer.ipynb       # Optional: Jupyter notebook version for indexing
├── requirements.txt    # Python dependencies
├── README.md           # This file
└── ...                 # Other files (e.g., generated index files, downloaded data)

Setup

1. Prerequisites

• Python 3.8+
• Telegram API Credentials:
  • API ID and API Hash from my.telegram.org
  • Bot Token from @BotFather on Telegram.

2. Installation

Clone the repository and install the required Python packages:

git clone <your-repo-url>
cd <repository-folder>
pip install -r requirements.txt 
# Or install manually:
# pip install pyrogram Pillow facenet-pytorch torch torchvision opencv-python python-dotenv numpy

(Note: You might need specific versions of torch and torchvision depending on your system and CUDA setup if using a GPU. Check the PyTorch website for installation instructions.)

3. Configuration

Create a .env file in the root directory of the project. You can copy the example below and fill in your actual values:

# .env file

# === Telegram API Credentials ===
# Get from my.telegram.org
API_ID=YOUR_API_ID
API_HASH=YOUR_API_HASH

# Get from @BotFather on Telegram
BOT_TOKEN=YOUR_BOT_TOKEN

# === Proxy Settings (Optional) ===
# JSON format, leave empty {} if no proxy needed
# Example: PROXY={"scheme": "socks5", "hostname": "127.0.0.1", "port": 1080}
PROXY={}

# === Downloader Settings ===
# Target chat ID (integer ID or username string) for downloader.py
DOWNLOADER_TARGET_CHAT_ID=YOUR_TARGET_CHAT_ID_OR_USERNAME
# Directory where downloader.py saves images
DOWNLOADER_OUTPUT_DIR=data

# === Indexer Settings ===
# Directory where indexer.py/indexer.ipynb reads images from
INDEXER_INPUT_DIR=data
# Output file path for the generated index (used by indexer.py/indexer.ipynb)
INDEXER_OUTPUT_FILE=index1.pkl

# === Bot Settings ===
# Comma-separated list of index files (.pkl) for the bot to load.
# Should match the output(s) from the indexer (INDEXER_OUTPUT_FILE).
INDEX_FILES=index1.pkl

Important:

• Replace YOUR_API_ID, YOUR_API_HASH, YOUR_BOT_TOKEN, and YOUR_TARGET_CHAT_ID_OR_USERNAME with your actual values.
• Adjust PROXY if needed.
• Ensure DOWNLOADER_OUTPUT_DIR and INDEXER_INPUT_DIR match if the downloader output is directly used by the indexer.
• Ensure the filenames listed in INDEX_FILES correspond to the files generated by the indexer script/notebook (like INDEXER_OUTPUT_FILE).

4. Data Download and Indexing

• Run downloader.py: Configure DOWNLOADER_TARGET_CHAT_ID and DOWNLOADER_OUTPUT_DIR in .env. Then run python downloader.py to download images from the specified chat into the output directory. You'll run this using your user account session (it will prompt for login details if my_account.session doesn't exist) as bots cannot typically access chat history this way.
• Run indexer.py or indexer.ipynb: Configure INDEXER_INPUT_DIR (usually the same as DOWNLOADER_OUTPUT_DIR) and INDEXER_OUTPUT_FILE in .env. Run either python indexer.py or execute the cells in the indexer.ipynb notebook. This processes images in the input directory, detects faces, generates embeddings, and saves them into the specified .pkl index file. Make sure the generated file name matches what's listed in INDEX_FILES in your .env.

5. Running the Bot

Once the .env file is configured and the index files are generated and listed in .env, you can run the bot:

python bot.py

The bot will load the configuration, initialize the models, load the index files, and start listening for incoming photos.

Basic Usage

1. Start a chat with your bot on Telegram.
2. Send the /start command (or /help).
3. Send a photo containing a face you want to search for.
4. The bot will process the photo, search the index, and display a button to view similar images.
5. Click the button to see the original messages containing the matching faces forwarded to you.

Credits

• Built upon the foundation provided by AlisaLC's repository
• Uses facenet-pytorch for MTCNN and FaceNet implementations.
• Uses pyrogram for Telegram API interaction.