О проекте

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

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

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

Попробовать: www.afm.codes. Откройте «Сравнить документы» и выберите встроенный пример или загрузите свои комплекты. Для воспроизводимой проверки без обращений к модели используйте локальный запуск с DEMO_MODE=true.

Хакатонный прототип работает без API-ключей и GPU. OpenAI опционально добавляет наблюдения и ответы по документам. Данные сравнений и демонстрационные действия участников сохраняются в пределах одной сессии.

Выводы рекомендательные. Проверенная цитата подтверждает наличие текста в источнике; интерпретацию и итоговое решение проверяет ответственный человек.

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

Возможность	Что доступно в текущем коде
Загрузка документов	Несколько DOCX, PDF с текстовым слоем, XLSX или TXT в каждом комплекте. Общий лимит двух комплектов — 50 МиБ.
Сравнение структуры	Сопоставление упоминаний подразделений и должностей: сохранение, признаки реорганизации, кандидаты на создание или упразднение.
Сопоставление функций	Извлечение явно заданных обязанностей и запретов; поиск сохранённых, переданных, изменённых, новых и потенциально утраченных функций. Неоднозначные пары выделяются для проверки.
Поиск рисков	Кандидаты на потерю и дублирование функций, противоречия функции и запрету, совмещение выполнения и контроля одного объекта.
Объяснение результата	Краткое заключение, таблицы, графики, фильтры находок, просмотр структуры и пунктов документов, журнал этапов. Находку можно подтвердить или отклонить вручную.
Помощник по документам	Большая кнопка «Спросить ИИ» открывает отдельное окно чата. С OpenAI доступны ответы по выбранным выдержкам; без ключа — подбор релевантных фрагментов. История привязана к сравнению.
Экспорт	Скачивание оригиналов и отчёта DOCX. В отчёт включаются только записи с подтверждёнными источниками.
Согласование	Создание версии пакета с оригиналами, выбранными изменениями и получателями; фиксированный состав участников, согласование или возврат с обязательным комментарием, журнал решений.
Ознакомление	После согласования всеми участниками — назначение документов сотрудникам, вопросы и ответы, отметки по каждому документу и точной версии, просмотр прогресса.
Документы новичка	Отдельная форма: имя, фамилия, должность и моковый список документов с галочками. Также доступен сценарий назначения уже опубликованных согласованных версий.

В «Моих сравнениях» можно переключаться между запусками: у каждого сохраняются свои исходные документы, результаты, решения, вопросы и связанная версия пакета в пределах текущей сессии.

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

1. Загрузить два комплекта. Пользователь добавляет предыдущие и новые редакции документов либо выбирает один из встроенных примеров.
2. Запустить сравнение. Приложение извлекает текст и пункты, выделяет подразделения и функции, сопоставляет их и проверяет цитаты. При включённом OpenAI отдельно добавляет наблюдения модели.
3. Проверить результат. Пользователь читает резюме, раскрывает находки и источники, при необходимости задаёт вопрос по документам и скачивает отчёт.
4. Подготовить версию к согласованию. Ответственный выбирает изменения, назначает получателей, проверяет цитаты и фиксирует версию пакета. Участники согласуют её или возвращают на доработку.
5. Открыть ознакомление. После согласования всех участников ответственный публикует пакет назначенным сотрудникам. Они читают оригиналы, задают вопросы и отмечают ознакомление с конкретной версией.

Технологии

Компонент	Реализация
Язык и среда	Python; Docker и GitHub Actions настроены на Python 3.11.
Веб-интерфейс	Streamlit >=1.64,<2, локальные CSS/SVG, графики ECharts через st.echarts_chart.
Чтение и создание Word	python-docx: извлечение абзацев и таблиц DOCX, создание отчёта DOCX.
Чтение PDF	PyMuPDF: извлечение текстового слоя.
Чтение Excel	openpyxl: чтение всех листов XLSX, включая текст формул.
Локальный анализ	Регулярные выражения, правила, собственная реализация TF-IDF и косинусного сходства на стандартной библиотеке Python.
Генеративный ИИ	Опционально OpenAI Python SDK и Responses API, ответы по JSON Schema. Модель по умолчанию в конфигурации — gpt-5.4-mini, заменяется через OPENAI_MODEL.
Проверки	pytest, Streamlit AppTest, контрольный синтетический комплект.
Развёртывание	Docker и ручной деплой в Railway. Резервный workflow использует Railway CLI 4.36.1 и Node.js 22.

Полный список зависимостей находится в requirements.txt. Векторная база данных и нейросетевые эмбеддинги в текущем анализаторе не используются.

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

Браузер → Streamlit (app/main.py)
                  │
                  ├─ src/agent.py → app/local_analysis.py
                  │                    ├─ src/parse.py: текст и пункты
                  │                    └─ src/structure.py: структура
                  │
                  ├─ app/ai_assistant.py → src/config.py → OpenAI (опционально)
                  ├─ src/report.py → отчёт DOCX
                  └─ app/workflow.py → согласование → ознакомление

Аналитические этапы

1. Разбор документов (parse). Текст делится на фрагменты с полями doc, clause, text, section. Ненумерованный текст тоже сохраняется.
2. Структура и функции (structure, functions). Правила извлекают упоминания подразделений, исполнителей, обязанностей и запретов. Учитывается контекст заголовков.
3. Сопоставление (match). TF-IDF и косинусное сходство помогают найти пары функций «до/после». Близкие конкурирующие варианты не объявляются автоматически потерянными или новыми.
4. Находки (findings). Формируются кандидаты на изменения и риски; текстовое сходство само по себе не считается доказательством одинакового смысла.
5. Проверка источников (verify). Цитата ищется в исходном документе и пункте после нормализации регистра и пробелов. Записи с неподтверждёнными источниками исключаются. Здесь используется точное вхождение, а не нечёткий поиск.
6. Заключение (report). Создаётся краткое резюме находок с проверенными цитатами. Журнал показывает фактически выполненные этапы.

Результат содержит units, function_map, findings, conclusion; источники представлены как doc, clause, quote, verified. Решение пользователя по находке хранится отдельно и не меняет verified.

Фактическая точка входа — src/agent.py. Адаптер предусматривает подключение src.pipeline.run, но src/pipeline.py в текущем репозитории отсутствует. Поэтому рабочий анализ выполняет app/local_analysis.py. Обычные кнопки сравнения читают документы; тестовая функция run_stub() не используется для пользовательского анализа. Готовый artifacts/sample_result.json также не используется.

Основные файлы

Путь	Назначение
app/main.py	Загрузка, запуск анализа, список сравнений, результаты, чат и навигация.
app/local_analysis.py	Локальное извлечение функций, сопоставление, находки и проверка цитат.
src/parse.py, src/structure.py	Чтение документов, выделение пунктов и организационных единиц.
app/ai_assistant.py, src/config.py	Дополнительные наблюдения ИИ, поиск источников для чата, настройка API.
src/report.py	Формирование DOCX из записей с подтверждёнными источниками.
app/workflow.py	Карточки изменений и снимки версий с оригиналами, получателями и ответственным.
app/approvals.py, app/acknowledgements.py	Маршруты согласования, ознакомление, вопросы и пакеты новичков.
app/onboarding_ui.py	Отдельная форма новичка с моковым чек-листом.
app/source_explorer.py	Просмотр структуры и исходных пунктов.
app/presentation.py, app/styles.css, app/interactive_ui.py	Оформление, графики и отображение хода анализа.
data/, tests/, scripts/eval_control.py	Примеры документов, автоматические тесты и проверка контрольного комплекта.

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

Локально, без API-ключей

Нужны Python 3.11 и pip. Команды ниже предназначены для macOS/Linux и выполняются из корня проекта. GPU не требуется.

1. Получите репозиторий и перейдите в его каталог:

   git clone https://github.com/BAITC-Hacks/hack-101116b6-swag.git
   cd hack-101116b6-swag
   

   Для приватного репозитория нужен доступ. Если проект передан архивом, распакуйте его и откройте корневой каталог.

2. Создайте виртуальное окружение и установите зависимости:

   python3.11 -m venv .venv
   source .venv/bin/activate
   python -m pip install -r requirements.txt
   

3. Запустите приложение:

   DEMO_MODE=true python -m streamlit run app/main.py
   

4. Откройте http://localhost:8501. Для первого знакомства выберите «Сравнить документы» → «Синтетический пример: подключения и кабельные работы».

DEMO_MODE=true отключает обращения к модели, даже если в окружении есть API-ключ. Это локальный анализ выбранных документов, а не подстановка готового ответа.

После обновления кода перезапустите уже работающий локальный Streamlit: остановите его через Ctrl+C и повторите команду запуска. Старый процесс может сохранять ранее загруженные Python-модули и выдавать ImportError при открытии нового раздела. Перезапуск сбрасывает данные текущих сессий.

Через Docker

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

docker build -t orgstructure .
docker run --rm -p 8501:8501 -e DEMO_MODE=true orgstructure

Приложение доступно на http://localhost:8501. Dockerfile запускает Streamlit на 0.0.0.0 и использует переменную PORT, по умолчанию 8501.

Опционально: OpenAI

Ключи читаются только из переменных окружения через src/config.py. Файл .env автоматически не загружается. Для режима OpenAI задайте окружение процесса или переменные сервиса Railway:

Переменная	Значение
DEMO_MODE	true — без обращений к модели; false — разрешить использование настроенного API. Без явного значения режим определяется наличием ключей.
OPENAI_API_KEY	Ваш ключ OpenAI API; не нужен для локального режима.
OPENAI_MODEL	Необязательно: имя модели, поддерживающей используемый Responses API с JSON Schema. Значение по умолчанию в коде — gpt-5.4-mini.

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

export OPENAI_API_KEY="<ваш_API-ключ>"
export DEMO_MODE=false
python -m streamlit run app/main.py

При доступном OpenAI переключатель «Улучшить анализ с OpenAI» изначально включён. Его можно выключить перед сравнением. Наблюдения модели показываются отдельно в разделе «Заключение» и не заменяют локальные находки. При ошибке API локальный результат сохраняется.

Чат использует OpenAI независимо от переключателя анализа, если ключ доступен и DEMO_MODE не равен true. Для полностью локального сценария запускайте приложение с DEMO_MODE=true. Подробнее о передаваемых данных — ниже.

Как проверить решение: сценарий для жюри

1. Сравнение и проверка источников

1. Запустите приложение без ключей по инструкции выше.
2. В «Моих сравнениях» нажмите «Сравнить документы», затем «Синтетический пример: подключения и кабельные работы». Он использует файлы из data/control/.
3. Прочитайте краткое резюме. Откройте «Все находки, функции и источники» → «Находки» и проверьте кандидатов на потерю, дублирование, реорганизацию и конфликт. Для каждой находки доступны документ, пункт и цитата.
4. Сверьте источники с data/control/before/regulation.txt и data/control/after/regulation.txt. Например, контрольная проверка потери функции опирается на пункт 2.1.2 исходной редакции, а переименования — на пункт 1.4 новой редакции.
5. Нажмите «Спросить ИИ» и задайте вопрос: «Кто ремонтирует наружные кабельные линии?». В локальном режиме отобразятся ближайшие выдержки, а не сгенерированный ответ. Закройте и снова откройте окно: история этого сравнения сохранится.
6. Нажмите «Скачать отчёт» и откройте DOCX: проверьте наличие источников у экспортированных записей.

Для второго примера создайте новое сравнение и нажмите «Демо на тестовом комплекте». Будут проанализированы две обезличенные редакции положения о внутреннем аудите из data/sample/. Готовые ответы под эти файлы не подставляются; полноту найденных изменений следует оценивать по самим документам.

2. Согласование и ознакомление

В том же синтетическом сравнении:

1. Нажмите «Передать на согласование». Выберите хотя бы одно изменение и назначьте ему получателя из демонстрационного списка.
2. Укажите название, редакцию пакета и ответственного. Отметьте «Я проверил выбранные изменения, цитаты и получателей» и нажмите «Создать версию для согласования».
3. Оставьте вымышленных руководителей и нажмите «Начать согласование». По очереди выберите каждого участника и нажмите «Согласовать версию».
4. После согласования всеми нажмите «Назначить ознакомление» → «Открыть ознакомление назначенным сотрудникам».
5. Перейдите в «Мои документы», выберите назначенного сотрудника, прочитайте оригинал и нажмите «Ознакомлен с этой версией документа». Вернитесь к ознакомлению в сравнении и проверьте прогресс.

Это симуляция ролей в одной сессии. Если вместо согласования вернуть версию с комментарием, маршрут завершится; повторное согласование требует новой редакции пакета.

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

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

Из корня проекта с активированным виртуальным окружением:

DEMO_MODE=true python -m pytest -q
DEMO_MODE=true python scripts/eval_control.py

Оценочный скрипт проверяет четыре ожидаемых случая из data/control/expected.json: потерю, дублирование, реорганизацию и конфликт. Для совпадения нужны правильный тип находки, сторона сравнения, пункт, цитата и признак её проверки. Успешный итог:

4/4 проверок пройдено; данные синтетические.

expected.json читает только оценочный скрипт, а не анализатор. Эти четыре проверки подтверждают работу на контрольном примере и не являются измерением точности на произвольных документах.

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

Для отдельной проверки извлечения текста:

python -m src.parse data/sample --limit 3

Команда выводит количество фрагментов и первые три фрагмента каждого документа.

Данные и внешние сервисы

Источники данных

Источник	Содержимое и назначение
data/sample/before/, data/sample/after/	Обезличенные DOCX «Положение о внутреннем аудите», редакции 8 и 9. Пример сравнения документов.
data/control/	Вымышленные регламенты «до/после» с контрольными изменениями. Не являются действующими регламентами организации.
Загружаемые файлы	Пользовательские комплекты поддерживаемых форматов. Встроенный поиск по внешним сайтам и корпоративным хранилищам не выполняется.
Демонстрационные участники и чек-лист новичка	Вымышленные данные для показа пользовательских сценариев.

DOCX читается вместе с таблицами в порядке документа. Из PDF извлекается текстовый слой. В XLSX читаются все листы, формулы сохраняются как текст формул. Для TXT поддерживаются UTF-8, UTF-8 с BOM и Windows-1251.

Хранение и внешние сервисы

• Локальный режим: анализ выполняется на машине или сервере, где запущен Streamlit. При удалённом размещении загруженные файлы передаются этому серверу.
• Сессия: исходные файлы, результаты, чат, версии и решения хранятся в памяти серверной сессии Streamlit. Временные файлы загрузки удаляются после анализа; копии оригиналов остаются в сессии для просмотра и скачивания. Постоянной базы данных нет.
• OpenAI, если включён: для дополнительного анализа отправляются группы изменённых пунктов; для чата — вопрос, выбранные выдержки с обозначениями документов и часть истории диалога. Ответы запрашиваются по JSON Schema, идентификаторы источников проверяются, цитаты берутся из прочитанных документов.
• Кэш ИИ: ответы дополнительного анализа сохраняются в .cache/llm/, если доступна запись. Это отдельное от сессии хранение на диске; кэш может содержать сведения из документов и исключён из Git. История чата в этот кэш не записывается.
• Railway: размещение приложения и ручной деплой. Резервный GitHub Actions workflow отключён; автоматических запусков при push нет. Для локального запуска эти сервисы не нужны.
• Shields.io: изображения бейджей в этом README загружаются с внешнего сервиса. Документы в него не отправляются.

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

• Неполнота анализа. Правила ориентированы на русскоязычные тексты с явными исполнителями. Неявные обязанности, сложные переформулировки и связи между документами могут быть пропущены. Отсутствие находок не означает отсутствие рисков; единственное упоминание в одной редакции не доказывает создание или упразднение подразделения.
• Качество исходного текста. OCR отсутствует. PDF без текстового слоя не анализируется; при предупреждении о частично извлечённом PDF отключаются выводы об отсутствии функций и подразделений. Автоматическая нумерация Word, не включённая в текст абзаца, не восстанавливается. Старые форматы .doc и .xls не поддерживаются.
• Ограниченный контекст ИИ. Дополнительный анализ обрабатывает не более восьми групп изменённых пунктов; длинные фрагменты сокращаются. Чат получает выбранные выдержки, а не весь комплект. В интерфейсе установлен лимит 20 вопросов на сравнение и 2000 символов на вопрос.
• Нет постоянного рабочего пространства. Потеря сессии, обновление страницы с созданием новой сессии или перезапуск сервера могут удалить результаты и решения. Между браузерами они не синхронизируются. Дисковый кэш ИИ не восстанавливает рабочую сессию.
• Симуляция документооборота. Нет аутентификации, разграничения реальных пользователей, электронной подписи, внешних уведомлений и интеграции с кадровой системой или СЭД. Выбор участника имитирует вход. Отметки согласования и ознакомления не являются ЭЦП.
• Границы экспорта и моковых данных. Экспорт XLSX не реализован. DOCX включает находки, структуру и сопоставления с подтверждёнными источниками; свободный текст заключения и дополнительные наблюдения ИИ отдельно не экспортируются. Чек-лист новичка формирует только демонстрационный список.
• Запланированная архитектура реализована частично. Нет отдельных src/pipeline.py, src/functions.py, src/match.py, src/findings.py, src/verify.py: соответствующая локальная логика собрана в app/local_analysis.py. Эмбеддинги и LLM-подтверждение пар функций не подключены. В src/config.py есть заготовка клиента NVIDIA, но текущие анализ и чат интерфейса используют только интеграцию OpenAI.
• Воспроизводимость зависимостей. В requirements.txt часть версий не закреплена; lock-файл отсутствует. Контрольный комплект небольшой, метрики качества на независимом корпусе документов не представлены.

Live demo и ручной деплой

Приложение: https://www.afm.codes.

Сейчас проект деплоится вручную в Railway. Сборка описана в Dockerfile: Python 3.11, установка requirements.txt, запуск Streamlit на 0.0.0.0 с портом из PORT (по умолчанию 8501).

Перед ручным деплоем выполните локальные проверки:

DEMO_MODE=true python -m pytest -q
DEMO_MODE=true python scripts/eval_control.py

Переменные DEMO_MODE, OPENAI_API_KEY и OPENAI_MODEL задаются в окружении сервиса Railway. Ключи не нужно добавлять в репозиторий.

Резервный GitHub Actions workflow

Workflow Railway сохранён только для ручного запуска (workflow_dispatch); триггера на push нет. В настройках GitHub Actions workflow отключён, пока команда использует ручной деплой.

Если потребуется вернуть запуск через Actions, включите workflow Manual test and deploy to Railway, задайте secret RAILWAY_TOKEN и variable RAILWAY_SERVICE_ID, затем запустите его на ветке main. Он выполнит тесты и передаст код в Railway. Для запуска нужны доступные GitHub Actions runners; состояние сборки и приложения проверяется в Railway.