HackAlem AI #79-lite

API и веб-интерфейс для хакатон-задачи «умный подбор подрядчиков». Проект помогает организатору мероприятия быстро подобрать event-подрядчиков по городу, дате, формату, категории, бюджету, языку и длительности. На выходе пользователь получает до трёх карточек с конкретным объяснением, почему подрядчик подходит или почему точных вариантов меньше трёх.

Публичной deployed-версии пока нет. Проект запускается локально или через Docker Compose.

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

• Подбор подрядчиков из анонимизированного CSV-датасета на 66 профилей.
• Жёсткие фильтры по городу, категории, занятости на дату, бюджету, формату, языку и длительности.
• Поддержка составных категорий в CSV через |: запрос по одной категории находит часть составной.
• Стабильный порядок карточек для одинакового запроса.
• Максимум 3 карточки в ответе.
• Три различимых исхода для пользователя:
  • matched — найдены точные или близкие карточки;
  • no_category_in_city — в выбранном городе нет такой категории;
  • no_candidates_after_filters — категория есть, но условия отсеяли кандидатов.
• Прозрачные альтернативы, если точных совпадений меньше трёх: карточка сохраняет город, категорию и формат, а отличия по дате, бюджету, языку или длительности перечисляются в differences.
• Персональные объяснения по бюджету, формату, языку, длительности, дате и смыслу описания.
• Таблица сверки в каждой карточке: запрос заказчика сравнивается с данными исполнителя, а отличия подсвечиваются отдельно и не заменяют человеческое объяснение.
• Шесть быстрых сценариев с точными результатами, редкой категорией и прозрачными альтернативами.
• Fallback без OpenAI API: сервис продолжает работать детерминированно без ключа.
• Веб-интерфейс с ручной формой, вкладкой свободного текста и страницей просмотра датасета.
• Отображение флагов качества данных: synthetic, city_imputed, price_imputed.
• Swagger-документация backend API.

Бронирования, платежей, уведомлений и личных кабинетов в текущей версии нет.

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

1. Пользователь открывает Next.js-интерфейс и вводит параметры мероприятия вручную или свободным текстом.
2. Frontend отправляет запрос через same-origin proxy на NestJS backend.
3. Backend валидирует DTO и нормализует входные значения.
4. Модуль contractors читает нормализованные профили из CSV.
5. Модуль matching применяет обязательные фильтры: город, категория, дата занятости, бюджет, формат, язык и длительность.
6. Если есть подходящие кандидаты и настроен OPENAI_API_KEY, backend передаёт только допустимые профили в OpenAI Responses API для смыслового ранжирования и генерации объяснений.
7. Ответ модели проверяется через Zod Structured Outputs и сверяется с исходными профилями.
8. При отсутствии ключа, таймауте или невалидном ответе включается детерминированный fallback.
9. Сервис сортирует результат, возвращает максимум три карточки и явно сообщает, почему карточек меньше трёх, если это произошло.

ИИ не имеет права возвращать занятого подрядчика, менять цену или придумывать отсутствующие поля: жёсткие бизнес-правила проверяются обычным кодом до и после вызова модели.

Технологии

Backend:

• Node.js 22, TypeScript, NestJS;
• REST API с префиксом /api/v1;
• @nestjs/config, class-validator, class-transformer;
• @nestjs/swagger для OpenAPI/Swagger;
• csv-parse для чтения датасета;
• официальный пакет openai, Responses API и Structured Outputs;
• Zod для проверки структурированных ответов модели;
• nestjs-pino, pino-pretty, helmet, CORS, @nestjs/throttler;
• Jest и Supertest для тестов.

Frontend:

• Next.js 15 App Router, React 19, TypeScript;
• Tailwind CSS;
• shadcn/ui, Radix UI, Lucide React;
• React Hook Form, Zod, @hookform/resolvers;
• TanStack Query;
• Sonner;
• Vitest, Testing Library и Playwright.

Инфраструктура:

• Docker Compose для запуска backend и frontend;
• named volume recommendations для кэша повторяемых результатов;
• локальные smoke-скрипты в scripts/.

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

Репозиторий — монорепозиторий с двумя приложениями:

backend/   NestJS API, подбор подрядчиков, фильтры, OpenAI-интеграция, fallback
frontend/  Next.js web-интерфейс, форма, чат-ввод, просмотр датасета
docs/      архитектура и API-контракт
scripts/   smoke-проверки
tests/     дополнительные тестовые артефакты

Основной поток:

Next.js form/chat
  -> /api/v1/* proxy
  -> NestJS DTO validation
  -> CSV repository
  -> matching filters
  -> OpenAI Responses API + Zod validation или fallback scoring
  -> stable sort
  -> response with exact cards and transparent alternatives

Ключ OpenAI хранится только в backend-переменной OPENAI_API_KEY. Frontend не обращается к OpenAI напрямую и не получает секреты. Подробности архитектуры описаны в docs/ARCHITECTURE.md, контракт API — в docs/API-CONTRACT.md.

Основная ветка

main — единственная основная ветка проекта. Актуальная версия решения, изменения для демонстрации и итоговая версия для сдачи хранятся в main; в рамках текущего процесса отдельные рабочие ветки не используются.

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

Нужны Node.js 22, npm и два терминала. Команды выполняются из корня репозитория.

Backend:

npm --prefix backend ci
npm --prefix backend run start:dev

Frontend:

npm --prefix frontend ci
npm --prefix frontend run dev

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

• сайт: http://localhost:3000;
• страница датасета: http://localhost:3000/dataset;
• API: http://localhost:3001/api/v1;
• Swagger: http://localhost:3001/api/docs;
• healthcheck: http://localhost:3001/api/v1/health.

Без API-ключа приложение работает в fallback-режиме. Для включения ИИ создайте backend/.env по примеру backend/.env.example и задайте OPENAI_API_KEY:

PORT=3001
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o-mini
OPENAI_TIMEOUT_MS=7000
DATASET_PATH=./data/contractors.csv
CACHE_DIR=./cache
FRONTEND_ORIGIN=http://localhost:3000

Frontend использует серверную переменную BACKEND_URL из frontend/.env.example. Не кладите API-ключ в NEXT_PUBLIC_*.

Запуск через Docker

Docker Desktop должен быть запущен в режиме Linux containers.

docker compose config --quiet
docker compose build
docker compose up -d --wait
node scripts/smoke.mjs

Открыть интерфейс: http://localhost:3000. Swagger: http://localhost:3001/api/docs.

backend/.env подключается при наличии, но запуск без него поддерживается. В Docker frontend обращается к backend по http://backend:3001, а исходный CSV копируется в backend-образ без изменения. Кэш рекомендаций хранится в named volume recommendations, поэтому переживает restart/rebuild.

Для остановки:

docker compose down

Для других портов используйте FRONTEND_PORT и BACKEND_PORT; для smoke-проверки — FRONTEND_URL и API_URL.

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

Самый простой повторяемый сценарий для жюри:

1. Запустить проект через Docker Compose.
2. Открыть http://localhost:3000.
3. Выбрать демо-сценарий или вручную ввести:
   • город: Алматы;
   • дата: 2026-10-15;
   • формат: корпоратив;
   • категория: Ведущий;
   • бюджет: 900000;
   • язык: русский.
4. Убедиться, что возвращаются до трёх карточек, у каждой есть конкретное объяснение и таблица критериев.
5. Повторить запрос с датой 2026-12-20: выдача должна измениться из-за декабрьской занятости.
6. Проверить редкий сценарий: Астана, 2026-11-14, Флорист, бюджет 900000.
7. Проверить пустой сценарий: плотный запрос с бюджетом 1 или Астана + Инструменталист.

Быстрые сценарии на главной странице подобраны по текущему датасету и всегда показывают рекомендации:

Сценарий	Что демонстрирует	Ожидаемый результат
Корпоратив · ведущий	Плотная точная выдача в Алматы	3 точных
Корпоратив · флорист	Редкая категория в Астане	1 точный
Корпоратив · новая дата	Занятость на выбранную дату	3 близкие альтернативы
Свадьба · фотограф	Длительность работы 6 часов	3 точных
Той · ведущий	Казахский язык и длительность	2 точных + 1 альтернатива
Свадьба · банкетный зал	Комбинированная выдача	1 точный + 2 альтернативы

Нулевая выдача остаётся частью корректного поведения: система не подменяет категорию и не рекомендует профиль, если безопасной альтернативы в заданных пределах нет.

Те же проверки можно выполнить автоматически:

node scripts/smoke.mjs

Smoke проверяет healthcheck, catalog, intake parser, рекомендации, альтернативы, повторяемость, датасет, валидацию, frontend и proxy.

Пример прямого API-запроса:

curl -s http://localhost:3001/api/v1/recommendations \
  -H 'Content-Type: application/json' \
  -d '{"city":"Алматы","date":"2026-10-15","eventFormat":"корпоратив","category":"Ведущий","budgetKzt":900000,"language":"русский"}'

Браузерная проверка всей связки:

npm --prefix frontend exec -- playwright install chromium
node scripts/browser-smoke.mjs

Проверки качества:

npm --prefix backend run lint
npm --prefix backend test
npm --prefix backend run build
npm --prefix frontend run lint
npm --prefix frontend test
npm --prefix frontend run build

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

Используемые данные:

• hackathon dataset anonymized.csv — основной источник профилей подрядчиков;
• HackAlem AI_ Хакатон-задача_ умный подбор подрядчиков.docx — исходное ТЗ;
• hackathon dataset preview.html — локальный preview исходных данных.

Характеристики датасета:

• 66 строк, 13 колонок;
• города: Алматы — 50, Астана — 15, Зарубежье — 1;
• synthetic — 13 профилей;
• city_imputed — 8 профилей;
• price_imputed — 18 профилей;
• max_hours = null означает, что работа не привязана к присутствию на площадке.

Внешние сервисы:

• OpenAI API используется опционально для смыслового ранжирования и генерации объяснений;
• без OpenAI API работает локальный детерминированный fallback;
• других внешних сервисов, баз данных, очередей или векторных хранилищ в MVP нет.

Ограничения текущей версии

• Публичной deployed-версии пока нет.
• Поддерживается MVP-топология с одним backend-процессом.
• База данных и Redis не используются; CSV остаётся единственным источником профилей.
• Календарь доступности ограничен диапазоном 2026-09-23 — 2026-12-31; даты вне окна отклоняются с HTTP 400.
• Результаты кэшируются как JSON-снимки. Изменение CSV, модели, версии промпта/пайплайна или удаление кэша создаёт новый набор результатов.
• Первый сохранённый результат для запроса может быть fallback, если в момент первого запроса OpenAI был недоступен.
• Нет дообучения модели на 66 строках и нет embeddings/vector search.
• Нет реального бронирования подрядчиков, оплаты, календарной синхронизации и уведомлений.
• Синтетические профили допустимы только с флагом synthetic: true; интерфейс показывает этот флаг пользователю.

Полезные ссылки

• Архитектура: docs/ARCHITECTURE.md
• API-контракт: docs/API-CONTRACT.md
• Swagger после запуска: http://localhost:3001/api/docs
• Frontend после запуска: http://localhost:3000
• Deployed-версия: отсутствует на момент подготовки README