Alya-chan Telegram Bot

🌸 Project Overview

Alya-chan is an AI-powered Telegram bot based on Alya from the anime/manga series "時々ボソッとロシア語でデレる隣のアーリャさん" (Alya Sometimes Hides Her Feelings in Russian), commonly known as "Roshidere". The bot features Alya's unique tsundere personality with Russian expressions and provides powerful AI capabilities powered by Google's Gemini model.

✨ Key Features

• 🌸 Dynamic Personality - Tsundere character with evolving relationship levels
• 💫 Memory System - Context-aware conversations using RAG technology
• 🧠 Emotion Detection - Recognizes user emotions and responds appropriately
• 🎭 Multi-mood Responses - Various response styles based on context
• 🔍 Media Analysis - Vision capabilities for images and documents
• 🎯 Smart Web Search - Advanced search capabilities with multiple modes

For a complete list of commands and features, see COMMANDS.md.

🛠️ Technology Stack

• Python 3.8+ - Core language
• python-telegram-bot v21 - Telegram API wrapper with async support
• Google Gemini 2.5 Flash - Primary AI language model
• MySQL - Database storage
• ChromaDB - Vector database for RAG implementation
• HuggingFace Models - Emotion detection and NLP tasks
• aiohttp - Async HTTP client for API interactions

🚀 Installation

Prerequisites

• Python 3.8 or higher
• Git
• A Telegram Bot Token (from @BotFather)
• Google Gemini API Key

Basic Setup

1. Clone the repository

   git clone https://github.com/Afdaan/alya-bot-telegram.git
   cd alya-bot-telegram

2. Create a virtual environment

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment variables

   cp .env.example .env
   # Edit .env with your API keys

5. Run the bot

   python main.py

For detailed configuration options and deployment instructions, see the Configuration section below.

⚙️ Configuration

Required Environment Variables

# Telegram Bot
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

# Admin Settings
ADMIN_IDS=your_telegram_id  # Comma-separated for multiple admins (e.g., 123456,789012)

# Gemini AI
GEMINI_API_KEYS=your_gemini_api_key  # Comma-separated for key rotation
GEMINI_MODEL=gemini-2.0-flash

Optional Environment Variables

# External APIs
SAUCENAO_API_KEY=your_saucenao_api_key  # For anime image source detection
GOOGLE_CSE_ID=your_google_search_engine_id  # For web search capabilities
GOOGLE_API_KEYS=your_google_api_key  # For Google Custom Search Engine

# Database Settings (defaults to SQLite)
DATABASE_URL=sqlite:///data/alya.db
# Alternative: DATABASE_URL=postgresql://user:password@localhost/alya

# Performance Settings
MEMORY_LIMIT=200  # Maximum number of messages to remember per user
CACHE_EXPIRY=3600  # Cache expiry time in seconds

API Key Rotation System

Alya supports multiple API keys to ensure reliability and handle rate limits:

# Multiple comma-separated keys for automatic rotation
GEMINI_API_KEYS=key1,key2,key3
GOOGLE_API_KEYS=key1,key2,key3

The bot will automatically:

• Rotate to the next key when rate limits are reached
• Track usage and distribute load across keys
• Fall back gracefully if all keys are exhausted

Database Configuration

Read on Database Configuration for detailed instructions on setting up your database.

🚀 Deployment Options

Development Mode

python main.py

Production with TMUX

tmux new-session -s alya-bot
python main.py
# Ctrl+B then D to detach
# tmux attach -t alya-bot to reconnect

Docker Deployment

# Build image
docker build -t alya-bot .

# Run container
docker run -d \
  --name alya-bot \
  --restart unless-stopped \
  --env-file .env \
  -v ./data:/app/data \
  alya-bot

🏗️ Architecture

Core Components

• Bot Core - Main initialization and command registration
• Handlers - Message processors for different commands and features
• Memory System - RAG-based conversation context manager
• NLP Engine - Emotion detection and intent recognition
• Persona Manager - Controls bot's personality and response style
• Database - Stores user data, relationships and conversation history

Database Schema

• Users - User profiles with relationship progression
• Conversations - Message history and context tracking
• Memory - Vector embeddings for RAG implementation
• Settings - User preferences and configurations
• Stats - Usage statistics and analytics

🛡️ Security Features

• Input validation and sanitization
• Protection against prompt injection
• Rate limiting to prevent abuse
• Secure storage of API keys
• Safe HTML/Markdown rendering
• Comprehensive error handling and logging

🧪 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following our coding standards
4. Test your changes thoroughly
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Before submitting, please make sure your code follows our style guidelines as documented in the repo.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contact

• Creator: Afdaan
• Website: alif.horn-yastudio.com
• GitHub: Afdaan
• Facebook: Afdaan

🤖 Bot Commands

For a complete list of commands and their usage, please refer to the COMMANDS.md file.

🙏 Acknowledgments

• Alya character from "Roshidere" anime/manga series
• Google Gemini AI for natural language processing
• Telegram for their excellent Bot API
• SauceNAO for anime image source identification
• The open source community for various libraries and tools

---

Crafted with devops && coffee by Afdaan☕⚙️