Сверка · AI First

Прототип ИИ-агента для кейса Казахтелекома «Анализ организационной структуры и функционала», hackalem.ai. Команда AI First, один участник.

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

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

• Загрузка комплектов DOCX, текстовых PDF и XLSX, до 20 МБ на файл.
• Извлечение подразделений и обязанностей; определение созданных, сохранённых и преобразованных подразделений по тексту документов.
• Реестр функций ДО → ПОСЛЕ: сохранение, передача, изменение, потенциальная потеря, добавление и неопределённые соответствия. Кандидаты обратной сверки не скрываются.
• Поиск дублирования и потенциальных конфликтов интересов внутри редакции с несколькими источниками. Исполнение и независимый контроль различаются.
• Проверка документа, пункта/фрагмента и дословного вхождения каждой принятой цитаты.
• Интерфейс: прогресс, журнал агентов, фильтры реестра, карточки доказательств, рекомендации и итоговое заключение.
• Сохранение результатов и промежуточных этапов в PostgreSQL. Готовые анализы открываются по прежней ссылке после перезапуска.

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

Нужны Docker с Compose v2, интернет для сборки и OpenAI API, API-ключ с доступным балансом. В терминале из корня репозитория:

cp .env.example .env
cp .back_env.example .back_env

В .back_env заполните OPENAI_API_KEY и укажите в OPENAI_MODEL модель, доступную вашему API-проекту. В .env задайте POSTGRES_PASSWORD перед первым запуском. Секреты не коммитятся.

docker compose up --build -d --wait
docker compose ps

• Приложение: http://localhost:3001
• Swagger API: http://localhost:8010/docs
• Проверка backend и БД: http://localhost:8010/health
• Логи: docker compose logs -f backend frontend.

Compose сам запускает БД и создаёт таблицу результатов. Фронтенд собирается внутри Docker: Node нужен только на стадии сборки, готовые файлы раздаёт nginx. По умолчанию /api проксируется в backend; вручную задавать адрес API не нужно.

Файл / параметр	Назначение
.back_env: OPENAI_API_KEY, OPENAI_MODEL	Обязательные настройки модели; поддержан OpenAI
.back_env: AGENT_MAX_REVISIONS	Число исправлений отчёта: 0–2, по умолчанию 1
.back_env: REGISTRY_*	Размеры пакетов, параллельность и бюджет обработки; см. пример
.env: POSTGRES_*, BACKEND_PORT, FRONTEND_PORT	БД и порты Compose
.env: API_BASE	Пустой — локальный proxy; внешний API требует CORS, пересборка не нужна

DATABASE_URL контейнер получает из настроек БД в Compose. .front_env.example оставлен как шаблон: Vite и Compose не читают .front_env автоматически.

Результаты и загрузки хранятся в именованных томах. docker compose down их сохраняет; docker compose down -v удаляет данные. Прерванный анализ получает статус ошибки; автоматического продолжения и повторного расходования API-кредитов нет.

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

1. Загрузите документы в два комплекта и запустите реальный анализ.
2. Дождитесь результата; откройте отклонение и сравните цитаты ДО/ПОСЛЕ.
3. В реестре включите «Требует проверки», проверьте источники спорных соответствий.
4. Откройте риски внутри редакции, журнал проверки/исправления и заключение.

Кнопка демо использует явно обозначенные тестовые данные, а не анализ файлов. Документы заказчика и API-ключи в репозиторий не включены.

Презентация

Презентация HTML: 6 слайдов для защиты примерно на 3 минуты. Текст выступления и ответы жюри.

Откройте docs/presentation/presentation.html в Chrome через «Открыть файл» (Ctrl+O) или из корня репозитория в Ubuntu:

xdg-open docs/presentation/presentation.html

Команда использует браузер по умолчанию. На GitHub HTML отображается как исходный код: скачайте файл кнопкой Download raw file и откройте его локально. Для слайдов не нужны интернет, Docker или установка зависимостей.

Управление: ← / → — слайды, F — полный экран, Esc — выход из полного экрана, H — скрыть/показать подсказки, P — печать.

Ссылка на последнем слайде открывает конкретный сохранённый анализ на localhost:3001. Для неё нужен запущенный проект и исходная локальная БД автора. В чистом клоне этого анализа нет: откройте http://localhost:3001 и загрузите свои документы либо используйте явно обозначенное тестовое демо.

Архитектура

Vue 3 + Quasar + TypeScript → nginx → FastAPI / Python 3.12 → PostgreSQL. Состояния и результаты хранятся в JSONB. Образ БД содержит pgvector, но векторный поиск не используется.

Парсеры → пакетный извлекатель функций → сопоставитель ДО ↔ ПОСЛЕ
        → аналитик изменений → кодовая проверка источников → LLM-контролёр
        → ограниченное исправление: принять или откатить → заключение

Оркестратор написан на Python; ответы модели проверяются схемами Pydantic. Извлечение и сопоставление пакетные, аналитик и контролёр получают полный текст. Пропуски и противоречия остаются needs_review. Контролёр оценивает результат по исходникам; правка не принимается, если ухудшает проверяемость источников. Заключение собирается из принятых выводов и предупреждений. Это явный агентный workflow, без RAG, embeddings и самостоятельного tool calling LLM.

Тесты и результаты

Проверено: 90 backend-тестов (включая 4 с PostgreSQL), Ruff, 44 frontend-сценария, TypeScript и production-сборка. Также проверен запуск из чистого клона с новой пустой БД: все три сервиса healthy, таблица создаётся автоматически, API доступен через nginx. Тесты используют заглушку модели; это не измерение её точности.

# Backend: Python 3.12, из backend/, в виртуальном окружении
pip install -e '.[dev]'
python -m pytest -q
ruff check app tests

# Frontend: Node 22, из frontend/
npm ci
npm test
npm run build

Для четырёх интеграционных тестов БД задайте TEST_DATABASE_URL доступной PostgreSQL; без него они пропускаются. Тесты используют собственные временные схемы. Для разработки frontend: npm run dev (Vite проксирует /api на localhost:8010).

Полный прогон редакций №8/№9 заказчика занял 472,1 секунды: 6 отклонений, 5 записей структуры, 66 спорных сопоставлений и 14 неразрешённых фрагментов из 981. Все 1119 опубликованных цитат повторно проверены по загруженным файлам. Смысловая полнота не доказана; найденное изменение по 4.4 требует уточнения. Последняя поправка входа контролёра проверена тестами, без повторного полного прогона.

Подробности и границы проверок: VALIDATION.md. Контролируемые платные проверки на синтетических документах: backend/scripts/live_registry_smoke.py и backend/scripts/live_structural_risk_smoke.py. Они обращаются к работающему API и расходуют кредиты только при явном запуске.

Ограничения

• Нет OCR и надёжного разбора графических оргсхем. Для DOCX автонумерация может адресоваться как «абзац N»; колонтитулы и вложенные объекты покрыты не полностью.
• Цитата подтверждает источник, но не правильность интерпретации. Полнота извлечения и точность сопоставления не измерены. При кодовых замечаниях итоговая оценка контролёра ограничена 0,49 — это не точность 49%.
• Проверка по законодательству/стандартам и сравнение с другими операторами не реализованы.
• Нет авторизации, экрана истории, распределённой очереди и автоматического возобновления. Поддерживается один backend-процесс; не публикуйте прототип в открытый интернет.
• Документы передаются OpenAI. Используйте обезличенные данные либо согласованный заказчиком режим обработки. Экономия времени на работе сотрудников пока не измерена.

Исходники: backend/, frontend/. Требования: REQUIREMENTS.md. Контракт: API_CONTRACT.md. Решения: docs/decisions. AGENTS.md и симлинк CLAUDE.md содержат общие инструкции для разработки.