220 lines
24 KiB
Markdown
220 lines
24 KiB
Markdown
# Study Qpid (study.qpid.pro)
|
||
|
||
> **Автономный персональный тренажёр и интерактивная языковая среда английского языка.**
|
||
> Создан для быстрого и надёжного расширения активного словарного запаса, автоматизации грамматики и беглого чтения технической и художественной литературы с поддержкой локального искусственного интеллекта (Ollama) и локального синтеза речи (Piper TTS) без внешних платных API.
|
||
|
||
---
|
||
|
||
## 🎯 Концепция и философия системы
|
||
|
||
Традиционное изучение языка разбивается о разрозненность: словарь в одном приложении, карточки в другом, книги в третьем, а грамматика в тетрадке.
|
||
|
||
**Study Qpid** объединяет весь цикл в единый закрытый контур по принципу **«автомата Калашникова»**:
|
||
1. **100% автономность и приватность**: веб-сервис развернут в Docker, защищён строгой авторизацией (сессии HttpOnly, хэширование PBKDF2-HMAC-SHA256, rate limiting). Локальный ИИ (Qwen 2.5 3B) и синтез речи (Piper) работают полностью на собственном сервере без передачи данных сторонним компаниям.
|
||
2. **Контекстный якорь и лексический подход**: слова изучаются в готовых блоках (*chunks*) и живых предложениях из прочитанных книг и документации.
|
||
3. **Многомодальный интервальный тренажер (SRS SM-2)**: 5 различных режимов работы с карточками (3D Flashcards, умная викторина с дистракторами по частям речи, активный ввод Typing, аудио-диктант, аудирование Q&A).
|
||
4. **Интерактивная читалка**: мгновенный перевод кликом по слову, захват предложений в карточки в 1 клик, поддержка форматов EPUB, PDF, TXT, Markdown, спецификаций IETF RFC и статей Wikipedia.
|
||
5. **Грамматический трек Murphy & CEFR**: 15 базовых юнитов грамматики с формулами, связка с бумажной рабочей тетрадью, 260 интерактивных тестов Cloze Tap и автоматическая отправка ошибок в активную очередь повторений.
|
||
6. **Конструктор комплексного урока**: единый сессионный раннер, собирающий ежедневный урок из слов, грамматики, аудирования, чтения и завершающийся педагогическим разбором ошибок от локальной нейросети.
|
||
|
||
---
|
||
|
||
## 🚀 Основной реализованный функционал
|
||
|
||
### 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 специализированных режимов повторений**:
|
||
1. *3D Flashcards* — классические двусторонние карточки с 3D-анимацией переворота.
|
||
2. *Smart Quiz* — множественный выбор из 4 вариантов с автоматическим подбором правдоподобных дистракторов из той же части речи.
|
||
3. *Active Typing* — активная продукция: печать английского слова по русскому переводу и контексту с пропуском.
|
||
4. *Audio Dictation* — аудиотренажёр: прослушивание произношения через Piper TTS и ввод слова на слух.
|
||
5. *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 (Рекомендуемый)
|
||
|
||
```bash
|
||
# Клонирование репозитория
|
||
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
|
||
```
|
||
|
||
### Управление ветками и откат:
|
||
|
||
```bash
|
||
# Быстрый переход на бета-версию:
|
||
./scripts/deploy_beta.sh
|
||
|
||
# Мгновенный откат на стабильную ветку main:
|
||
./scripts/rollback_to_main.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 📄 Лицензия и статус проекта
|
||
* Проект разрабатывается в активной фазе для повседневного практического освоения языка.
|
||
* 100% открытый исходный код без проприетарных платных облачных зависимостей.
|