🚀 AI Sana Challenge Hub

AI-платформа, которая превращает сырую бизнес-проблему в структурированную, измеримую и готовую к работе задачу для студенческих команд.

Проект разработан в рамках HackAlem / AI Sana Challenge.

---

🎯 Что решает проект

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

Например:

«Хотим с помощью ИИ уменьшить очереди в нашей клинике».

Такого описания недостаточно, чтобы студенческая команда сразу начала работу:

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

AI Sana Challenge Hub помогает бизнесу пройти путь от такой идеи до полноценной карточки задачи.

---

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

Основной пользовательский сценарий:

Бизнес описывает проблему
        ↓
OpenAI анализирует описание
        ↓
Определяет недостающую информацию
        ↓
Генерирует ≥ 3 уточняющих вопросов
        ↓
Бизнес отвечает
        ↓
AI формирует структурированную карточку
        ↓
Бизнес проверяет и редактирует её
        ↓
Человек подтверждает карточку
        ↓
Рассчитывается Readiness Score 0–100
        ↓
Задача публикуется
        ↓
Попадает в каталог
        ↓
Студенческие команды предлагают решения
        ↓
Бизнес сравнивает предложения
        ↓
Accept / Reject
        ↓
Для принятой команды можно подготовить план пилота

AI помогает структурировать информацию, но не принимает финальные решения вместо человека.

---

✨ Возможности

Для бизнеса

Бизнес может:

• создать черновик задачи;
• получить AI-анализ;
• получить минимум 3 уточняющих вопроса;
• ответить на вопросы;
• получить структурированную карточку;
• проверить источники AI-полей;
• вручную изменить любое поле;
• получить AI-разбор качества карточки;
• увидеть Readiness Score;
• увидеть недостающую информацию;
• получить рекомендации по улучшению;
• подтвердить карточку;
• опубликовать задачу;
• просматривать предложения команд;
• сравнивать предложения;
• принять одну или несколько команд;
• отклонить предложения;
• подготовить и подтвердить план пилота;
• открыть печатную версию карточки/пилота.

---

Для студенческой команды

Команда может:

• открыть каталог задач;
• фильтровать задачи;
• сортировать задачи по готовности;
• открыть полную карточку;
• подготовить предложение;
• использовать AI-помощника для идеи и плана;
• самостоятельно отредактировать предложение;
• отправить предложение бизнесу.

---

🤖 Где используется AI

В проекте используется реальный OpenAI API.

AI применяется там, где требуется работа с естественным языком и неполной информацией.

1. Анализ первоначального описания

AI определяет, какой информации недостаточно.

Например:

Хотим автоматизировать работу склада.

Система может определить отсутствие:

users
data_and_materials
constraints
success_criteria
expected_result

---

2. Уточняющие вопросы

AI генерирует минимум три различных вопроса.

Например:

Кто будет основным пользователем системы?

Какие данные о работе склада уже доступны?

По каким показателям будет измеряться успех решения?

Backend дополнительно проверяет, чтобы вопросы действительно отличались друг от друга.

---

3. Формирование Task Card

После получения ответов AI структурирует предоставленные сведения.

AI не должен придумывать отсутствующие факты.

---

4. AI Review

Для уже сформированной карточки AI может найти:

• расплывчатые формулировки;
• пропущенные сведения;
• потенциальные противоречия;
• места, которые стоит дополнительно уточнить.

---

5. Proposal Coach

AI помогает студенческой команде подготовить:

• идею решения;
• план реализации;
• вопросы бизнесу.

При этом AI самостоятельно не назначает:

• название команды;
• сроки;
• prototype URL.

Финальное предложение отправляет человек.

---

6. Pilot Assistant

После ручного принятия команды AI может предложить:

• этапы пилота;
• открытые вопросы.

Фактические данные пилота берутся обычной логикой приложения из карточки задачи и предложения команды.

---

🛡 Защита от выдуманных AI-фактов

При генерации карточки AI возвращает:

значение
+
дословную цитату-источник

Backend принимает значение только если:

1. AI предоставил цитату;
2. цитата действительно присутствует в первоначальном описании или ответах пользователя;
3. значение прошло проверку.

Если подтверждения нет:

field = null

Тексты самих AI-вопросов не считаются источниками фактов.

После генерации карточку всё равно проверяет человек.

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

---

🧠 Structured Outputs

Backend не пытается разбирать произвольный текст LLM.

Используются:

• OpenAI Structured Outputs;
• AsyncOpenAI.responses.parse;
• Pydantic.

Пример AI-ответа:

{
  "missing_fields": [
    "users",
    "data_and_materials",
    "success_criteria"
  ],
  "questions": [
    "Кто будет пользоваться решением?",
    "Какие данные уже доступны?",
    "Как будет измеряться успех?"
  ]
}

Это позволяет backend работать с предсказуемой структурой данных.

---

🔐 OpenAI

Конфигурация находится в:

backend/app/core/config.py

Используются environment variables:

OPENAI_API_KEY=
OPENAI_MODEL=gpt-4.1-mini

API key:

• хранится только локально;
• не передаётся frontend;
• не хранится в исходном коде;
• не должен попадать в Git;
• не выводится в логи.

OpenAI-запросы выполняются с:

store=False

При ошибке API или невалидном ответе выполняется одна повторная попытка.

Если запрос всё равно не выполнен, пользователь получает понятную ошибку и может продолжить заполнение карточки вручную.

Скрытого mock AI fallback в рабочем приложении нет.

---

🏆 Readiness Score

Каждая задача получает рейтинг готовности:

0 ───────────────────────────────── 100

Он показывает насколько задача заполнена и готова к работе со студенческой командой.

Он не оценивает:

• ценность компании;
• коммерческий потенциал;
• качество идеи;
• достоверность предоставленных данных.

---

Формула

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

Рейтинг вычисляется обычной Python business logic.

LLM рейтинг не определяет.

Backend возвращает:

{
  "score": 75,
  "level": "ready",
  "missing": [],
  "improvements": []
}

---

Уровни

Score	Level
0–39	draft
40–69	working
70–89	ready
90–100	priority

Низкий рейтинг не запрещает публикацию.

---

🎮 Геймификация

Пользователь видит:

• текущий score;
• уровень;
• недостающие сведения;
• рекомендации;
• изменение рейтинга после редактирования.

Логика:

Более полная задача
        ↓
Выше Readiness Score
        ↓
Выше уровень готовности
        ↓
Выше позиция в каталоге

Это мотивирует бизнес улучшать качество постановки задачи.

---

📝 Task Card

Карточка содержит:

title
topic
context
need
users
data_and_materials
constraints
expected_result
success_criteria
contact
interaction_format

Также хранятся:

id
status
readiness_score
created_at
updated_at

---

Статусы

draft
  ↓
confirmed
  ↓
published

Если пользователь изменяет уже подтверждённую карточку:

confirmed → draft

После этого требуется повторное подтверждение и публикация.

Это предотвращает незаметное изменение уже подтверждённой задачи.

---

📚 Каталог

Каталог показывает опубликованные задачи.

Доступны:

• сортировка по Readiness Score;
• фильтр по topic;
• фильтр по readiness level;
• просмотр полной карточки.

Высокий рейтинг влияет на позицию задачи, но низкий рейтинг не скрывает её.

---

👨‍💻 Team Proposal

Команда может отправить:

team_name
solution_idea
plan
estimated_time
prototype_url

Количество предложений не ограничивается.

---

🤝 Business Decision

Бизнес просматривает предложения и самостоятельно принимает решение:

[ Accept ]

[ Reject ]

Можно:

• принять одну команду;
• принять несколько;
• отклонить все.

Автоматического AI-назначения команды нет.

---

📊 Сравнение предложений

Для бизнеса доступны два представления:

Cards

Каждое предложение показывается отдельной карточкой.

Comparison Table

Предложения можно сравнить между собой по основным параметрам.

---

🧪 Pilot Plan

После принятия предложения бизнес может подготовить план пилота.

Документ содержит:

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

Фактические поля копируются обычной Python-логикой.

AI предлагает только:

этапы
+
открытые вопросы

---

Правила Pilot Plan

AI-генерация сама ничего не сохраняет.

Сохранение ручных изменений снимает подтверждение.

Если исходная задача или предложение изменились:

Pilot → outdated

Перед подтверждением должны быть заполнены обязательные поля и существовать хотя бы один этап.

Для отклонённой команды нельзя сохранить или подтвердить pilot.

Подтверждение бизнеса не означает автоматического согласия команды.

---

🏗 Архитектура

                         USER
                           │
                           ▼
                ┌────────────────────┐
                │ React + TypeScript │
                │      Frontend      │
                └─────────┬──────────┘
                          │
                     HTTP / JSON
                          │
                          ▼
                  ┌──────────────┐
                  │   FastAPI    │
                  │   Backend    │
                  └──────┬───────┘
                         │
              ┌──────────┴──────────┐
              │                     │
              ▼                     ▼
      ┌───────────────┐      ┌──────────────┐
      │  OpenAI API   │      │  PostgreSQL  │
      │ Structured AI │      │ Persistent DB│
      └───────────────┘      └──────────────┘

Backend:

api/
      ↓
business_logic/
      ↓
data_access/
      ↓
PostgreSQL

---

🛠 Технологии

Frontend

• React
• TypeScript
• Vite
• Tailwind CSS
• React Router

Backend

• Python
• FastAPI
• Pydantic
• SQLAlchemy Async
• Alembic

Database

• PostgreSQL

AI

• OpenAI API
• OpenAI Python SDK
• Structured Outputs

Development

• Git
• GitHub
• Codex
• Pytest

---

📁 Структура

.
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── business_logic/
│   │   ├── core/
│   │   └── data_access/
│   │
│   ├── alembic/
│   └── tests/
│
├── frontend/
│   ├── src/
│   └── public/
│
├── scripts/
│   ├── start-local.ps1
│   ├── stop-local.ps1
│   └── check_secrets.py
│
├── docs/
│   └── AUDIT.md
│
├── .env.example
├── .gitignore
├── docker-compose.yml
└── README.md

---

🗄 Database

Основные сущности:

BusinessTask
TeamProposal

Используются:

• UUID;
• Foreign Keys;
• cascade delete;
• timestamps;
• indexes;
• status constraints;
• rating constraints.

Данные сохраняются в настоящей PostgreSQL.

---

🔄 Alembic

В проекте используются миграции:

0001
→ BusinessTask + TeamProposal

0002
→ Pilot document storage

Применение:

alembic upgrade head

---

🌱 Demo Data

Seed создаёт:

5 бизнес-задач
5 предложений команд

Задачи имеют разную степень заполненности, чтобы показать различные значения Readiness Score.

Seed является идемпотентным: повторный запуск не создаёт дубликаты.

---

🚀 Быстрый запуск на Windows

Для текущего development environment предусмотрен автоматический PowerShell-скрипт.

Из корня проекта:

powershell -ExecutionPolicy Bypass -File scripts/start-local.ps1

Скрипт:

1. запускает локальный PostgreSQL;
2. задаёт DATABASE_URL;
3. применяет Alembic migrations;
4. запускает seed;
5. запускает FastAPI;
6. запускает frontend;
7. ожидает готовности сервисов.

После запуска:

Frontend

http://localhost:5173

Backend / Swagger

http://127.0.0.1:8000/docs

Local PostgreSQL

127.0.0.1:55432

---

🛑 Остановка

powershell -ExecutionPolicy Bypass -File scripts/stop-local.ps1

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

---

⚙️ Стандартный запуск

Также проект можно запускать без portable development environment.

Потребуются:

• Python;
• Node.js;
• PostgreSQL либо Docker.

---

1. Clone

git clone <REPOSITORY_URL>
cd <REPOSITORY_NAME>

---

2. Environment

Создайте:

.env

на основе:

.env.example

Минимально:

OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4.1-mini

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/hackalem

Никогда не коммитьте .env.

---

3. Backend

cd backend

python -m venv .venv

Windows:

.venv\Scripts\activate

Linux/macOS:

source .venv/bin/activate

Установка:

pip install -r requirements.txt

Миграции:

alembic upgrade head

Запуск:

uvicorn app.main:app --reload

---

4. Frontend

В отдельном терминале:

cd frontend
npm install
npm run dev

---

❤️ Health Check

Backend предоставляет:

GET /api/health

Health endpoint проверяет не только FastAPI, но и доступность таблиц PostgreSQL.

---

🔌 Основные API

AI / Tasks

POST /api/tasks/analyze
POST /api/tasks/generate
POST /api/tasks/generate-with-sources
POST /api/tasks/preview
POST /api/tasks/review

Frontend использует:

POST /api/tasks/generate-with-sources

Ответ:

{
  "card": {},
  "sources": {}
}

---

Tasks

GET  /api/tasks
POST /api/tasks
GET  /api/tasks/{id}
PUT  /api/tasks/{id}

POST /api/tasks/{id}/confirm
POST /api/tasks/{id}/publish

---

Business

GET /api/business/tasks

---

Proposals

POST  /api/proposals/{task_id}

GET   /api/business/tasks/{task_id}/proposals

PATCH /api/business/proposals/{proposal_id}

---

Proposal AI Coach

POST /api/tasks/{id}/proposal-coach

---

Pilot

GET  /api/business/proposals/{id}/pilot
PUT  /api/business/proposals/{id}/pilot

POST /api/business/proposals/{id}/pilot/generate
POST /api/business/proposals/{id}/pilot/confirm

---

🎭 Роли

В интерфейсе есть переключатель:

Я бизнес
Я команда

Он используется