TeacherFlow · FAQ для жюри

Учитель загружает эталон → система генерирует 2–10 вариантов той же сложности → учитель проверяет, правит, выгружает раздатку.

TeacherFlow — веб-сервис для школьных учителей: мультипликация заданий с контролем методики, а не «ещё один чат с GPT».

Эталон (текст / PDF / DOCX / фото) → анализ → параметры (N, типы вариации) → генерация → карточки вариантов → экспорт PDF/DOCX/ZIP.

Прогресс — асинхронная job + polling/SSE. Учитель не ждёт в одном HTTP-запросе. Демо: teacherflow.ru, материалы: /zakazchik.

Текст, PDF, DOCX, изображение с OCR, повтор из библиотеки заданий.

Фото распознаётся через GigaChat по шаблону ocr.md (дроби, степени, разбиение на пункты), затем текст автоматически приводится к нормальному виду.

От 2 до 10 за один запуск — по требованию кейса.

Каждый вариант проходит тот же контур проверки; если не проходит, система делает автоматическую доработку и повторную попытку (до 4 попыток на весь набор вариантов, а не на каждый вариант отдельно).

Числа, порядок условий, синонимы, контекст (с сохранением логики), имена/единицы — через анализатор + генератор.

Учитель может зафиксировать части условия. В интерфейсе есть готовые наборы настроек («стандартная вариация чисел» и т.п.). Детали — docs/research.md, §2.

Да — сетка карточек с подсветкой различий относительно эталона и вердиктами качества.

Можно открыть вариант, отредактировать вручную, перегенерировать один вариант, не трогая остальные.

PDF, DOCX, ZIP; маркировка «Вариант 1…N»; ответы для учителя — отдельно от ученической раздатки.

В PDF/DOCX дроби для печати упрощаются (a/b), чтобы WeasyPrint не ломал вёрстку. Нумерация пунктов — без двойных «1. 1.».

Личное хранилище эталонов и прошлых наборов вариантов с поиском и повторным запуском генерации.

Не публичный каталог чужих заданий — только данные учителя после регистрации.

Да — сущности класс, ученики, назначение «вариант №» каждому.

Дополнение к кейсу: помогает на уроке раздать разные листы без ручной таблицы. Это не полноценная система ведения журнала и оценок.

Да — /share/[slug] на share.teacherflow.ru: только условие, без эталона и без ключей.

Раздача вынесена на отдельный домен; учитель копирует ссылку из интерфейса. Это не «второй продукт», а страница только для просмотра варианта.

5-осевой профиль сложности + пороги в правилах + (в полном режиме) 3 ИИ-судьи с голосованием.

Не IRT по реальным ответам учеников — честно заявляем: относительная сопоставимость с эталоном. Подробно: docs/difficulty-methodology.md.

steps, operations, bloom_level, lexical_complexity, answer_form.

Что это значит на практике:

steps — число шагов решения. Сколько логических действий нужно, чтобы решить задачу. Пример: «найти 3/4 от 60» — это 2 шага (умножить, потом разделить), а не 1.

operations — какие именно действия нужны. Не только «сколько шагов», но и «какие»: сложение, деление, перевод, грамматическая трансформация и т.д. Если в варианте появилась новая операция, сложность может уехать.

bloom_level — когнитивный уровень по Блуму. Условно: вспомнить / понять / применить / проанализировать и т.п. Большинство школьных задач — apply; если вариант сдвинулся в analyze, это уже другой уровень.

lexical_complexity — сложность формулировки текста. Насколько «тяжелый» язык условия: длина, структура фраз, лексика. Даже при одинаковой математике текст может стать сложнее для ученика.

answer_form — форма ответа. Что ожидается: число, выражение, список, текст, выбор. Если было «одно число», а стало «развернутый текст», это уже другое задание.

Для математики добавляются диапазон чисел и уникальность решения. Для английского — уровень CEFR и грамматические цели. Пороги лежат в apps/api/policies/ и версионируются.

Три независимые проверки: сохранена ли структура задания, сопоставима ли сложность, и не дублируются ли ответы между вариантами.

Если «за» минимум 2 из 3 проверок — вариант принимается. Иначе уходит на доработку или в ручной разбор. Судьи работают на GigaChat-2 Lite (быстрее и дешевле Pro).

Быстрый — для демо: меньше проверок и заметно быстрее. Полный — все три судьи и голосование, как в методологии.

На скринкасте для жюри лучше показывать полный режим на 2–3 вариантах; для массовой генерации учитель может выбрать быстрый.

Эталонный набор пар «задание → хороший вариант». В автоматической проверке на живом GigaChat нужно набрать минимум 80%, иначе изменение не принимается.

Базовое ядро — 15 ручных пар (10 математика 5–6 + 5 английский A2). Далее покрытие расширено до 47 фикстур / 26 предметов. См. docs/goldset/.

9 заведомо плохих вариантов; в автоматической проверке система должна отклонять минимум 80% таких кейсов.

Примеры: сдвиг Bloom, скачок лексики, коллизия ответов, дубликат формулировок. docs/antipatterns/.

keep — вариант принят; warn — принят с предупреждением; repair — уходит на автодоработку; needs_review — нужен ручной разбор учителем.

Это подсказка, а не жёсткий запрет: финальное решение всё равно остаётся за учителем.

Да — финальное решение за учителем. Система предупреждает (warn/fail), не блокирует экспорт жёстко.

Продуктовая позиция: ИИ — ассистент, не замена педагога. Журнал правок и вердикты сохраняются для разбора.

Генератор + судьи + политики на уникальность ответа и лексическое расстояние.

Antipattern a01-answer-collision и дубликаты формулировок — отдельные кейсы в bench.

MVP сначала калибровали на математике 5–6 и английском A2, затем расширяли покрытие на каталог предметов.

Важно: строгая проверка в CI есть там, где уже собран goldset. Для остальных направлений это режим пилота, без той же гарантии порога.

Блок на странице задания после генерации: отпечаток сложности по пяти осям (эталон и варианты на одной шкале с зоной допуска) + заключения судей в полном режиме.

Это объяснение для учителя, не оценка ученика. Дополняет карточки вариантов и goldset-контур, но не заменяет финальное решение педагога.

Раздел /methodical: учитель загружает методички, КТП, критерии. Два совещательных контура: проверка эталона до генерации и комплекта после — по соответствию загруженным документам.

API: POST /tasks/{id}/methodical-check и POST /variant_sets/{id}/methodical-check. Fail-open, не трогают idempotency генерации. Отличие от судей сложности: там сравнение с эталоном, здесь — с методичкой учителя.

docs/research.md — обзор практик и ограничений: вариативные задания, таксономия Блума, когнитивная нагрузка, реальные барьеры учителей.

Ограничение: без живых интервью (соло-участник). После MVP — 5+ интервью для калибровки порогов. Ссылка на диске и в /links.

Гипотеза: с 30–60 мин ручной работы до нескольких минут (генерация + просмотр).

Это оценка из проектной модели, пока без полноценного полевого сравнения. На пилоте в школе планируем уточнить цифры на реальных уроках.

Нужен не один «умный запрос», а целый контур: анализ структуры, инварианты, метрики сложности, судьи, автоматическая проверка регрессий, экспорт, библиотека, классы.

Простой запрос в чат не даёт повторяемости результата и не проходит критерий методического качества из кейса.

PDF на Яндекс Диске + веб-страница /zakazchik/mat-prototype.

В репозитории: docs/Карточка_прототипа.md.

Соло-участник + оркестрация ИИ-агентов (Claude, Codex, Cursor) под единым планом и проверками качества в CI.

Школьный учитель-предметник в команде не привлекался — методику валидируем через goldset и документацию.

DESIGN.md — шрифт Inter, нейтральный фон, акцент #3D52D5, без визуального шума.

Статусы: зелёный «принято», янтарный «предупреждение», красный «нужна доработка». Иконки SVG, без эмодзи.

/help — пошаговые статьи с примерами экранов + PDF.

Двойной источник: TSX + scripts/help_pdf_bodies.py — синхронизация перед релизом.

/zakazchik — ценность, пайплайн, контроль качества, границы MVP и план развития.

Все ссылки собраны на /links (QR в презентации). Методматериалы: /zakazchik/methodical-materials.

В репозитории — папка demo-materials: TXT-методички (~3000 символов) для математики 6 и биологии 6, скриншоты эталонных контрольных, сценарий демо.

Сценарий: загрузить методичку → эталон по скриншоту → проверка эталона → генерация → «Почему эти варианты равноценны» → проверка комплекта.

Да, для генерации нужен вход: личная библиотека и классы привязаны к аккаунту учителя.

Публичная ссылка для ученика открывается без логина. Отдельного единого школьного входа в MVP пока нет.

FastAPI + PostgreSQL + Next.js 14 + GigaChat (Pro/Lite) + WeasyPrint (PDF).

Python 3.12, Pydantic v2, Alembic, фоновые asyncio-задачи. Фронт: Tailwind, shadcn/ui.

Требование/контур хакатона СберОбразования; Pro для анализа/генерации/OCR, Lite для судей.

Единый клиент LLMClient с режимами «без сети», «записанные ответы» и «живой GigaChat» — это позволяет стабильно тестировать и локально, и в CI.

Генерация запускается как фоновая asyncio-задача и пишется в generation_jobs; интерфейс обновляет статус каждые 2 секунды.

Осознанное упрощение MVP: один сервер и один воркер, без Redis. Масштабирование вынесено в следующий этап.

Ограничения такие: не больше 8 параллельных LLM-вызовов, 60 секунд на один запрос, до 4 повторных попыток на набор вариантов.

Идемпотентный ключ защищает от дублей при повторном клике. Корреляционный ID помогает разбирать ошибки в логах.

Да — apps.api.llm.LLMClient.call(schema=…). Прямой httpx к GigaChat вне слоя запрещён.

Шаблоны запросов версионируются в apps/api/prompts/*.md; какая версия ушла в прод — сохраняется в variant_sets.prompt_versions_json.

Промпты — в apps/api/prompts/*.md, политики сложности — в apps/api/policies/*.yaml.

И промпты, и политики версионируются: при изменениях обновляем версии, а в variant_sets сохраняется, чем именно был сгенерирован набор (для отладки и воспроизводимости).

В каждом наборе вариантов сохраняются версии шаблонов запросов и правил — можно точно понять, «на какой конфигурации» получен результат.

Технически: variant_sets.prompt_versions_json + policy_name/policy_version. Это помогает разбирать регрессии после изменений и связывать поведение с конкретным MR.

Анализатор → Генератор → профиль и правила → Судьи → Голосование → Доработка (если вариант не прошёл).

Схема: /zakazchik/pipeline, код: apps/api/pipeline/.

pytest -m fast (<5 с) + в merge request проверка goldset + антипримеров на GigaChat.

Кассеты tests/cassettes/ нужны для повторяемых тестов без ключа. Раннер — свой, на Docker.

Swagger, OpenAPI JSON, healthz/readyz.

Сейчас API в первую очередь обслуживает собственный фронт; партнёрские интеграции вынесены на следующий этап (mat-production).

Нет. Только подготовка и раздача вариантов, не ведение успеваемости.

Нет. Один тип пользователя — учитель. Роль школьного администратора — после MVP.

Нет. Сейчас один сервер, Docker Compose, nginx-proxy + Let's Encrypt.

Достаточно для демо и пилота; при росте — вынести workers и Redis (план в PDD).

Нет. Адаптивный веб; touch targets ≥44px.

Нет универсального солвера. Только контроль структуры и сложности варианта, не проверка ответов класса.

Нет. LLM может ошибиться; goldset снижает регрессии, учитель — финальный фильтр.

VPS pet-server, запуск через docker compose -f infra/docker-compose.prod.yml.

Домены: teacherflow.ru (web), api.teacherflow.ru (API), share.teacherflow.ru (раздачи). Инструкция: docs/deploy.md.

GitLab · проектный пакет docs/project/ · разработчик docs/developer/.

Сводка ссылок: teacherflow.ru/links.

Яндекс Диск «Macadamm» — скринкаст, карточка прототипа, слайды.

curl https://api.teacherflow.ru/healthz и /readyz (database: ok).

Локально: make smoke с API_URL / WEB_URL.

Шаблон запроса — только один слой. Поверх него есть структурированный анализ, правила, метрики, ансамбль судей и автоматическая проверка регрессий.

Без этого контура любое изменение запроса легко ломало бы результат; CI ловит такие срывы до выката.

Для IRT нужны большие массивы реальных ответов и предметные банки. В MVP мы решаем более узкую задачу: учителю быстро получить 2–10 сопоставимых вариантов на урок.

По методике опираемся на идею параллельных форм заданий (см. research), а не на экзаменационную статистическую калибровку.

Срабатывает многоуровневая защита: структурный судья, инварианты, предупреждение на карточке, ручная правка и точечная перегенерация одного варианта.

Antipatterns ловят типовые срывы (Bloom, шаги, ответы). 100% автоматом — нереалистично обещать.

Фото распознаёт vision-модель по шаблону v1.2 (дроби, пункты). После обновления шаблона фото нужно загрузить заново.

Учитель всегда может поправить текст эталона перед генерацией — это ожидаемый путь.

MVP: минимум PII (имя в классе), без паспортов; хостинг на своём VPS; политика и DPA — перед пилотом в школе.

Тексты заданий уходят в GigaChat — как у любого LLM-сервиса; для прода нужен договор с провайдером.

Зависит от N, выбранного режима и числа доработок. Нагрузку ограничиваем лимитами параллельности и бюджетом повторных попыток.

Точные рубли за запрос не обещаем на защите — есть лимиты в коде; биллинга для учителя в MVP нет.

Задача помечается как неуспешная, учитель видит ошибку и может повторить запуск. Остальная часть сервиса при этом продолжает работать.

Для тестов есть режим записанных ответов; в проде остаёмся зависимы от внешней доступности провайдера модели.

Наш фокус — сопоставимая сложность с измеримым профилем и автоматическим контролем качества, а не просто «красивый лист».

Конкурентный обзор — в research; честно: у крупных игроков больше контента, у нас — прозрачная методика для жюри кейса 4.

/zakazchik/mat-roadmap — пилот в школе, расширение предметов, единый школьный вход, API для партнёров.

Подробный план: docs/project/09-execution-plan.md.