Career Quest — AI-навигатор развития сотрудника

Хакатон: HackAlem AI | Трек: Halyk Bank | Команда: Gophers

Платформа геймификации жизненного цикла сотрудника с объяснимыми AI-рекомендациями развития, динамическим радаром компетенций и моделированием альтернативных карьерных траекторий (Career Twin).

---

🌟 Ключевые возможности

1. Профиль сотрудника и радар компетенций:

   • Наглядная карта hard/soft навыков (текущий уровень vs требования следующего грейда).
   • Выделение критичных навыков (critical_skill) для повышения.
   • История активностей за 24 месяца со статусами прохождения.

2. Объяснимые AI-рекомендации (Explainability):

   • Подбор 1–3 релевантных шагов с обоснованием минимум по 3 факторам: грейд, разрывы компетенций, история участия (штрафы за drop/no-show), критичность для промоушена и пререквизиты.
   • Multi-LLM Pipeline: OpenAI gpt-4o-mini (основная) $\to$ NVIDIA API (фолбэк) $\to$ Heuristic Fallback (без падений при отсутствии ключей/сети).
   • Локализация обоснования на 3 языка: казахский (kk), русский (ru), английский (en).

3. Интерактивный цикл развития (Completion):

   • Отметка активности как выполненной пересчитывает навыки с учетом правила роста (gain до max_level) и обновляет траекторию в реальном времени.

4. Career Twin (Альтернативные карьерные пути):

   • Сравнение «Быстрого пути» (максимальная скорость закрытия разрывов) и «Гибкого пути» с учетом ограничений сотрудника (формат: онлайн / офлайн / в своем темпе, доступные часы в неделю).
   • Прогноз готовности к следующему грейду (readiness %).

5. HR-дашборд и приватность:

   • Агрегированная аналитика по проседающим навыкам и вовлеченности в разрезе департаментов.
   • Строгое соблюдение приватности: данные об индивидуальной вовлеченности скрыты от коллег, доступ к HR-аналитике защищен ролью (X-Role: hr).

6. Проверочные профили жюри (Jury-Ready):

   • Эндпоинт POST /admin/load-dataset для загрузки дополнительных тестовых профилей и истории в формате стартового кита.
   • Успешно проходит проверочный сценарий жюри с конфликтом факторов (System Design vs Public Speaking).

---

🚀 Быстрый запуск и деплой (One-Command Deploy)

Запуск через Docker Compose (Рекомендуемый способ для жюри)

Все сервисы (бэкенд, фронтенд, датасет) поднимаются одной командой:

# 1. Склонируйте репозиторий и перейдите в папку проекта
git clone https://github.com/BAITC-Hacks/hack-463da2da-gophers.git
cd hack-463da2da-gophers

# 2. (Опционально) Создайте .env и укажите ключи для LLM-объяснений:
cp .env.example .env
# Заполните OPENAI_API_KEY и/или NVIDIA_API_KEY в .env (при их отсутствии работает мгновенный heuristic fallback)

# 3. Запустите проект одной командой:
docker compose up --build

После запуска доступны:

• 🌐 Frontend (UI): http://localhost:5173
• 🔌 Backend API: http://localhost:8000
• 📑 Интерактивная документация Swagger/OpenAPI: http://localhost:8000/docs

---

💻 Локальный запуск для разработки

Бэкенд (Python 3.11+ / FastAPI):

cd backend
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Запуск тестов (45 тестов):
pytest

# Запуск сервера:
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Фронтенд (React / TypeScript / Vite):

cd frontend
npm install
npm run build    # Проверка типов и сборка
npm run dev      # Запуск дев-сервера на http://localhost:5173

---

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

hack-463da2da-gophers/
├── backend/
│   ├── app/
│   │   ├── ai/                      # AI-ядро
│   │   │   ├── core/                # Анализатор профиля, расчет гэпов и скоринг
│   │   │   ├── llm/                 # Мультиязычный LLM Explainer (OpenAI/NVIDIA/Heuristic)
│   │   │   └── recommender.py       # Главный оркестратор рекомендаций
│   │   ├── api/                     # FastAPI эндпоинты, Pydantic схемы, хранилище
│   │   │   ├── routes.py            # REST API маршруты
│   │   │   ├── store.py             # In-memory хранилище датасета с валидацией
│   │   │   └── career_paths.py      # Движок Career Twin
│   │   └── main.py                  # Точка входа FastAPI
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── pages/                   # Страницы сотрудника, HR-дашборда, Career Twin
│   │   ├── api/                     # Клиент API по OpenAPI контракту
│   │   ├── i18n.ts                  # Локализация на kk/ru/en
│   │   └── theme/                   # Темная и светлая темы Halyk
├── docs/
│   └── openapi.yaml                 # OpenAPI 3.1.0 спецификация контракта
├── career_quest_dataset/            # Датасет стартового кита (200 профилей, 40 событий)
└── docker-compose.yml               # Единый конфигуратор запуска

---

📡 Спецификация API (OpenAPI 3.1)

Метод	Эндпоинт	Описание	Заголовки / Доступ
GET	/health	Проверка работоспособности сервиса	Публичный
GET	/employees	Список всех сотрудников компании	X-Role: hr
GET	/employees/{id}	Профиль сотрудника, радар навыков, история	X-Role: employee / hr
POST	/recommendations/{id}	AI-рекомендации с обоснованием (≥3 фактора)	X-Role: employee / hr
POST	/employees/{id}/complete/{event_id}	Отметка о прохождении и пересчет навыков	X-Role: employee / hr
POST	/employees/{id}/career-paths	Моделирование путей Career Twin	X-Role: employee / hr
GET	/hr/dashboard	HR-аналитика проседающих компетенций	X-Role: hr
POST	/admin/load-dataset	Загрузка проверочных датасетов жюри	X-Role: hr

---

🎯 Сценарий демонстрации для жюри (Demo Script)

1. Открытие профиля сотрудника:

   • Перейдите на http://localhost:5173.
   • Выберите сотрудника E0028 (Middle Backend Engineer).
   • Продемонстрируйте радар компетенций (текущий уровень vs требования Senior) и историю активностей.

2. Генерация AI-рекомендаций:

   • В блоке рекомендаций отображаются релевантные курсы и воркшопы.
   • Раскройте карточку: отображаются 3+ фактора скоринга и связное человечное обоснование на казахском/русском/английском языке.

3. Интерактивный сдвиг прогресса:

   • Нажмите «Выполнено» на одной из карточек.
   • Навык мгновенно вырастает с соблюдением max_level, радар перестраивается, а рекомендации автоматически пересчитываются.

4. Проверка Career Twin:

   • Разверните блок «Выбрать другой путь».
   • Укажите фильтр (например, только online, 4 часа в неделю) $\to$ система построит быстрый и гибкий маршруты с прогнозом готовности к промоушену.

5. HR-дашборд и безопасность:

   • Перейдите во вкладку «HR-дашборд».
   • Показаны топ-проседающие компетенции по департаментам и общая вовлеченность при сохранении приватности личных оценок.

6. Проверочный конфликтный кейс жюри:

   • Запустите команду тестирования конфликтного профиля: pytest backend/app/ai/tests/test_jury_check.py — убедитесь, что алгоритм не ведется на поверхностный гэп и отдает приоритет критическому навыку с учетом истории пропусков.

---

👥 Команда разработчиков

Проект разработан командой Gophers для хакатона HackAlem AI (Halyk Bank Track).