ATLAS · HackAlem AI

ИИ-агент для анализа изменений организационного функционала. Команда Blitz.

ATLAS помогает проверить, что произошло с обязанностями при реорганизации или обновлении внутренних документов. Пользователь загружает два файла — «до» и «после», запускает смысловой анализ и получает сопоставление функций с замечаниями и ссылками на источники.

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

Возможности

ATLAS берёт на себя первичное сопоставление документов, чтобы эксперт мог сосредоточиться на существенных изменениях и проверке спорных вопросов.

• Понять, что изменилось по существу. Сравните обязанности до и после реорганизации: какие сохранились, какие переданы другим ответственным, какие появились впервые и для каких не найден преемник. Анализ учитывает смысл, а не только совпадение слов — в том числе при перефразировании, переносе и разделении пунктов.
• Найти места, требующие внимания. Получите замечания о возможной потере функций, дублировании полномочий и конфликтах интересов. Это помогает направить экспертную проверку на потенциальные пробелы и пересечения ответственности.
• Проверить основания каждого замечания. Перейдите от вывода к исходной цитате и её месту в документе. Не нужно вручную искать нужный пункт среди страниц, абзацев и строк таблиц.
• Зафиксировать экспертное решение. Подтвердите или отклоните замечание, добавьте пояснение и при необходимости уточните разметку обязанностей. Решение остаётся за специалистом, а его комментарии сохраняются в заключении.
• Подготовить материалы для обсуждения. Получите аналитическое заключение с источниками, рекомендациями и результатами проверки. Экспортируйте отчёт или таблицу сопоставлений, чтобы передать их коллегам и использовать при согласовании изменений.
• Работать с привычными документами. Загружайте положения и регламенты в Word, текстовом PDF, Excel, TXT или CSV — без переноса содержания в специальный шаблон.

Навигация

• Архитектура и принцип работы
• Технологии и зависимости
• Подготовка
• Запуск через Docker
• Локальный запуск без Docker
• Параметры окружения
• Как пользоваться
• Проверка основного сценария
• Автоматические проверки
• Хранение данных и остановка
• Диагностика
• Ограничения и безопасность

Архитектура и принцип работы

Браузер · React / TypeScript
          │ /api
          ▼
Vite proxy (локально) / Nginx (Docker)
          │
          ▼
FastAPI · Python
  ├── Парсинг документов → текст, ID и адреса фрагментов
  ├── OpenAI Responses API → извлечение и сопоставление функций
  ├── Проверка ответа → существующие ID, полнота, источники
  ├── SQLite → документы, разметка, результаты и решения
  └── Экспорт → HTML / Markdown / CSV

1. Загрузка. Backend проверяет файл, извлекает текст и сохраняет оригинал. Для DOCX фиксируется номер абзаца, для PDF — страница и строка, для XLSX — лист и строка. XLSX читается как текст строк, без выполнения формул.
2. Извлечение функций. После явного запуска модель определяет обязанности. Нумерованные заголовки передаются вместе с вложенными пунктами как контекст. Ручные исправления разметки имеют приоритет.
3. Сопоставление. GPT сопоставляет функции по смыслу и формирует объяснения и потенциальные риски. Большие документы обрабатываются частями без намеренного обрезания текста. Каждая часть «до» сравнивается со всеми частями «после».
4. Проверка ответа. Backend проверяет формат JSON, полноту сопоставления и существование идентификаторов источников. Названия подразделений берутся из исходного каталога, цитаты — из сохранённого текста, а не генерируются заново.
5. Проверка человеком. Пользователь открывает замечание, сверяет источники и сохраняет решение. После этого можно экспортировать заключение.

Анализ выполняется фоновой задачей FastAPI; браузер опрашивает состояние. Для отмены используется уникальный токен запуска: сервер закрывает текущий HTTP-запрос, прекращает дальнейшую обработку и не принимает запоздалый результат. Отдельные Redis, Celery и PostgreSQL для запуска не нужны.

Подробности: docs/architecture.md. Интерактивная документация API после запуска: Swagger UI.

Технологии и зависимости

Часть	Технологии
Интерфейс	React 19, TypeScript 5.8, Vite 7, CSS, Lucide
Backend	Python 3.12, FastAPI, Uvicorn, Pydantic
AI	OpenAI Responses API, модель gpt-5.6-sol, Structured Outputs, reasoning.effort=low
Чтение файлов	pypdf, openpyxl, стандартные XML / ZIP / CSV-модули Python
HTTP и конфигурация	httpx, python-dotenv
Хранение	SQLite, стандартный модуль sqlite3
Контейнеры	Docker Compose v2, Nginx
Проверки	pytest, Ruff, Node.js test runner, TypeScript, Prettier

Воспроизводимые зависимости зафиксированы в backend/requirements.lock.txt и frontend/package-lock.json. Для проверок backend используется backend/requirements-dev.txt.

Подготовка

Для любого варианта запуска нужны:

• Git и доступ к репозиторию;
• доступ в интернет для установки зависимостей и обращения backend к api.openai.com:443;
• API-ключ OpenAI с доступом к gpt-5.6-sol, доступной квотой и средствами для API-вызовов;
• свободные локальные порты 5173 и 8000.

Для Docker нужны Docker Engine / Docker Desktop в режиме Linux-контейнеров и Compose v2. Python и Node.js на хосте тогда не обязательны.

Для запуска без Docker нужны Python 3.12 и Node.js 22.12+ с npm.

git clone https://github.com/BAITC-Hacks/hack-1790cb51-blitz.git
cd hack-1790cb51-blitz

Все команды далее выполняются в этом каталоге, если не указано иное. Выберите один способ запуска: Docker или локальные процессы.

Без API-ключа доступны интерфейс, загрузка и просмотр файлов, а также автоматические тесты. Полный смысловой анализ требует действующего ключа. Демо-режима и локальной подмены GPT нет.

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

1. Подготовьте окружение

Windows PowerShell:

Copy-Item .env.example .env

Linux / macOS:

cp .env.example .env

Откройте созданный корневой .env и укажите собственный ключ:

OPENAI_API_KEY=YOUR_OPENAI_API_KEY

Копирование нужно только при первой установке: не перезаписывайте уже настроенный .env. Не добавляйте ключ в Git и не передавайте его во frontend.

2. Соберите и запустите приложение

docker compose config --quiet
docker compose up --build -d --wait --wait-timeout 180
docker compose ps

При первой сборке Docker скачает образы и установит зависимости. Backend должен перейти в состояние healthy, frontend — запуститься. Если сборка или запуск завершились ошибкой:

docker compose logs --tail=100 backend frontend

3. Откройте приложение

Адрес	Назначение
localhost:5173	Пользовательский интерфейс
localhost:8000/docs	Swagger UI
localhost:5173/api/health	Проверка backend через frontend-прокси
localhost:8000/api/health	Прямая проверка backend

В ответе health-check ожидаются status: "ok", model: "gpt-5.6-sol" и, после настройки ключа, gpt_configured: true. Последний флаг означает только наличие ключа, а не проверку его баланса или разрешений.

После изменения корневого .env примените новые настройки:

docker compose up -d --force-recreate backend

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

Запускайте backend и frontend в двух отдельных терминалах. Активация виртуального окружения не требуется.

Windows PowerShell

Терминал 1 — backend:

cd backend
py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.lock.txt
Copy-Item .env.example .env

Заполните OPENAI_API_KEY в backend/.env, затем в том же терминале:

.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Если Python Launcher py отсутствует, используйте python -m venv .venv, предварительно проверив python --version.

Терминал 2 — frontend, из корня репозитория:

cd frontend
npm.cmd ci
npm.cmd run dev -- --host 127.0.0.1 --port 5173 --strictPort

Linux / macOS

Терминал 1 — backend:

cd backend
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock.txt
cp .env.example .env

Заполните OPENAI_API_KEY в backend/.env, затем:

.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Терминал 2 — frontend, из корня репозитория:

cd frontend
npm ci
npm run dev -- --host 127.0.0.1 --port 5173 --strictPort

Откройте http://127.0.0.1:5173. Vite перенаправляет запросы /api на backend порта 8000. После изменения .env перезапустите backend.

Для разработки можно добавить --reload к команде Uvicorn. Не используйте автоматическую перезагрузку или несколько worker-процессов во время демонстрационного анализа: текущие фоновые задачи не переживают перезапуск.

Дополнительно для Windows есть scripts/dev.ps1: после настройки backend/.env он устанавливает зависимости и запускает оба сервера. Повторный запуск без установки — .\scripts\dev.ps1 -SkipInstall. Логи скрипта находятся в корневом data/. Ручные команды выше не требуют изменения PowerShell Execution Policy.

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

Параметр	Назначение	Локальный запуск	Docker
OPENAI_API_KEY	Ключ для смыслового анализа; без него запуск анализа заблокирован	backend/.env	Корневой .env, передаётся в backend
DATABASE_PATH	Путь к SQLite; каталог создаётся автоматически и должен быть доступен для записи	data/atlas.sqlite3 по умолчанию, относительно рабочей папки backend	/app/data/atlas.sqlite3, задан в Compose

Backend читает backend/.env, затем корневой .env, не перезаписывая уже заданные переменные процесса. Для предсказуемого запуска не задавайте разные ключи одновременно в нескольких местах.

Модель закреплена в коде: gpt-5.6-sol. Параметр OPENAI_MODEL не используется. Для frontend отдельный .env не нужен: он обращается к API через прокси. В Compose путь к БД задан явно, поэтому изменение DATABASE_PATH только в корневом .env его не переопределит.

Как пользоваться

Работа в ATLAS состоит из трёх этапов: загрузить документы → запустить анализ → проверить результаты. Регистрация и создание аккаунта не нужны.

Перед началом запустите приложение по инструкции через Docker или локально, настройте API-ключ и откройте http://127.0.0.1:5173.

1. Подготовьте две версии документа

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

Поддерживаются DOCX, PDF с текстовым слоем, XLSX, TXT и CSV, до 10 МБ на файл. PDF-сканы необходимо предварительно распознать: встроенного OCR нет.

Что получите: исходную пару для сравнения — что действовало раньше и что предлагается теперь.

2. Загрузите файлы и проверьте текст

На этапе загрузки добавьте прежнюю версию в блок «До», новую — в «После». В каждом блоке должен быть один файл. Нажмите «Проверить текст» и убедитесь, что содержимое читается, а нужные пункты присутствуют. При необходимости скорректируйте разметку функций и сохраните изменения.

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

3. Запустите сравнение

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

Именно при запуске анализа текст отправляется в OpenAI и расходуются API-кредиты. Кнопка «Отменить анализ» позволяет остановить обработку; загруженные документы останутся доступны для повторного запуска, но уже потраченные кредиты не возвращаются.

Что получите: сравнение функций двух версий и список потенциальных проблем для экспертной проверки.

4. Разберитесь, что изменилось

После завершения откроются результаты. Во вкладке «Функции и замечания» изучите сопоставленные пункты «До» и «После»: какие функции сохранились, переданы, появились впервые или не нашли преемника. Используйте поиск и фильтры, чтобы сосредоточиться на нужных изменениях. Связанные замечания показаны рядом с функциями.

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

5. Проверьте замечания по источникам

Откройте интересующее замечание и перейдите к источнику: приложение покажет фрагмент документа, на котором основан вывод. Сопоставьте цитату с контекстом, добавьте свой комментарий и нажмите «Подтвердить» или «Отклонить».

Выводы ИИ — повод для проверки, а не окончательное решение. Например, отсутствие найденного соответствия ещё не доказывает, что обязанность действительно исключили.

Что получите: проверенные замечания с зафиксированными экспертными решениями и пояснениями.

6. Получите готовые материалы

Перейдите во вкладку «Заключение», изучите выводы и рекомендации. Через «Экспорт» скачайте отчёт в HTML или Markdown, а таблицу функций — в CSV. Чтобы сохранить заключение в PDF, выберите «Печать / PDF» и сохранение в файл в системном окне печати.

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

Текущее сравнение и решения сохраняются при обновлении страницы в том же браузере и по тому же адресу. Перед началом нового сравнения скачайте нужный отчёт: отдельного экрана истории нет. Если замените документы или измените разметку функций, запустите анализ заново, чтобы выводы соответствовали новым данным.

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

Подготовьте контрольную пару

Можно использовать собственные документы или вручную создать два небольших TXT-файла в кодировке UTF-8. Пример ниже не содержит конфиденциальных данных и позволяет проверить сценарий без подготовки Word / PDF.

before.txt:

Подразделение: Финансовый отдел
1. Основные функции:
1.1. Формирование годового бюджета организации.
1.2. Подготовка ежемесячного финансового отчёта.
1.3. Ведение реестра договоров с поставщиками.

after.txt:

Подразделение: Финансовый отдел
2. Основные обязанности:
2.1. Составление годового бюджета организации.
2.2. Подготовка ежемесячного финансового отчёта.
2.3. Мониторинг исполнения утверждённого бюджета.

Выполните сценарий

1. Загрузка. Откройте приложение. В блок «До» загрузите before.txt, в блок «После» — after.txt. Должны появиться названия файлов; второй файл в тот же блок добавляется только через явную замену.
2. Проверка источников. Нажмите «Проверить текст». Убедитесь, что текст и номера пунктов читаются, а заголовок списка не размечен как самостоятельная функция.
3. Запуск. Нажмите «Перейти к анализу», затем «Начать анализ». Должны появиться прогресс, текущий этап и кнопка «Отменить анализ». Именно запуск, а не загрузка или переход на экран, отправляет текст в OpenAI.
4. Результаты. Дождитесь автоматического перехода к результатам. Для этой пары ожидаются сопоставление бюджета с перефразированным пунктом, сохранение отчётности, кандидат на потерю ведения реестра и новая функция мониторинга бюджета. Формулировки модели и дополнительные замечания могут отличаться: сверяйте их с текстом, а не с фиксированным количеством рисков.
5. Замечание. Откройте замечание рядом с функцией, перейдите к источнику и проверьте выделенный фрагмент. Добавьте комментарий и подтвердите либо отклоните замечание.
6. Заключение. Откройте «Заключение». Проверьте сохранённое решение и комментарий. Скачайте HTML / Markdown через «Экспорт» и CSV-таблицу функций. Для PDF используйте «Печать / PDF» и системную печать в файл.
7. Сохранение. Обновите страницу в том же браузере и по тому же адресу. Текущее сравнение, документы и решения должны остаться.

Дополнительная проверка отмены: запустите анализ повторно и нажмите «Отменить анализ», пока он выполняется. Должно появиться состояние «Анализ отменён»; документы доступны для замены и повторного запуска, частичный результат не выдаётся за успешный. Уже использованные API-кредиты не возвращаются. Если короткий анализ успел завершиться до нажатия, готовый результат сохраняется.

Признак успешной технической проверки: приложение самостоятельно запускается, принимает пару файлов, выполняет реальный анализ, позволяет проверить цитаты и сохранить решение, экспортирует отчёт и восстанавливает данные после обновления страницы.

Автоматические проверки

Тесты не требуют API-ключа: ответы OpenAI заменены контролируемыми данными. Платных вызовов в автоматических тестах нет. Они проверяют код и API-контракт, но не заменяют ручную проверку качества модели.

Backend — из папки backend, Windows:

.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.venv\Scripts\python.exe -m pytest -q
.venv\Scripts\ruff.exe check app tests

Backend — из папки backend, Linux / macOS:

.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pytest -q
.venv/bin/ruff check app tests

Frontend — из папки frontend:

npm ci
npm test
npm run build
npm run format:check

В PowerShell при блокировке npm.ps1 используйте npm.cmd вместо npm. Сборка создаёт frontend/dist/.

Покрыты загрузка, парсинг, вложенные заголовки, смысловые соответствия на контролируемых ответах, проверка источников, ручные решения, экспорт, переходы интерфейса и отмена на разных этапах, включая запоздалый ответ после нового запуска.

В GitHub Actions настроены проверки backend, frontend и сборка Docker Compose с HTTP-проверкой интерфейса и API. Наличие workflow не заменяет проверку статуса конкретного запуска CI.

Хранение данных и остановка

• Локально: backend/data/atlas.sqlite3, если backend запущен из своей папки с настройками по умолчанию.
• В Docker: SQLite в именованном volume atlas_data (фактическое имя Docker может содержать префикс проекта).
• В БД сохраняются оригиналы файлов, извлечённый текст, разметка, результаты и решения проверяющего. Отдельный сервер БД устанавливать не нужно.
• Браузер хранит идентификатор текущего сравнения в localStorage. localhost и 127.0.0.1 — разные адреса для этого хранилища; для проверки восстановления используйте один адрес.
• «Новое сравнение» открывает пустую пару, но не удаляет прошлые данные из БД. Переключателя истории в интерфейсе нет — предварительно экспортируйте нужное заключение.
• Остановка локального запуска — Ctrl+C в обоих терминалах. Остановка Docker:

docker compose down

Обычный down сохраняет volume. Не добавляйте -v, если хотите сохранить документы и результаты: эта опция удаляет volume. Перед резервным копированием SQLite остановите backend. После перезапуска данные остаются, но незавершённый анализ нужно запустить заново.

Диагностика

Симптом	Что проверить
«Нужен API-ключ OpenAI»	Правильный .env, непустой OPENAI_API_KEY, перезапуск backend или пересоздание контейнера
Ошибка доступа к модели / ключу	Действительность ключа и доступ API-проекта к gpt-5.6-sol; флаг health-check не подтверждает доступ
Ошибка лимита OpenAI	Баланс и квоты API-проекта; локальная подмена анализа отсутствует
«Не удалось получить ответ OpenAI»	Исходящий HTTPS у процесса backend, прокси, firewall и возможный таймаут; доступ браузера в интернет сам по себе недостаточен
Backend работает, но интерфейс не получает данные	Адрес /api/health через порт 5173, порт backend 8000, логи Vite / Nginx
Порт уже занят	Не запускайте Docker и локальные процессы одновременно на тех же портах; остановите только свой прежний сервер
PDF не читается / текст не найден	Наличие текстового слоя, отсутствие пароля; сканам сначала нужен внешний OCR
Долгий анализ	Количество фрагментов и частей: запросы последовательные, попарное сравнение увеличивает время; можно отменить запуск
После изменения файла нет прежнего результата	Изменение документа или разметки сбрасывает текущий результат: требуется новый анализ

Для Docker используйте docker compose logs --tail=100 backend frontend. При ручном запуске ошибки видны в терминалах. При запуске через scripts/dev.ps1 смотрите data/backend-error.log и data/frontend-error.log. Перед передачей логов убедитесь, что они не содержат секретов и конфиденциальных данных.

Ограничения и безопасность

• Размеры: до 10 МБ на файл, до 150 страниц PDF, до 4 000 извлекаемых строк и 600 000 символов на документ. Отдельный фрагмент с метаданными не должен превышать 140 КБ UTF-8.
• Форматы: старые DOC / XLS нужно сохранить как DOCX / XLSX. TXT и CSV ожидаются в UTF-8. OCR, выполнение Excel-формул и восстановление сложной вёрстки PDF не реализованы. Автонумерация Word может не попасть в извлечённый текст — тогда используется адрес абзаца.
• Качество: отсутствие преемника — кандидат на потерю функции, а не доказательство. Проценты сходства ближайших фрагментов не являются уверенностью GPT. Проверки ID и цитат не гарантируют правильность смыслового вывода.
• Внешние данные: законодательные базы, юридическая проверка и бенчмаркинг других организаций не подключены.
• Конфиденциальность: извлечённый текст отправляется в OpenAI при запуске анализа. Передавайте только разрешённые к такой обработке документы. Запросы используют store=false; это не утверждение об отсутствии любого хранения на стороне провайдера. API-ключ остаётся на backend и не передаётся браузеру.
• Время и стоимость: большие документы требуют нескольких запросов; число сравнений может расти квадратично. Повторный запуск обрабатывает документы заново, без продолжения с последней части.
• Развёртывание: это хакатонный прототип для доверенного локального окружения, без авторизации и разграничения пользователей. Docker публикует порты только на loopback. Для публичного доступа нужны аутентификация, изоляция данных, TLS и контроль доступа.
• Масштабирование: текущая SQLite и фоновые задачи рассчитаны на один процесс backend. Очередь задач и серверная БД потребуются для многопользовательской нагрузки.

Структура репозитория

backend/
  app/
    main.py            API и управление запуском
    parser.py          Чтение файлов и контекст заголовков
    ai.py              Запросы к GPT и проверка контрактов
    cancellation.py    Отмена выполняющегося HTTP-запроса
    analysis.py        Сопоставления, замечания и статистика
    storage.py         SQLite и миграция схемы
    report.py          Экспорт
  tests/               Автоматические проверки
  requirements.lock.txt
  requirements-dev.txt
  .env.example
  Dockerfile
frontend/
  src/pages/           Загрузка, анализ, результаты и заключение
  src/components/      Источники, проверка замечаний и общие элементы
  tests/               Проверки маршрутов и связей замечаний
  package-lock.json
  nginx.conf
  Dockerfile
docs/architecture.md   Подробная архитектура
scripts/dev.ps1        Локальный запуск Windows
.github/workflows/ci.yml
docker-compose.yml
.env.example