Moodcast

Telegram bot for movie and TV show recommendations based on user mood and plot themes

_{Recommendation card with poster, ratings, navigation buttons and watchlist toggle}

Moodcast is an asynchronous Telegram bot that suggests films and TV series based on free-form mood descriptions and plot keywords.

The bot combines zero-shot emotion classification via Hugging Face Transformers, an intent parser for genre and theme extraction, and Kinopoisk API integration with multi-factor catalog scoring. A local SQLite database stores user bookmarks.

• Free-text mood analysis using the MoritzLaurer/mDeBERTa-v3-base-mnli-xnli model across 15 emotion categories
• Intent extraction for story themes (space, survival, superheroes, heists, zombies) and specific content types (documentaries, short films, 18+)
• Multi-factor scoring algorithm weighting Kinopoisk/IMDb ratings, genre relevance, country filters, and release dates
• Interactive Telegram cards with movie posters, synopsis, runtime, direct Kinopoisk links, and pagination
• Personal watchlist stored locally in SQLite with one-click toggles (/watchlist)
• Quick random hit mode for top-rated recommendations without text input (/random)
• Key rotation and automatic failover across multiple Kinopoisk API keys with rate-limit protection

moodcast/
├── main.py                  # Bot entry point and lifecycle management
├── moodcast_core/           # Core library
│   ├── config.py            # Configuration, genre mapping, scoring weights
│   ├── database.py          # SQLite persistence for user bookmarks
│   ├── handlers.py          # Telegram command and callback handlers
│   ├── intent.py            # Intent extraction and keyword parsing
│   ├── kinopoisk.py         # Async Kinopoisk API client and ranking engine
│   ├── models.py            # Dataclasses and enum definitions
│   ├── nlp.py               # Hugging Face zero-shot classification pipeline
│   └── utils.py             # Formatting and HTML helpers
├── docs/screenshots/        # Documentation assets
├── requirements.txt         # Project dependencies
├── .env.example             # Template for required environment variables
├── .gitignore
├── LICENSE
└── README.md

• Python 3.10 or newer
• A Telegram bot token from @BotFather
• At least one API key from kinopoiskapiunofficial.tech

git clone https://github.com/DamianEhrenburg/moodcast.git
cd moodcast

python -m venv venv

# Windows:
venv\Scripts\activate

# Linux / macOS:
source venv/bin/activate

pip install -r requirements.txt

Create a .env file based on .env.example:

cp .env.example .env

Set your bot token and API keys in .env:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
KINOPOISK_API_KEY=your_primary_key_here,your_secondary_key_here

Multiple Kinopoisk API keys can be specified as a comma-separated list to support automatic rotation when daily quotas are reached.

python main.py

• User bookmarks are stored locally in an SQLite database (moodcast.db).
• The bot does not transmit user data or viewing history to external services, other than necessary search requests to Kinopoisk and Telegram APIs.
• Text emotion classification is performed locally on the machine via PyTorch.

git clone https://github.com/DamianEhrenburg/moodcast.git
cd moodcast
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

TELEGRAM_BOT_TOKEN=ваш_токен_бота
KINOPOISK_API_KEY=первый_ключ,второй_ключ

python main.py

Moodcast is distributed under the MIT License.