ИИ-агент «Анализ организационной структуры и функционала»

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

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

• Загрузка документов DOCX, PDF и XLSX для сторон «до» и «после», фоновый запуск анализа, просмотр прогресса и результата.
• Сравнение извлечённого текста двух редакций с выделением добавлений и удалений; просмотр подразделений, функций, рисков и диаграммы перемещения функций (Sankey). По ссылке «Источник» открывается пункт документа с цитатой.
• Python-пакет ai/: разбор документов, сопоставление пунктов, подразделений и функций, поиск возможных потерь, дублирования и конфликтов по правилам разделения обязанностей, проверка цитат, агент-критик и формирование заключения.
• FastAPI: хранение заданий и результатов, история анализов, API для подтверждения или отклонения вывода сотрудником и выгрузка служебной записки DOCX. История и проверка выводов человеком реализованы в API, но пока не выведены в веб-интерфейс.

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

1. Пользователь загружает документы «до» и «после». Веб-интерфейс отправляет их в FastAPI.
2. Backend сохраняет файлы, запускает задачу в фоне и отдаёт статус. Пакет ai разбирает документы, выделяет пункты, сопоставляет структуру и функции, формирует кандидатов на риски и проверяет подтверждающие цитаты. Агент-критик пытается опровергнуть найденные риски.
3. Интерфейс показывает сравнение текста, изменения подразделений, таблицу функций, диаграмму переходов, выводы и источники. Backend может сформировать DOCX-отчёт. Решение сотрудника по выводу можно передать через API; заключение после этого пересобирается.

flowchart LR
    U[Пользователь] --> F[frontend: React + Vite]
    F -->|HTTP: файлы, статус, результат| B[backend: FastAPI]
    B -->|вызов Python-функции| A[ai: пайплайн анализа]
    B <--> S[Локальное хранилище заданий]
    A -->|генерация и эмбеддинги| P[OpenAI API / NVIDIA API]
    A --> B --> F

Папки: frontend/ — интерфейс; backend/ — HTTP API, задания и экспорт; ai/ — анализ; shared/api.md — общий контракт. Подробная схема и исходная постановка находятся в ARCHITECTURE.md; при расхождении описания с кодом ориентируйтесь на текущую реализацию и API-контракт.

Технологии и интеграции

Компонент	Используется
Интерфейс	React, TypeScript, Vite, Tailwind CSS и CSS
Сервер	Python, FastAPI, Pydantic, Uvicorn, python-multipart, python-docx
Анализ	Python, Pydantic, python-docx, PyMuPDF, openpyxl, RapidFuzz, NumPy, PyYAML
AI API	OpenAI SDK; генерация через OpenAI или NVIDIA API, эмбеддинги через OpenAI
Запуск	Docker Compose, Python 3.11 и Node.js 22 внутри контейнеров

В шаблоне ai/.env.example указаны модели по умолчанию: gpt-5.4-mini, gpt-5.4 и text-embedding-3-small. Доступ к ним зависит от ваших ключей и аккаунта. При использовании NVIDIA для генерации ключ OpenAI всё равно нужен для эмбеддингов. Анализ отправляет содержимое документов внешнему AI-провайдеру.

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

Запуск Приложения https://kazakhtelecom-scandoc.onrender.com/

Для демо и интеграционной проверки: из корня актуальной копии main одна команда поднимает frontend и backend без установки Python, Node.js, venv или npm-зависимостей на машине:

docker compose up --build

Нужны только Docker и Docker Compose. Интерфейс: http://localhost:5173, API: http://localhost:8000/docs. Команда собирает текущий checkout; перед запуском обновите main, если нужна последняя версия из Git. По умолчанию backend использует подготовленный ответ: загрузка файлов проверяет сквозной путь, но не запускает AI-анализ их содержимого. Остановить сервисы можно Ctrl+C; данные заданий хранятся в томе Docker. Порты 8000 и 5173 должны быть свободны.

Если один из портов занят, можно задать другие порты хоста, например:

BACKEND_PORT=18000 FRONTEND_PORT=15173 docker compose up --build

В этом случае интерфейс откроется на http://localhost:15173, API — на http://localhost:18000/docs.

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

AI_MOCK=false docker compose up --build

Для OpenAI нужен OPENAI_API_KEY. При LLM_PROVIDER=nvidia дополнительно нужны NVIDIA_API_KEY и NVIDIA_MODEL; ключ OpenAI также нужен для эмбеддингов. Секреты храните только в локальном ai/.env. Вариант запуска без Docker описан в README backend/ и frontend/.

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

После запуска проверьте ответ {"status":"ok"} на http://localhost:8000/health. В интерфейсе запустите встроенный комплект, дождитесь статуса done, откройте сравнение, заключение и источники, затем выгрузите DOCX-отчёт. Для проверки реального анализа запустите стек с AI_MOCK=false и загрузите пару обезличенных документов из samples/before/ и samples/after/. Текущий веб-интерфейс ограничен одной парой, хотя backend принимает несколько файлов.

Историю и проверку вывода сотрудником можно проверить через http://localhost:8000/docs: GET /api/analyses, затем PATCH /api/analyses/{id}/findings/{finding_id} с телом {"status":"accepted"}. Автоматические проверки модулей описаны в README соответствующих папок.

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

• В репозитории есть обезличенные DOCX редакций 8 и 9 в samples/, которые можно использовать для проверки анализа.
• При запуске через Compose backend сохраняет задания, исходные файлы, статусы и результаты в именованном томе Docker; при ручном запуске — в backend/storage/. AI-анализ обращается к OpenAI API или NVIDIA API для генерации и к OpenAI API для эмбеддингов. Другие внешние наборы данных или интеграции в текущем коде не подключены.

Ограничения

• Для анализа загруженных файлов необходимы AI_MOCK=false, настроенные ключи и доступ к внешним AI API.
• PDF без текстового слоя не распознаются: OCR не реализован. Сравнение текста не сохраняет исходное оформление Word, PDF или Excel.
• История анализов и проверка выводов сотрудником доступны через API, но не через текущий интерфейс. Чат с документами указан в контракте как планируемый и не реализован.
• Результаты носят рекомендательный характер. Проверка цитаты подтверждает её наличие в документе, но интерпретацию вывода должен проверить сотрудник.

Развёрнутая версия

Публичная ссылка на развёрнутое приложение в текущем репозитории не указана. Для проверки используйте локальный запуск выше.