ИИ-агент для сравнения организационных документов

Streamlit-приложение помогает сравнить комплекты положений и организационных документов до и после реорганизации. Оно извлекает текст TXT, DOCX и PDF с текстовым слоем, передаёт подтверждённые фрагменты ИИ-модели для смыслового сравнения и формирует выводы с точными цитатами, документами и расположением источника.

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

Как устроен агент

• Интерфейс и загрузка реализованы в app.py.
• org_audit/reader.py читает TXT, абзацы и таблицы DOCX, а также текстовые страницы PDF. Номера страниц сохраняются только для PDF. Для PDF без текстового слоя показывается необходимость OCR.
• org_audit/agent.py вызывает Responses API и выдаёт модели только два прикладных инструмента: поиск фрагментов в памяти процесса и чтение одного фрагмента по ID. Модель не получает доступ к терминалу, произвольным файлам, URL или редактированию источников.
• Сначала агент извлекает функции, затем сопоставляет их и ищет спорные доказательства. Число запросов и вызовов инструментов ограничено; обращения имеют тайм-аут и одну повторную попытку через SDK.
• org_audit/validation.py проверяет JSON, принадлежность ID комплекту, существование всех доказательств и минимальные требования к категориям. Цитаты, названия документов и расположение подставляются из исходных фрагментов.
• org_audit/report.py формирует заключение Markdown и CSV с BOM для корректного открытия кириллицы.
• Текст документов считается недоверенным. Фраза с инструкцией внутри документа не может добавить модели новые инструменты или доступ к внешним адресам.

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

Установка на Windows

Первый запуск

1. Установите Python 3.12 для Windows с python.org. В установщике оставьте включёнными Python Launcher и добавление Python в PATH.
2. Откройте папку проекта в Проводнике и дважды нажмите setup_windows.bat. Скрипт создаст чистое окружение .venv, установит нужные библиотеки и создаст .env, если его ещё нет. Если папка .venv уже существует, скрипт спросит разрешение пересоздать только её.
3. Откройте файл .env в VS Code. Впишите свой ключ после OPENAI_API_KEY=. Кавычки не нужны. Строку OPENAI_MODEL= можно оставить пустой — тогда используется gpt-5.6.
4. Запустите сайт двойным нажатием на start_windows.bat. Откроется адрес локального приложения, обычно http://localhost:8501. Чтобы остановить сайт, нажмите Ctrl+C в появившемся окне.

Ключ хранится только в локальном .env, который исключён из Git. Не вставляйте его в app.py, чат или GitHub.

Без API-ключа можно открыть приложение, загрузить документы и посмотреть демонстрационные примеры; сравнение с ИИ будет выключено. Для анализа нужен действующий ключ OpenAI API, доступ к выбранной модели и доступный бюджет API.

Если запуск не удался

• После установки Python закройте и снова откройте VS Code, чтобы он увидел команду py.
• Если появится сообщение о недостающем модуле или сломанной .venv, снова запустите setup_windows.bat и подтвердите пересоздание окружения.
• Если сайт открылся, но анализ вернул ошибку API, проверьте в .env ключ и модель, а также доступный бюджет API в проекте OpenAI.

Тесты

Установите тестовые зависимости и запустите pytest:

python -m pip install -r requirements-dev.txt
python -m pytest -q

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

Демонстрация за 3 минуты

1. Запустите приложение и включите «Добавить вымышленные демонстрационные данные».
2. Покажите предпросмотр до/после: подразделения, пункты и строки с prompt injection.
3. Если настроен API-ключ, подтвердите право передачи и нажмите «Сравнить документы».
4. Покажите сводку категорий, отфильтруйте возможное дублирование и раскройте цитаты с документами и расположением.
5. Скачайте Markdown-заключение и CSV. Напомните, что отсутствующее соответствие не доказывает ликвидацию функции.

Примеры в examples/ полностью вымышленные и не содержат реальных положений Казахтелекома. Без ключа API можно показать загрузку и предпросмотр, но ИИ-сравнение не выполняется и не подменяется подготовленными ответами.

Ограничения

• PDF поддерживается, если содержит извлекаемый текст. OCR сканов не реализован.
• DOCX сохраняет абзацы и расположение таблиц; номера Word-списков берутся из структуры файла, если она доступна. Номера страниц DOCX не указываются.
• Смысловое сопоставление зависит от модели и полноты загруженных документов. Итог требует проверки человеком.
• Приложение показывает только выводы с проверенными ссылками. При невалидном ответе, ошибках чтения или ограничении контекста анализ помечается как частичный.
• Перед внешней передачей документов пользователь должен подтвердить право на такую передачу.