hack-7f3075b1-nazhmdt

Репозиторий команды HackAlem AI для участника nazhmdt.

Выбран кейс 1: Career Quest — AI-навигатор развития сотрудника. Employee-first MVP с закрытым профилем, карьерной лестницей, заданиями, Coins и отдельным HR-контуром.

1. Название проекта

Рабочее название решения — Career Quest.

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

Career Quest превращает развитие сотрудника в понятный маршрут: личный профиль → карьерная лестница → персональные задания и курсы → Coins и достижения → следующий уровень. Сотрудник видит только свой кабинет; HR получает отдельный контур для анализа индивидуальных и командных рисков.

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

Реализованы демо-вход по коду сотрудника, личный кабинет в стиле мобильного приложения Halyk, карьерная лестница, прогресс, Coins, достижения, персональные рекомендации и выполнение активностей. В разделе «Развитие» добавлен AI-помощник: он объясняет интерфейс, помогает выбрать первый шаг и отвечает на вопросы о развитии. HR-сводка сохранена отдельным API-контуром и не показывается сотруднику в основном интерфейсе.

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

Сценарий сотрудника: ввести код → открыть личный кабинет → увидеть текущую роль и следующий уровень → перейти в «Развитие» → задать вопрос AI-помощнику или выбрать рекомендованный курс/задание → выполнить его → получить Coins и обновлённый прогресс. Рекомендации строятся по навыкам, истории и карьерной цели, а причины видны сотруднику. Если ключ OpenAI не настроен, помощник использует локальные демо-ответы, поэтому основной сценарий всегда доступен жюри.

5. Технологии

Для ведения проекта используются Git, GitHub и AI-агент Codex. MVP написан на Python без внешних зависимостей: стандартный HTTP-сервер, HTML/CSS/JavaScript и синтетический датасет. AI-модель подключается опционально через OpenAI Responses API; рекомендации и локальный fallback работают детерминированно.

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

В репозитории находятся:

• README.md — описание текущего состояния проекта.
• .gitignore — исключения для локальных секретов и генерируемых файлов.
• app/data_loader.py — загрузка и проверка JSON/CSV.
• app/recommendations.py — цели, gaps, фильтры и ranking рекомендаций.
• data/career_quest_dataset/ — синтетический стартовый датасет.
• app/service.py — состояние сценария сотрудника и HR-сводка.
• app/server.py — локальный HTTP API и раздача интерфейса.
• app/static/ — employee-first интерфейс с входом, карьерным маршрутом, Coins, заданиями, настройками и AI-помощником.
• scripts/build_static.py — сборка автономной демонстрационной версии для публикации.
• scripts/build_single_file.py — сборка файла career-quest-standalone.html для простого статического хостинга.
• tests/ — проверки загрузки, recommendation engine и сценария выполнения активности.
• scripts/demo_recommendations.py — воспроизводимый пример для трёх профилей.
• hr_dashboard/ — отдельный HR-сайт и сервер; employee-сайт остаётся без изменений.

Подробный анализ кейса находится в анализе кейса.

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

Для получения исходников необходимы Git и доступ к приватному репозиторию команды:

git clone https://github.com/BAITC-Hacks/hack-7f3075b1-nazhmdt.git
cd hack-7f3075b1-nazhmdt

Внешние зависимости для текущего MVP не нужны. Из корня репозитория выполните:

python3 -m unittest discover -s tests -v
python3 scripts/demo_recommendations.py
python3 -m app.server

После запуска откройте http://127.0.0.1:8000.

Для другого интерфейса/порта: python3 -m app.server --host 0.0.0.0 --port 8000. Адрес 127.0.0.1 доступен только пока процесс сервера запущен.

API-ключи нельзя добавлять в репозиторий.

AI-помощник и API-ключи

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

export OPENAI_API_KEY="ваш_ключ_openai"
python3 -m app.server

Модель можно заменить без изменения кода:

export OPENAI_MODEL="gpt-4o-mini"

Ключ используется только сервером в endpoint /api/coach, не попадает в JavaScript и не должен храниться в .env, GitHub или в HTML-файле. На хостинге ключ добавляется в защищённые runtime environment variables, если хостинг поддерживает серверные переменные. При размещении одного статического HTML-файла ключ добавлять нельзя — используется демо-режим.

NVIDIA API для текущего MVP не обязателен. Его можно подключить позже для отдельной модели, но ключ также должен храниться только в серверных переменных.

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

Проверочный сценарий использует профили E0001, E0002 и E0028. Тесты проверяют количество и связи данных, выбор цели, расчёт gaps, отсутствие обязательных и уже завершённых активностей в рекомендациях, а также сценарий просмотра профиля и выполнения активности.

Быстрая проверка жюри без API-ключа

API-ключ жюри не нужен: основной сценарий и локальный fallback AI-агента работают автономно.

git clone https://github.com/BAITC-Hacks/hack-7f3075b1-nazhmdt.git
cd hack-7f3075b1-nazhmdt
python3 -m app.server

Откройте http://127.0.0.1:8000/ и войдите кодом E0002. Затем проверьте:

1. Главная — новости компании и баланс Coins.
2. Развитие — персональные задания, курсы и тесты.
3. AI-агент — нажмите «С чего начать развитие?» или задайте свой вопрос.
4. Курс/тест — откройте демо-карточку и завершите сценарий.
5. Coins — убедитесь, что награда добавилась в баланс.
6. Профиль — проверьте настройки языка, темы и уведомлений.

Для проверки изолированных профилей можно выйти и войти кодом E0001 или E0028: сотрудник видит только собственный профиль.

Проверка AI-ответа через OpenAI

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

export OPENAI_API_KEY="ключ_жюри"
export OPENAI_MODEL="gpt-4o-mini"
python3 -m app.server

Ключ не нужен для оценки MVP и не должен добавляться в GitHub. Endpoint /api/coach использует его только на сервере. Если ключ не задан или временно недоступен, интерфейс автоматически возвращается к контекстному демо-ответу.

Полный сценарий проверки вынесен в docs/jury-check.md.

Отдельная HR-панель запускается отдельным процессом рядом с employee-сайтом. Сначала в одном терминале запустите основной сервер, затем во втором:

python3 -m hr_dashboard.server

Она открывается на http://127.0.0.1:8010/, использует код HR-DEMO-2026 и обновляет сводку каждые 15 секунд. Клик по сотруднику открывает подробную статистику: прогресс, карьерную цель, Coins, навыковые разрывы, рекомендации и последнюю активность. В HR-панели также можно загрузить дополнительные employees.json и activity_history.csv; employee-сайт при этом не изменяется. Подробности — в docs/hr-dashboard.md.

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

В репозитории используется синтетический датасет Career Quest: 200 профилей, 40 активностей, 60 навыков и 2 743 записи истории. Опциональный AI-помощник использует OpenAI Responses API через серверный endpoint /api/coach; внешний ключ не передаётся в браузер. HR и банковские интеграции пока не подключены.

10. Ограничения

• LLM-слой подключается опционально; без ключа используется локальный fallback, а рекомендации формируются детерминированным ядром.
• Вход по коду и Coins работают в демонстрационном режиме; постоянная БД и интеграции с HR/банковскими системами не подключены.
• Состояние выполнения активности хранится в памяти процесса и сбрасывается после перезапуска.

11. Развёрнутая версия

Открыть демонстрацию Career Quest

12. Один файл для самостоятельного хостинга

После сборки проекта выполните:

python3 scripts/build_static.py
python3 scripts/build_single_file.py

Готовый career-quest-standalone.html содержит интерфейс, стили, JavaScript и демо-данные внутри одного файла. Файл собирается локально и намеренно не хранится в GitHub, чтобы оставить тебе личную версию для проверки. Его можно загрузить на статический хостинг. В таком режиме AI-помощник работает в демо-режиме; для OpenAI нужен серверный endpoint и защищённая переменная OPENAI_API_KEY.