Development Analytic Bot

🚀 Тестовое задание

• Telegram-бот для аналитики по видео на основе задач на естественном языке

✅ Выполненные требования ТЗ:

1. Развернутая БД

   • Таблицы VideoSnapshot, Video
   • PostgreSQL с SQLAlchemy ORM
   • Парсинг данных с JSON

2. Backend логика

   • Работа с LLM асинхронно
   • Обработка TEXT -> SQL/SQL -> TEXT
   • Автоматизированный скрипт для загрузки данных с JSON

3. Телеграм бот

   • Асинхроннный бот aiogram
   • Принимает сообщения на русском языке и далее строит SQL запросы
   • В ответе одно число

🛠️ Технологии

⚡ Быстрый старт

1. Клонируйте репозиторий, затем войдите в папку проекта

git clone https://github.com/N1chegons/AnalyticsBot.git
cd AnalyticsBot

2. Создайте свой .env и измените переменные, исходя из ваших настроек для работы с переменными окружения на основе .env.example. Составляющее файла:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=my_db
DB_USER=user
DB_PASS=pass

API_KEY_LLM=your_github_token

TELEGRAM_API_TOKEN=your_telegram_token

Настройки переменных окружения

• Telegram Token — у @BotFather(/newbot - 'Name' - YourName_bot - Copy field(Use this token to access the HTTP API: ))
• GitHub Token — в настройках GitHub (поставьте галочку на read:user)

3. Запустите через Docker

docker-compose up --build

🏗 Архитектура

[Пользователь] → Текстовый запрос ("Сколько видео?")
         ↓
[LLM Service] → Промпт + схема БД + few-shot examples
         ↓
[GitHub Models] → Генерирует SQL (gpt-4o-mini)
         ↓
[Query Service] → Передает SQL в репозиторий
         ↓
[Repository] → Выполняет SELECT запрос через asyncpg
         ↓
[БД PostgreSQL] → Возвращает число
         ↓
[Telegram Bot] → Отвечает пользователю ("📊 42")

🧠 Подход к Text-to-SQL

Детальное описание схемы — в промпт передаются все таблицы, колонки, связи и индексы

Few-shot обучение — 10+ примеров вопросов с эталонными SQL запросами

Четкие инструкции:

• Только SELECT
• Возвращать ОДНО число
• Формат дат: YYYY-MM-DD

Пост-обработка:

• Удаление markdown (```sql)
• Закрытие кавычек
• Очистка от пояснений

Безопасность:

• Блокировка DROP/DELETE/UPDATE
• Только чтение

✨ Почему это работает

• Промпт содержит всю схему — модель не гадает, а знает точные имена таблиц
• Примеры покрывают 80% кейсов — даты, COUNT, SUM, DISTINCT
• Низкая температура (0.1) — детерминированные ответы без галлюцинаций
• Валидация на выходе — кавычки, опасные операторы

👤 Автор

• Богдан
• GitHub: N1chegons
• Telegram: @Nichegons
• Email: nichegons@gmail.com