based — умный помощник студента в MAX

Хакатон: трек «Образовательные решения», платформа МАХ.

Чат-бот собирает конспекты лекций, ведёт расписание и напоминает о дедлайнах. Работает локально через Ollama, данные не покидают машину пользователя.

Возможности

• Конспекты — аудио, фото, презентации → PDF с формулами (whisper + Ollama + Playwright)
• Расписание — XLSX, PDF, DOCX, CSV, ICS, JSON, изображения → структурированные пары
• Домашние задания — статусы ⏳ ✅ ❌, дедлайны, напоминания
• Уведомления — дайджест, за N минут до пары, за день до дедлайна, в день дедлайна

Технологический стек:

• MAX Bot API — среда взаимодействия
• Ollama + gemma4:e4b — генерация и очистка текста
• Ollama + glm-ocr — распознавание изображений и слайдов
• faster-whisper large-v3 — транскрибация аудио (CUDA или CPU)
• Playwright + Chromium — рендер PDF с MathJax и Mermaid
• SQLite — локальное хранилище

Основной пользовательский сценарий

1. Открывает бота в MAX, /start.
2. «Конспекты → Загрузить материал».
3. Пишет дисциплину, например «Математический анализ».
4. Выбирает тип занятия: лекция / семинар / лабораторная / другое.
5. Отправляет аудио, фото доски или презентацию.
6. Нажимает «Сгенерировать конспект» — бот показывает прогресс.
7. Получает PDF с формулами, диаграммами и структурой.
8. Отдельно загружает расписание — бот показывает пары.
9. Ведёт домашние задания — отмечает ✅, ❌, удаляет 🗑.
10. Настраивает напоминания в «Настройки → Уведомления».

Архитектура

┌─────────────────────────────────────────────────────┐
│                    MAX Messenger                    │
└───────────────────────┬─────────────────────────────┘
                        │ HTTPS
┌───────────────────────▼─────────────────────────────┐
│                  bot/  (maxapi)                     │
│  handlers/   → сценарии (конспект, расписание, ДЗ)  │
│  scheduler/  → фоновый планировщик напоминаний      │
│  session/    → сессии, SQLite бота                  │
│  ui/         → клавиатуры и тексты                  │
│  utils/__pdf → Playwright + MathJax + Mermaid       │
└───────────────────────┬─────────────────────────────┘
                        │ Python API
┌───────────────────────▼─────────────────────────────┐
│                based/  (библиотека)                 │
│  modules/notes  → whisper + vision + LLM            │
│  modules/skeds  → парсинг расписания через LLM      │
│  modules/tasks  → SQLite CRUD                       │
│  utils/__llm    → Ollama client                     │
│  utils/__db     → SQLite: расписание, ДЗ            │
│  utils/__assets → загрузка промптов и тестов        │
└───────────────────────┬─────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
    ┌────────┐     ┌─────────┐     ┌──────────┐
    │ Ollama │     │ Whisper │     │  SQLite  │
    │локально│     │локально │     │ локально │
    └────────┘     └─────────┘     └──────────┘

Бот не знает про пайплайны — вызывает NotesAPI, SkedsAPI, TasksAPI. Библиотека не знает про UI. Слои разделены, всё работает локально.

Документация

Документ	Что внутри
based/README.md	API библиотеки: BasedAPI, NotesAPI, SkedsAPI, TasksAPI, схемы, метрики
bot/README.md	API бота: хендлеры, сессии, планировщик, UI, безопасность
samples/README.md	тестовые данные и сценарий проверки

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

cp .env.example .env
docker compose up --build

Поднимает ollama (порт 11434) и bot.

Первая сборка — около 5 минут (без учёта загрузки базовых образов). Модели Ollama и whisper тянутся при первом использовании.

Переменные окружения

Переменная	По умолчанию	Описание
BOT_TOKEN	—	токен MAX (обязательно)
OLLAMA_HOST	http://localhost:11434	адрес Ollama
ASSETS_BASE_URL	GitHub URL	архив промптов и тестовых данных
ASSETS_VERSION	v1.0.0	версия архива
BOT_CACHE_DIR	~/.cache/based-bot	кеш бота
BASED_CACHE_DIR	~/.cache/based	кеш библиотеки
BOT_ALLOWED_USER_IDS	пусто	список ID через запятую

Порты

Порт	Сервис
11434	Ollama
8080	bot (резерв)

Зависимости

• requirements.txt — базовые (pydantic, pyyaml, httpx, rich)
• requirements-bot.txt — бот (maxapi, markdown, playwright)
• requirements-skeds.txt — расписание (pdfplumber, python-pptx, openpyxl)
• requirements-notes.txt — конспекты (faster-whisper, ctranslate2, CUDA)

Системные: Python 3.11, ffmpeg, Chromium.

Внешние сервисы, не воспроизводимые в Docker:

• MAX Bot API — облачный сервис мессенджера, нужен токен.
• GitHub Releases — источник архива assets.zip.

Работа с данными

Персональные данные (аудио, фото, конспекты, расписание) хранятся локально в ~/.cache/based и ~/.cache/based-bot. Наружу не уходят.

База данных — SQLite:

• based.db: groups, user_groups, schedules, lessons, tasks
• sessions.db: sessions, session_files, user_settings, reminders

MVP не передаёт данные третьим лицам и не использует внешние LLM-сервисы.

Сценарий проверки

Автоматически:

python verify.py

Проверит импорты, конфиг, загрузку BasedAPI с метриками, парсинг расписания, создание задачи, конвертацию markdown в PDF.

Вручную через бота MAX:

1. /start.
2. Конспект из текста:
   • «Конспекты → Загрузить материал»
   • дисциплина: «Математический анализ»
   • тип: «лекция»
   • отправить .txt или .md
   • «Сгенерировать конспект» → PDF в чат
3. Расписание:
   • «Расписание → Загрузить файл»
   • отправить samples/schedule_sample.csv
4. ДЗ:
   • «Домашние задания → Добавить»
   • отправить строку из samples/tasks_sample.txt
5. Напоминание:
   • «Настройки → Уведомления → Пары → 5 минут»
   • загрузить расписание с парой через 10 минут
   • дождаться уведомления

Ожидаемое поведение

Конспект. После отправки аудио бот показывает прогресс («Обрабатываю файлы», «Извлекаю текст из аудио», «Генерирую конспект»), затем присылает PDF-файл с заголовками, формулами и диаграммой.

Расписание. После загрузки CSV бот отвечает «Расписание сохранено: N занятий, ДАТА–ДАТА». Кнопки «Сегодня» / «Завтра» / «На неделю» показывают пары с временем, предметом, преподавателем и аудиторией.

ДЗ. После отправки строки предмет | дата | описание бот отвечает «Задача добавлена: предмет, до дата». В списке — статусы ⏳ ✅ ❌ и кнопки ✅ ❌ 🗑 ↩.

Напоминание. За N минут до пары бот присылает сообщение с временем, предметом и аудиторией, плюс кнопки «Открыть расписание» и «Отключить напоминания».

Известные ограничения

• Русский язык для промптов и транскрибации.
• Транскрибация large-v3 на CPU медленная (~1× от длительности аудио).
• На коротких входах LLM может достраивать формулы.
• MathJax для PDF требует интернета при первом запуске конвертации.
• Напоминания работают, только пока бот запущен.
• В MAX Bot API нельзя удалить сообщение пользователя.
• Whisper-модель скачивается при первой транскрибации (~1.5 ГБ).

Остановка и повторный запуск

docker compose down       # остановка
docker compose up -d      # повторный запуск
docker compose down -v    # полная очистка томов

Метрики

Скрипт verify.py показывает время загрузки каждого модуля через BasedAPI.timings():

notes  → 809.7s  (транскрибация + LLM)
skeds  → 38.9s   (парсинг через LLM)
tasks  → 0.66s   (SQLite CRUD)

Лицензия

MIT.