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 — Адаптивность и интервальное повторение — DONE

Сделано: frontend/js/trainer/adaptive.js (window.TrainerAdaptive, чистая логика) — nextSkill (приоритет: in-session повтор → серверный due → прогрессия → удержание по box), onWrong/onCorrect (in-session очередь повторения), sessionStats. Умная тренировка на странице (по умолчанию вкл, тумблер): авто-подбор навыка, ведёт от простого к сложному, возвращает ошибки; сессия из 10 задач с итогом (верно/точность/ навыки/«стоит повторить»). Неверный ответ авто-показывает решение. Сервер: SR-поля box+due_at на practice_progress (мигр.082, Leitner-интервалы 0/1/3/7/16/30 дней), listProgress отдаёт box/due_at/due. Смоуки: adaptive 12/12, страница 23/23, practice.test.js 11/11 (+SR box/due).

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

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

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

Сделано: серверная проверка backend/src/utils/practiceVerify.js (грузит SimExpr в Node через require, verifyRoot подстановкой). Сервис practiceGenService.js: buildMessages→LLM→parseProblem→validateAndVerify (компиляция SimExpr + подстановка корня + санитизация story/шагов) с авторетраем по фидбэку; LLM-вызов инъектируется (opts.ask, дефолт — assistantController.callLLMFailover). Пул practice_problems (мигр.083, status approved/draft). Эндпоинты: POST /api/practice/generate (учитель/админ) + GET /api/practice/pool (ученикам). Клиент: LS.practicePool/Generate, тема «Текстовые задачи» на странице (берёт из пула; учителю — кнопка «Сгенерировать»). Гарантия: невалидная/неверная задача в БД НЕ пишется → ученику не попадёт. Тесты practice-gen.test.js 13/13 (verify, ретраи, off→503, 403 ученику, пул).

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

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

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

Сделано (переиспользуя P3-проверку): ручной авторинг — POST /api/practice/author (учитель пишет story/lhs/rhs/answer → та же validateAndVerify подстановкой → пул; не сходится → 422). Раздача классу — POST /api/practice/assign (владелец/админ → durable pushNotif каждому ученику класса, ссылка /trainer). Клиент: LS.practiceAuthor/Assign; в теме «Текстовые задачи» учителю — кнопки «Своя задача» (модалка-форма с серверной проверкой) и «Выдать классу» (пикер классов → уведомление). Тесты: author (валид→пул, неверный→422, ученик→403), assign (владелец уведомляет, чужой→403). Не делалось (осознанно): полноценный визуальный конструктор ПАРАМЕТРИЧЕСКИХ генераторов (pick/derive/lhs/rhs DSL) — крупный отдельный билдер; текущий авторинг закрывает «учитель создаёт задачи + раздаёт классу» переиспользованием пула и инварианта проверки.

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

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

Phase 5 — Типы ответов и проверки — DONE (частично)

Сделано: движок получил несколько корней (gen.answers → problem.answers; _checkMultiRoot — ввод всех корней через «;», сверка мультимножеством) и эквивалентность выражений (kind:'simplify', gen.srcExpr/answerExpr; _sampleEquiv — численный сэмплинг в фикс. точках, без Math.random; _checkEquiv). exprToLatex чинит знаковые коэффициенты (-5x, x²−5x+6, a−(−b)→a+b). Новые темы: Упрощение (привести подобные, раскрыть скобки) и Квадратные (Виета x²+bx+c=0, разность квадратов — 2 корня). Страница: префикс «x=» и подсказка ввода по типу, ответ-лейбл (корни/выражение). Смоук движка 291/291 (T11 roots, T12 simplify, T13 latex). Осталось (стретч): неравенства (нужен парсер отношений) — не вошло.

Цель (исходная): не только «корень-число».

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

Phase 6 — Геймификация, аналитика, UX — DONE (частично)

Сделано: учительская аналитика — GET /api/practice/class-stats?class_id= (classStats, владелец класса/админ): агрегаты по навыкам (attempted/mastered/accuracy)

• матрица ученик×навык. Клиент: кнопка «Аналитика класса» (учителю) → модалка с тепловой картой (ученики × навыки, цвет по точности, ✓ освоено) + пикер классов. LS.practiceClassStats. Лёгкая геймификация: строка общего прогресса «Освоено навыков M из N · решено всего K» (из агрегатов practice_progress), бейджи мастерства на чипах (P2). Тесты practice.test.js +4 (владелец видит, чужой/ученик→403, без id→400). Смоук страницы 27/27. Осталось (стретч): XP в общую геймификацию, виртуальная клавиатура, сократические подсказки — не вошло (отдельные крупные направления).

Изначальный список:

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

---

Сквозное

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

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

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