Кузя Bot

Умный бот-помощник Кузя для управления задачами с интеграцией AI, системой достижений и мотивации.

✨ Функционал

📋 Управление задачами

• Добавление задач через команду /add <текст> или обычным сообщением
• Просмотр списка задач /list
• Отметка задач как выполненных /done <номер>
• 🤖 AI-разбиение сложных задач на подзадачи через /decompose

🏆 Система достижений

• 8 уровней достижений (10, 50, 100, 250, 500, 1000, 2500, 5000 задач)
• AI генерирует уникальные названия и эмодзи для каждого достижения
• Автоматические уведомления при разблокировке
• Просмотр прогресса через меню "🏆 Достижения"

💬 Система мотивации

• 3 стиля напоминаний:
  • 😊 Дружеский — теплый и поддерживающий
  • 😐 Нейтральный — деловой и вежливый
  • 💪 Агрессивный — требовательный с сарказмом
• AI генерирует персонализированные мотивационные сообщения
• Напоминания 2-3 раза в день (с возможностью отключения)
• Учитывает прогресс и количество невыполненных задач

📅 Расписание

• Добавление повторяющихся задач: /schedule_add <день> <время> <текст>
• Просмотр расписания: /schedule
• Удаление из расписания: /schedule_remove <id>
• Поддержка дней недели (полное название, сокращение, номер)

📊 Статистика

• Счетчик выполненных задач в главном меню
• Отображение прогресса к следующему достижению
• История достижений с датами разблокировки

🚀 Установка и запуск

Требования

• Python 3.10+ или Docker
• Max Bot токен (получить у @masterbot)
• AI токен от Google Gemini (получить на https://aistudio.google.com)

🔑 Получение AI токена:

1. Перейдите на https://aistudio.google.com
2. Войдите в аккаунт Google
3. Нажмите "Get API key"
4. Создайте новый API ключ
5. Скопируйте ключ для использования в .env файле

🐳 Docker (Рекомендуется)

Быстрый запуск

1. Клонирование репозитория

git clone https://github.com/FrankyShelloy/kuzia-bot
cd kuzia-bot

2. Настройка окружения

cp .env.example .env
# Отредактируйте .env файл с вашими токенами

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

./docker-run.sh

Docker команды

# Быстрая сборка и запуск (рекомендуется)
make run

# Просмотр логов
make logs

# Остановка
make stop

# Или стандартные команды Docker Compose:
# Сборка и запуск с кэшированием
DOCKER_BUILDKIT=1 docker compose up --build -d

# Просмотр логов
docker compose logs -f

# Остановка
docker compose down

# Пересборка после изменений
docker compose build --no-cache

🐍 Установка через Python

Шаги установки

1. Клонирование репозитория

git clone https://github.com/FrankyShelloy/kuzia-bot
cd kuzia-bot

2. Создание виртуального окружения

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

3. Установка зависимостей

pip install -r requirements.txt

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

Создайте файл .env в корне проекта:

TOKEN=your_max_bot_token_here
AI_TOKEN=your_gemini_api_key_here
DB_URL=sqlite:///db.sqlite3
LOG_LEVEL=WARNING
DEBUG_MODE=false

📋 Как получить токены:

• TOKEN: Создайте бота у @masterbot в Max messenger
• AI_TOKEN: Получите API ключ на https://aistudio.google.com

5. Запуск бота

python main.py

📱 Использование

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

1. Отправьте /start для открытия главного меню
2. Добавьте задачу: просто отправьте текст или нажмите "➕ Добавить задачу"
3. Выберите стиль мотивации в меню "💬 Стиль мотивации"
4. Выполняйте задачи и получайте достижения! 🎉

Команды

• /start — главное меню
• /add <текст> — добавить задачу
• /list — список всех задач
• /done <номер> — отметить задачу выполненной
• /decompose <текст> — разбить задачу на подзадачи с помощью AI
• /schedule_add <день> <время> <текст> — добавить в расписание
• /schedule — посмотреть расписание
• /schedule_remove <id> — удалить из расписания

Примеры

Задачи:

/add Купить продукты
Позвонить врачу  # без команды - тоже добавится
/list  # посмотреть все задачи
/done 1  # отметить первую задачу

AI-разбиение:

/decompose Организовать день рождения
# AI создаст 3-5 подзадач: забронировать место, пригласить гостей, купить торт и т.д.

Расписание:

/schedule_add понедельник 09:00 Утренняя зарядка
/schedule_add пт 18:00 Встреча с друзьями

🛠 Технологии

• maxapi 0.9.7 — фреймворк для бота
• Tortoise ORM 0.25.1 — работа с БД
• litellm 1.79.3 — интеграция с AI
• SQLite — база данных
• python-dotenv — управление конфигурацией

📂 Структура проекта

kuzia-bot/
├── core/
│   ├── achievements.py    # Система достижений
│   ├── ai_core.py         # AI интеграция
│   ├── callbacks.py       # Обработчики callback
│   ├── config.py          # Конфигурация
│   ├── handlers.py        # Обработчики команд
│   ├── keyboards.py       # Клавиатуры
│   ├── models.py          # Модели БД
│   ├── motivation.py      # Система мотивации
│   ├── state.py           # Управление состоянием
│   ├── utils.py           # Утилиты
│   └── message_utils.py   # Утилиты для сообщений
├── scripts/
│   └── clear_db.py        # Скрипт очистки БД
├── main.py                # Точка входа
├── requirements.txt       # Зависимости
├── Dockerfile             # Образ Docker (оптимизирован)
├── docker-compose.yml     # Оркестрация Docker
├── docker-run.sh          # Скрипт запуска
├── Makefile              # Команды для сборки
├── .env.example           # Пример конфигурации
└── .env                   # Конфигурация (не в git)

🔧 Развертывание в продакшене

Docker Compose (Рекомендуется)

# Подготовка
cp .env.example .env
# Настройте токены в .env:
# - TOKEN: получите у @masterbot в Max messenger
# - AI_TOKEN: получите на https://aistudio.google.com

# Запуск в фоне
docker compose up -d

# Мониторинг
docker compose logs -f kuzia.bot

Systemd сервис (Linux)

# Создать сервис
sudo nano /etc/systemd/system/kuzia-bot.service

[Unit]
Description=Kuzia Bot
After=network.target

[Service]
Type=simple
User=kuzia
WorkingDirectory=/opt/kuzia-bot
ExecStart=/opt/kuzia-bot/.venv/bin/python main.py
Restart=always

[Install]
WantedBy=multi-user.target

# Запуск сервиса
sudo systemctl enable kuzia-bot
sudo systemctl start kuzia-bot