24 KiB
24 KiB
Study Qpid (study.qpid.pro)
Автономный персональный тренажёр и интерактивная языковая среда английского языка.
Создан для быстрого и надёжного расширения активного словарного запаса, автоматизации грамматики и беглого чтения технической и художественной литературы с поддержкой локального искусственного интеллекта (Ollama) и локального синтеза речи (Piper TTS) без внешних платных API.
🎯 Концепция и философия системы
Традиционное изучение языка разбивается о разрозненность: словарь в одном приложении, карточки в другом, книги в третьем, а грамматика в тетрадке.
Study Qpid объединяет весь цикл в единый закрытый контур по принципу «автомата Калашникова»:
- 100% автономность и приватность: веб-сервис развернут в Docker, защищён строгой авторизацией (сессии HttpOnly, хэширование PBKDF2-HMAC-SHA256, rate limiting). Локальный ИИ (Qwen 2.5 3B) и синтез речи (Piper) работают полностью на собственном сервере без передачи данных сторонним компаниям.
- Контекстный якорь и лексический подход: слова изучаются в готовых блоках (chunks) и живых предложениях из прочитанных книг и документации.
- Многомодальный интервальный тренажер (SRS SM-2): 5 различных режимов работы с карточками (3D Flashcards, умная викторина с дистракторами по частям речи, активный ввод Typing, аудио-диктант, аудирование Q&A).
- Интерактивная читалка: мгновенный перевод кликом по слову, захват предложений в карточки в 1 клик, поддержка форматов EPUB, PDF, TXT, Markdown, спецификаций IETF RFC и статей Wikipedia.
- Грамматический трек Murphy & CEFR: 15 базовых юнитов грамматики с формулами, связка с бумажной рабочей тетрадью, 260 интерактивных тестов Cloze Tap и автоматическая отправка ошибок в активную очередь повторений.
- Конструктор комплексного урока: единый сессионный раннер, собирающий ежедневный урок из слов, грамматики, аудирования, чтения и завершающийся педагогическим разбором ошибок от локальной нейросети.
🚀 Основной реализованный функционал
1. 🔍 Контекстный словарь и поиск
- Локальная словарная база: более 140 000 словарных статей в SQLite, дополненных морфологическим анализатором (лемматизация инфлексий
starts→start,studying→study). - Детектор фразовых глаголов и идиом: при поиске слова в контексте предложения система автоматически определяет устойчивые связки (look forward to, run into, figure out) и предлагает сохранить именно целостное выражение.
- Каскадный перевод: офлайн-словарь + транскрипция IPA + толкование на английском + русский перевод.
- Управление базой: разбивка по коллекциям (General, IT/Tech, Phrasal Verbs и др.), система тегов, быстрый поиск и фильтрация, пакетные операции (перемещение, тегирование, удаление).
2. 🧠 Локальный ИИ (Ollama & Qwen 2.5 3B)
- Контекстный перевод предложений: перевод предложения с фокусом на точное значение целевого слова в данном контексте через локальную LLM (
qwen2.5:3b). - Кэширование переводов: все сгенерированные переводы сохраняются в SQLite (
sentence_translations) с моментальной отдачей при повторных запросах. - Педагогический дебрифинг урока: анализ ошибок сессии, определение паттернов (путаница времен, предлогов), рекомендации и выставление объективной оценки сессии.
- Отказоустойчивость: постоянный пул соединений с Keep-Alive (120s) в FastAPI lifespan; при недоступности Ollama система мгновенно переключается на детерминированный математический отчёт без зависаний.
3. 🔊 Автономная нейро-озвучка (Piper TTS)
- Локальный VITS-инференс: чистый нативный звук дикторов без внешних запросов к облакам (
en_US-lessac,ru_RU-dmitri+ поддержка альтернативных дикторов). - Проактивное фоновое пред-кэширование: при добавлении слова в словарь аудиозапись слова и контекста синтезируется сервером в фоне, обеспечивая нулевую задержку при повторении в тренажере.
- Аудио в читалке: озвучивание отдельных слов, целых предложений оригинала и русского перевода.
4. 🎓 Тренажёр интервальных повторений (SRS SM-2)
- Алгоритм SuperMemo SM-2: адаптивный расчёт интервалов (1, 6,
I \times EFдней) на основе оценок пользователя (Снова, Трудно, Хорошо, Легко). - 5 специализированных режимов повторений:
- 3D Flashcards — классические двусторонние карточки с 3D-анимацией переворота.
- Smart Quiz — множественный выбор из 4 вариантов с автоматическим подбором правдоподобных дистракторов из той же части речи.
- Active Typing — активная продукция: печать английского слова по русскому переводу и контексту с пропуском.
- Audio Dictation — аудиотренажёр: прослушивание произношения через Piper TTS и ввод слова на слух.
- Listening Comprehension — интерактивные аудио-сценарии с вопросами на проверку понимания.
- Smart Daily Mix: сбалансированная ежедневная тренировка (10 новых слов + 10 плановых повторений + 5 проблемных слов-личей, перемешанных для интерливинга).
- Аналитика и визуализация: GitHub-style календарь активности за 180 дней, подсчёт непрерывного стрика, распределение по статусам (New, Learning, Review, Mastered), расчёт Retention Rate и оценка словарного уровня по CEFR.
5. 📚 Интерактивная читалка и библиотека
- Поддержка форматов: загрузка книг в форматах EPUB, PDF, TXT, Markdown (
.md). - Импорт RFC-спецификаций: загрузка технических стандартов IETF RFC по номеру или URL с автоматической разбивкой на структурированные главы.
- Интеграция с Wikipedia: автономный импорт статей по названию, теме и доступному бюджету времени на чтение.
- Интерактивный клик-перевод: каждое слово кликабельно с показом всплывающей карточки (на десктопе — всплывающее окно у курсора, на смартфоне — удобный Bottom Sheet).
- Непрерывное чтение: бесконечный скролл с навигационными карточками завершения глав, автоматическое сохранение позиции чтения (
current_chapter,current_position). - Типографика и темы: 6 цветовых схем (Light, Dark, Sepia, Night, Parchment, Hacker), регулировка ширины страницы, межстрочного интервала и шрифтов (Georgia, Inter, JetBrains Mono).
6. 🏆 Тесты CEFR (A1–B2) & Автоматическая Gap-ингестия
- 260 интерактивных заданий Cloze Tap, распределённых по международным уровням владения языком (A1, A2, B1, B2).
- Автоматическое устранение пробелов (Gap Ingestion): любая допущенная ошибка в тесте мгновенно конвертируется в словарную карточку и отправляется в активную очередь SRS со статусом
learning. - Фоновый майнер тестов из книг: асинхронный фоновый воркер для автоматического извлечения тестовых заданий из загруженных пользователем книг с фильтрацией по целевому уровню CEFR.
7. 📖 Грамматический трек Murphy & Тетрадь
- 15 базовых юнитов классической методики Raymond Murphy (Essential Grammar in Use).
- Структура каждого юнита:
- Карточка юнита со статусом освоения и баллом.
- Полноэкранный теоретический модуль с формулами образования, русскими объяснениями и маркерами времени.
- 5 интерактивных упражнений Cloze Tap с мгновенной проверкой.
- Интеграция с бумажным конспектом: чекбокс ручной фиксации упражнений в физической тетради для задействования моторной памяти.
8. ⚡ Конструктор комплексного урока & Сессионный раннер
- Гибкая структура занятия: настройка порядка этапов, переключение тумблеров активности, выбор объема слов и упражнений.
- Готовые пресеты:
- ⚡ Утренний экспресс (10 мин)
- 🎯 Сбалансированный урок (20 мин)
- 📖 Глубокое погружение (30 мин)
- 🎧 Аудио + Чтение (15 мин)
- Возможность сохранения собственных шаблонов в базу SQLite.
- Умный подбор грамматики: адаптивный выбор темы грамматики на основе истории ошибок («Самая слабая тема», «Предыдущая тема» или ручной выбор).
- Сквозной раннер: бесшовный интерфейс с таймером, прогресс-баром и финальным ИИ-дебрифингом.
🛠 Техническая архитектура и стек
https://study.qpid.pro
│
┌──────────────────▼──────────────────┐
│ Nginx (Host SSL / Reverse Proxy) │
└──────────────────┬──────────────────┘
│ :8002
┌─────────────────────────────────────────▼────────────────────────────────────────┐
│ Docker Container: study-qpid-pro │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Application (app/main.py) │ │
│ │ • GZipMiddleware (≥1000B) • Security Headers Middleware │ │
│ │ • Persistent Lifespan Pool • Service Worker Static Precache (v6.7) │ │
│ └─────────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────▼────────────────────────────────────┐ │
│ │ Модульные APIRouters │ │
│ │ • auth.py • cards.py • dictionary.py • srs.py │ │
│ │ • reader.py • cefr.py • grammar.py • lessons.py │ │
│ │ • listening.py • tasks.py • export.py │ │
│ └─────────────────┬───────────────────┬──────────────────┬─────────────────┘ │
│ │ │ │ │
│ ┌─────────────────▼─────────┐ ┌───────▼────────┐ ┌───────▼─────────────────┐ │
│ │ SQLite WAL (data/notes) │ │ Piper TTS │ │ Seed Datasets (JSON) │ │
│ │ • Memory-Mapped I/O │ │ • Offline VITS │ │ • cefr_questions.json │ │
│ │ • Full Schema Integrity │ │ • Zero-Latency │ │ • grammar_units.json │ │
│ │ • Sub-millisecond reads │ │ • Voice Cache │ │ • phrasal_verbs.json │ │
│ └───────────────────────────┘ └────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────┬────────────────────────────────────────┘
│ http://ollama:11434
┌─────────────────────────────────────────▼────────────────────────────────────────┐
│ Docker Container: study-ollama │
│ • Model: Qwen 2.5 3B Instruct (GGUF) │
│ • Connection Pool with Keep-Alive (120s) │
└──────────────────────────────────────────────────────────────────────────────────┘
- Backend: Python 3.12, FastAPI, Uvicorn, Pydantic v2.
- База данных: SQLite в режиме
WAL(Write-Ahead Logging) сmmap_size = 256MBи индексами по внешним ключам и выражениям. - Frontend: Vanilla ES6+ модули, HTML5 PWA, CSS-переменные (7 предметных таблиц стилей), поддержка offline через Service Worker.
- AI & TTS: Ollama (
qwen2.5:3b), Piper Neural TTS (локальный бинарник). - Тестирование: Pytest + TestClient (44 автоматических интеграционных теста).
📁 Структура проекта
study.qpid.pro/
├── app/
│ ├── main.py # Лаконичная точка входа FastAPI (lifespan, middleware, роутеры)
│ ├── auth.py # Безопасность, хэширование PBKDF2, сессии, rate limiting
│ ├── config.py # Переменные окружения и системные пути
│ ├── database.py # Инициализация SQLite WAL, индексы, миграции
│ ├── dictionary.py # Поиск в офлайн-словаре, лемматизация, каскадные запросы
│ ├── ai.py # Интеграция с Ollama (Keep-Alive пул, промпты, дебрифинг)
│ ├── tts.py # Синтез речи Piper TTS и управление кэшем аудио
│ ├── srs.py # SM-2 интервалы, викторины, аналитика, тепловая карта
│ ├── reader.py # Парсеры EPUB, PDF, TXT, Markdown, RFC и Wikipedia
│ ├── cefr.py # Уровневое тестирование A1–B2 и gap-ингестия
│ ├── grammar.py # Движок Murphy Grammar и журнал конспектов
│ ├── lessons.py # Конструктор уроков, пресеты, история сессий
│ ├── listening.py # Сценарии аудирования и оценка ответов
│ ├── miner.py # Фоновый майнинг предложений из литературы
│ ├── tasks.py # Управление фоновыми задачами SQLite
│ ├── export.py # Экспорт базы (CSV, JSON, Anki, Markdown)
│ ├── routers/ # Модульные роутеры FastAPI (11 файлов)
│ └── static/ # Статика веб-приложения
│ ├── index.html # Одностраничное приложение (PWA Shell)
│ ├── sw.js # Service Worker (кэширование v6.7)
│ ├── manifest.json # PWA-манифест
│ ├── css/ # Модульная таблица стилей
│ │ ├── style.css # Мастер-файл со структурой и @import
│ │ ├── base.css # Токены, темы, сброс, safe-areas
│ │ ├── components.css # Навбар, меню, кнопки, модалки, таб-бар
│ │ ├── dictionary.css # Поиск, карточки слов, коллекции, теги
│ │ ├── srs.css # Карточки 3D, квизы, ввод, аналитика
│ │ ├── reader.css # Читалка, темы оформления, Wikipedia
│ │ ├── grammar_cefr.css # CEFR и юниты Murphy
│ │ └── lesson.css # Конфигуратор и раннер уроков
│ └── js/ # ES6 модули фронтенда
│ ├── app.js # Точка входа SPA, роутинг, хоткеи
│ └── modules/ # Модули логики (ui, api, dictionary, srs, reader, cefr, grammar, lesson)
├── data/
│ ├── notes.db # Основная база данных SQLite
│ ├── offline_dict.tsv.gz # Локальный словарь (140k+ записей)
│ ├── audio_cache/ # Кэш предсинтезированных WAV-файлов
│ └── seeds/ # Кураторские JSON-датасеты (CEFR, Murphy, Phrasal, Articles)
├── scripts/
│ ├── deploy_beta.sh # Развертывание бета-ветки в 1 клик
│ ├── rollback_to_main.sh # Мгновенный откат на стабильный main
│ └── build_offline_dict.py # Сборщик офлайн-словаря
├── tests/
│ └── test_api.py # Набор интеграционных тестов (44 теста)
├── docker-compose.yml # Декларация контейнеров study-web и ollama
└── Dockerfile # Образ веб-приложения на Python 3.12-slim
🚀 Развёртывание и запуск
Запуск через Docker Compose (Рекомендуемый)
# Клонирование репозитория
git clone https://ai.qpid.pro/gitea/Antigravity/notes-qpid-pro.git
cd notes-qpid-pro
# Запуск связки веб-сервера и локальной Ollama
DOCKER_HOST=tcp://127.0.0.1:2375 docker compose up -d
# Запуск тестов внутри контейнера
DOCKER_HOST=tcp://127.0.0.1:2375 docker exec -i -e PYTHONPATH=. study-qpid-pro pytest tests/test_api.py
Управление ветками и откат:
# Быстрый переход на бета-версию:
./scripts/deploy_beta.sh
# Мгновенный откат на стабильную ветку main:
./scripts/rollback_to_main.sh
📄 Лицензия и статус проекта
- Проект разрабатывается в активной фазе для повседневного практического освоения языка.
- 100% открытый исходный код без проприетарных платных облачных зависимостей.