TaskFinder is a lightweight, production-ready, asynchronous Telegram userbot designed to monitor freelance and software development tasks from public channels and groups in real-time.
Instead of simple keyword matching, TaskFinder leverages a two-stage filtering pipeline—combining deterministic heuristic scoring with optional AI adjudication—to route high-confidence tasks straight to your Telegram inbox while keeping noise, spammers, and agency/parser channels out.
- Asynchronous Monitoring: Monitors incoming messages across all public groups, supergroups, and channels your Telegram account is joined to.
- Two-Stage Order Evaluation:
- Heuristic Intent Scoring: Scores messages based on intent signals (hiring language, budgets, deadlines, tech nouns) and penalties (job seekers, generic debugging questions, full-time vacancies).
- AI Adjudication: Automatically forwards borderline ("gray zone") candidates to an OpenAI-compatible API (e.g., OpenRouter or local Ollama) for strict verification. AI is skipped for high-confidence matches to keep latency and costs low.
- SQLite Candidate Corpus: Persists all candidate messages to an SQLite database (
data/candidates.db) with complete scoring breakdowns, decisions, and operator feedback. - Feedback & Tuning Loop: Supports direct operator feedback (
👍/👎) via a local web panel and an admin Telegram bot. The feedback is saved to SQLite to calibrate weights and verify accuracy. - Automated Source Discovery: Safely searches public chats by keyword query in the background and suggests candidate chats to join.
- Safe Background Joiner: Automatically joins approved chats with a randomized pacing delay (3–5 chats/day max) to avoid Telegram rate limits and account flags.
- Automated Mute & Folder Routing: Newly joined chats are instantly muted for 10 years and added to a dedicated Telegram folder named "Routes" for a clean workspace.
- Marketplace & Parser Rejection: Automatically filter out marketplace links (Upwork, Freelance.ru, Kwork, etc.) and bot-parser repost signatures to ensure direct client contacts only.
- Robustness & Rate-Limiting: Bounded async queues prevent pipeline bottlenecks, and uvicorn binds cleanly on configurable ports.
Telegram Incoming Message Stream
│
[ DM / Self-Message Filter ]
│
[ Parser/Marketplace Veto ]
│
[ Keyword & Exclude Filter ]
│
[ Exact Deduplicator ]
│
[ Deterministic Intent Scorer ]
│
┌──────────┴──────────┐
▼ ▼
Score >= High Mid <= Score < High
│ │
│ [ AI Enabled? ]
│ ┌──────┴──────┐
│ Yes No
│ ▼ ▼
│ [ AI Scorer ] [ Skip AI ]
│ ┌─────┴─────┐ │
│ Approved Rejected │
│ ▼ ▼ │
├────────┴────────► Drop │
▼ ▼
[ Alert Queue ] [ SQLite Corpus ]
│
[ Serialized Sender ]
│
Saved Messages
- Python 3.10+
- Telegram API Credentials (
API_ID,API_HASH). Get them from my.telegram.org.
- Clone the repository and navigate to its root:
git clone https://github.com/VernaculusF/TaskFinder.git cd TaskFinder - Create and activate a virtual environment:
python3 -m venv .venv source .venv/bin/activate - Install dependencies:
pip install -r requirements.txt
- Copy the environment template and fill in your variables:
cp .env.example .env # Edit .env with your credentials
Start the monitoring service:
python -m task_finderNote: On the first run, the terminal will prompt you to enter your phone number, login code, and 2FA password (if enabled) to create the persistent session file inside data/.
TaskFinder is configured via .env variables:
# --- Telegram Userbot ---API_ID=12345678
API_HASH=your_api_hash
TARGET_CHAT_ID=me # Numeric ID, username, or "me" for Saved MessagesSESSION_PATH=data/task_finder
# --- Connection ---TELEGRAM_PROXY= # Optional tg://proxy?server=... MTProto proxy URL# --- Admin Web Panel ---ADMIN_HOST=0.0.0.0
ADMIN_PORT=8095
# --- Admin Bot ---ADMIN_BOT_TOKEN= # Telegram Bot Token from @BotFatherADMIN_USER_IDS=8215172504 # Comma-separated admin Telegram IDs# --- Automated Chat Discovery ---DISCOVERY_ENABLED=true
DISCOVERY_QUERIES=freelance python,разработка ботов,заказ разработка
DISCOVERY_LIMIT=30
DISCOVERY_INTERVAL_SECONDS=86400
DISCOVERY_DELAY_SECONDS=10
# --- Live Joiner & Pacing ---JOINER_POLL_SECONDS=300TaskFinder includes configuration and scripts for running as a background systemd service.
- Deploy to server:
Make
/home/jester/Work/TaskFinder/deploy.shexecutable and run it to deploy, compile, and configure the systemd unit automatically on your remote VPS:./deploy.sh
- Control the service:
Use the helper script to manage the background service:
./scripts/task-finder-service start ./scripts/task-finder-service status ./scripts/task-finder-service logs ./scripts/task-finder-service stop
A clean, responsive dashboard designed for system monitoring and rule calibration.
- Overview: Real-time stats, connection state, system uptime, and matching metrics.
- Matches: Review candidate texts, check scores, see reason breakdowns, provide
👍/👎feedback, and open original messages. - Discovery: Review newly discovered public chats. Approve or reject candidates, and manually join them.
- Rules: Edit keywords and exclude terms at runtime. Toggle AI scoring.
Interact with TaskFinder directly inside Telegram:
/status— View current scan statistics, uptime, and system health./rules— Show active keyword and exclude rules./ai on|off— Toggle AI scoring./matches— View the 10 newest candidates with inline feedback actions./sources— List monitored channels and message throughput./discovery— List discovered chat candidates with approve/reject buttons./feedback <id> <good|bad>— Fallback command for candidate evaluation./pause//resume— Pause or resume monitoring operations.
MIT