Versa — сравнение организационных документов

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

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

Репозиторий команды: BAITC-Hacks/hack-e384891b-ainalineast-coder.

В проекте есть локальное приложение на Python и статическая браузерная сборка с тем же Python-движком через Pyodide. Подтверждённой опубликованной версии и действующей публичной ссылки нет. Наличие кода статической сборки не означает, что сайт развёрнут. Для проверки доступны воспроизводимые команды запуска ниже.

2. Краткое описание: проблема и пользователи

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

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

Versa объединяет две задачи:

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

Основной алгоритм использует правила, нормализацию текста, сопоставление структуры, лексическое сходство и difflib. Это не обучение собственной модели, не поиск по эмбеддингам и не автоматическая юридическая экспертиза. Коэффициент текстового сходства не является вероятностью правильности вывода. Итоговое решение принимает эксперт.

3. Реализованные возможности

Возможность	Что получает пользователь
Загрузка двух редакций	По одному документу или комплекту файлов на каждую сторону; названия и подразделения можно уточнить в интерфейсе
Импорт	Word DOCX, PDF с текстовым слоем, Excel XLSX, MD, TXT, CSV и TSV
Полная таблица	Три столбца: «Документ 1», «Документ 2», «Содержание изменений и дополнений»
Выделение отличий	Удалённые фрагменты показаны красным зачёркнутым текстом, дополнения — красным жирным текстом
Статусы	Без изменений, изменение редакции, дополнение, исключение, изменение нумерации или положения
Навигация	Поиск, фильтр изменений, прокрутка трёх столбцов, разворачивание таблицы на экран
Ссылки на источник	Название документа, пункт, подпункт, раздел или ненумерованный фрагмент в соответствии с распознанной структурой
Заключение	Предмет сравнения, выводы, перечень изменений с цитатами, замечания, рекомендации и пределы анализа
Экспертная проверка	Подтверждение или отклонение замечаний и заметки эксперта; сохраняются в HTML-заключении и JSON
Скачивание	DOCX, XLSX, PDF, HTML, CSV и JSON

Word, Excel, PDF и HTML-таблица сохраняют все строки, названия документов и выделение изменений независимо от выбранного фильтра. Word и PDF используют альбомный A3. В XLSX закреплена шапка, есть фильтр; длинные пункты продолжаются на следующих строках. CSV передаёт текст трёх столбцов без цветового оформления. Отдельная кнопка на вкладке «Заключение» сохраняет HTML с заключением, замечаниями, решениями эксперта и сравнительной таблицей.

4. Пользовательский сценарий и демонстрация

1. Откройте приложение. Оно начинает с экрана «Загрузка» и двух пустых областей. Документы и анализ автоматически не запускаются.
2. Добавьте исходную редакцию в «Документ 1», новую — в «Документ 2». Можно использовать несколько файлов на каждой стороне. Проверьте названия, подразделения и предупреждения об извлечении текста.
3. Либо явно выберите пример и нажмите «Загрузить пример». Локальная версия содержит предоставленные обезличенные редакции 8 и 9 и синтетический контрольный пример; статическая публичная сборка включает только синтетический пример.
4. Нажмите «Сравнить документы». Приложение покажет таблицу с обеими формулировками и пояснениями. Отсутствующая сторона обозначается фразой «Данный пункт в документе отсутствует».
5. Используйте поиск и фильтр «Только изменения». Для локального примера редакций 8 и 9 найдите 9.15: можно проверить изменение формулировки с добавлением слова «может». Затем проверьте пункт 3.4 и состав подразделений.
6. Откройте «Заключение», прочитайте цитаты и рекомендации. При необходимости рассмотрите замечания и внесите решения эксперта.
7. Нажмите «Скачать таблицу» и выберите Word, Excel, PDF, HTML, CSV или JSON. Для сохранения заключения используйте соответствующую кнопку на вкладке «Заключение».

Изменение входных документов сбрасывает предыдущий результат. Решения и заметки в интерфейсе действуют до перезагрузки страницы: сохраните HTML-заключение или JSON перед закрытием. В локальном режиме экспорты записываются в exports/ и скачиваются браузером. В браузерной сборке скачивание создаётся из данных в памяти вкладки.

5. Технологический стек

Слой	Реализация
Интерфейс	HTML, CSS, JavaScript без UI-фреймворка; встроенный шрифт Roboto
Основной движок	Python, стандартная библиотека: difflib, регулярные выражения, ZIP/XML, JSON, CSV
Локальный сервер	http.server.ThreadingHTTPServer; по умолчанию 127.0.0.1:8765
PDF: импорт	pypdf==6.10.0
DOCX: экспорт	python-docx==1.2.0
PDF: экспорт	reportlab==4.4.9, статические начертания Roboto
XLSX: экспорт	Собственный генератор OOXML на стандартной библиотеке Python
Браузерное исполнение	Pyodide 0.27.7, Python в Web Worker; библиотеки форматов загружаются по необходимости
Браузерные зависимости	Совместимые сборки lxml и Pillow из Pyodide; Python-пакеты через micropip
Необязательная модель	Локальная Ollama для дополнительной проверки кандидатов на соответствие функций
Проверки	unittest, интеграционные проверки HTTP API, форматов, отчётов и браузерного адаптера

Для основного анализа API-ключ, облачная LLM и Node.js не требуются. Проверенная локальная среда — Python 3.12.14, Windows. После установки зависимостей локальный основной сценарий работает без интернета.

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

Локальный маршрут: интерфейс → app.py → backend.py / comparison.py → заключение и экспорт. Браузерный маршрут: интерфейс → browser-api.js → Web Worker / Pyodide → browser_adapter.py → тот же движок. В браузерном маршруте Python-сервер для обработки документов не используется.

Файл или каталог	Назначение
index.html, app.js, styles.css	Загрузка, сравнение, заключение и скачивание
app.py	Локальный HTTP API, раздача интерфейса и локальных экспортов
backend.py	Извлечение текста, разбор функций, замечания и необязательная Ollama
comparison.py	Полное упорядоченное сопоставление пунктов и выделение текстовых различий
legal_text.py	Названия документов и ссылки на распознанные структурные элементы
legal_report.py	Подготовка заключения и его самостоятельного HTML-представления
comparison_report.py	Самостоятельная HTML-таблица для проверочного запуска
export_api.py	Проверка структуры данных и выбор бинарного формата
export_documents.py, export_xlsx.py	Экспорт Word/PDF и Excel
browser-api.js, browser-worker.mjs	Передача запросов в worker, загрузка среды, управление операциями и Blob-скачиванием
browser_adapter.py	Аналоги API-операций в браузере; LLM принудительно отключена
build_site.py	Статическая сборка по явному списку разрешённых файлов в dist/
assets/	Roboto и лицензия шрифта
data/	Предоставленные обезличенные документы для локальной проверки
tests*.py, verify.py, validation/	Тесты, воспроизводимая проверка и полученные результаты
docs/	Дополнительная техническая документация

Порядок исходной редакции служит основой таблицы. Новые пункты вставляются около сопоставленных соседних позиций; перенумерованные положения остаются доступны рядом с исходным текстом. Анализ функций и постатейная таблица — связанные, но разные представления: количество функций не равно количеству строк таблицы.

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

Локальное приложение

Получите репозиторий и перейдите в его корень. Требуется установленный Python; рекомендуемая версия для воспроизведения — 3.12.

git clone https://github.com/BAITC-Hacks/hack-e384891b-ainalineast-coder.git
cd hack-e384891b-ainalineast-coder
python --version
python -m pip install -r requirements.txt
python -B app.py

Откройте локальное приложение. Остановка сервера — Ctrl+C. На Windows также можно запустить start.cmd, если python доступен в PATH. На Linux/macOS, где команда называется python3, используйте её вместо python.

Чтобы изолировать зависимости, перед установкой создайте окружение python -m venv .venv и используйте его интерпретатор: .venv\Scripts\python.exe на Windows или .venv/bin/python на Linux/macOS.

Порт задаётся переменной VERSA_PORT; совместимая прежняя переменная — ORGLENS_PORT. Например, в PowerShell:

$env:VERSA_PORT = "8765"
python -B app.py

Дополнительная Ollama не обязательна. Если она уже установлена, запущена на 127.0.0.1:11434 и нужная модель загружена, укажите её реальное имя перед запуском:

$env:ORGLENS_LLM_MODEL = "имя-установленной-модели"
python -B app.py

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

Браузерная версия

Из корня репозитория выполните:

python -B build_site.py
python -m http.server 8766 --bind 127.0.0.1 --directory dist

Откройте браузерную сборку. Открытие index.html через file:// не является поддерживаемым способом запуска: worker и его ресурсы должны загружаться по HTTP(S).

build_site.py собирает dist/ по явному списку файлов и проверяет состав результата. В сборку не включаются предоставленные редакции аудита, пользовательские экспорты, история, тестовые результаты и серверные файлы. Доступен синтетический контрольный пример; пользователь может загрузить собственные документы.

При первом действии загружаются Pyodide и компоненты приложения. Для PDF-импорта и Word/PDF-экспорта дополнительно загружаются библиотеки форматов. Поэтому первый запуск требует доступа к CDN/PyPI и может занимать больше времени; работа без сети с пустым кешем не гарантируется. Документы обрабатываются в памяти браузера, а не отправляются в Python API. Скачивание отчётов создаётся локально во вкладке. Браузерная версия не вызывает Ollama.

Каталог dist/ подготовлен для размещения на статическом хостинге. Команды выше проверяют сборку локально и не публикуют сайт. Публичный адрес не заявляется.

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

Запустите весь набор тестов:

python -X utf8 -B -m unittest discover -p "tests*.py" -v

Для полного проверочного прогона с сохранением отчётов:

python -X utf8 -B verify.py

Последний сохранённый протокол содержит 73 успешно пройденных теста, включая 10 тестов браузерного адаптера. Проверяются извлечение текста, ограничения запросов, порядок и охват пунктов, изменения и перенумерация, восстановление исходного текста из выделенных частей, ссылки на источники, HTTP API, DOCX/XLSX/PDF, заключение и принудительное отключение LLM в браузерном адаптере. Тесты адаптера исполняются в обычном Python; сами по себе они не заменяют проверку Pyodide в браузере.

Локальный пример предоставленных редакций 8 и 9 даёт следующую статистику постатейной таблицы:

Статус строки	Количество
Без изменений	326
Изменение редакции	72
Добавлено	19
Исключено	20
Перенумеровано / изменено положение	70
Всего	507

Это 507 сопоставленных позиций, а не 507 ошибок, замечаний или функций. Отдельный функциональный анализ этого примера содержит 388 исходных и 382 новых извлечённых функций и 11 замечаний. Синтетический контрольный пример даёт 9 строк таблицы. Числа относятся к конкретным входным документам и текущему алгоритму, не являются оценкой точности на произвольных документах.

verify.py обновляет validation/tests.txt, validation/summary.json, JSON-анализ и HTML-таблицы/заключения для обоих примеров. Он также проверяет, что доказательные ссылки указывают на существующие исходные фрагменты с совпадающим текстом. Для этого запуска нужны локальные файлы data/; в статическую публичную сборку они не входят.

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

Входные данные — документы, выбранные пользователем. Для локальной демонстрации в data/ сохранены обезличенные редакции 8 и 9 положения о внутреннем аудите; отдельный контрольный пример создан синтетически. Реальные положения не включаются в статическую сборку.

В основном локальном режиме внешние API не вызываются. Дополнительная интеграция — локальный HTTP API Ollama, только при настройке и выборе пользователем. Браузерный режим загружает среду Pyodide с cdn.jsdelivr.net и библиотеки через PyPI/дистрибутив Pyodide; это загрузка программных зависимостей, пользовательские документы туда не отправляются. Интеграции с корпоративными системами Казахтелекома и внешней правовой базой не реализованы.

10. Ограничения и обращение с данными

Ограничение	Текущее поведение
Файлы	До 30 документов на каждую сторону, до 15 МиБ на отдельный файл
Запрос	До 35 МиБ JSON на запрос локального API; браузерный адаптер также проверяет этот предел. Передача файла в base64 увеличивает размер запроса
Текст	До 600 000 символов на документ
Анализ функций	До 1800 извлечённых пунктов суммарно; это отдельный предел функционального анализа, а не лимит строк итоговой таблицы
Экспорт	Проверка структуры; до 6000 строк в запросе бинарного экспорта
Архивные форматы	Защита от чрезмерной распаковки DOCX/XLSX: до 80 МиБ распакованных данных и 4000 записей архива
Старые форматы	DOC/XLS нужно предварительно сохранить в DOCX/XLSX
Сканы и изображения	OCR не реализован; схемы, SmartArt, изображения и встроенные объекты не интерпретируются
Excel	Читаются значения ячеек; формулы не пересчитываются
Сложная вёрстка PDF	Порядок извлечения колонок и таблиц нужно проверить по оригиналу

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

Локальный сервер слушает только loopback-интерфейс. Корпоративная аутентификация, роли, централизованный аудит действий и многопользовательская эксплуатация не реализованы. Экспорт в локальной версии оставляет файлы в exports/; пользователь управляет их хранением и удалением. В браузерной версии исходные данные и результаты находятся в памяти вкладки, а скачанные файлы сохраняются средствами браузера. Документы рассматриваются как данные: содержащиеся внутри них команды не исполняются.

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

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

Редакции 8 и 9 — обезличенные материалы, предоставленные пользователем для задачи; отдельная открытая лицензия на них не заявлена. Право их публикации за пределами конкурсного репозитория должно определяться владельцем. Поэтому статическая сборка содержит только синтетический пример. Лицензии сторонних библиотек, происхождение шрифта и сведения об ИИ-помощи перечислены в THIRD_PARTY.md; лицензия Roboto находится в assets/Roboto-OFL.txt.

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

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