🤖 Friday Chatbot

Friday is an advanced Telegram chatbot/userbot engineered with an asynchronous LLM pipeline via the Groq API and powered by the Pyrogram framework.

Unlike standard, robotic assistants, Friday is configured with a sharp, witty, and hyper-realistic 16-year-old coding enthusiast from Delhi persona. She communicates natively in ultra-short Hinglish, processes dynamic context, responds intelligently to stickers/images, and features intelligent context handling.

---

🚀 Key Features

• 🎭 Immersive Personality Engine: Powered by Groq's llama-3.1-8b-instant model, configured with explicit constraints for authentic Hinglish, internet slang, concise single-line texting, and adaptive emotional modes (ranging from friendly teasing to soft empathy).
• ⚡ Asynchronous Architecture: Completely non-blocking event loops built with asyncio, handling incoming messages, media analysis, and API calls concurrently.
• 📨 Smart DM Burst Grouping: Implements a message-burst buffer mechanism (DM_BURST_DELAY = 3.0). Instead of firing individual API responses to rapid-fire sequential texts, it merges closely-timed messages into a single coherent prompt.
• 🖼️ Multimodal Capabilities: Automatically downloads and processes user-sent images using a local Salesforce/blip-image-captioning-base pipeline to understand visual context before passing description data to the core LLM.
• 🎭 Dynamic Reactions & Stickers: Programmed to intelligently react via the Telegram Bot API (setMessageReaction) using a strict subset of human-like emojis and can contextually counter-reply with categorized stickers.
• 🛠️ Robust Admin/Owner Suite: Integrated commands for live configuration reloads (/reload), performance benchmarks (/ping), user memory wipes (/reset), and live runtime blacklist controls (/add / /rm).

---

🛠️ Configuration & Environment Setup

The script loads runtime configurations dynamically from a localized .env file.

Create a .env file in the root directory and define the following variables:

API_ID=your_telegram_api_id
API_HASH=your_telegram_api_hash
BOT_TOKEN=your_telegram_bot_token
OWNER_ID=your_numeric_telegram_user_id
GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=llama-3.1-8b-instant
BLOCKED_USER_IDS=

📂 System Architecture

• bot.py - Main execution engine containing the Pyrogram event handlers, local chat history managers (chats/*.json), image processors, and the core Groq orchestration logic.

• sticker_manager.py / stickers.py - Dynamic helper utilities utilized to cache, categorize, and dynamically load Telegram sticker sets into local memory maps during execution.

• friday_tasks.log - An automated task-logging file where contextually parsed action items are appended whenever the AI flags an interaction with the log_task structural schema.

⚙️ Core Command Set

• /help - Visualizes user-facing utility documentation and controls.

• /reset - Fully wipes the user's localized JSON interaction history.

• /ping (Owner Only) - Outputs execution benchmarks, loop round-trip latency (ms), and server uptime.

• /reload (Owner Only) - Flushes the state machine environment variables and fully refreshes the .env cache without restarting the process.

• /add <user_id> (Owner Only) - Appends a targeted user ID to the global conversation blacklist array.

• /rm <user_id> (Owner Only) - Removes a targeted user from the blacklist array.

Developer Credits

• Developer: urstarkz
• Website: urstark.is-a.dev
• Telegram: t.me/urstarkz
• Instagram: @urstarkz

📜 License

This repository is distributed under the standard open-source conventions. Review local repository metadata files for specific terms.