Sana AI

Репозиторий команды · Кейс МНВО — AI Sana: рейтинг качества бизнес-задач и открытый выбор команд.

Краткое описание

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

Что реализовано

• Три рабочих пространства: «Каталог задач», «Конструктор задачи» и «Мои задачи». Интерфейс на русском, казахском и английском; исходный пользовательский текст не переводится автоматически.
• Настоящий AI-агент с вызовами инструментов, 3–5 различными вопросами, объяснением каждого вопроса, проверкой цитат и журналом действий.
• Десять редактируемых полей карточки, предварительный рейтинг «было → стало», ручное подтверждение публикации и повторная проверка после правок.
• Рейтинг 0–100: баллы, основание, причина и следующий шаг по каждому критерию. Источник оценки различается: AI, локальная проверка или учебный пример.
• Общий каталог с поиском, фильтрами темы и готовности, сортировкой по убыванию рейтинга. Низкий рейтинг не запрещает отклик.
• Предложения команд с идеей, планом, сроком и ссылкой на прототип; ручные действия «Выбрать команду», «Отклонить», «В избранное». Можно выбрать несколько команд или не выбрать ни одной.
• Подтверждение фактического этапа выбранной команды: +10 баллов один раз на предложение. Сервер блокирует повторное начисление, в том числе одновременные запросы.
• SQLite сохраняет публикации, отклики и решения после перезапуска. Анонимная cookie ограничивает редактирование и решения владельцем задачи.
• AI-разбор сохраняется как серверное задание: переход в каталог и перезагрузка страницы не теряют результат. Повтор запроса с тем же идентификатором не запускает второй оплачиваемый анализ. Незавершённые предложения и правки карточки сохраняются в исходном браузере.
• По пять связанных записей для демонстрации в каждом наборе: черновики, карточки, команды и предложения. Кнопки подстановки учебных данных позволяют пройти сценарий без набора текста.

Как работает решение

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

Соответствие требованиям кейса

Требование	Реализация	Где в коде	Как проверить
Свободный черновик и минимум 3 уместных вопроса	3–5 вопросов по разным полям; каждый содержит причину и подсказку	agent/architect.py, agent/architect_prompts.py	Сравнить вопросы для библиотеки и учебного кафе
Карточка из 10 полей, ручная проверка	Все поля редактируются; сервер требует confirmed: true	frontend/src/App.jsx, server/app.py	Без подтверждения публикация запрещена
Рейтинг, расшифровка, пересчёт	Семь критериев, уровни 0–4, формула на сервере	agent/architect_tools.py, рубрика	Раскрыть критерий, изменить сведения и повторить анализ
Общий каталог, сортировка, фильтры	Все задачи доступны; фильтры не зависят от команды	frontend/src/App.jsx, server/app.py	Открыть задачу с рейтингом 23 и отправить предложение
Неограниченные отклики	Каждая отправка создаёт отдельное предложение; лимита количества нет	POST /api/challenges/{id}/proposals	Отправить два предложения на одну задачу
Ручной выбор одной, нескольких или ни одной команды	Решение доступно только автору; агент не имеет инструмента выбора	PATCH /api/proposals/{id}	Выбрать две команды либо отклонить все
Баллы за подтверждённый прогресс	Принятая команда получает +10 после подтверждения автором	POST /api/proposals/{id}/milestones	Подтвердить этап; повторный запрос возвращает 409
AI не добавляет факты в карточку	Python собирает поля из исходных фрагментов; явные ответы и очистка поля имеют приоритет	agent/evidence.py, validate_analysis, verify_quotes	Тесты отклоняют выдуманные контакты, данные и цитаты; полнота смыслового извлечения проверяется отдельно
Рабочий запуск и данные	Локальная SQLite, зафиксированные зависимости, примеры	requirements.txt, frontend/package-lock.json, data/	Запустить по инструкции ниже

Как работает AI-агент

agent/architect.py вызывает OpenAI Responses API. Модель выбирает инструменты и их порядок; успешный цикл требует минимум двух вызовов, включая проверку цитат. После инструментального этапа отдельный AI-аудит заново получает исходные сведения и рубрику, без предыдущей оценки. Лимиты: четыре запроса основного цикла, при необходимости один дополнительный раунд инструментов, один аудит и не более одной попытки исправления формата; максимум шесть исполненных инструментов. Внешние запросы ограничены тайм-аутом; автоматических повторов SDK нет.

Инструмент	Вход	Результат
get_readiness_rubric	Без аргументов	Семь критериев, веса, шкала и формула
verify_user_evidence	Поле, цитата, обозначение источника	Проверка цитаты по реальному вводу, хранящемуся на сервере
calculate_readiness	Извлечённые поля и оценка критериев	Детерминированные баллы и уровень готовности
compare_revision	Текущие и исходные поля	Список различий после уточнений

Промпт и строгая JSON-схема находятся в agent/architect_prompts.py; инструменты — в agent/architect_tools.py. Приложение передаёт {draft, answers, language, score_is_preview}. Python делит исходник на фрагменты с идентификаторами; модель возвращает их распределение по полям (coverage), наличие задачи (task_present), вопросы, критерии и предупреждения. Python собирает карточку из оригинальных фрагментов и возвращает {summary, fields, questions, criteria, warnings, evidence, score, readiness, mode, trace}.

Программные проверки: допустимые поля и идентификаторы источников, 3–5 разных вопросов, ровно семь критериев, уровни 0–4, цитаты из реального ввода. Явный ответ пользователя для поля сохраняется дословно, включая намеренно пустой ответ; сведения из других ответов могут дополнять другие подходящие поля. Пробелы и переносы сверяются без изменения слов и отрицаний. Пустые поля, отсутствие задачи и критерии, обозначенные моделью как непригодные, получают ноль. Цитата подтверждает происхождение текста, не его истинность или безошибочность классификации. Смысловой аудит также выполняется моделью и не является независимой человеческой экспертизой.

Финальная оценка опирается на 13 фиксированных требований внутри семи критериев: модель возвращает для каждого исходные фрагменты, состояние met / partial / missing / blocked и короткое объяснение. Python выводит уровень из состояний, затем считает баллы; модель не выбирает итоговое число. Отдельная классификация существующих материалов помогает отличать входной документ от будущего результата. Это делает основания проверяемыми, но не исключает смысловые ошибки модели.

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

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

Семь весов: контекст и потребность — 20, данные — 20, результат — 15, критерии успеха — 15, ограничения — 10, пользователи — 10, связь с бизнесом — 10. Для каждого критерия: баллы = floor(вес × уровень / 4 + 0.5), где уровень 0–4 означает степень пригодности сообщённых сведений. Итог — сумма, от 0 до 100; бонуса за длину текста нет. Полная шкала: docs/RUBRIC.md.

До подтверждения оценка предварительная. После подтверждения сервер публикует баллы; изменённые сведения требуют актуальной проверки. Уровни: 0–39 — черновик, 40–69 — рабочая, 70–89 — готовая, 90–100 — приоритетная. Каталог сортируется по убыванию рейтинга, затем по времени создания; низкий рейтинг не скрывает задачу и не запрещает отклик. Рейтинг команды отделён от рейтинга задачи: +10 один раз за подтверждённый этап принятого предложения, без автоматического назначения исполнителя.

Примененные технологии

Компонент	Версия / назначение
Python	3.11+; при разработке использован Python 3.13
React / React DOM	18.3.1 — интерфейс
Vite	8.3.0 — сборка; Node.js 22.12+
FastAPI / Uvicorn	0.115.12 / 0.34.3 — API и HTTP-сервер
SQLite	Встроена в Python; локальное транзакционное хранилище
OpenAI Python SDK	1.107.2 — Responses API с инструментами и JSON-схемой
python-dotenv	1.1.1 — настройки из .env
pytest / httpx	8.4.2 / 0.28.1 — автоматические тесты API и логики
Streamlit	1.49.1 — сохранённая первая версия, устанавливается отдельно

AI-модель задаётся через OPENAI_MODEL, скрытого значения по умолчанию нет. Для демонстрации проверена gpt-4.1: в наших пробах она точнее сохраняла факты и задавала более предметные вопросы, чем gpt-4o-mini. Это локальное наблюдение, не универсальный рейтинг моделей. Модель должна быть доступна вашему аккаунту; официальная документация GPT-4.1 подтверждает поддержку Responses API, вызовов функций и строгого вывода. Python-зависимости зафиксированы в requirements.txt, frontend-зависимости — в frontend/package-lock.json.

Архитектура проекта

Браузер: frontend/src/App.jsx + i18n.js + стили
    │ JSON /api/* + HttpOnly cookie владельца
    ▼
server/app.py — проверка ввода, права, публикация и решения
    ├── agent/architect.py → OpenAI Responses API
    │     ├── architect_prompts.py — промпт и строгая схема
    │     ├── evidence.py — исходные фрагменты и проверка цитат
    │     └── architect_tools.py — рубрика и арифметика рейтинга
    ├── server/database.py → data/challenges.sqlite3
    ├── server/jobs.py — сохранённые задания, очередь, восстановление результата
    ├── server/limits.py — один активный AI-запрос на браузер, до шести в минуту
    └── server/messages.py — сообщения ru / kk / en

data/*.json → первоначальные учебные записи SQLite
frontend/dist/ → собранный интерфейс, отдаётся тем же сервером
tests/ → агент, рубрика, API, права и полный сценарий
scripts/evaluate_architect.py → 12 примеров для оценки качества AI
scripts/evaluate_workflows.py → 3 полных изолированных сценария ru / kk / en
scripts/evaluate_semantics.py → 6 сложных примеров и вопросы для ручной оценки

Подробности: формула рейтинга и результаты проверок. Сохранённая Streamlit-версия (app.py, agent/core.py, rating.py, storage.py) сохранена отдельно; новый frontend её не вызывает.

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

Нужны Python 3.11+ и Node.js 22.12+ с npm. Команды выполняются из корня репозитория. Интернет нужен для установки пакетов и реального AI; внешняя база данных не требуется. После сборки Node.js не нужен для обслуживания интерфейса.

Если исходники ещё не скачаны:

git clone https://github.com/BAITC-Hacks/hack-82e6beb1-proof-by-intimidation.git
cd hack-82e6beb1-proof-by-intimidation

Windows — PowerShell

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Для AI заполните .env ключом и моделью; для локального режима оставьте ключ пустым. Существующий .env не перезаписывайте. Затем:

Set-Location frontend
npm ci
npm run build
Set-Location ..
.\.venv\Scripts\python.exe -m uvicorn server.app:app --host 127.0.0.1 --port 8000

Linux/macOS

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
cp -n .env.example .env

Для AI заполните .env; для локального режима оставьте ключ пустым. Затем:

cd frontend
npm ci
npm run build
cd ..
.venv/bin/python -m uvicorn server.app:app --host 127.0.0.1 --port 8000

Откройте http://127.0.0.1:8000. Проверка API: /api/health; документация запросов: /docs. При первом запуске SQLite создаётся автоматически с пятью учебными задачами. Надпись «AI настроен» означает наличие настройки ключа и модели, а не гарантированную доступность внешнего сервиса.

Запускайте один процесс Uvicorn, как в командах выше; --workers больше одного не поддерживается текущей очередью. Перезагрузка вкладки восстанавливает ожидание задания, а перезапуск сервера во время AI-разбора завершает его понятной ошибкой: черновик остаётся, новый анализ запускается только явным действием пользователя.

Переменная	Назначение	Пример	Обязательна
OPENAI_API_KEY	Ключ аккаунта OpenAI	Свой ключ, только в .env	Для реального AI
OPENAI_MODEL	Доступная модель	gpt-4.1	Для AI; без значения нет скрытого выбора модели
CHALLENGE_DB	Путь к SQLite	data/jury-run.sqlite3	Нет; по умолчанию data/challenges.sqlite3

Для чистой демонстрации задайте новый, ещё не существующий путь CHALLENGE_DB и перезапустите сервер. Прежние записи сохранятся, а новая база получит учебные примеры. .env, SQLite, её служебные файлы и data/runtime.json не входят в Git; не добавляйте их в архив для жюри.

Разработка и сохранённая первая версия

Для разработки запустите Uvicorn на порту 8000, а во втором терминале выполните cd frontend и npm run dev. Vite откроет адрес http://127.0.0.1:5173 и перенаправит /api на порт 8000. Используйте один адрес сайта последовательно: cookie владельца привязана к браузеру и хосту.

Первая Streamlit-версия необязательна для нового продукта. Для неё установите requirements-legacy.txt тем же интерпретатором и запустите app.py. В PowerShell:

.\.venv\Scripts\python.exe -m pip install -r requirements-legacy.txt
.\.venv\Scripts\python.exe -m streamlit run app.py

На Linux/macOS аналогично используйте .venv/bin/python.

Как проверить решение

Демонстрация до пяти минут

Перед показом проверьте ключ, доступность модели и загрузку приложения. Для демонстрации содержательной AI-функции нужен реальный AI-режим. Подготовленные ответы — факты синтетического примера, не ответы модели.

Время	Действие	Что показать
0:00–0:30	«Создать задачу» → «Начать с примера» → первый пример → «Использовать пример»	Слабый черновик из data/drafts.json: студенты не находят учебники на казахском
0:30–1:30	«Разобрать с AI»	Не менее трёх разных вопросов, причины, предварительный рейтинг и журнал инструментов
1:30–2:45	«Заполнить ответы из примера» → «Собрать карточку»	Конкретные данные, критерии приёмки, ограничения; сравнить «Было» и «Стало» и раскрыть критерий
2:45–3:15	Проверить поля, отметить подтверждение → «Подтвердить и опубликовать»	Новая задача в общем каталоге; публикация не выполняется AI
3:15–4:00	«Открыть задачу» → «Предложить решение» → «Заполнить пример предложения» → «Отправить предложение»	Студенческая команда сама откликнулась; отклик не назначает её исполнителем
4:00–5:00	«Мои задачи» → «Выбрать команду» → «Заполнить пример этапа» → «Подтвердить этап · +10 баллов»	Ручное решение, подтверждённый результат, 10 баллов; обновить страницу и показать сохранённые записи

AI-запросы зависят от провайдера и могут занять дольше этих интервалов. Конкретные вопросы и AI-баллы не зафиксированы; показывайте смысл и основания изменения. Каталожные примеры используют проверяемые вручную оценки 93, 81, 89, 23 и 43 — это не результат текущего AI-вызова.

23.09.2026 полный браузерный сценарий с настоящим AI прошёл за 4 минуты 4 секунды, включая паузы проверки: библиотечный черновик 28 → 100, публикация, предложение, ручной выбор и сохранённые после reload +10 баллов. Это одна локальная репетиция, не гарантия задержки провайдера. После публикации повторное «Создать задачу» открыло пустой редактор.

Если внешний API недоступен, выберите «Продолжить с локальной проверкой» и покажите отметку «без AI». Остальной сценарий работает, но такой показ не доказывает качество AI-анализа. Локальный рейтинг учитывает лишь наличие информации и не превышает 27.

Обработка ошибок и безопасность

• Черновик: от 12 до 12000 символов; ответы и поля: до 4000 на поле и до 24000 в сумме. Неизвестные поля, пустые обязательные значения и неподтверждённая публикация отклоняются.
• Ссылки на прототип: только полные http:// и https:// адреса без встроенных учётных данных. Сервер не загружает и не исполняет их содержимое.
• Ключ остаётся на сервере. Ввод отправляется OpenAI только при запуске AI; для демо используйте синтетические сведения.
• В общий каталог и чужой браузер не передаются исходный частный черновик, внутренние пояснения AI и тексты предложений других команд. Публикуются подтверждённые поля, рейтинг и проверяемые по этим полям цитаты; исходный черновик и предложения доступны автору задачи.
• SQL-запросы параметризованы. Транзакции защищают начисление баллов, версия карточки предотвращает перезапись устаревших правок.
• Cookie владельца имеет HttpOnly, SameSite=Strict; при HTTPS добавляется Secure. Другой браузер может отправить предложение, но не изменить задачу или выбрать команду.
• Один браузер может выполнять один оплачиваемый анализ одновременно и запускать до шести в минуту. При ограничении возвращаются 429 и Retry-After; это защита одного процесса, не полная защита публичного сервиса от злоупотреблений.
• Общий предел процесса: два одновременно исполняемых анализа, до восьми незавершённых заданий. Старый синхронный /api/analyze использует те же общие ограничения. POST /api/analysis-jobs принимает UUID повторного запроса, а GET /api/analysis-jobs/{id} возвращает состояние только исходному владельцу.

Тесты

Windows:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts/evaluate_architect.py
.\.venv\Scripts\python.exe scripts/evaluate_workflows.py
.\.venv\Scripts\python.exe scripts/evaluate_semantics.py

Linux/macOS:

.venv/bin/python -m pytest -q
.venv/bin/python scripts/evaluate_architect.py
.venv/bin/python scripts/evaluate_workflows.py
.venv/bin/python scripts/evaluate_semantics.py

Тесты проверяют источники фактов, формат ответа агента, подмену оценок, ручное подтверждение, публикацию, отклики, права владельца, сохранность после перезапуска, конфликт версий, ссылки, локализацию и однократное начисление баллов. API-тесты используют временную SQLite и заменяют внешние AI-вызовы; pytest не расходует API-кредиты.

Проверки состояния интерфейса выполняются командой npm test из frontend/. Они используют встроенный тестовый модуль Node.js и проверяют, что правки и очищенные поля не теряются при повторной проверке, старый рейтинг не считается актуальным, а смена исходной задачи сбрасывает прежние факты.

data/evaluation_cases.json содержит 12 разных проверочных черновиков на трёх языках. Скрипт без флагов проверяет локальный режим. Для платной проверки реального AI добавьте --live --case library_ru --with-answers к команде скрипта. Он печатает вопросы, критерии, инструменты и проверки. Релевантность вопросов и обоснованность уровней нужно просмотреть вручную; автоматическая проверка структуры не доказывает качество смысла.

На финальном контрольном прогоне 23.09.2026: 162 Python-теста, 56 frontend-тестов и 135 проверок трёх офлайн-сценариев прошли. В трёх сквозных сценариях с реальным AI прошли 138 из 138 проверок. Отдельный более сложный набор выявил оставшиеся ошибки: завершились 5 из 6 анализов, все автоматические условия прошли 4 из 6 примеров; ручная проверка нашла дополнительные смысловые недочёты. Это не процент точности модели. Проверки и ограничения: docs/VALIDATION.md.

scripts/evaluate_semantics.py проверяет шесть синтетических задач из data/semantic_cases.json: существующий документ, недоступные в срок данные, нецелевую инструкцию, явно указанные email/PDF/CSV, качественную приёмку печатного результата и казахские отрицательные условия. Без флага это только офлайн-проверка инфраструктуры. --live --output .qa/semantic-review.json запускает шесть платных анализов; скрипт не перезаписывает существующий отчёт и не объявляет смысловую корректность без ручного просмотра.

Запуск проверен в изолированном clone на Windows; условия и результаты — в отчёте. Linux/macOS отдельно не запускались. scripts/evaluate_workflows.py без флагов проверяет три полных локальных сценария в отдельной базе; --live явно включает платный реальный AI. Дополнительный ограниченный benchmark: python -m pytest tests/test_api_performance.py -q -s тем же интерпретатором виртуального окружения.

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

• data/drafts.json, tasks.json, teams.json, proposals.json — по пять синтетических записей, связанных идентификаторами.
• data/seed_reviews.json — вручную подготовленные оценки учебных карточек с цитатами. Сервер считает их той же формулой и помечает источник sample.
• data/evaluation_cases.json — собственный набор проверки AI; не учебная выборка модели и не реальные персональные данные.
• data/acceptance_cases.json — три дополнительных самостоятельных сценария с полными синтетическими ответами и требованиями для ручной оценки: ремонт проекторов, казахские эссе и инструкция архива.
• data/semantic_cases.json — шесть целевых сложных примеров, включая три новых контрольных входа; не статистически репрезентативная выборка.
• Единственная внешняя интеграция приложения — OpenAI API. Данные приложения хранятся локально; frontend отдаёт тот же сервер.

Ограничения

• Это MVP. Регистрации, восстановления доступа, подтверждения организации и надёжной идентификации команды нет.
• Доступ автора держится на cookie исходного браузера. Её удаление или смена браузера лишает возможности управлять прежней задачей; восстановления нет.
• В демо можно выбрать любой учебный профиль команды или указать своё название. Это не доказательство принадлежности команды отправителю; для публичного запуска нужны аккаунты и проверка прав.
• Учебные задачи доступны для просмотра и предложений, но посетитель не может принимать решения за их вымышленного владельца. Для полного сценария создайте свою публикацию.
• Человек подтверждает факт выполнения этапа; сервис не проверяет репозиторий или прототип самостоятельно. В MVP один учитываемый этап на предложение.
• Цитаты предотвращают добавление нового текста в поля, но не гарантируют истинность пользовательских сведений или безошибочность смысловой оценки AI.
• Известные ошибки AI: факт или срок может попасть не в нужное поле; модель может засчитать подразумеваемую проверку результата или описать необязательное уточнение как главный пробел. На сложном казахском примере получена ошибка валидации. Недоступные в срок данные и явно указанные email/PDF/CSV обработаны правильно в последней целевой проверке, но это не гарантия для других входов. Проверяйте основания баллов перед подтверждением.
• Изменённые после анализа поля теряют прежнюю AI-оценку и получают консервативный локальный рейтинг до повторной проверки. Источник оценки показан явно.
• При недоступном хранилище браузера интерфейс предупреждает, что восстановление после перезагрузки не гарантируется. Публикация и отправка предложения не имеют серверной идемпотентности: при неопределённом сетевом сбое сначала проверьте, появилась ли запись; интерфейс не повторяет эти изменения автоматически.
• Каталог пока загружается целиком. Проверка на 1 000 задач — небольшой локальный benchmark, не обещание промышленной нагрузки; для дальнейшего роста нужна серверная пагинация. Локальные БД и сохранённые черновики не зашифрованы приложением.
• Чат, уведомления, календарь, загрузка файлов, рекомендации по навыкам и производственная инфраструктура не реализованы. Автоматическое назначение команды отсутствует по требованиям кейса.

Ссылка на deployed-версию

Публичная версия не развёрнута. Локальный адрес: http://127.0.0.1:8000.

Команда

Git-аккаунт	Подтверждённые изменения
ibrakhim2906	Структура проекта, первая версия, финальные AI/UI и тесты
SlrLothar	Frontend
Beiba0404	Architecture