Learn_System/plans/ai-trainer/PLAN.md

ИИ-Тренажёр — план развития модуля

Модуль /trainer: бесконечные задачи, которые рождаются из данных-генераторов, а математика считается и проверяется детерминированно через SimExpr (без eval). LLM в ядре не участвует — его роль (Уровень 1+) сочинять генераторы и текстовые задачи, которые тот же слой верифицирует подстановкой. Тема-пилот: уравнения, 7 класс.

Инвариант корректности (не нарушать)

Любой источник задачи (генератор, шаблон, LLM) обязан пройти TrainerEngine.verifyRoot: заявленный корень подставляется в уравнение, расходится → задача отбрасывается. Та же подстановка проверяет ответ ученика (принимает 5, x=5, 10/2, 2+3). Выражения — ТОЛЬКО SimExpr (whitelist, без eval/new Function). Цвета/текст от пользователя — только в безопасные стоки или с escape.

Состояние: Phase 0 — DONE (прототип, в этом коммите)

• Движок frontend/js/trainer/_trainer_engine.js: instantiate / generateBatch / verifyRoot / checkStudentAnswer / exprToLatex (AST→LaTeX, reusable) / makeRng.
• Генераторы frontend/js/trainer/generators.js: 5 типов (линейное ax+b=c, скобки, переменная с двух сторон, дробь x/a+b=c, дробный коэффициент ax/b=c). Приём «корень-вперёд» → гарантированно целые ответы, самопроверка всегда проходит.
• Страница frontend/trainer.html: KaTeX-рендер уравнений и шагов, чипы-темы, мгновенная проверка, подсказка/решение, авто-выбор первого неосвоенного навыка.
• Прогресс на сервере: practice_progress (мигр.081), practiceController + routes/practice (/api/practice/progress|attempt), клиент LS.practiceProgressList/Submit. Мастерство = серия 5 верных подряд (липкое).
• Фича-флаг trainer: тумблер в админке (Модули), requireFeature('trainer'), скрытие из сайдбара + редирект страницы (FEATURE_HREFS), запись в MODULE_CATALOG.
• Тесты: practice.test.js (10/10), headless-смоуки движка/страницы. lint:routes 0.

---

Phase 1 — Ширина контента (генераторы) — DONE

Сделано: таксономия тема → навык с метаданными (topic/order/subject/grade), TrainerGenerators.topics()/byTopic(). 13 генераторов в 3 темах: Уравнения (7: ax+b=c, a(x+b)=c, ax+b=cx+d, a(x+b)=c(x+d), x/a+b=c, ax/b=c, (ax+b)/c=d), Пропорции (3), Проценты (3, kind:'compute' — текстовый prompt + проверка подстановкой). UI: выбор темы (вкладки) → навыки (чипы) с бейджами мастерства, авто-выбор первой неосвоенной темы/навыка. Подробные объяснения: каждый шаг расписан словами + шаг «Проверка» (подстановка корня). Движок: exprToLatex чинит отрицательные множители (7·(−5)), kind:'compute'. Смоуки 238/238 (движок) + 19/19 (страница).

Цель (исходная): перестать быть «демкой одной темы». Структура класс → предмет → тема → навык.

• Реестр генераторов: вынести в данные с метаданными { grade, subject, topic, skill, order, difficulty }. Группировка чипов по темам/классам; выбор класса/предмета вверху.
• Новые генераторы 7 кл: пропорции, раскрытие скобок с обеих сторон a(x+b)=c(x+d), уравнения с дробью-уравнением (ax+b)/c = d, простые буквенные преобразования.
• Соседние темы (параметрические, без LLM): упрощение выражений, степени, проценты, линейные неравенства (расширить checkStudentAnswer под интервалы — см. P5).
• Acceptance: ≥3 темы × ≥3 навыка, у каждого generateBatch(50) даёт 50 разных корректных задач; solvability-смоук на сетке параметров.

Phase 2 — Адаптивность и интервальное повторение

Цель: вести ученика, а не давать случайное.

• Диагностика на входе (по 1–2 задачи на навык) → стартовый уровень.
• Подбор следующего навыка по мастерству (escalate при серии, откат при ошибках).
• Ошибки уходят в очередь повторения (свой лёгкий SR или reuse flashcards Tier-1).
• «Продолжить тренировку», дневная норма/цель, сводка сессии (что освоено, над чем работать).
• Сервер: расширить practice_progress (или новая practice_review_queue); агрегаты для аналитики.
• Acceptance: сессия из N задач сама ведёт от простого к сложному; промахнутый навык всплывает повторно; прогресс переживает перезаход.

Phase 3 — Уровень 1: LLM-задачи с верификацией

Цель: текстовые/контекстные задачи, которых не даёт параметрика.

• LLM (через провайдеров админки) генерирует { lhs, rhs, answer, story }; сервер прогоняет verifyRoot; расхождение → авторетрай с фидбэком («корень не удовлетворяет, исправь»).
• Кэш-пул practice_problems (предгенерация, ревью учителем) — не платить за каждый показ.
• Генерация «по теме урока» (связка с theory/exam-prep).
• Acceptance: доля задач, прошедших верификацию с 1–2 ретраев, ≥95%; пул кэшируется; ни одна неверная задача не доходит до ученика (гарантирует инвариант).

Phase 4 — Авторинг учителем

Цель: учитель создаёт свои наборы и раздаёт классу (как sim-builder/Quantik Ф5).

• Конструктор генераторов: шаблон lhs/rhs, диапазоны параметров, формула ответа, шаги решения; превью + клиентская валидация через SimExpr.compile.
• Хранение (таблица по образцу custom_sims), серверная validateSpec без исполнения, раздача классу + уведомление, привязка к ДЗ/уроку.
• Acceptance: учитель собирает рабочий генератор без кода; ученик решает; права/видимость как у custom-sim (own + раздано).

Phase 5 — Типы ответов и проверки

Цель: не только «корень-число».

• Множество корней (квадратные/факторизация), интервалы (неравенства), упрощение выражений (эквивалентность через численный сэмплинг по диапазону, а не строковое равенство).
• Пошаговый ввод (проверять каждый шаг подстановкой), несколько форматов ответа.
• Acceptance: квадратное уравнение принимает оба корня в любом порядке; (x+1)^2 ≡ x^2+2x+1 через сэмплинг; неравенство принимает x>3 и эквивалент.

Phase 6 — Геймификация, аналитика, UX

• XP/энергия/стрики (reuse инфраструктуры Квантика), бейджи мастерства на чипах (есть основа).
• Учительская аналитика: кто на каком навыке застрял, тепловая карта класса, отчёты.
• UX: виртуальная клавиатура для дробей/степеней, «почему неверно» (разбор ошибки), сократические подсказки через Квантик-ассистента, мобильная раскладка, доступность.

---

Сквозное

• Безопасность: только SimExpr; авторские генераторы — серверная validateSpec без исполнения (длины/лимиты, escape текста), как custom_sims.
• Тесты: на каждый генератор — solvability-смоук (сетка параметров → есть корректные задачи + достижим целевой ответ); бэкенд-тесты на новые роуты; headless-смоук страницы.
• Контент = данные: генераторы и темы — JS-данные/таблицы, не код.

Рекомендуемый следующий шаг

Phase 1 (ширина контента) — даёт наибольшую пользу при минимальном риске и переиспользует готовый движок/проверку/страницу. Затем Phase 2 (адаптивность) для удержания.