Career Quest

Описание и назначение

Внутренняя HR-платформа показывает сотруднику профиль, разрывы навыков до следующего грейда и до трёх объяснимых активностей. HR видит агрегированные дефициты навыков, участие и причины отсутствия подходящего шага. Рекомендации не являются оценкой сотрудника или решением о повышении.

Исходный датасет организаторов в BackendAI/dataset/: 200 сотрудников, 40 активностей, 60 навыков, 32 профиля ролей, 2743 записи истории. Данные синтетические; дата среза — 2026-10-01. Формат описан в README датасета.

Ценность и применимость

Career Quest превращает разрозненный каталог HR-активностей в понятный следующий карьерный шаг. Сотрудник видит, какой разрыв сокращает рекомендация и как прохождение влияет на требования следующего грейда. Негативная история похожих активностей снижает приоритет, поэтому система не предлагает обучение только потому, что навык имеет самый низкий уровень. HR получает агрегированный срез дефицитов и причины отсутствия подходящего шага без публичного рейтинга сотрудников.

Подход применим к новому каталогу и новым профилям без переобучения: данные загружаются в исходном JSON/CSV-формате через /api/upload, валидируются и сразу участвуют в том же расчёте. Если подходящих активностей нет или требования уже выполнены, система возвращает объяснимый пустой результат вместо искусственной рекомендации.

Оригинальность и потенциал развития

Решение разделяет принятие решения и генерацию текста: воспроизводимый Python-скоринг выбирает и ранжирует активности, а LLM только формулирует объяснение из уже рассчитанных факторов. Такой слой продолжает работать без внешнего API, не передаёт провайдеру имя или ID сотрудника и позволяет проверить каждый балл. Специальных веток для проверочных профилей жюри нет — они проходят через общий алгоритм.

Следующие шаги развития: серверное разграничение Employee/HR, интеграция с корпоративными LMS/HRIS, локальная LLM внутри защищённого контура и мониторинг качества рекомендаций на обратной связи. Эти возможности не заявлены как реализованные в текущем прототипе.

Архитектура

BackendAI/app/main.py отдаёт API и static/ одним FastAPI-сервером. Pydantic проверяет вход. loader.py читает JSON/CSV и хранит снимок в памяти; scoring.py фильтрует и ранжирует; explain.py формулирует объяснения; completion.py симулирует завершение; profiles.py строит профиль и HR-срез. Завершения после последней оценки навыков применяются по датам с учётом max_level; более ранние уже включены в оценку. Отсутствующий навык имеет уровень 0.

/api/upload добавляет или заменяет записи по ID, требования роли — по паре (role, grade). Весь пакет проверяется до публикации нового снимка; ошибка сохраняет прежнее состояние. Исходные файлы не изменяются.

Технологии

Python 3.12, FastAPI, Uvicorn, Pydantic v2, pandas, OpenAI Python SDK; HTML, локальный CSS и vanilla JavaScript. Текущий фронтенд не подключает Tailwind или DaisyUI: static/index.html использует static/style.css и локальный Manrope из static/vendor/.

Оформление интерфейса

Интерфейс оформлен в static/style.css. Палитра задана переменными :root: основной зелёный #00896B, тёмный #005744, текст #0B1F1A, вторичный текст #5B7A72, фон #F4F8F6, границы #E2EBE7. Manrope с начертаниями 400–800 подключён локально для латиницы и кириллицы; запасной стек — системные шрифты. Скругления карточек, кнопок и крупного блока профиля составляют 16, 10 и 20 px; у карточек и блока профиля отдельные тени. Отступы компонентов собраны вокруг шагов 8, 12, 16, 20, 24, 28, 36 и 40 px.

Повторяющиеся элементы оформлены классами card, button-*, factor-pill, skill-*, profile-*, quest-*, hr-*, nav-tab, data-drop. Разметка создаётся тем же static/app.js; API и расчёт рекомендации оформлением не меняются. Страница загружает только /, /static/... и запросы /api/...; при отключённом интернете шрифт и CSS остаются доступными через локальный сервер.

Быстрый запуск

Требуются Git, свободный порт 8000 и Docker Desktop для Windows/macOS либо Docker Engine с Compose v2.24+ для Linux. На Windows Docker Desktop должен быть запущен в режиме Linux containers; Python и зависимости отдельно устанавливать не нужно. Ключ LLM для основной проверки не нужен.

Docker Compose — рекомендуемый способ

Клонируйте репозиторий и перейдите в его каталог:

git clone https://github.com/BAITC-Hacks/hack-26559053-cairx.git
cd hack-26559053-cairx

Соберите и запустите приложение одной командой:

docker compose up --build --wait --wait-timeout 60

Команда запускает контейнер в фоне и завершается после успешного /api/health. Файл .env необязателен: без LLM-ключей автоматически используется локальное объяснение.

• Интерфейс: http://localhost:8000
• Swagger UI: http://localhost:8000/docs
• Health check: http://localhost:8000/api/health

# Логи
docker compose logs -f app

# Остановка
docker compose down

Для live-объяснений скопируйте пример, добавьте собственный ключ провайдера и повторите команду запуска:

cp .env.example .env

Не добавляйте реальные ключи в .env.example или другие файлы репозитория. Локальный .env исключён из Git.

Локальный запуск без Docker

Нужен Python 3.12+. На Linux/macOS из корня проекта:

python3 -m venv BackendAI/.venv
BackendAI/.venv/bin/python -m pip install -r BackendAI/requirements.txt
BackendAI/.venv/bin/python BackendAI/run.py

На Windows используйте BackendAI/.venv/Scripts/python.exe вместо BackendAI/.venv/bin/python. Скрипт BackendAI/run.py --llm openai может запросить ключ скрытым вводом для текущего процесса; также доступны --llm nvidia и --llm both. BackendAI/set_llm_env.ps1 сохраняет ключ как пользовательскую переменную Windows.

Образ содержит backend, dataset и static/; дополнительные volumes для Docker-запуска не требуются. После изменений кода повторите команду запуска с --build.

Переменные окружения

Образец конфигурации — корневой .env.example. Приложение читает переменные процесса, а Docker Compose передаёт ему необязательный корневой .env.

Переменная	Значение по умолчанию / назначение
PROJECT_NAME, VERSION, DESCRIPTION, API_V1_STR	Career Quest, 2.0.0, описание API, /api/v1
HOST, PORT, DEBUG	0.0.0.0, 8000, false
CORS_ORIGINS	*; список через запятую или JSON-массив
DATA_DIR	dataset, путь относительно BackendAI/ или абсолютный
SNAPSHOT_DATE	2026-10-01 для истории, стажа и сессий
MAX_UPLOAD_BYTES	10485760 на пакет
OPENAI_API_KEY, NVIDIA_API_KEY	Необязательные ключи провайдеров
OPENAI_MODEL, NVIDIA_MODEL	gpt-4o-mini, meta/llama-3.1-70b-instruct
LLM_TIMEOUT_SECONDS, LLM_TOTAL_TIMEOUT_SECONDS	8 секунд на провайдера, 9 секунд на все объяснения

Порядок проверки основного сценария

Начните с POST /api/reset в /docs или curl-команды ниже. В интерфейсе откройте вкладку «Сотрудник» и ищите по имени.

1. Обычный профиль: E0001, Marat Yessenov, Backend Engineer, Junior → Middle. В навыках видны разрывы System Design 1→2, API Design 2→3, Public Speaking 0→1. «Следующие шаги» показывают EV_005 System Design Fundamentals с сырым баллом 60, затем EV_036 Public Speaking Club с баллом 20. Карточки содержат объяснение и числовые factors. Без ключа LLM ответ имеет llm_used: false.
2. Низкий навык против критичного: E0042, Ekaterina Kuznetsova, Frontend Engineer, Junior → Middle. API Design равен 0 при требовании 1 и не критичен. Критичный TypeScript равен 1 при требовании 3. Первой рекомендацией идёт EV_013 TypeScript in Depth (40), затем EV_036 и EV_017. В «Не рекомендуем сейчас» найдите System Design Fundamentals, развивающий API Design: интерфейс показывает причину исключения. В ответе API эта активность имеет event_id: EV_005, reason_code: history_penalty и итог −10 из-за похожей истории; компоненты есть в factors.score_breakdown.
3. Завершение активности: E0001 и EV_005. Нажмите «Пройти» на карточке System Design Fundamentals. Интерфейс обновит профиль: System Design 1→2 и API Design 2→3, прогресс траектории и список рекомендаций. Ответ /api/complete также показывает уровни до/после; повторный запрос возвращает HTTP 409. Грейд не меняется.
4. HR-срез. Переключите роль на HR и откройте вкладку «HR»: видны дефициты относительно целевых требований, участие и сотрудники без доступного шага с причинами. Счётчик «Без рекомендованного шага» равен числу записей в no_recommendation. Это агрегаты, не рейтинг.

Дополнительный воспроизводимый пример из BackendAI/tests/fixtures/jury/: загрузите вместе employees.json и activity_history.csv. У JURY_HISTORY_TRAP Public Speaking 0→2 и критичный System Design 3→4. Три пропуска клуба дают EV_036 расчёт 20 + 10 + 0 − 90 = −60; рекомендуются EV_006 и EV_007. У JURY_NO_HISTORY с теми же навыками EV_036 входит третьим с баллом 30. У JURY_REQUIREMENTS_MET нет разрывов и рекомендаций. После демонстрации сброс удаляет эти профили.

Эквивалентные curl-команды

Из корня проекта при работающем сервере; завершение меняет данные в памяти.

curl -X POST http://localhost:8000/api/reset
curl http://localhost:8000/api/employees/E0001
curl -X POST http://localhost:8000/api/recommend -H 'Content-Type: application/json' -d '{"employee_id":"E0001"}'
curl http://localhost:8000/api/employees/E0042
curl -X POST http://localhost:8000/api/recommend -H 'Content-Type: application/json' -d '{"employee_id":"E0042"}'
curl -X POST http://localhost:8000/api/complete -H 'Content-Type: application/json' -d '{"employee_id":"E0001","event_id":"EV_005"}'
curl http://localhost:8000/api/hr/overview

Готовый пример файла собственных профилей — BackendAI/tests/fixtures/jury/employees.json; его можно использовать как образец структуры и заменить содержимое своими профилями. Пример загрузки файла вместе с историей:

curl -X POST http://localhost:8000/api/upload -F 'files=@BackendAI/tests/fixtures/jury/employees.json' -F 'files=@BackendAI/tests/fixtures/jury/activity_history.csv'
curl http://localhost:8000/api/employees/JURY_HISTORY_TRAP
curl -X POST http://localhost:8000/api/recommend -H 'Content-Type: application/json' -d '{"employee_id":"JURY_HISTORY_TRAP"}'
curl -X POST http://localhost:8000/api/reset

После загрузки примера /api/health показывает 203 сотрудника. /api/upload принимает от одного до четырёх файлов с именами employees.json, events.json, skills.json, activity_history.csv; поле multipart — files или files[]. JSON допускает исходную обёртку или массив; skills.json может содержать skills и/или role_profiles. Дубли ID внутри файла, неизвестные ссылки и неверные схемы отклоняют весь пакет. Повторная загрузка заменяет существующие ID; будущая история сохраняется, но не участвует в текущем срезе.

Как формируется рекомендация

Цель — следующий грейд в текущей роли; личная карьерная цель не переопределяет его. Для Lead следующий грейд отсутствует (next_grade: null), но оставшиеся разрывы проверяются по требованиям Lead. Прогресс траектории равен sum(min(текущий, требуемый)) / sum(требуемый) по целевым навыкам с округлением до четырёх знаков; это покрытие требований, не вероятность повышения.

Фильтры. Активность исключается, если она обязательная; уже пройдена (кроме повторяемого EV_036, доступного один раз в дату среза); находится в процессе; не подходит текущей роли или грейду; не выполнены prerequisites; нет сессии на дату среза или позже (самостоятельные self_paced доступны всегда); достигнут потолок max_level по всем её навыкам; нет сокращения разрыва до целевых требований; либо требования целевого профиля не загружены.

Для полезного навыка s: c_s — текущий уровень, r_s — требование целевого грейда, gain_s и max_level_s — свойства активности. Реальный прирост g_s = min(gain_s, max(0, max_level_s − c_s)). В суммы входят только навыки с c_s < r_s и g_s > 0. Формула с фактическими весами из BackendAI/app/services/scoring.py:

raw = 10 × Σ(r_s − c_s)
    + 10 × Σ min(g_s, r_s − c_s)
    + 20 × число критичных для целевого грейда полезных навыков
    − 30 × (пропуски/прерывания + отказы по похожим активностям)

Первое слагаемое — размер разрыва до следующего грейда. Второе — покрытие разрыва достижимым приростом активности с учётом потолка. Третье — критичность навыка именно для целевого грейда. Четвёртое — штраф за dropped, no_show и declined по похожим активностям. Похожесть означает тот же тип или общий развиваемый навык; одна запись считается один раз. Выполненные похожие активности показываются в history_fit.similar_attended, но балл не повышают. При raw <= 0 кандидат исключается с history_penalty.

Положительные кандидаты сортируются по убыванию сырого балла, при равенстве — по возрастанию event_id; берутся первые три. Публичный score = round(raw / (raw + 100), 6) сохраняет этот порядок. Остальные положительные кандидаты получают lower_priority и сравнение с последним выбранным; при равенстве явно указана ничья. Каждая активность каталога находится ровно в recommendations или not_recommended. Коды исключений: ineligible, missing_target, no_gap, history_penalty, lower_priority. У жёстких исключений factors: null; у оценённых альтернатив факторы сохраняются. Исключения по истории и низшему приоритету идут прежде остальных, внутри групп — по event_id.

Рекомендация опирается на четыре независимых фактора, однофакторного правила в системе нет. Детерминизм дают фиксированная дата среза, расчёт в Python по одному снимку данных и стабильная сортировка. При одинаковых профиле и истории порядок и числовые factors повторяются; generated_at отражает реальное время запроса.

В карточке рекомендации блок «Почему подходит» показывает плашки с числовыми factors из /api/recommend: разрыв, критичность, похожую историю, достижимость и компоненты итогового балла. В factors.skill_gains[] и factors.gap_closure API передаёт код навыка, поэтому плашка показывает этот код без выдуманного названия. Полный ответ с исходными факторами доступен в /docs.

Числа и порядок считаются детерминированно. LLM только формулирует текст из рассчитанных факторов и содержания активности при temperature=0. Для каждой карточки пробуется OpenAI, затем NVIDIA; до трёх объяснений обрабатываются параллельно с общим лимитом 9 секунд. Если провайдер недоступен, работает локальный шаблон. llm_used показывает, применялся ли LLM хотя бы к одной карточке; explanation_source, explanation_model, explanation_cached, explanation_fallback_reason показывают путь каждой карточки. Успешные тексты кешируются до пяти минут, fallback — нет. Имена и ID сотрудников не отправляются провайдерам; числовые factors остаются источником решения.

API и ошибки

Маршруты доступны под /api и под API_V1_STR (по умолчанию /api/v1).

Маршрут	Результат
GET /api/health	Статус, число сотрудников, дата среза, настроенный провайдер
GET /api/employees	Поиск имени/ID, фильтры role, grade, limit (50 по умолчанию, максимум 1000)
GET /api/employees/{employee_id}	Профиль, эффективные навыки, разрывы, история, траектория
POST /api/recommend	JSON с employee_id; до трёх шагов, факторы и причины исключений
POST /api/complete	JSON с employee_id и event_id; уровни до/после и новые шаги
GET /api/hr/overview	Дефициты, участие, причины отсутствия рекомендаций
POST /api/upload, POST /api/reset	Загрузка и возврат исходных данных

Для участника, подключающего frontend: GET /api/employees без параметров возвращает только первые 50 из 200 исходных сотрудников. Для полного списка используйте GET /api/employees?limit=1000; это существующий параметр API, менять контракт не требуется. В текущем static/app.js загрузка списка уже вызывает маршрут с limit=1000.

Есть алиасы POST /api/recommend/{employee_id} и POST /api/complete/{employee_id}/{event_id}. Обязательную или повторно завершённую активность нельзя симулировать (409). Неверный вход — 422, отсутствующий ID — 404, превышение лимита — 413. Ошибки возвращают JSON с success: false, error_code, detail; ошибка валидации также имеет errors. Стек внутренней ошибки клиенту не раскрывается.

Проверка без личных аккаунтов команды

Штатный автономный режим: запустите docker compose up --build --wait --wait-timeout 60 без .env и выполните сценарий выше. Исходный датасет уже находится в образе. Поиск сотрудников, профиль, числовой скоринг, объяснения, завершение активности, HR-срез, загрузка и сброс работают без внешнего сервиса. В ответе POST /api/recommend будет llm_used: false, а у карточек explanation_source: "template" и explanation_fallback_reason: "not_configured". Порядок рекомендаций и factors совпадают с режимом LLM. Логин и регистрация не нужны; переключатель роли в интерфейсе не является авторизацией. Проверочные профили в BackendAI/tests/fixtures/jury/ искусственные, автоматически не загружаются и не имеют специальных веток в алгоритме.

Для проверки LLM-пути скопируйте .env.example в .env, добавьте собственный ключ провайдера и повторите команду запуска с --build и --wait. Успешный вызов помечается llm_used: true и explanation_source: "openai"; при ошибке или таймауте используется тот же локальный шаблон. Ключ нужен только для текста объяснения и не требуется для проверки основного сценария. Не добавляйте реальные ключи в .env.example или другие файлы репозитория.

Тесты и запуск

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

BackendAI/.venv/bin/python -m pytest BackendAI/tests -q
BackendAI/.venv/bin/python -m pytest BackendAI/tests/test_jury_scenario.py -q

В Windows замените путь к Python как выше. Тесты покрывают исходный датасет, фильтры, ранжирование, историю и потолки навыков, загрузку и сброс, прохождение, ошибки API, HR-агрегаты и сбои провайдеров. Внешний ключ для них не нужен.

Без локальной установки Python тесты можно запустить через Compose:

docker compose run --rm app python -m pytest tests -q

Известные ограничения

Формула — прозрачная эвристика с фиксированными весами, не подтверждённый прогноз обучения или повышения. Совпадение по широкому типу активности может штрафовать другой курс; причины пропусков неизвестны. gain — допущение каталога, а /api/complete демонстрирует расчёт, не подтверждает участие. При отсутствии подходящих курсов шагов может быть меньше трёх или ноль. Переход в другую роль и личная карьерная цель не моделируются. Состояние живёт в памяти одного процесса; перезапуск и /api/reset удаляют загрузки и симуляции. API не имеет аутентификации. Смысл сгенерированного LLM текста не проверяется полностью — сверяйте его с factors.

Использованные внешние материалы

BackendAI/requirements.txt задаёт диапазоны допустимых версий, а не точные версии установленной среды; lock-файла нет. Лицензии указаны по первичным страницам проектов.

Компонент	Версия из requirements.txt	Лицензия и источник
FastAPI	>=0.115.0	MIT
Uvicorn (standard)	>=0.30.0	BSD-3-Clause
Pydantic	>=2.8.0,<3	MIT
pydantic-settings	>=2.9.0,<3	MIT
python-multipart	>=0.0.18	Apache-2.0
httpx	>=0.27.0	BSD-3-Clause
openai (Python SDK)	>=1.40.0,<3	Apache-2.0
pandas	>=2.2.0	BSD-3-Clause
pytest	>=8.0.0	MIT
pytest-asyncio	>=0.23.0	Apache-2.0

Фронтенд использует локальный static/style.css; внешние CSS-фреймворки в текущем HTML не подключены. Manrope загружается локально из static/vendor/; исходный проект шрифта, лицензия SIL OFL 1.1. Запасные системные шрифты выбирает браузер.

Датасет организаторов — BackendAI/dataset/; данные синтетические, люди и компании вымышлены. Описание исходного набора.

При разработке использовался OpenAI Codex для анализа кода и документации; изменения проверялись по исходникам и запуском приложения. Рабочий интерфейс использует только static/ без React и сборщиков. Файлы BackendAI/Files/ — рабочие текстовые черновики, не исполняемые компоненты.