job-stalker 0.2.0

Telegram bot that filters job vacancies with a web UI

JobStalker | Telegram Vacancy Filter Bot

This is a Telegram bot that filters job vacancies from specified channels using a machine learning model. It has a web interface for configuration, authorization, and viewing results.

✨ Features

• Filters vacancies from public Telegram channels.
• Uses a machine learning model to determine the relevance of a vacancy.
• Web interface for easy configuration and authorization in Telegram.
• Real-time monitoring of new vacancies.
• Saves results in a database.

🖼 Screenshots

🚀 Installation and Usage

⚠️ Important! This application is a Telegram client that works on behalf of your personal account. You must obtain your own API_ID and API_HASH from my.telegram.org.

Do not share your API keys with anyone. Using someone else's keys or sharing yours is a violation of Telegram's terms of service and can lead to your account being banned.

There are four ways to run this application:

1. Install via pip (Recommended)
2. Using Docker
3. From source code
4. As a standalone executable

1️⃣ Install via pip

Use this option if you don't need the source code and just want to start quickly.

Prerequisites:

• Python 3.11+ and pip.

Steps:

1. Create a working directory:

   mkdir job-stalker-data
   cd job-stalker-data
   

2. Install the package:

   pip install job-stalker       # for CPU
   pip install "job-stalker[gpu]"  # or just job-stalker if you don't need GPU monitoring (optional)
   

3. Download and configure .env:

   curl -o .env.example https://raw.githubusercontent.com/10sorry/JobStalker/main/.env.example
   cp .env.example .env
   # fill in API_ID, API_HASH and optional proxy settings
   

4. Run the web interface:

   job-stalker
   

   The server will start on http://0.0.0.0:8000. Run the command from the directory that contains .env.

2️⃣ Using Docker

This is the easiest and recommended way to run the application.

Prerequisites:

• Docker installed on your system.
• Docker Compose installed on your system.

Steps:

1. Clone the repository:

   git clone <repository-url>
   cd telegram-filter-bot
   

2. Create the environment file: Copy the example .env.example file to .env and fill in your details.

   cp .env.example .env
   

   You will need to get your API_ID and API_HASH from my.telegram.org.

3. Build and run the container:

   docker-compose up --build
   

   This will build the Docker image and start the application.

4. Open the web interface: Open your web browser and go to http://localhost:8000.

5. Authorize and configure:

   • You will be prompted to authorize your Telegram account.
   • In the settings, specify the channels you want to monitor and other parameters.

6. Start scanning: Click the "START SCAN" button to begin the filtering process.

3️⃣ From Source Code

This method is for users who want to run the application directly from the source code.

Prerequisites:

• Python 3.11 or higher.
• venv module for creating virtual environments.

Steps:

1. Clone the repository:

   git clone <repository-url>
   cd telegram-filter-bot
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate
   

   On Windows, use venv\Scripts\activate.

3. Install the dependencies (editable mode):

   pip install -e ".[gpu]"   # or without [gpu] if you don't need GPU monitoring
   

4. Create the environment file: Copy the example .env.example file to .env and fill in your details.

   cp .env.example .env
   

5. Run the application:

   job-stalker
   

   (You can also use python -m job_stalker.run, but the CLI script is shorter.) This will start the web server.

6. Open the web interface: Open your web browser and go to http://localhost:8000 and follow the configuration steps as described in the Docker section.

4️⃣ Standalone Executable

This method is for users who want to run the application without installing Python or any dependencies.

Steps:

1. Download the executable: Go to the [Releases](/releases) page and download the telegram_filter_bot executable for your operating system.

2. Create the environment file: Create a .env file in the same directory as the executable and fill in your API_ID and API_HASH.

   API_ID=...
   API_HASH=...
   # Optional proxy settings
   # PROXY_ENABLED=false
   # PROXY_HOST=
   # PROXY_PORT=
   # PROXY_USER=
   # PROXY_PASS=
   

3. Run the executable: On Linux and macOS, you may need to make the file executable first:

   chmod +x telegram_filter_bot
   

   Then, run the application:

   ./telegram_filter_bot
   

   On Windows, you can just double-click the .exe file.

4. Open the web interface: Open your web browser and go to http://localhost:8000.

🛠 Development

If you want to contribute to the project, you can follow the instructions for running from source code.

Building the pip package

Artifacts for PyPI/TestPyPI are built from pyproject.toml.

pip install build twine
python -m build            # produces dist/*.whl and dist/*.tar.gz
twine upload --repository testpypi dist/*
# after verification:
twine upload dist/*

Building the Executable

To build the executable yourself, you need to have Python and the project dependencies installed. Then, run the build script:

python pyinstaller_build.py

The executable will be created in the dist directory.

⚙️ .gitignore

The following files and directories are ignored by Git:

.env
/data/
/venv/
/build/
/dist/
*.spec
__pycache__/
*.pyc

---