🏆 Quoto — Quote of the Day

English | Русский

A Telegram bot that tracks quote days and only publishes a quote of the day when the conversation was actually worth quoting.

✨ Features

• 🏆 Quote of the Day Flow — scores messages between two daily cutoff points
• 🤖 AI Scoring — evaluates messages for humor, wit, depth, and memorability via OpenRouter API
• 🧵 Optional Quote Context — adds up to 5 consecutive or reply-linked messages only when needed
• 😴 Boring-Day Detection — if the day feels flat, the bot says so instead of forcing a weak quote
• ❤️ Reaction Context — sends emoji reactions to AI as context for each message
• 🧾 AI Audit Log — writes the exact OpenRouter request body and raw response to logs/ai_audit.jsonl for 7 days
• 🌐 Localized Interface — supports Russian, Ukrainian, English, and German UI text
• 🧭 One-Time Language Detection — if a group has no saved language, the next daily AI run chooses the best interface language and stores it
• 📏 Text Context — stores message length signals for transparent details
• 🧭 Single /start Control Panel — stats, group language, and close cleanup live behind inline buttons
• 📌 Auto-Pin — pins the winning quote in the chat
• 📊 Statistics — chat stats, personal stats, top authors, and rating breakdown
• ⏰ Scheduler — configurable daily time for quote selection
• 🐳 Docker Support — easy deployment with Docker Compose

⚙️ How It Works

1. Add the bot to your Telegram group and grant admin rights
2. Members chat as usual — the bot silently collects messages and reactions
3. The bot collects messages for the day from the previous cutoff to the next one
4. At the scheduled time (default 21:00), the bot evaluates the closed day
5. If there are fewer than 10 messages, the day is skipped silently
6. If there are 10+ messages, AI both scores messages and decides whether the whole day is quote-worthy
7. The best message is selected by the AI score; reactions and length are only context:

Component	Weight	Description
AI Score	100%	LLM-based evaluation with reaction context
Reactions	Context	Emoji reactions sent to AI when present
Length	Context	Stored for transparent quote details

8. If the quote needs setup, AI may attach a validated consecutive/reply-linked context block of up to 5 messages
9. If the group has no saved interface language yet, the same AI run selects one of ru, uk, en, or de and the bot stores it for future UI messages
10. If the day is boring, the bot posts a boring-day notice with a Details link instead of a weak quote

📌 Commands

Command	Description
/start	Opens the context-aware control panel

🚀 Quick Start

Prerequisites

• Python 3.10+
• PostgreSQL 16+ (in production Quoto runs on a shared core database — see the Database section below)
• Docker (optional)

Local Installation

# 1. Clone the repository
git clone https://github.com/FreshLabDev/quoto.git
cd quoto

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
. venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Apply database migrations
alembic upgrade head

Configuration

Create a .env file in the root directory (see .env.example):

BOT_TOKEN=your_telegram_bot_token
BOT_USERNAME=your_bot_username
# Production points DB_URL at the shared core-postgres as the quoto_core role
# (postgresql+asyncpg://quoto_core:***@core-postgres:5432/core). For local dev
# docker-compose builds it from the POSTGRES_* vars — see Database below.
DB_URL=postgresql+asyncpg://user:password@localhost:5432/dbname
OPENROUTER_API_KEY=sk-or-v1-your-key-here
OPENROUTER_EVAL_MODEL=poolside/laguna-s-2.1:free
# Used only if the primary eval model errors out after retries.
OPENROUTER_EVAL_FALLBACK_MODEL=poolside/laguna-s-2.1
OPENROUTER_EVAL_REASONING_EFFORT=medium
OPENROUTER_EVAL_MAX_TOKENS=32000
OPENROUTER_MEDIA_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free
OPENROUTER_MEDIA_FALLBACK_MODEL=google/gemini-2.5-flash-lite
OPENROUTER_MEDIA_REASONING_EFFORT=medium
OPENROUTER_HTTP_REFERER=https://t.me/quototbot
OPENROUTER_APP_TITLE=Quoto
MEDIA_ANALYSIS_ENABLED=True
MEDIA_PHASH_DISTANCE=5
MEDIA_CACHE_PROMPT_VERSION=v2
MEDIA_IMAGE_MAX_SIDE=1280
MEDIA_IMAGE_QUALITY=82
MEDIA_VIDEO_MAX_SECONDS=3600
MEDIA_VIDEO_LOW_RES_MAX_SECONDS=10800
MEDIA_VIDEO_MAX_HEIGHT=720
MEDIA_VIDEO_CRF=30
MEDIA_VIDEO_FPS=12
MEDIA_AUDIO_BITRATE=64k
MEDIA_AUDIO_SAMPLE_RATE=24000
MEDIA_COMMAND_TIMEOUT_SECONDS=300
MEDIA_PENDING_RETRY_INTERVAL_SECONDS=300
MEDIA_PENDING_RETRY_BATCH_SIZE=10
MEDIA_RETRY_MAX_ATTEMPTS=5
MEDIA_RETRY_BASE_DELAY_SECONDS=300
MEDIA_RETRY_MAX_DELAY_SECONDS=3600
MEDIA_PROVIDER_COOLDOWN_SECONDS=900
MEDIA_PENDING_ITEM_TIMEOUT_SECONDS=600
DEVELOPER_IDS=[1234567890]
QUOTE_HOUR=21
QUOTE_MINUTE=0
TIMEZONE=Europe/Kyiv
MIN_MESSAGES_FOR_AUTO_REVIEW=10
WEIGHT_REACTIONS=0.0
WEIGHT_AI=1.0
WEIGHT_LENGTH=0.0

Running

Use /start in a private chat or group. In groups, regular users see stats buttons, while admins also get group language controls.

python main.py

🐳 Docker Support

You can easily run the bot using Docker Compose:

docker-compose up -d --build

🗄️ Database

Quoto stores its data in PostgreSQL and shares one database with the other FreshLabDev bots (vido, branchy, searcher):

• In production it connects to the shared core database as the least-privilege role quoto_core. Quoto's own tables live in the quoto schema; shared identity, chats and language live in the core schema (core.person, core.chat, and the core.set_language / core.effective_language functions). Quoto's tables reference core.person and core.chat by the Telegram natural keys (user id, chat id) — there is no separate per-bot users/groups identity table.
• For local development docker-compose up starts a bundled Postgres seeded with a copy of the core schema (deploy/core-init.sql) so the foreign keys into core.person / core.chat resolve; the app's DB_URL is built from the POSTGRES_* variables in .env.

Apply migrations with alembic upgrade head (the Alembic version table lives in the quoto schema).

🛠️ Tech Stack

Layer	Technology
Framework	Aiogram 3
Database	Shared PostgreSQL core (schema quoto) + SQLAlchemy (Async)
Validation	Pydantic
AI	OpenRouter API (any LLM)
Scheduler	APScheduler
HTTP Client	HTTPX

📂 Project Structure

quoto/
├── app/
│   ├── ai.py           # OpenRouter AI integration & message evaluation
│   ├── config.py       # Settings, logging, environment variables
│   ├── core.py         # Core business logic (people, groups, messages)
│   ├── core_client.py  # Helpers over the shared core.* functions (touch, language)
│   ├── db.py           # Database session & initialization
│   ├── handlers.py     # Telegram bot handlers & commands
│   ├── menu.py         # /start control panel rendering
│   ├── models.py       # SQLAlchemy models (GroupSettings, Message, Quote, …) — FK into core.person/core.chat
│   ├── scheduler.py    # APScheduler jobs & quote of the day pipeline
│   ├── scoring.py      # Scoring engine & best quote selection
│   └── utils.py        # Utility functions
├── docker-compose.yml
├── Dockerfile
├── main.py             # Entry point
├── requirements.in
├── requirements.txt
└── .env.example

🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

©️ License

GNUv3 License — see LICENSE file for details

👤 Author

Created with ❤️ by FreshLabDev

⭐ Add a star to my project!