1. AI Sana Challenge Hub

MVP для HackAlem AI, Education-трек: от короткой потребности бизнеса до понятной задачи, открытого каталога и самостоятельного выбора команд.

Состояние проверки: READY WITH RISKS. Пройдены 108 тестов и 7 подслучаев, реальные API, полный браузерный сценарий и ограниченная нагрузочная проверка. Записано демовидео текущего интерфейса длительностью 1:46. Сохраняется риск потери ограничения при формировании карточки; чистая установка и непрерывная живая демонстрация до пяти минут не подтверждены. Подробности — в VERIFICATION.md.

Смотреть / скачать демовидео — 1 минута 46 секунд. MP4, Full HD, 16:9, около 3,8 МБ. Реальный AI и полный путь от черновика до выбора команды и +10 за подтверждённый демонстрационный этап. Видео собрано из кадров браузера, с поясняющими титрами, без озвучки; паузы сокращены монтажом. Все данные и этап работы синтетические. Длительность ролика не является замером непрерывного прохождения.

Документы проекта: официальный кейс, демонстрация, описание приложения, проверки, решения.

2. Проблема и аудитория

Бизнес часто описывает задачу слишком коротко: студентам непонятны доступные данные, границы работы и критерии приёмки. AI Sana помогает уточнить описание и подготовить карточку, по которой команда может оценить возможность участия.

Бизнес видит, какие сведения нужны и как их подтверждение влияет на рейтинг. Студенческие команды получают открытый каталог, самостоятельно выбирают задачи и отправляют предложения. Решение о сотрудничестве принимает бизнес.

3. Реализованные функции

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

Функция	Поведение
Черновик задачи	Свободное описание и тема/отрасль
AI-уточнение	AI-проверка полноты и противоречий сопоставляет сведения бизнеса с условиями старта команды; первый круг содержит 3–5 вопросов
Объяснение вопросов	Краткая подпись, диалог «Как это работает?» и пояснение у каждого вопроса; цитаты-источники в карточке
Редактируемая карточка	Десять полей, цитаты-источники предложений AI, отдельное ручное подтверждение
Рейтинг 0–100	Расшифровка баллов, подсказки улучшения и пересчёт при сохранении
Открытый каталог	Опубликованные задачи доступны всем командам; сортировка по рейтингу, фильтры по теме и готовности
Отклики	Идея, план, срок, ссылка на прототип; возможны несколько предложений
Решение бизнеса	Ручной выбор или отклонение; можно выбрать одну, несколько или ни одной команды
Подтверждённый этап	Выбранной команде начисляется +10; повторное подтверждение одного этапа не должно начислять баллы заново
Хранение	Карточки, команды и отклики сохраняются в SQLite

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

Формула рейтинга

Рейтинг — сумма баллов по подтверждённым полям. AI его не назначает.

Поле	Максимум
Контекст	10
Потребность	10
Данные и материалы	20
Ожидаемый результат	15
Критерии успеха	15
Ограничения	10
Пользователи	10
Контакт	5
Формат взаимодействия	5

Название баллов не даёт. Для содержательных текстовых полей требуется минимум 20 символов и 10 буквенно-цифровых символов. Контакт проверяется как e-mail, телефон или @handle. Данные должны содержать указание доступного источника или формата; недоступные, будущие и неоднозначно доступные материалы не дают баллов. Ограничения должны указывать конкретную границу. Неизмеримый критерий успеха получает 7,5 из 15 баллов.

Уровни: 0–39 — требует уточнения; 40–69 — рабочая; 70–89 — готовая; 90–100 — приоритетная, выделена золотой рамкой и значком «★ Приоритетная». Каталог сортируется по баллу, затем по времени публикации. Низкий рейтинг не скрывает опубликованную задачу и не запрещает отклик. Публикация требует подтверждения всех непустых полей; изменения требуют нового подтверждения и публикации.

4. Полный пользовательский сценарий

1. Бизнес создаёт короткий черновик задачи.
2. После создания автоматически начинается AI-анализ. Бизнес рассматривает разбор и отвечает на вопросы первого круга: их не менее трёх.
3. Получает карточку, проверяет цитаты, редактирует и подтверждает сведения.
4. Сохраняет карточку и видит пересчитанный рейтинг и способы его повысить.
5. Публикует задачу в общем каталоге.
6. Студенческая команда самостоятельно находит задачу и отправляет предложение.
7. Бизнес сравнивает отклики и вручную выбирает или отклоняет команды.
8. После фактического выполнения этапа бизнес подтверждает его, команда получает баллы прогресса.

Роли «Бизнес» и «Студент» переключаются в интерфейсе для демонстрации. Это не система авторизации.

5. Технологии и внешние сервисы

Часть	Используется
Backend	Python 3.11+, FastAPI, Uvicorn, Pydantic
HTTP и настройки	HTTPX, python-dotenv
Frontend	JavaScript, React 19, Vite 6, CSS
Хранилище	SQLite
Автотесты	pytest, pytest-asyncio
AI	Простой движок light; разные модели для исполнителя и судьи
Провайдеры по коду	OpenAI-совместимые API: OpenAI, NVIDIA NIM, настраиваемый endpoint; отдельный клиент GigaChat

В шаблоне настроек указаны OpenAI и модели gpt-4.1-mini для исполнителя, gpt-4.1-nano для судьи. Это значения по умолчанию, а не подтверждение доступности моделей на конкретном аккаунте и не результат живого прогона. Модели и провайдеры настраиваются отдельно по ролям.

Вызовы AI выполняет сервер; ключи не помещаются во frontend. Купон NVIDIA Brev оплачивает инфраструктуру и не заменяет ключ NVIDIA NIM API.

6. Архитектура и проверка противоречий

Авторская методология

В основе — построение модели ситуации до формирования вопросов. Система представляет, что сообщил бизнес и что нужно студенческой команде для старта. Затем выявляет пробелы и несовместимые условия, связывает их с вопросами и отслеживает, что изменилось после ответов.

«Мир задачи» — структурированное представление сообщённых сведений и связей. Пробел означает отсутствие информации; противоречие — несовместимость утверждений. Неполное описание нельзя автоматически объявлять противоречивым.

Черновик → сведения бизнеса и условия старта команды → пробелы/конфликты → вопросы → ответы → оценка найденных проблем → карточка с источниками → ручное подтверждение.

Польза такого подхода — видимое основание каждого уточнения. Команда понимает, почему важен вопрос о данных или критериях приёмки, а бизнес видит, что ещё мешает подготовить задачу. Измеренного улучшения сроков работы или успешности проектов пока не заявляется.

Что делает простой движок

Исполнитель выделяет элементы описания с цитатами и условия старта команды. Противоположная позиция задана предметной областью: команда должна иметь возможность начать работу по карточке. Первый круг содержит 3–5 вопросов, связанных с найденными проблемами и полями.

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

Сначала карточка собирается из цитат. Затем допустимо перефразирование с сохранением смысла: программные проверки ограничивают добавление чисел, названий, ссылок и потерю отрицаний; изменение формулировки не должно менять баллы. Отдельная модель-судья сверяет перефразирование с источниками. При отклонении либо недоступности этого судьи сохраняются цитаты.

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

Наглядность и ограничения доказательств

Граф связей хранится в состоянии анализа и связывает сведения, проблемы, вопросы и ответы. В пользовательском интерфейсе процесс объясняет короткая подпись и диалог «Как это работает?», а у вопросов видны пояснения. Цитаты в карточке позволяют проверить происхождение текста. Отдельные блоки графа на экране не выводятся. Это объяснение результатов обработки, а не полная запись внутреннего мышления модели.

Цитата не доказывает истинность слов бизнеса. Программные проверки и судья снижают риск добавления сведений, но не исключают все смысловые ошибки. Неизвестное должно оставаться пустым; контакт вводится вручную. Человек проверяет и подтверждает результат перед публикацией.

Разделение модулей

Путь	Назначение
app/api/	HTTP-интерфейс сценария, ручные действия и публикация
app/contracts.py	Контракты карточек, задач и ответов
app/store.py	SQLite, отклики, решения и начисление прогресса
app/scoring.py	Прозрачные правила рейтинга
app/catalog.py	Открытый каталог, фильтрация, сортировка
app/ai/	Адаптер движка, проверка источников и события
engines/light/	Ограниченный AI-конвейер, схемы и промпты
engines/common/	Контракты движка, провайдеры, источники и трассы
web/	Пользовательский интерфейс
seed/data.json	Синтетический начальный набор

Рейтинг, публикация и выбор команд не поручаются AI. Ручное сохранение карточки не запускает анализ автоматически. При повторном запуске адаптер передаёт исходный черновик и допустимые сохранённые источники prior_sources, включая сведения предыдущих ответов и правок. Сохранение источников не гарантирует безошибочной смысловой интерпретации.

7. Установка и запуск

Требуется Python 3.11+. Для сборки интерфейса рекомендуются Node.js 20.19+ и npm. Первый запуск установки требует сети. Команды ниже предназначены для Windows PowerShell из корня проекта.

Если репозиторий ещё не получен:

git clone https://github.com/BAITC-Hacks/hack-5273bcd8-papanda.git
cd hack-5273bcd8-papanda

Создайте окружение, установите зависимости и явно соберите текущий frontend:

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[test]"
npm --prefix web ci
npm --prefix web run build

Создайте локальный файл настроек, только если его ещё нет:

if (-not (Test-Path -LiteralPath .env)) { Copy-Item -LiteralPath .env.example -Destination .env }

Для настоящего AI настройте провайдера и AI_MODE=engine. Начальный режим интерфейс получает из /api/health; при AI_MODE=stub используется честно обозначенная локальная заглушка. Укажите свой ключ в локальном .env; ключ не должен попадать в Git, документацию или браузер. Для OpenAI используется OPENAI_API_KEY. Исполнитель и судья задаются ACTOR_PROVIDER / JUDGE_PROVIDER и ACTOR_MODEL / JUDGE_MODEL; имена моделей должны различаться. Настройка AI_MODE=engine выбирает простой движок для запросов без явного режима.

Для NVIDIA используются NVIDIA_API_KEY и NVIDIA_BASE_URL, для пользовательского совместимого endpoint — CUSTOM_API_KEY и CUSTOM_BASE_URL; GigaChat использует GIGACHAT_AUTH_KEY. Настройки AI_ACTOR_API_KEY / AI_JUDGE_API_KEY не следует считать действующими в текущем клиенте: ключ выбирается по провайдеру. Содержимое секретных настроек не включается в отчёт.

Запустите приложение:

.venv\Scripts\sana.exe

Адрес по умолчанию: http://127.0.0.1:8000. При занятом порте укажите другой PORT в локальных настройках, не останавливая чужой процесс. SANA_DB задаёт путь базы; для отдельной проверки используйте новый путь, сохраняя прежнюю базу.

После изменения frontend снова выполните сборку:

npm --prefix web run build

Запуск sana автоматически собирает frontend только при отсутствии готового web/dist/index.html. Существующая сборка не обновляется автоматически.

Режим AI_MODE=stub работает без внешнего провайдера после установки и сборки. Интерфейс показывает «Без ИИ · локальная заглушка»: вопросы определяются заполненностью полей, анализ противоречий не выполняется. После ошибки AI кнопка «Продолжить без ИИ» явно запускает заглушку; автоматической скрытой подмены нет. Работа этих новых элементов в браузере подтверждается отдельно в VERIFICATION.md.

8. Воспроизводимый сценарий для жюри

План демонстрации — до пяти минут; фактическая длительность новой версии ещё не измерена. Нужны запущенное приложение, настроенный AI и отдельная демонстрационная база. Все сведения ниже синтетические.

Время	Действие и ожидаемый результат
0:00–0:25	В режиме «Бизнес» открыть «Новая задача», указать тему «Образование» и слабый черновик ниже; нажать «Создать черновик»
0:25–1:30	Дождаться автоматически начатой проверки. Показать вопросы и кратко открыть «Как это работает?»
1:30–2:30	Ответить на фактически полученные вопросы, нажать «Отправить уточнения». Показать поля и цитаты в карточке
2:30–3:15	Заполнить недостающие поля, проверить сведения и отметить подтверждения. Нажать «Сохранить и пересчитать», показать рост рейтинга
3:15–3:40	Нажать «Опубликовать задачу», открыть «Открытый каталог», показать сортировку и доступность задач с низким рейтингом
3:40–4:15	Переключиться на «Студент», выбрать Data Qanat, открыть задачу и нажать «Отправить предложение» после заполнения формы
4:15–4:45	Вернуться в «Бизнес», открыть отклик и вручную нажать «Выбрать команду» либо «Отклонить»
4:45–5:00	Для выбранной команды подтвердить выполненный демонстрационный этап и показать +10 в «Команды и прогресс»

Слабый черновик: «Учебному центру нужен помощник для вопросов о курсах. Данных пока нет, срок — месяц». Это пример неполноты, а не заранее доказанного противоречия.

Ответы даются только по смыслу фактически заданного вопроса. Подготовленные сведения для ответов и ручного дополнения:

Поле	Синтетические сведения
Название	Помощник учебного центра
Контекст	Администраторы учебного центра вручную отвечают на повторяющиеся вопросы о расписании
Потребность	Сократить повторяющиеся ответы администратора на вопросы о расписании курсов
Пользователи	Будущие слушатели курсов и администраторы учебного центра
Данные	Уточняем исходное описание: доступен CSV с расписанием и 30 обезличенных вопросов
Ограничения	Срок прототипа — 4 недели, Python, только публичные учебные данные
Ожидаемый результат	Веб-прототип помощника по расписанию с передачей неизвестных вопросов администратору
Критерии успеха	Не менее 80% из 30 тестовых вопросов получают ответ со ссылкой на расписание
Контакт, вручную	[email protected]
Формат взаимодействия	Бизнес проводит консультацию раз в неделю и отвечает на вопросы в течение двух дней

Отклик Data Qanat: идея — «Соберём помощника по расписанию на предоставленном CSV»; план — «Проверим данные, создадим прототип и сравним ответы с критериями бизнеса»; срок — «4 недели»; ссылка — https://example.test/prototype. Ссылка синтетическая, она не обозначает опубликованный прототип.

В случае ошибки AI покажите фактический статус; не выдавайте заглушку или запись за успешный текущий вызов. Кнопка «Посмотреть промпт и формат AI» открывает контракт анализа. Также он доступен по адресу /api/ai/contract, документация API — /docs. После ошибки нажмите «Продолжить без ИИ» и покажите явную подпись заглушки. Это резервный сценарий без вызовов моделей, а не успешное выполнение живого AI-этапа.

Что проверить дополнительно

Сценарий	Ожидаемое поведение
Неподтверждённое поле	Не даёт баллов; мешает публикации, если поле непустое
Низкий рейтинг	Опубликованная задача остаётся доступной для отклика
Неизвестный ответ	Не превращается в установленный факт
Отклонение предложения	Решение принимает бизнес вручную
Несколько команд	Допускается ручной выбор нескольких команд
Повтор подтверждения этапа	Один этап не увеличивает баллы дважды
Ошибка или некорректный ответ API	Явная ошибка либо предусмотренный отказ от неподтверждённой формулировки

Последняя проверка 23.09.2026 в 17:00: 108 тестов и 7 подслучаев прошли за 3,09 с. Полный браузерный путь завершён; нагрузка — 300 операций, 360 HTTP-запросов, параллельность 20, ошибок 0, p95 операции 329 мс. Финальные weak/conflict/unknown дошли до карточки на реальном API. Технический успех не исключает смысловых ошибок; подробности и границы — в docs/VERIFICATION.md. Ранние числа 55/106 относятся к истории.

9. Данные и интеграции

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

Внешняя интеграция нужна для реальных AI-запросов. Контактное поле не передаётся модели. Проверка свободного текста распознаёт некоторые контакты, но не является полным детектором персональных или чувствительных данных. Для демонстрации используются только синтетические сведения.

.env, локальные базы, трассы и артефакты исключены из Git. Трассы могут содержать текст задачи и ответов, поэтому не являются автоматически безопасным материалом для публикации.

10. Ограничения и статус проверки

• Приложение предназначено для локальной демонстрации. Полноценная авторизация и разграничение доступа по владельцам отсутствуют.
• Текущий пользовательский AI-путь использует только простой движок. Данные старого аудита о двух движках относятся к истории проекта.
• Ручные правки автоматически не запускают AI; повторная проверка выполняется отдельным действием с сохранёнными допустимыми источниками.
• Не все неизвестные гарантированно устраняются за два круга вопросов. Неполную карточку допускается вручную дополнить.
• Источники и модель-судья снижают риск выдуманных фактов, но не доказывают истинность исходных сведений и не исключают все ошибки интерпретации.
• Заглушка не анализирует противоречия; её явно обозначенный сценарий нельзя выдавать за результат реальной модели.
• Незавершённый AI-прогон не возобновляется после перезапуска сервера. Сохранённые карточки и отклики остаются в SQLite.
• Рекомендации задач по навыкам, полноценный проектный трекер, чат и календарь не реализованы как отдельные функции и не входят в обязательный объём кейса.
• Статус READY WITH RISKS: в конфликтном примере запрет сохранился в графе, но потерялся в карточке. Ошибки старого полного примера не подтверждены исправленными. Нужна ручная проверка всех ограничений. Чистая установка, нажатие fallback после реальной ошибки и пятиминутная репетиция не подтверждены; последние UI-пояснения отдельно не проверялись.

11. Ссылки

Репозиторий: https://github.com/BAITC-Hacks/hack-5273bcd8-papanda

Подтверждённой публичной deployed-ссылки нет. Локальный адрес после запуска — http://127.0.0.1:8000; это не публичный deployment.

---

Ниже сохранено исходное описание демонстрационного агента организатора.

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

Запуск

Требуется Python 3.10 или новее.

python mini_agent.py

В чате напишите помощь. Доступные команды: время, задача <текст>, задачи и выход.

tasks.txt создаётся во время работы и намеренно не хранится в Git.